@objectstack/runtime 0.3.3 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @objectstack/runtime
 
+## 0.4.2
+
+### Patch Changes
+
+- Unify all package versions to 0.4.2
+- Updated dependencies
+  - @objectstack/spec@0.4.2
+  - @objectstack/objectql@0.4.2
+  - @objectstack/types@0.4.2
+
+## 0.4.1
+
+### Patch Changes
+
+- Version synchronization and dependency updates
+
+  - Synchronized plugin-msw version to 0.4.1
+  - Updated runtime peer dependency versions to ^0.4.1
+  - Fixed internal dependency version mismatches
+
+- Updated dependencies
+  - @objectstack/spec@0.4.1
+  - @objectstack/types@0.4.1
+  - @objectstack/objectql@0.4.1
+
+## 0.4.0
+
+### Minor Changes
+
+- Release version 0.4.0
+
 ## 0.3.3
 
 ### Patch Changes

package/README.md

@@ -0,0 +1,162 @@
+# @objectstack/runtime
+
+ObjectStack Core Runtime & Query Engine
+
+## Overview
+
+The runtime package provides the `ObjectStackKernel` - the central orchestrator for ObjectStack applications. It manages the application lifecycle, plugins, and the ObjectQL data engine.
+
+## Installation
+
+```bash
+npm install @objectstack/runtime
+```
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import { ObjectStackKernel, ObjectQLPlugin } from '@objectstack/runtime';
+import { InMemoryDriver } from '@objectstack/driver-memory';
+
+const kernel = new ObjectStackKernel([
+  // Register ObjectQL engine
+  new ObjectQLPlugin(),
+  
+  // Add database driver
+  new InMemoryDriver(),
+  
+  // Add your app configurations
+  // appConfig,
+]);
+
+await kernel.start();
+```
+
+### Custom ObjectQL Instance
+
+If you have a separate ObjectQL implementation or need custom configuration:
+
+```typescript
+import { ObjectStackKernel, ObjectQLPlugin, ObjectQL } from '@objectstack/runtime';
+
+// Create custom ObjectQL instance
+const customQL = new ObjectQL({
+  env: 'production',
+  customConfig: true
+});
+
+// Pre-configure with custom hooks
+customQL.registerHook('beforeInsert', async (ctx) => {
+  console.log(`Inserting into ${ctx.object}`);
+});
+
+const kernel = new ObjectStackKernel([
+  // Use your custom ObjectQL instance
+  new ObjectQLPlugin(customQL),
+  
+  // ... other plugins
+]);
+
+await kernel.start();
+```
+
+### Backward Compatibility
+
+For backward compatibility, the kernel will automatically initialize ObjectQL if no `ObjectQLPlugin` is provided:
+
+```typescript
+// This still works, but will show a deprecation warning
+const kernel = new ObjectStackKernel([
+  new InMemoryDriver(),
+  // ... other plugins
+]);
+```
+
+## Architecture
+
+### ObjectStackKernel
+
+The kernel is responsible for:
+- Orchestrating application lifecycle
+- Managing plugins
+- Coordinating the ObjectQL engine
+- Handling data operations
+
+### ObjectQLPlugin
+
+The `ObjectQLPlugin` provides:
+- Explicit ObjectQL engine registration
+- Support for custom ObjectQL instances
+- Clean separation of concerns
+- Better testability
+
+## API Reference
+
+### ObjectStackKernel
+
+#### Constructor
+```typescript
+constructor(plugins: any[] = [])
+```
+
+#### Methods
+- `start()`: Initialize and start the kernel
+- `find(objectName, query)`: Query data
+- `get(objectName, id)`: Get single record
+- `create(objectName, data)`: Create record
+- `update(objectName, id, data)`: Update record
+- `delete(objectName, id)`: Delete record
+- `getMetadata(objectName)`: Get object metadata
+- `getView(objectName, viewType)`: Get UI view definition
+
+### ObjectQLPlugin
+
+#### Constructor
+```typescript
+constructor(ql?: ObjectQL, hostContext?: Record<string, any>)
+```
+
+#### Parameters
+- `ql` (optional): Custom ObjectQL instance
+- `hostContext` (optional): Host context configuration
+
+## Examples
+
+See the `examples/` directory for complete examples:
+- `examples/host/` - Full server setup with Hono
+- `examples/msw-react-crud/` - Browser-based setup with MSW
+- `examples/custom-objectql-example.ts` - Custom ObjectQL instance
+
+## Migration Guide
+
+### From Hardcoded ObjectQL to Plugin-Based
+
+**Before:**
+```typescript
+const kernel = new ObjectStackKernel([appConfig, driver]);
+```
+
+**After (Recommended):**
+```typescript
+const kernel = new ObjectStackKernel([
+  new ObjectQLPlugin(),
+  appConfig, 
+  driver
+]);
+```
+
+**After (Custom Instance):**
+```typescript
+const customQL = new ObjectQL({ /* config */ });
+const kernel = new ObjectStackKernel([
+  new ObjectQLPlugin(customQL),
+  appConfig, 
+  driver
+]);
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { ObjectQL, SchemaRegistry } from '@objectstack/objectql';
 export { ObjectStackKernel } from './kernel';
+export { ObjectQLPlugin } from './objectql-plugin';
 export { ObjectStackRuntimeProtocol } from './protocol';
 export * from './types';

package/dist/index.js

@@ -1,5 +1,6 @@
 // Export core engine
 export { ObjectQL, SchemaRegistry } from '@objectstack/objectql';
 export { ObjectStackKernel } from './kernel';
+export { ObjectQLPlugin } from './objectql-plugin';
 export { ObjectStackRuntimeProtocol } from './protocol';
 export * from './types';

package/dist/kernel.d.ts

@@ -6,9 +6,14 @@ import { ObjectQL } from '@objectstack/objectql';
  * plugins, and the core ObjectQL engine.
  */
 export declare class ObjectStackKernel {
-    ql: ObjectQL;
+    ql?: ObjectQL;
     private plugins;
     constructor(plugins?: any[]);
+    /**
+     * Ensure ObjectQL engine is initialized
+     * @throws Error if ObjectQL is not available
+     */
+    private ensureObjectQL;
     start(): Promise<void>;
     seed(): Promise<void>;
     find(objectName: string, query: any): Promise<{
@@ -21,7 +26,7 @@ export declare class ObjectStackKernel {
     delete(objectName: string, id: string): Promise<any>;
     getMetadata(objectName: string): {
         fields: Record<string, {
-            type: "number" | "boolean" | "code" | "date" | "text" | "textarea" | "email" | "url" | "phone" | "password" | "markdown" | "html" | "richtext" | "currency" | "percent" | "datetime" | "time" | "select" | "lookup" | "master_detail" | "image" | "file" | "avatar" | "formula" | "summary" | "autonumber" | "location" | "geolocation" | "address" | "color" | "rating" | "slider" | "signature" | "qrcode";
+            type: "number" | "boolean" | "code" | "date" | "text" | "textarea" | "email" | "url" | "phone" | "password" | "markdown" | "html" | "richtext" | "currency" | "percent" | "datetime" | "time" | "toggle" | "select" | "multiselect" | "radio" | "checkboxes" | "lookup" | "master_detail" | "tree" | "image" | "file" | "avatar" | "video" | "audio" | "formula" | "summary" | "autonumber" | "location" | "address" | "json" | "color" | "rating" | "slider" | "signature" | "qrcode" | "progress" | "tags" | "vector";
             required: boolean;
             searchable: boolean;
             multiple: boolean;
@@ -82,15 +87,22 @@ export declare class ObjectStackKernel {
                 currencyMode: "dynamic" | "fixed";
                 defaultCurrency: string;
             } | undefined;
+            vectorConfig?: {
+                dimensions: number;
+                distanceMetric: "cosine" | "euclidean" | "dotProduct" | "manhattan";
+                normalized: boolean;
+                indexed: boolean;
+                indexType?: "flat" | "hnsw" | "ivfflat" | undefined;
+            } | undefined;
         }>;
         name: string;
         active: boolean;
         isSystem: boolean;
         abstract: boolean;
         datasource: string;
+        tags?: string[] | undefined;
         label?: string | undefined;
         description?: string | undefined;
-        tags?: string[] | undefined;
         search?: {
             fields: string[];
             displayFields?: string[] | undefined;

package/dist/kernel.js

@@ -7,11 +7,27 @@ import { SchemaRegistry, ObjectQL } from '@objectstack/objectql';
  */
 export class ObjectStackKernel {
     constructor(plugins = []) {
-        // 1. Initialize Engine with Host Context (Simulated OS services)
-        this.ql = new ObjectQL({
-            env: process.env.NODE_ENV || 'development'
-        });
         this.plugins = plugins;
+        // Check if any plugin provides ObjectQL via type: 'objectql'
+        // This aligns with the manifest schema that supports objectql as a package type
+        const hasObjectQLPlugin = plugins.some(p => p && typeof p === 'object' && p.type === 'objectql');
+        if (!hasObjectQLPlugin) {
+            // Backward compatibility: Initialize ObjectQL directly if no plugin provides it
+            console.warn('[Kernel] No ObjectQL plugin found, using default initialization. Consider using ObjectQLPlugin.');
+            this.ql = new ObjectQL({
+                env: process.env.NODE_ENV || 'development'
+            });
+        }
+    }
+    /**
+     * Ensure ObjectQL engine is initialized
+     * @throws Error if ObjectQL is not available
+     */
+    ensureObjectQL() {
+        if (!this.ql) {
+            throw new Error('[Kernel] ObjectQL engine not initialized. Ensure ObjectQLPlugin is registered or kernel is properly initialized.');
+        }
+        return this.ql;
     }
     async start() {
         console.log('[Kernel] Starting...');
@@ -44,13 +60,13 @@ export class ObjectStackKernel {
             // @ts-ignore
             const { InMemoryDriver } = await import('@objectstack/driver-memory');
             const driver = new InMemoryDriver();
-            this.ql.registerDriver(driver);
+            this.ensureObjectQL().registerDriver(driver);
         }
         catch (e) {
             // Ignore if not present
         }
         // 2. Initialize Engine
-        await this.ql.init();
+        await this.ensureObjectQL().init();
         // 3. Seed Data
         await this.seed();
         // 4. Start Runtime Plugins
@@ -84,11 +100,11 @@ export class ObjectStackKernel {
                     for (const seed of app.data) {
                         try {
                             // Check if data exists
-                            const existing = await this.ql.find(seed.object, { top: 1 });
+                            const existing = await this.ensureObjectQL().find(seed.object, { top: 1 });
                             if (existing.length === 0) {
                                 console.log(`[Kernel] Inserting ${seed.records.length} records into ${seed.object}`);
                                 for (const record of seed.records) {
-                                    await this.ql.insert(seed.object, record);
+                                    await this.ensureObjectQL().insert(seed.object, record);
                                 }
                             }
                         }
@@ -106,26 +122,26 @@ export class ObjectStackKernel {
     // Forward methods to ObjectQL
     async find(objectName, query) {
         this.ensureSchema(objectName);
-        const results = await this.ql.find(objectName, { top: 100 });
+        const results = await this.ensureObjectQL().find(objectName, { top: 100 });
         return { value: results, count: results.length };
     }
     async get(objectName, id) {
         this.ensureSchema(objectName);
         // Find One
-        const results = await this.ql.find(objectName, { top: 1 }); // Mock implementation
+        const results = await this.ensureObjectQL().find(objectName, { top: 1 }); // Mock implementation
         return results[0];
     }
     async create(objectName, data) {
         this.ensureSchema(objectName);
-        return this.ql.insert(objectName, data);
+        return this.ensureObjectQL().insert(objectName, data);
     }
     async update(objectName, id, data) {
         this.ensureSchema(objectName);
-        return this.ql.update(objectName, id, data);
+        return this.ensureObjectQL().update(objectName, id, data);
     }
     async delete(objectName, id) {
         this.ensureSchema(objectName);
-        return this.ql.delete(objectName, id);
+        return this.ensureObjectQL().delete(objectName, id);
     }
     // [New Methods for ObjectUI]
     getMetadata(objectName) {

package/dist/objectql-plugin.d.ts

@@ -0,0 +1,27 @@
+import { ObjectQL } from '@objectstack/objectql';
+import { RuntimePlugin, RuntimeContext } from '@objectstack/types';
+/**
+ * ObjectQL Engine Plugin
+ *
+ * Registers the ObjectQL engine instance with the kernel.
+ * This allows users to provide their own ObjectQL implementation or configuration.
+ *
+ * Usage:
+ * - new ObjectQLPlugin() - Creates new ObjectQL with default settings
+ * - new ObjectQLPlugin(existingQL) - Uses existing ObjectQL instance
+ * - new ObjectQLPlugin(undefined, { custom: 'context' }) - Creates new ObjectQL with custom context
+ */
+export declare class ObjectQLPlugin implements RuntimePlugin {
+    name: string;
+    type: "objectql";
+    private ql;
+    /**
+     * @param ql - Existing ObjectQL instance to use (optional)
+     * @param hostContext - Host context for new ObjectQL instance (ignored if ql is provided)
+     */
+    constructor(ql?: ObjectQL, hostContext?: Record<string, any>);
+    /**
+     * Install the ObjectQL engine into the kernel
+     */
+    install(ctx: RuntimeContext): Promise<void>;
+}

package/dist/objectql-plugin.js

@@ -0,0 +1,41 @@
+import { ObjectQL } from '@objectstack/objectql';
+/**
+ * ObjectQL Engine Plugin
+ *
+ * Registers the ObjectQL engine instance with the kernel.
+ * This allows users to provide their own ObjectQL implementation or configuration.
+ *
+ * Usage:
+ * - new ObjectQLPlugin() - Creates new ObjectQL with default settings
+ * - new ObjectQLPlugin(existingQL) - Uses existing ObjectQL instance
+ * - new ObjectQLPlugin(undefined, { custom: 'context' }) - Creates new ObjectQL with custom context
+ */
+export class ObjectQLPlugin {
+    /**
+     * @param ql - Existing ObjectQL instance to use (optional)
+     * @param hostContext - Host context for new ObjectQL instance (ignored if ql is provided)
+     */
+    constructor(ql, hostContext) {
+        this.name = 'com.objectstack.engine.objectql';
+        this.type = 'objectql';
+        if (ql && hostContext) {
+            console.warn('[ObjectQLPlugin] Both ql and hostContext provided. hostContext will be ignored.');
+        }
+        if (ql) {
+            this.ql = ql;
+        }
+        else {
+            this.ql = new ObjectQL(hostContext || {
+                env: process.env.NODE_ENV || 'development'
+            });
+        }
+    }
+    /**
+     * Install the ObjectQL engine into the kernel
+     */
+    async install(ctx) {
+        // Attach the ObjectQL engine to the kernel
+        ctx.engine.ql = this.ql;
+        console.log('[ObjectQLPlugin] ObjectQL engine registered');
+    }
+}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@objectstack/runtime",
-  "version": "0.3.3",
+  "version": "0.4.2",
   "description": "ObjectStack Core Runtime & Query Engine",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
-    "@objectstack/objectql": "0.3.3",
-    "@objectstack/types": "0.3.3",
-    "@objectstack/spec": "0.3.3"
+    "@objectstack/objectql": "0.4.2",
+    "@objectstack/types": "0.4.2",
+    "@objectstack/spec": "0.4.2"
   },
   "devDependencies": {
     "typescript": "^5.0.0"

package/src/index.ts

@@ -1,6 +1,7 @@
 // Export core engine
 export { ObjectQL, SchemaRegistry } from '@objectstack/objectql';
 export { ObjectStackKernel } from './kernel';
+export { ObjectQLPlugin } from './objectql-plugin';
 export { ObjectStackRuntimeProtocol } from './protocol';
 
 export * from './types';

package/src/kernel.ts

@@ -8,15 +8,36 @@ import { SchemaRegistry, ObjectQL } from '@objectstack/objectql';
  * plugins, and the core ObjectQL engine.
  */
 export class ObjectStackKernel {
-  public ql: ObjectQL;
+  public ql?: ObjectQL; // Will be set by ObjectQLPlugin or fallback initialization
   private plugins: any[];
 
   constructor(plugins: any[] = []) {
-    // 1. Initialize Engine with Host Context (Simulated OS services)
-    this.ql = new ObjectQL({
-        env: process.env.NODE_ENV || 'development'
-    });
     this.plugins = plugins;
+    
+    // Check if any plugin provides ObjectQL via type: 'objectql'
+    // This aligns with the manifest schema that supports objectql as a package type
+    const hasObjectQLPlugin = plugins.some(p => 
+      p && typeof p === 'object' && p.type === 'objectql'
+    );
+    
+    if (!hasObjectQLPlugin) {
+      // Backward compatibility: Initialize ObjectQL directly if no plugin provides it
+      console.warn('[Kernel] No ObjectQL plugin found, using default initialization. Consider using ObjectQLPlugin.');
+      this.ql = new ObjectQL({
+        env: process.env.NODE_ENV || 'development'
+      });
+    }
+  }
+
+  /**
+   * Ensure ObjectQL engine is initialized
+   * @throws Error if ObjectQL is not available
+   */
+  private ensureObjectQL(): ObjectQL {
+    if (!this.ql) {
+      throw new Error('[Kernel] ObjectQL engine not initialized. Ensure ObjectQLPlugin is registered or kernel is properly initialized.');
+    }
+    return this.ql;
   }
 
   async start() {
@@ -54,13 +75,13 @@ export class ObjectStackKernel {
         // @ts-ignore
         const { InMemoryDriver } = await import('@objectstack/driver-memory');
         const driver = new InMemoryDriver();
-        this.ql.registerDriver(driver);
+        this.ensureObjectQL().registerDriver(driver);
     } catch (e) {
         // Ignore if not present
     }
     
     // 2. Initialize Engine
-    await this.ql.init();
+    await this.ensureObjectQL().init();
 
 
     // 3. Seed Data
@@ -102,11 +123,11 @@ export class ObjectStackKernel {
                 for (const seed of app.data) {
                      try {
                         // Check if data exists
-                        const existing = await this.ql.find(seed.object, { top: 1 });
+                        const existing = await this.ensureObjectQL().find(seed.object, { top: 1 });
                         if (existing.length === 0) {
                              console.log(`[Kernel] Inserting ${seed.records.length} records into ${seed.object}`);
                              for (const record of seed.records) {
-                                 await this.ql.insert(seed.object, record);
+                                 await this.ensureObjectQL().insert(seed.object, record);
                              }
                         }
                      } catch (e) {
@@ -124,30 +145,30 @@ export class ObjectStackKernel {
   // Forward methods to ObjectQL
   async find(objectName: string, query: any) {
     this.ensureSchema(objectName);
-    const results = await this.ql.find(objectName, { top: 100 });
+    const results = await this.ensureObjectQL().find(objectName, { top: 100 });
     return { value: results, count: results.length };
   }
 
   async get(objectName: string, id: string) {
     this.ensureSchema(objectName);
     // Find One
-    const results = await this.ql.find(objectName, { top: 1 }); // Mock implementation
+    const results = await this.ensureObjectQL().find(objectName, { top: 1 }); // Mock implementation
     return results[0];
   }
 
   async create(objectName: string, data: any) {
      this.ensureSchema(objectName);
-     return this.ql.insert(objectName, data);
+     return this.ensureObjectQL().insert(objectName, data);
   }
 
   async update(objectName: string, id: string, data: any) {
     this.ensureSchema(objectName);
-    return this.ql.update(objectName, id, data);
+    return this.ensureObjectQL().update(objectName, id, data);
   }
 
   async delete(objectName: string, id: string) {
     this.ensureSchema(objectName);
-    return this.ql.delete(objectName, id);
+    return this.ensureObjectQL().delete(objectName, id);
   }
 
   // [New Methods for ObjectUI]

package/src/objectql-plugin.ts

@@ -0,0 +1,47 @@
+import { ObjectQL } from '@objectstack/objectql';
+import { RuntimePlugin, RuntimeContext } from '@objectstack/types';
+
+/**
+ * ObjectQL Engine Plugin
+ * 
+ * Registers the ObjectQL engine instance with the kernel.
+ * This allows users to provide their own ObjectQL implementation or configuration.
+ * 
+ * Usage:
+ * - new ObjectQLPlugin() - Creates new ObjectQL with default settings
+ * - new ObjectQLPlugin(existingQL) - Uses existing ObjectQL instance
+ * - new ObjectQLPlugin(undefined, { custom: 'context' }) - Creates new ObjectQL with custom context
+ */
+export class ObjectQLPlugin implements RuntimePlugin {
+  name = 'com.objectstack.engine.objectql';
+  type = 'objectql' as const;
+  
+  private ql: ObjectQL;
+
+  /**
+   * @param ql - Existing ObjectQL instance to use (optional)
+   * @param hostContext - Host context for new ObjectQL instance (ignored if ql is provided)
+   */
+  constructor(ql?: ObjectQL, hostContext?: Record<string, any>) {
+    if (ql && hostContext) {
+      console.warn('[ObjectQLPlugin] Both ql and hostContext provided. hostContext will be ignored.');
+    }
+    
+    if (ql) {
+      this.ql = ql;
+    } else {
+      this.ql = new ObjectQL(hostContext || {
+        env: process.env.NODE_ENV || 'development'
+      });
+    }
+  }
+
+  /**
+   * Install the ObjectQL engine into the kernel
+   */
+  async install(ctx: RuntimeContext) {
+    // Attach the ObjectQL engine to the kernel
+    ctx.engine.ql = this.ql;
+    console.log('[ObjectQLPlugin] ObjectQL engine registered');
+  }
+}