Add browser execution support with interactive demos and documentation

Co-authored-by: huangyiirene <7665279+huangyiirene@users.noreply.github.com>

Author: Copilot

README.md

@@ -36,6 +36,8 @@ ObjectQL is organized as a Monorepo to ensure modularity and universal compatibi
 | **`@objectql/core`** | Universal | **The Engine.** The runtime logic, validation, and repository pattern. |
 | **`@objectql/driver-sql`** | Node.js | Adapter for SQL databases (Postgres, MySQL, SQLite) via Knex. |
 | **`@objectql/driver-mongo`** | Node.js | Adapter for MongoDB. |
+| **`@objectql/driver-memory`** | Universal | **In-Memory Driver.** Zero dependencies, perfect for testing and browser apps. |
+| **`@objectql/driver-localstorage`** | Browser | **Browser Storage.** Persistent client-side storage using LocalStorage. |
 | **`@objectql/sdk`** | Universal | **Remote Driver.** Connects to an ObjectQL server via HTTP. |
 | **`@objectql/platform-node`**| Node.js | Utilities for loading YAML files from the filesystem. |
 
@@ -130,6 +132,55 @@ ObjectQL isolates the "What" (Query) from the "How" (Execution).
 * Instead of connecting to a DB, it connects to an ObjectQL Server API.
 * The API usage remains exactly the same (`repo.find(...)`), but it runs over HTTP.
 
+#### Memory Driver (`@objectql/driver-memory`)
+
+* **Zero dependencies** - Pure JavaScript implementation
+* **Universal** - Works in Node.js, Browser, Edge environments
+* Perfect for testing, prototyping, and client-side state management
+* See [Browser Demo](./examples/browser-demo/) for live examples
+
+#### LocalStorage Driver (`@objectql/driver-localstorage`)
+
+* **Browser-native persistence** - Data survives page refreshes
+* Built on Web Storage API
+* Perfect for offline apps, PWAs, and user preferences
+* See [LocalStorage Demo](./examples/browser-localstorage-demo/) for examples
+
+### Browser Support 🌐
+
+ObjectQL runs **natively in web browsers** with zero backend required! This makes it perfect for:
+
+- 🚀 **Rapid Prototyping** - Build UIs without server setup
+- 📱 **Offline-First Apps** - PWAs with client-side data
+- 🎓 **Educational Tools** - Interactive learning experiences
+- 🧪 **Testing** - Browser-based test environments
+
+**Try it now:** Check out our interactive [Browser Demo](./examples/browser-demo/) and [LocalStorage Demo](./examples/browser-localstorage-demo/)!
+
+```javascript
+// Running ObjectQL in the browser - it's that simple!
+import { ObjectQL } from '@objectql/core';
+import { MemoryDriver } from '@objectql/driver-memory';
+
+const driver = new MemoryDriver();
+const app = new ObjectQL({ datasources: { default: driver } });
+
+app.registerObject({
+  name: 'tasks',
+  fields: {
+    title: { type: 'text', required: true },
+    completed: { type: 'boolean', defaultValue: false }
+  }
+});
+
+await app.init();
+
+// Use it just like on the server!
+const ctx = app.createContext({ isSystem: true });
+const tasks = ctx.object('tasks');
+await tasks.create({ title: 'Build awesome app!' });
+```
+
 ### Extensibility
 
 ObjectQL's driver architecture supports custom database implementations. Potential databases include:

examples/browser-demo/vite.config.js

@@ -3,6 +3,13 @@ import { resolve } from 'path';
 
 export default defineConfig({
   root: '.',
+  resolve: {
+    alias: {
+      '@objectql/core': resolve(__dirname, '../../packages/foundation/core/src/index.ts'),
+      '@objectql/driver-memory': resolve(__dirname, '../../packages/drivers/memory/src/index.ts'),
+      '@objectql/types': resolve(__dirname, '../../packages/foundation/types/src/index.ts')
+    }
+  },
   build: {
     outDir: 'dist',
     rollupOptions: {
@@ -13,9 +20,6 @@ export default defineConfig({
   },
   server: {
     port: 3000,
-    open: true
-  },
-  optimizeDeps: {
-    include: ['@objectql/core', '@objectql/driver-memory', '@objectql/types']
+    open: false
   }
 });

examples/browser-localstorage-demo/vite.config.js

@@ -3,6 +3,13 @@ import { resolve } from 'path';
 
 export default defineConfig({
   root: '.',
+  resolve: {
+    alias: {
+      '@objectql/core': resolve(__dirname, '../../packages/foundation/core/src/index.ts'),
+      '@objectql/driver-localstorage': resolve(__dirname, '../../packages/drivers/localstorage/src/index.ts'),
+      '@objectql/types': resolve(__dirname, '../../packages/foundation/types/src/index.ts')
+    }
+  },
   build: {
     outDir: 'dist',
     rollupOptions: {
@@ -13,9 +20,6 @@ export default defineConfig({
   },
   server: {
     port: 3000,
-    open: true
-  },
-  optimizeDeps: {
-    include: ['@objectql/core', '@objectql/driver-memory', '@objectql/types']
+    open: false
   }
 });

package.json

@@ -27,6 +27,7 @@
     "supertest": "^7.2.2",
     "ts-jest": "^29.4.6",
     "typescript": "^5.3.0",
+    "vite": "^7.3.1",
     "vitepress": "^1.6.4"
   },
   "version": "0.1.0",

packages/drivers/memory/README.md

@@ -96,6 +96,79 @@ await repo.update(user.id, { email: 'alice.new@example.com' });
 await repo.delete(user.id);
 ```
 
+## Browser Usage
+
+The Memory Driver works seamlessly in web browsers! Perfect for prototyping, client-side apps, and offline experiences.
+
+### Quick Start in Browser
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <title>ObjectQL in Browser</title>
+</head>
+<body>
+    <h1>ObjectQL Browser Demo</h1>
+    <script type="module">
+        import { ObjectQL } from '@objectql/core';
+        import { MemoryDriver } from '@objectql/driver-memory';
+        
+        // Initialize
+        const driver = new MemoryDriver();
+        const app = new ObjectQL({
+            datasources: { default: driver }
+        });
+        
+        // Define schema
+        app.registerObject({
+            name: 'tasks',
+            fields: {
+                title: { type: 'text', required: true },
+                completed: { type: 'boolean', defaultValue: false }
+            }
+        });
+        
+        await app.init();
+        
+        // Use it!
+        const ctx = app.createContext({ isSystem: true });
+        const tasks = ctx.object('tasks');
+        
+        await tasks.create({ title: 'Learn ObjectQL in Browser!' });
+        const allTasks = await tasks.find({});
+        console.log('Tasks:', allTasks);
+    </script>
+</body>
+</html>
+```
+
+### Interactive Browser Demo
+
+See the **[Browser Demo](../../../examples/browser-demo/)** for a complete interactive example with:
+- 🎨 Beautiful UI with live CRUD operations
+- 🖥️ Browser console debugging
+- 📊 Real-time statistics
+- ✨ Sample data generation
+
+### Browser Compatibility
+
+- ✅ Chrome/Edge 90+
+- ✅ Firefox 88+
+- ✅ Safari 14+
+- ✅ All modern browsers with ES6+ support
+
+### Browser vs Node.js
+
+| Feature | Browser | Node.js |
+|---------|---------|---------|
+| **Performance** | ⚡ Fast | ⚡ Fast |
+| **Persistence** | ❌ Lost on refresh | ❌ Lost on process exit |
+| **Use Case** | Prototyping, Client state | Testing, Dev, Edge |
+| **Data Limit** | RAM (GB) | RAM (GB) |
+
+**For persistent browser storage**, use the [LocalStorage Driver](../localstorage/README.md).
+
 ## Configuration Options
 
 ### Basic Configuration

packages/foundation/types/schemas/object.schema.json

@@ -559,6 +559,23 @@
           "$ref": "#/definitions/ValidationAiContext",
           "description": "AI context for the field. Provides semantic information for AI tools."
         },
+        "blank_as_zero": {
+          "description": "Treat blank/null as zero in formula calculations.",
+          "type": "boolean"
+        },
+        "data_type": {
+          "description": "Expected return data type for formula fields.",
+          "enum": [
+            "number",
+            "text",
+            "date",
+            "datetime",
+            "boolean",
+            "currency",
+            "percent"
+          ],
+          "type": "string"
+        },
         "defaultValue": {
           "description": "The default value if not provided during creation."
         },
@@ -574,8 +591,12 @@
           "items": {},
           "type": "array"
         },
+        "format": {
+          "description": "Display format for formula results (e.g., \"0.00\", \"YYYY-MM-DD\").",
+          "type": "string"
+        },
         "formula": {
-          "description": "Formula expression.",
+          "description": "Formula expression (for 'formula' type fields).",
           "type": "string"
         },
         "help_text": {
@@ -649,6 +670,10 @@
           },
           "type": "array"
         },
+        "precision": {
+          "description": "Decimal precision for numeric formula results.",
+          "type": "number"
+        },
         "readonly": {
           "description": "Whether the field is read-only in UI.",
           "type": "boolean"
@@ -677,6 +702,27 @@
           "description": "Type of summary (count, sum, min, max, avg).",
           "type": "string"
         },
+        "treat_blank_as": {
+          "anyOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "number"
+            },
+            {
+              "type": "boolean"
+            },
+            {
+              "format": "date-time",
+              "type": "string"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Default value for null/undefined referenced fields in formulas."
+        },
         "type": {
           "$ref": "#/definitions/FieldType",
           "description": "The data type of the field."