@objectstack/objectql 4.0.2 → 4.0.4

package/dist/index.mjs

@@ -301,7 +301,7 @@ var SchemaRegistry = class {
     if (type === "object") {
       return ObjectSchema.parse(item);
     }
-    if (type === "apps") {
+    if (type === "app") {
       return AppSchema.parse(item);
     }
     if (type === "package") {
@@ -451,13 +451,13 @@ var SchemaRegistry = class {
   // App Helpers
   // ==========================================
   static registerApp(app, packageId) {
-    this.registerItem("apps", app, "name", packageId);
+    this.registerItem("app", app, "name", packageId);
   }
   static getApp(name) {
-    return this.getItem("apps", name);
+    return this.getItem("app", name);
   }
   static getAllApps() {
-    return this.listItems("apps");
+    return this.listItems("app");
   }
   // ==========================================
   // Plugin Helpers
@@ -513,6 +513,7 @@ SchemaRegistry.metadata = /* @__PURE__ */ new Map();
 
 // src/protocol.ts
 import { parseFilterAST, isFilterAST } from "@objectstack/spec/data";
+import { PLURAL_TO_SINGULAR, SINGULAR_TO_PLURAL } from "@objectstack/spec/shared";
 function simpleHash(str) {
   let hash = 0;
   for (let i = 0; i < str.length; i++) {
@@ -640,16 +641,25 @@ var ObjectStackProtocolImplementation = class {
     };
   }
   async getMetaTypes() {
-    return {
-      types: SchemaRegistry.getRegisteredTypes()
-    };
+    const schemaTypes = SchemaRegistry.getRegisteredTypes();
+    let runtimeTypes = [];
+    try {
+      const services = this.getServicesRegistry?.();
+      const metadataService = services?.get("metadata");
+      if (metadataService && typeof metadataService.getRegisteredTypes === "function") {
+        runtimeTypes = await metadataService.getRegisteredTypes();
+      }
+    } catch {
+    }
+    const allTypes = Array.from(/* @__PURE__ */ new Set([...schemaTypes, ...runtimeTypes]));
+    return { types: allTypes };
   }
   async getMetaItems(request) {
     const { packageId } = request;
     let items = SchemaRegistry.listItems(request.type, packageId);
     if (items.length === 0) {
-      const alt = request.type.endsWith("s") ? request.type.slice(0, -1) : request.type + "s";
-      items = SchemaRegistry.listItems(alt, packageId);
+      const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
+      if (alt) items = SchemaRegistry.listItems(alt, packageId);
     }
     if (items.length === 0) {
       try {
@@ -665,21 +675,50 @@ var ObjectStackProtocolImplementation = class {
             return data;
           });
         } else {
-          const alt = request.type.endsWith("s") ? request.type.slice(0, -1) : request.type + "s";
-          const altRecords = await this.engine.find("sys_metadata", {
-            where: { type: alt, state: "active" }
-          });
-          if (altRecords && altRecords.length > 0) {
-            items = altRecords.map((record) => {
-              const data = typeof record.metadata === "string" ? JSON.parse(record.metadata) : record.metadata;
-              SchemaRegistry.registerItem(request.type, data, "name");
-              return data;
+          const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
+          if (alt) {
+            const altRecords = await this.engine.find("sys_metadata", {
+              where: { type: alt, state: "active" }
             });
+            if (altRecords && altRecords.length > 0) {
+              items = altRecords.map((record) => {
+                const data = typeof record.metadata === "string" ? JSON.parse(record.metadata) : record.metadata;
+                SchemaRegistry.registerItem(request.type, data, "name");
+                return data;
+              });
+            }
           }
         }
       } catch {
       }
     }
+    try {
+      const services = this.getServicesRegistry?.();
+      const metadataService = services?.get("metadata");
+      if (metadataService && typeof metadataService.list === "function") {
+        let runtimeItems = await metadataService.list(request.type);
+        if (packageId && runtimeItems && runtimeItems.length > 0) {
+          runtimeItems = runtimeItems.filter((item) => item?._packageId === packageId);
+        }
+        if (runtimeItems && runtimeItems.length > 0) {
+          const itemMap = /* @__PURE__ */ new Map();
+          for (const item of items) {
+            const entry = item;
+            if (entry && typeof entry === "object" && "name" in entry) {
+              itemMap.set(entry.name, entry);
+            }
+          }
+          for (const item of runtimeItems) {
+            const entry = item;
+            if (entry && typeof entry === "object" && "name" in entry) {
+              itemMap.set(entry.name, entry);
+            }
+          }
+          items = Array.from(itemMap.values());
+        }
+      }
+    } catch {
+    }
     return {
       type: request.type,
       items
@@ -688,8 +727,8 @@ var ObjectStackProtocolImplementation = class {
   async getMetaItem(request) {
     let item = SchemaRegistry.getItem(request.type, request.name);
     if (item === void 0) {
-      const alt = request.type.endsWith("s") ? request.type.slice(0, -1) : request.type + "s";
-      item = SchemaRegistry.getItem(alt, request.name);
+      const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
+      if (alt) item = SchemaRegistry.getItem(alt, request.name);
     }
     if (item === void 0) {
       try {
@@ -700,18 +739,30 @@ var ObjectStackProtocolImplementation = class {
           item = typeof record.metadata === "string" ? JSON.parse(record.metadata) : record.metadata;
           SchemaRegistry.registerItem(request.type, item, "name");
         } else {
-          const alt = request.type.endsWith("s") ? request.type.slice(0, -1) : request.type + "s";
-          const altRecord = await this.engine.findOne("sys_metadata", {
-            where: { type: alt, name: request.name, state: "active" }
-          });
-          if (altRecord) {
-            item = typeof altRecord.metadata === "string" ? JSON.parse(altRecord.metadata) : altRecord.metadata;
-            SchemaRegistry.registerItem(request.type, item, "name");
+          const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
+          if (alt) {
+            const altRecord = await this.engine.findOne("sys_metadata", {
+              where: { type: alt, name: request.name, state: "active" }
+            });
+            if (altRecord) {
+              item = typeof altRecord.metadata === "string" ? JSON.parse(altRecord.metadata) : altRecord.metadata;
+              SchemaRegistry.registerItem(request.type, item, "name");
+            }
           }
         }
       } catch {
       }
     }
+    if (item === void 0) {
+      try {
+        const services = this.getServicesRegistry?.();
+        const metadataService = services?.get("metadata");
+        if (metadataService && typeof metadataService.get === "function") {
+          item = await metadataService.get(request.type, request.name);
+        }
+      } catch {
+      }
+    }
     return {
       type: request.type,
       name: request.name,
@@ -942,7 +993,21 @@ var ObjectStackProtocolImplementation = class {
   // ==========================================
   async getMetaItemCached(request) {
     try {
-      const item = SchemaRegistry.getItem(request.type, request.name);
+      let item = SchemaRegistry.getItem(request.type, request.name);
+      if (!item) {
+        const alt = PLURAL_TO_SINGULAR[request.type] ?? SINGULAR_TO_PLURAL[request.type];
+        if (alt) item = SchemaRegistry.getItem(alt, request.name);
+      }
+      if (!item) {
+        try {
+          const services = this.getServicesRegistry?.();
+          const metadataService = services?.get("metadata");
+          if (metadataService && typeof metadataService.get === "function") {
+            item = await metadataService.get(request.type, request.name);
+          }
+        } catch {
+        }
+      }
       if (!item) {
         throw new Error(`Metadata item ${request.type}/${request.name} not found`);
       }
@@ -1294,10 +1359,11 @@ var ObjectStackProtocolImplementation = class {
       for (const record of records) {
         try {
           const data = typeof record.metadata === "string" ? JSON.parse(record.metadata) : record.metadata;
-          if (record.type === "object") {
+          const normalizedType = PLURAL_TO_SINGULAR[record.type] ?? record.type;
+          if (normalizedType === "object") {
             SchemaRegistry.registerObject(data, record.packageId || "sys_metadata");
           } else {
-            SchemaRegistry.registerItem(record.type, data, "name");
+            SchemaRegistry.registerItem(normalizedType, data, "name");
           }
           loaded++;
         } catch (e) {
@@ -1447,10 +1513,15 @@ var ObjectStackProtocolImplementation = class {
 import { ExecutionContextSchema } from "@objectstack/spec/kernel";
 import { createLogger } from "@objectstack/core";
 import { CoreServiceName } from "@objectstack/spec/system";
+import { pluralToSingular } from "@objectstack/spec/shared";
 var _ObjectQL = class _ObjectQL {
   constructor(hostContext = {}) {
     this.drivers = /* @__PURE__ */ new Map();
     this.defaultDriver = null;
+    // Datasource mapping rules (imported from defineStack)
+    this.datasourceMapping = [];
+    // Package manifests registry (for defaultDatasource lookup)
+    this.manifests = /* @__PURE__ */ new Map();
     // Per-object hooks with priority support
     this.hooks = /* @__PURE__ */ new Map([
       ["beforeFind", []],
@@ -1648,6 +1719,9 @@ var _ObjectQL = class _ObjectQL {
     const id = manifest.id || manifest.name;
     const namespace = manifest.namespace;
     this.logger.debug("Registering package manifest", { id, namespace });
+    if (id) {
+      this.manifests.set(id, manifest);
+    }
     SchemaRegistry.installPackage(manifest);
     this.logger.debug("Installed Package", { id: manifest.id, name: manifest.name, namespace });
     if (manifest.objects) {
@@ -1737,7 +1811,7 @@ var _ObjectQL = class _ObjectQL {
         for (const item of items) {
           const itemName = item.name || item.id;
           if (itemName) {
-            SchemaRegistry.registerItem(key, item, "name", id);
+            SchemaRegistry.registerItem(pluralToSingular(key), item, "name", id);
           }
         }
       }
@@ -1843,7 +1917,7 @@ var _ObjectQL = class _ObjectQL {
         for (const item of items) {
           const itemName = item.name || item.id;
           if (itemName) {
-            SchemaRegistry.registerItem(key, item, "name", ownerId);
+            SchemaRegistry.registerItem(pluralToSingular(key), item, "name", ownerId);
           }
         }
       }
@@ -1867,6 +1941,16 @@ var _ObjectQL = class _ObjectQL {
       this.logger.info("Set default driver", { driverName: driver.name });
     }
   }
+  /**
+   * 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) {
+    this.realtimeService = service;
+    this.logger.info("RealtimeService configured for data events");
+  }
   /**
    * Helper to get object definition
    */
@@ -1892,27 +1976,99 @@ var _ObjectQL = class _ObjectQL {
   }
   /**
    * 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
    */
   getDriver(objectName) {
     const object = SchemaRegistry.getObject(objectName);
-    if (object) {
-      const datasourceName = object.datasource || "default";
-      if (datasourceName === "default") {
-        if (this.defaultDriver && this.drivers.has(this.defaultDriver)) {
-          return this.drivers.get(this.defaultDriver);
-        }
-      } else {
-        if (this.drivers.has(datasourceName)) {
-          return this.drivers.get(datasourceName);
+    if (object?.datasource && object.datasource !== "default") {
+      if (this.drivers.has(object.datasource)) {
+        return this.drivers.get(object.datasource);
+      }
+      throw new Error(`[ObjectQL] Datasource '${object.datasource}' configured for object '${objectName}' is not registered.`);
+    }
+    const mappedDatasource = this.resolveDatasourceFromMapping(objectName, object);
+    if (mappedDatasource && this.drivers.has(mappedDatasource)) {
+      this.logger.debug("Resolved datasource from mapping", {
+        object: objectName,
+        datasource: mappedDatasource
+      });
+      return this.drivers.get(mappedDatasource);
+    }
+    const fqn = object?.name || objectName;
+    const owner = SchemaRegistry.getObjectOwner(fqn);
+    if (owner?.packageId) {
+      const manifest = this.manifests.get(owner.packageId);
+      if (manifest?.defaultDatasource && manifest.defaultDatasource !== "default") {
+        if (this.drivers.has(manifest.defaultDatasource)) {
+          this.logger.debug("Resolved datasource from package manifest", {
+            object: objectName,
+            package: owner.packageId,
+            datasource: manifest.defaultDatasource
+          });
+          return this.drivers.get(manifest.defaultDatasource);
         }
-        throw new Error(`[ObjectQL] Datasource '${datasourceName}' configured for object '${objectName}' is not registered.`);
       }
     }
-    if (this.defaultDriver) {
+    if (this.defaultDriver && this.drivers.has(this.defaultDriver)) {
       return this.drivers.get(this.defaultDriver);
     }
     throw new Error(`[ObjectQL] No driver available for object '${objectName}'`);
   }
+  /**
+   * Resolve datasource from mapping rules
+   *
+   * Rules are evaluated in order (or by priority if specified).
+   * First matching rule wins.
+   */
+  resolveDatasourceFromMapping(objectName, object) {
+    if (!this.datasourceMapping || this.datasourceMapping.length === 0) {
+      return null;
+    }
+    const sortedRules = [...this.datasourceMapping].sort((a, b) => {
+      const aPriority = a.priority ?? 1e3;
+      const bPriority = b.priority ?? 1e3;
+      return aPriority - bPriority;
+    });
+    for (const rule of sortedRules) {
+      if (rule.namespace && object?.namespace === rule.namespace) {
+        return rule.datasource;
+      }
+      if (rule.package && object?.packageId === rule.package) {
+        return rule.datasource;
+      }
+      if (rule.objectPattern && this.matchPattern(objectName, rule.objectPattern)) {
+        return rule.datasource;
+      }
+      if (rule.default) {
+        return rule.datasource;
+      }
+    }
+    return null;
+  }
+  /**
+   * Simple glob pattern matching
+   * Supports * (any chars) and ? (single char)
+   */
+  matchPattern(objectName, pattern) {
+    const regexPattern = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".");
+    const regex = new RegExp(`^${regexPattern}$`);
+    return regex.test(objectName);
+  }
+  /**
+   * Set datasource mapping rules
+   * Called by ObjectQLPlugin during bootstrap
+   */
+  setDatasourceMapping(rules) {
+    this.datasourceMapping = rules;
+    this.logger.info("Datasource mapping rules configured", {
+      ruleCount: rules.length
+    });
+  }
   /**
    * Initialize the engine and all registered drivers
    */
@@ -1921,14 +2077,22 @@ var _ObjectQL = class _ObjectQL {
       driverCount: this.drivers.size,
       drivers: Array.from(this.drivers.keys())
     });
+    const failedDrivers = [];
     for (const [name, driver] of this.drivers) {
       try {
         await driver.connect();
         this.logger.info("Driver connected successfully", { driverName: name });
       } catch (e) {
+        failedDrivers.push(name);
         this.logger.error("Failed to connect driver", e, { driverName: name });
       }
     }
+    if (failedDrivers.length > 0) {
+      this.logger.warn(
+        `${failedDrivers.length} of ${this.drivers.size} driver(s) failed initial connect. Operations may recover via lazy reconnection or fail at query time.`,
+        { failedDrivers }
+      );
+    }
     this.logger.info("ObjectQL engine initialization complete");
   }
   async destroy() {
@@ -2130,6 +2294,39 @@ var _ObjectQL = class _ObjectQL {
         hookContext.event = "afterInsert";
         hookContext.result = result;
         await this.triggerHooks("afterInsert", hookContext);
+        if (this.realtimeService) {
+          try {
+            if (Array.isArray(result)) {
+              for (const record of result) {
+                const event = {
+                  type: "data.record.created",
+                  object,
+                  payload: {
+                    recordId: record.id,
+                    after: record
+                  },
+                  timestamp: (/* @__PURE__ */ new Date()).toISOString()
+                };
+                await this.realtimeService.publish(event);
+              }
+              this.logger.debug(`Published ${result.length} data.record.created events`, { object });
+            } else {
+              const event = {
+                type: "data.record.created",
+                object,
+                payload: {
+                  recordId: result.id,
+                  after: result
+                },
+                timestamp: (/* @__PURE__ */ new Date()).toISOString()
+              };
+              await this.realtimeService.publish(event);
+              this.logger.debug("Published data.record.created event", { object, recordId: result.id });
+            }
+          } catch (error) {
+            this.logger.warn("Failed to publish data event", { object, error });
+          }
+        }
         return hookContext.result;
       } catch (e) {
         this.logger.error("Insert operation failed", e, { object });
@@ -2176,6 +2373,26 @@ var _ObjectQL = class _ObjectQL {
         hookContext.event = "afterUpdate";
         hookContext.result = result;
         await this.triggerHooks("afterUpdate", hookContext);
+        if (this.realtimeService) {
+          try {
+            const resultId = typeof result === "object" && result && "id" in result ? result.id : void 0;
+            const recordId = String(hookContext.input.id || resultId || "");
+            const event = {
+              type: "data.record.updated",
+              object,
+              payload: {
+                recordId,
+                changes: hookContext.input.data,
+                after: result
+              },
+              timestamp: (/* @__PURE__ */ new Date()).toISOString()
+            };
+            await this.realtimeService.publish(event);
+            this.logger.debug("Published data.record.updated event", { object, recordId });
+          } catch (error) {
+            this.logger.warn("Failed to publish data event", { object, error });
+          }
+        }
         return hookContext.result;
       } catch (e) {
         this.logger.error("Update operation failed", e, { object });
@@ -2221,6 +2438,24 @@ var _ObjectQL = class _ObjectQL {
         hookContext.event = "afterDelete";
         hookContext.result = result;
         await this.triggerHooks("afterDelete", hookContext);
+        if (this.realtimeService) {
+          try {
+            const resultId = typeof result === "object" && result && "id" in result ? result.id : void 0;
+            const recordId = String(hookContext.input.id || resultId || "");
+            const event = {
+              type: "data.record.deleted",
+              object,
+              payload: {
+                recordId
+              },
+              timestamp: (/* @__PURE__ */ new Date()).toISOString()
+            };
+            await this.realtimeService.publish(event);
+            this.logger.debug("Published data.record.deleted event", { object, recordId });
+          } catch (error) {
+            this.logger.warn("Failed to publish data event", { object, error });
+          }
+        }
         return hookContext.result;
       } catch (e) {
         this.logger.error("Delete operation failed", e, { object });
@@ -2678,6 +2913,9 @@ var MetadataFacade = class {
 };
 
 // src/plugin.ts
+function hasLoadMetaFromDb(service) {
+  return typeof service === "object" && service !== null && typeof service["loadMetaFromDb"] === "function";
+}
 var ObjectQLPlugin = class {
   constructor(ql, hostContext) {
     this.name = "com.objectstack.engine.objectql";
@@ -2734,9 +2972,22 @@ var ObjectQLPlugin = class {
             ctx.logger.debug("Discovered and registered app service (legacy)", { serviceName: name });
           }
         }
+        try {
+          const realtimeService = ctx.getService("realtime");
+          if (realtimeService && typeof realtimeService === "object" && "publish" in realtimeService) {
+            ctx.logger.info("[ObjectQLPlugin] Bridging realtime service to ObjectQL for event publishing");
+            this.ql.setRealtimeService(realtimeService);
+          }
+        } catch (e) {
+          ctx.logger.debug("[ObjectQLPlugin] No realtime service found \u2014 data events will not be published", {
+            error: e.message
+          });
+        }
       }
       await this.ql?.init();
+      await this.restoreMetadataFromDb(ctx);
       await this.syncRegisteredSchemas(ctx);
+      await this.bridgeObjectsToMetadataService(ctx);
       this.registerAuditHooks(ctx);
       this.registerTenantMiddleware(ctx);
       ctx.logger.info("ObjectQL engine started", {
@@ -2929,6 +3180,97 @@ var ObjectQLPlugin = class {
       ctx.logger.info("Schema sync complete", { synced, skipped, total: allObjects.length });
     }
   }
+  /**
+   * 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).
+   */
+  async restoreMetadataFromDb(ctx) {
+    let protocol;
+    try {
+      const service = ctx.getService("protocol");
+      if (!service || !hasLoadMetaFromDb(service)) {
+        ctx.logger.debug("Protocol service does not support loadMetaFromDb, skipping DB restore");
+        return;
+      }
+      protocol = service;
+    } catch (e) {
+      ctx.logger.debug("Protocol service unavailable, skipping DB restore", {
+        error: e instanceof Error ? e.message : String(e)
+      });
+      return;
+    }
+    try {
+      const { loaded, errors } = await protocol.loadMetaFromDb();
+      if (loaded > 0 || errors > 0) {
+        ctx.logger.info("Metadata restored from database to SchemaRegistry", { loaded, errors });
+      } else {
+        ctx.logger.debug("No persisted metadata found in database");
+      }
+    } catch (e) {
+      ctx.logger.debug("DB metadata restore failed (non-fatal)", {
+        error: e instanceof Error ? e.message : String(e)
+      });
+    }
+  }
+  /**
+   * 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.
+   */
+  async bridgeObjectsToMetadataService(ctx) {
+    try {
+      const metadataService = ctx.getService("metadata");
+      if (!metadataService || typeof metadataService.register !== "function") {
+        ctx.logger.debug("Metadata service unavailable for bridging, skipping");
+        return;
+      }
+      if (!this.ql?.registry) {
+        ctx.logger.debug("SchemaRegistry unavailable for bridging, skipping");
+        return;
+      }
+      const objects = this.ql.registry.getAllObjects();
+      let bridged = 0;
+      for (const obj of objects) {
+        try {
+          const existing = await metadataService.getObject(obj.name);
+          if (!existing) {
+            await metadataService.register("object", obj.name, obj);
+            bridged++;
+          }
+        } catch (e) {
+          ctx.logger.debug("Failed to bridge object to metadata service", {
+            object: obj.name,
+            error: e instanceof Error ? e.message : String(e)
+          });
+        }
+      }
+      if (bridged > 0) {
+        ctx.logger.info("Bridged objects from SchemaRegistry to metadata service", {
+          count: bridged,
+          total: objects.length
+        });
+      } else {
+        ctx.logger.debug("No objects needed bridging (all already in metadata service)");
+      }
+    } catch (e) {
+      ctx.logger.debug("Failed to bridge objects to metadata service", {
+        error: e instanceof Error ? e.message : String(e)
+      });
+    }
+  }
   /**
    * Load metadata from external metadata service into ObjectQL registry
    * This enables ObjectQL to use file-based or remote metadata