@objectstack/objectql 4.0.2 → 4.0.4

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/objectql@4.0.2 build /home/runner/work/framework/framework/packages/objectql
+> @objectstack/objectql@4.0.4 build /home/runner/work/framework/framework/packages/objectql
 > tsup --config ../../tsup.config.ts
 
 CLI Building entry: src/index.ts
@@ -10,13 +10,13 @@
 CLI Cleaning output folder
 ESM Build start
 CJS Build start
-CJS dist/index.js     104.57 KB
-CJS dist/index.js.map 212.32 KB
-CJS ⚡️ Build success in 297ms
-ESM dist/index.mjs     102.83 KB
-ESM dist/index.mjs.map 211.02 KB
-ESM ⚡️ Build success in 297ms
+CJS dist/index.js     117.80 KB
+CJS dist/index.js.map 237.44 KB
+CJS ⚡️ Build success in 238ms
+ESM dist/index.mjs     115.90 KB
+ESM dist/index.mjs.map 236.13 KB
+ESM ⚡️ Build success in 244ms
 DTS Build start
-DTS ⚡️ Build success in 20150ms
-DTS dist/index.d.mts 77.34 KB
-DTS dist/index.d.ts  77.34 KB
+DTS ⚡️ Build success in 27180ms
+DTS dist/index.d.mts 79.80 KB
+DTS dist/index.d.ts  79.80 KB

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @objectstack/objectql
 
+## 4.0.4
+
+### Patch Changes
+
+- Updated dependencies [326b66b]
+  - @objectstack/spec@4.0.4
+  - @objectstack/core@4.0.4
+  - @objectstack/types@4.0.4
+
+## 4.0.3
+
+### Patch Changes
+
+- @objectstack/spec@4.0.3
+- @objectstack/core@4.0.3
+- @objectstack/types@4.0.3
+
+## 4.0.3
+
+### Patch Changes
+
+- fix: ObjectQL.init() now tracks and warns about failed driver connections instead of silently swallowing errors, improving debuggability for cold-start and serverless issues.
+
 ## 4.0.2
 
 ### Patch Changes

package/dist/index.d.mts

@@ -4,7 +4,7 @@ import { ObjectOwnership, ServiceObject, QueryAST, HookContext, EngineQueryOptio
 import { ObjectStackManifest, InstalledPackage, ExecutionContext } from '@objectstack/spec/kernel';
 import { ObjectStackProtocol, MetadataCacheRequest, MetadataCacheResponse, BatchUpdateRequest, BatchUpdateResponse, UpdateManyDataRequest, DeleteManyDataRequest } from '@objectstack/spec/api';
 import { IDataEngine, DriverInterface, Logger, Plugin, PluginContext, ObjectKernel } from '@objectstack/core';
-import { IFeedService } from '@objectstack/spec/contracts';
+import { IFeedService, IRealtimeService } from '@objectstack/spec/contracts';
 
 /**
  * XState-inspired State Machine Protocol
@@ -474,7 +474,7 @@ declare class SchemaRegistry {
         actions?: {
             name: string;
             label: string;
-            type: "url" | "script" | "modal" | "flow" | "api";
+            type: "url" | "flow" | "api" | "script" | "modal";
             refreshAfter: boolean;
             objectName?: string | undefined;
             icon?: string | undefined;
@@ -563,8 +563,9 @@ declare class SchemaRegistry {
     } | {
         manifest: {
             id: string;
+            defaultDatasource: string;
             version: string;
-            type: "theme" | "driver" | "app" | "server" | "ui" | "module" | "agent" | "objectql" | "plugin" | "gateway" | "adapter";
+            type: "theme" | "app" | "agent" | "driver" | "server" | "ui" | "module" | "objectql" | "plugin" | "gateway" | "adapter";
             name: string;
             namespace?: string | undefined;
             description?: string | undefined;
@@ -709,7 +710,7 @@ declare class SchemaRegistry {
                 extensionPoints?: {
                     id: string;
                     name: string;
-                    type: "provider" | "action" | "widget" | "hook" | "transformer" | "validator" | "decorator";
+                    type: "provider" | "action" | "hook" | "widget" | "transformer" | "validator" | "decorator";
                     cardinality: "multiple" | "single";
                     description?: string | undefined;
                     contract?: {
@@ -888,8 +889,9 @@ declare class SchemaRegistry {
         registeredNamespaces?: string[] | undefined;
     } | {
         id: string;
+        defaultDatasource: string;
         version: string;
-        type: "theme" | "driver" | "app" | "server" | "ui" | "module" | "agent" | "objectql" | "plugin" | "gateway" | "adapter";
+        type: "theme" | "app" | "agent" | "driver" | "server" | "ui" | "module" | "objectql" | "plugin" | "gateway" | "adapter";
         name: string;
         namespace?: string | undefined;
         description?: string | undefined;
@@ -1034,7 +1036,7 @@ declare class SchemaRegistry {
             extensionPoints?: {
                 id: string;
                 name: string;
-                type: "provider" | "action" | "widget" | "hook" | "transformer" | "validator" | "decorator";
+                type: "provider" | "action" | "hook" | "widget" | "transformer" | "validator" | "decorator";
                 cardinality: "multiple" | "single";
                 description?: string | undefined;
                 contract?: {
@@ -1487,10 +1489,13 @@ declare class ObjectQL implements IDataEngine {
     private drivers;
     private defaultDriver;
     private logger;
+    private datasourceMapping;
+    private manifests;
     private hooks;
     private middlewares;
     private actions;
     private hostContext;
+    private realtimeService?;
     constructor(hostContext?: Record<string, any>);
     /**
      * Service Status Report
@@ -1584,6 +1589,13 @@ declare class ObjectQL implements IDataEngine {
      * Register a new storage driver
      */
     registerDriver(driver: DriverInterface, isDefault?: boolean): void;
+    /**
+     * Set the realtime service for publishing data change events.
+     * Should be called after kernel resolves the realtime service.
+     *
+     * @param service - An IRealtimeService instance for event publishing
+     */
+    setRealtimeService(service: IRealtimeService): void;
     /**
      * Helper to get object definition
      */
@@ -1601,8 +1613,38 @@ declare class ObjectQL implements IDataEngine {
     private resolveObjectName;
     /**
      * Helper to get the target driver
+     *
+     * Resolution priority (first match wins):
+     * 1. Object's explicit `datasource` field (if not 'default')
+     * 2. DatasourceMapping rules (namespace/package/pattern matching)
+     * 3. Package's `defaultDatasource` from manifest
+     * 4. Global default driver
      */
     private getDriver;
+    /**
+     * Resolve datasource from mapping rules
+     *
+     * Rules are evaluated in order (or by priority if specified).
+     * First matching rule wins.
+     */
+    private resolveDatasourceFromMapping;
+    /**
+     * Simple glob pattern matching
+     * Supports * (any chars) and ? (single char)
+     */
+    private matchPattern;
+    /**
+     * Set datasource mapping rules
+     * Called by ObjectQLPlugin during bootstrap
+     */
+    setDatasourceMapping(rules: Array<{
+        namespace?: string;
+        package?: string;
+        objectPattern?: string;
+        default?: boolean;
+        datasource: string;
+        priority?: number;
+    }>): void;
     /**
      * Initialize the engine and all registered drivers
      */
@@ -1879,6 +1921,30 @@ declare class ObjectQLPlugin implements Plugin {
      * Drivers that do not implement `syncSchema` are silently skipped.
      */
     private syncRegisteredSchemas;
+    /**
+     * Restore persisted metadata from the database (sys_metadata) on startup.
+     *
+     * Calls `protocol.loadMetaFromDb()` to bulk-load all active metadata
+     * records (objects, views, apps, etc.) into the in-memory SchemaRegistry.
+     * This closes the persistence loop so that user-created schemas survive
+     * kernel cold starts and redeployments.
+     *
+     * Gracefully degrades when:
+     * - The protocol service is unavailable (e.g., in-memory-only mode).
+     * - `loadMetaFromDb` is not implemented by the protocol shim.
+     * - The underlying driver/table does not exist yet (first-run scenario).
+     */
+    private restoreMetadataFromDb;
+    /**
+     * Bridge all SchemaRegistry objects to the metadata service.
+     *
+     * This ensures objects registered by plugins and loaded from sys_metadata
+     * are visible to AI tools and other consumers that query IMetadataService.
+     *
+     * Runs after both restoreMetadataFromDb() and syncRegisteredSchemas() to
+     * catch all objects in the SchemaRegistry regardless of their source.
+     */
+    private bridgeObjectsToMetadataService;
     /**
      * Load metadata from external metadata service into ObjectQL registry
      * This enables ObjectQL to use file-based or remote metadata

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { ObjectOwnership, ServiceObject, QueryAST, HookContext, EngineQueryOptio
 import { ObjectStackManifest, InstalledPackage, ExecutionContext } from '@objectstack/spec/kernel';
 import { ObjectStackProtocol, MetadataCacheRequest, MetadataCacheResponse, BatchUpdateRequest, BatchUpdateResponse, UpdateManyDataRequest, DeleteManyDataRequest } from '@objectstack/spec/api';
 import { IDataEngine, DriverInterface, Logger, Plugin, PluginContext, ObjectKernel } from '@objectstack/core';
-import { IFeedService } from '@objectstack/spec/contracts';
+import { IFeedService, IRealtimeService } from '@objectstack/spec/contracts';
 
 /**
  * XState-inspired State Machine Protocol
@@ -474,7 +474,7 @@ declare class SchemaRegistry {
         actions?: {
             name: string;
             label: string;
-            type: "url" | "script" | "modal" | "flow" | "api";
+            type: "url" | "flow" | "api" | "script" | "modal";
             refreshAfter: boolean;
             objectName?: string | undefined;
             icon?: string | undefined;
@@ -563,8 +563,9 @@ declare class SchemaRegistry {
     } | {
         manifest: {
             id: string;
+            defaultDatasource: string;
             version: string;
-            type: "theme" | "driver" | "app" | "server" | "ui" | "module" | "agent" | "objectql" | "plugin" | "gateway" | "adapter";
+            type: "theme" | "app" | "agent" | "driver" | "server" | "ui" | "module" | "objectql" | "plugin" | "gateway" | "adapter";
             name: string;
             namespace?: string | undefined;
             description?: string | undefined;
@@ -709,7 +710,7 @@ declare class SchemaRegistry {
                 extensionPoints?: {
                     id: string;
                     name: string;
-                    type: "provider" | "action" | "widget" | "hook" | "transformer" | "validator" | "decorator";
+                    type: "provider" | "action" | "hook" | "widget" | "transformer" | "validator" | "decorator";
                     cardinality: "multiple" | "single";
                     description?: string | undefined;
                     contract?: {
@@ -888,8 +889,9 @@ declare class SchemaRegistry {
         registeredNamespaces?: string[] | undefined;
     } | {
         id: string;
+        defaultDatasource: string;
         version: string;
-        type: "theme" | "driver" | "app" | "server" | "ui" | "module" | "agent" | "objectql" | "plugin" | "gateway" | "adapter";
+        type: "theme" | "app" | "agent" | "driver" | "server" | "ui" | "module" | "objectql" | "plugin" | "gateway" | "adapter";
         name: string;
         namespace?: string | undefined;
         description?: string | undefined;
@@ -1034,7 +1036,7 @@ declare class SchemaRegistry {
             extensionPoints?: {
                 id: string;
                 name: string;
-                type: "provider" | "action" | "widget" | "hook" | "transformer" | "validator" | "decorator";
+                type: "provider" | "action" | "hook" | "widget" | "transformer" | "validator" | "decorator";
                 cardinality: "multiple" | "single";
                 description?: string | undefined;
                 contract?: {
@@ -1487,10 +1489,13 @@ declare class ObjectQL implements IDataEngine {
     private drivers;
     private defaultDriver;
     private logger;
+    private datasourceMapping;
+    private manifests;
     private hooks;
     private middlewares;
     private actions;
     private hostContext;
+    private realtimeService?;
     constructor(hostContext?: Record<string, any>);
     /**
      * Service Status Report
@@ -1584,6 +1589,13 @@ declare class ObjectQL implements IDataEngine {
      * Register a new storage driver
      */
     registerDriver(driver: DriverInterface, isDefault?: boolean): void;
+    /**
+     * Set the realtime service for publishing data change events.
+     * Should be called after kernel resolves the realtime service.
+     *
+     * @param service - An IRealtimeService instance for event publishing
+     */
+    setRealtimeService(service: IRealtimeService): void;
     /**
      * Helper to get object definition
      */
@@ -1601,8 +1613,38 @@ declare class ObjectQL implements IDataEngine {
     private resolveObjectName;
     /**
      * Helper to get the target driver
+     *
+     * Resolution priority (first match wins):
+     * 1. Object's explicit `datasource` field (if not 'default')
+     * 2. DatasourceMapping rules (namespace/package/pattern matching)
+     * 3. Package's `defaultDatasource` from manifest
+     * 4. Global default driver
      */
     private getDriver;
+    /**
+     * Resolve datasource from mapping rules
+     *
+     * Rules are evaluated in order (or by priority if specified).
+     * First matching rule wins.
+     */
+    private resolveDatasourceFromMapping;
+    /**
+     * Simple glob pattern matching
+     * Supports * (any chars) and ? (single char)
+     */
+    private matchPattern;
+    /**
+     * Set datasource mapping rules
+     * Called by ObjectQLPlugin during bootstrap
+     */
+    setDatasourceMapping(rules: Array<{
+        namespace?: string;
+        package?: string;
+        objectPattern?: string;
+        default?: boolean;
+        datasource: string;
+        priority?: number;
+    }>): void;
     /**
      * Initialize the engine and all registered drivers
      */
@@ -1879,6 +1921,30 @@ declare class ObjectQLPlugin implements Plugin {
      * Drivers that do not implement `syncSchema` are silently skipped.
      */
     private syncRegisteredSchemas;
+    /**
+     * Restore persisted metadata from the database (sys_metadata) on startup.
+     *
+     * Calls `protocol.loadMetaFromDb()` to bulk-load all active metadata
+     * records (objects, views, apps, etc.) into the in-memory SchemaRegistry.
+     * This closes the persistence loop so that user-created schemas survive
+     * kernel cold starts and redeployments.
+     *
+     * Gracefully degrades when:
+     * - The protocol service is unavailable (e.g., in-memory-only mode).
+     * - `loadMetaFromDb` is not implemented by the protocol shim.
+     * - The underlying driver/table does not exist yet (first-run scenario).
+     */
+    private restoreMetadataFromDb;
+    /**
+     * Bridge all SchemaRegistry objects to the metadata service.
+     *
+     * This ensures objects registered by plugins and loaded from sys_metadata
+     * are visible to AI tools and other consumers that query IMetadataService.
+     *
+     * Runs after both restoreMetadataFromDb() and syncRegisteredSchemas() to
+     * catch all objects in the SchemaRegistry regardless of their source.
+     */
+    private bridgeObjectsToMetadataService;
     /**
      * Load metadata from external metadata service into ObjectQL registry
      * This enables ObjectQL to use file-based or remote metadata