@objectstack/objectql 1.0.2 → 1.0.5

package/dist/index.mjs

@@ -0,0 +1,768 @@
+// src/registry.ts
+import { ObjectSchema } from "@objectstack/spec/data";
+import { ManifestSchema } from "@objectstack/spec/kernel";
+import { AppSchema } from "@objectstack/spec/ui";
+var SchemaRegistry = class {
+  /**
+   * Universal Register Method
+   * @param type The category of metadata (e.g., 'object', 'app', 'plugin')
+   * @param item The metadata item itself
+   * @param keyField The property to use as the unique key (default: 'name')
+   */
+  static registerItem(type, item, keyField = "name") {
+    if (!this.metadata.has(type)) {
+      this.metadata.set(type, /* @__PURE__ */ new Map());
+    }
+    const collection = this.metadata.get(type);
+    const key = String(item[keyField]);
+    try {
+      this.validate(type, item);
+    } catch (e) {
+      console.error(`[Registry] Validation failed for ${type} ${key}: ${e.message}`);
+    }
+    if (collection.has(key)) {
+      console.warn(`[Registry] Overwriting ${type}: ${key}`);
+    }
+    collection.set(key, item);
+    console.log(`[Registry] Registered ${type}: ${key}`);
+  }
+  /**
+   * Validate Metadata against Spec Zod Schemas
+   */
+  static validate(type, item) {
+    if (type === "object") {
+      return ObjectSchema.parse(item);
+    }
+    if (type === "app") {
+      return AppSchema.parse(item);
+    }
+    if (type === "plugin") {
+      return ManifestSchema.parse(item);
+    }
+    return true;
+  }
+  /**
+   * Universal Unregister Method
+   */
+  static unregisterItem(type, name) {
+    const collection = this.metadata.get(type);
+    if (collection && collection.has(name)) {
+      collection.delete(name);
+      console.log(`[Registry] Unregistered ${type}: ${name}`);
+    } else {
+      console.warn(`[Registry] Attempted to unregister non-existent ${type}: ${name}`);
+    }
+  }
+  /**
+   * Universal Get Method
+   */
+  static getItem(type, name) {
+    return this.metadata.get(type)?.get(name);
+  }
+  /**
+   * Universal List Method
+   */
+  static listItems(type) {
+    return Array.from(this.metadata.get(type)?.values() || []);
+  }
+  /**
+   * Get all registered metadata types (Kinds)
+   */
+  static getRegisteredTypes() {
+    return Array.from(this.metadata.keys());
+  }
+  // ==========================================
+  // Typed Helper Methods (Shortcuts)
+  // ==========================================
+  /**
+   * Object Helpers
+   */
+  static registerObject(schema) {
+    this.registerItem("object", schema, "name");
+  }
+  static getObject(name) {
+    return this.getItem("object", name);
+  }
+  static getAllObjects() {
+    return this.listItems("object");
+  }
+  /**
+   * Plugin Helpers
+   */
+  static registerPlugin(manifest) {
+    this.registerItem("plugin", manifest, "id");
+  }
+  static getAllPlugins() {
+    return this.listItems("plugin");
+  }
+  /**
+   * Kind (Metadata Type) Helpers
+   */
+  static registerKind(kind) {
+    this.registerItem("kind", kind, "id");
+  }
+  static getAllKinds() {
+    return this.listItems("kind");
+  }
+};
+// Nested Map: Type -> Name/ID -> MetadataItem
+SchemaRegistry.metadata = /* @__PURE__ */ new Map();
+
+// src/protocol.ts
+function simpleHash(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  return Math.abs(hash).toString(16);
+}
+var ObjectStackProtocolImplementation = class {
+  constructor(engine) {
+    this.engine = engine;
+  }
+  async getDiscovery(_request) {
+    return {
+      version: "1.0",
+      apiName: "ObjectStack API",
+      capabilities: {
+        graphql: false,
+        search: false,
+        websockets: false,
+        files: true,
+        analytics: false,
+        hub: false
+      },
+      endpoints: {
+        data: "/api/data",
+        metadata: "/api/meta",
+        auth: "/api/auth"
+      }
+    };
+  }
+  async getMetaTypes(_request) {
+    return {
+      types: SchemaRegistry.getRegisteredTypes()
+    };
+  }
+  async getMetaItems(request) {
+    return {
+      type: request.type,
+      items: SchemaRegistry.listItems(request.type)
+    };
+  }
+  async getMetaItem(request) {
+    return {
+      type: request.type,
+      name: request.name,
+      item: SchemaRegistry.getItem(request.type, request.name)
+    };
+  }
+  async getUiView(request) {
+    const schema = SchemaRegistry.getObject(request.object);
+    if (!schema) throw new Error(`Object ${request.object} not found`);
+    let view;
+    if (request.type === "list") {
+      view = {
+        type: "list",
+        object: request.object,
+        columns: Object.keys(schema.fields || {}).slice(0, 5).map((f) => ({
+          field: f,
+          label: schema.fields[f].label || f
+        }))
+      };
+    } else {
+      view = {
+        type: "form",
+        object: request.object,
+        sections: [
+          {
+            label: "General",
+            fields: Object.keys(schema.fields || {}).map((f) => ({
+              field: f
+            }))
+          }
+        ]
+      };
+    }
+    return view;
+  }
+  async findData(request) {
+    const options = { ...request.query };
+    if (options.top) options.top = Number(options.top);
+    if (options.skip) options.skip = Number(options.skip);
+    if (options.limit) options.limit = Number(options.limit);
+    const records = await this.engine.find(request.object, options);
+    return {
+      object: request.object,
+      value: records,
+      // OData compaibility
+      records,
+      // Legacy
+      total: records.length,
+      hasMore: false
+    };
+  }
+  async getData(request) {
+    const result = await this.engine.findOne(request.object, {
+      filter: { _id: request.id }
+    });
+    if (result) {
+      return {
+        object: request.object,
+        id: request.id,
+        record: result
+      };
+    }
+    throw new Error(`Record ${request.id} not found in ${request.object}`);
+  }
+  async createData(request) {
+    const result = await this.engine.insert(request.object, request.data);
+    return {
+      object: request.object,
+      id: result._id || result.id,
+      record: result
+    };
+  }
+  async updateData(request) {
+    const result = await this.engine.update(request.object, request.data, { filter: { _id: request.id } });
+    return {
+      object: request.object,
+      id: request.id,
+      record: result
+    };
+  }
+  async deleteData(request) {
+    await this.engine.delete(request.object, { filter: { _id: request.id } });
+    return {
+      object: request.object,
+      id: request.id,
+      success: true
+    };
+  }
+  // ==========================================
+  // Metadata Caching
+  // ==========================================
+  async getMetaItemCached(request) {
+    try {
+      const item = SchemaRegistry.getItem(request.type, request.name);
+      if (!item) {
+        throw new Error(`Metadata item ${request.type}/${request.name} not found`);
+      }
+      const content = JSON.stringify(item);
+      const hash = simpleHash(content);
+      const etag = { value: hash, weak: false };
+      if (request.cacheRequest?.ifNoneMatch) {
+        const clientEtag = request.cacheRequest.ifNoneMatch.replace(/^"(.*)"$/, "$1").replace(/^W\/"(.*)"$/, "$1");
+        if (clientEtag === hash) {
+          return {
+            notModified: true,
+            etag
+          };
+        }
+      }
+      return {
+        data: item,
+        etag,
+        lastModified: (/* @__PURE__ */ new Date()).toISOString(),
+        cacheControl: {
+          directives: ["public", "max-age"],
+          maxAge: 3600
+          // 1 hour
+        },
+        notModified: false
+      };
+    } catch (error) {
+      throw error;
+    }
+  }
+  // ==========================================
+  // Batch Operations
+  // ==========================================
+  async batchData(_request) {
+    throw new Error("Batch operations not yet fully implemented in protocol adapter");
+  }
+  async createManyData(request) {
+    const records = await this.engine.insert(request.object, request.records);
+    return {
+      object: request.object,
+      records,
+      count: records.length
+    };
+  }
+  async updateManyData(_request) {
+    throw new Error("updateManyData not implemented");
+  }
+  async analyticsQuery(_request) {
+    throw new Error("analyticsQuery not implemented");
+  }
+  async getAnalyticsMeta(_request) {
+    throw new Error("getAnalyticsMeta not implemented");
+  }
+  async triggerAutomation(_request) {
+    throw new Error("triggerAutomation not implemented");
+  }
+  async listSpaces(_request) {
+    throw new Error("listSpaces not implemented");
+  }
+  async createSpace(_request) {
+    throw new Error("createSpace not implemented");
+  }
+  async installPlugin(_request) {
+    throw new Error("installPlugin not implemented");
+  }
+  async deleteManyData(request) {
+    return this.engine.delete(request.object, {
+      filter: { _id: { $in: request.ids } },
+      ...request.options
+    });
+  }
+  async saveMetaItem(request) {
+    if (!request.item) {
+      throw new Error("Item data is required");
+    }
+    SchemaRegistry.registerItem(request.type, request.item, "name");
+    return {
+      success: true,
+      message: "Saved to memory registry"
+    };
+  }
+};
+
+// src/engine.ts
+import { createLogger } from "@objectstack/core";
+import { CoreServiceName } from "@objectstack/spec/system";
+var ObjectQL = class {
+  constructor(hostContext = {}) {
+    this.drivers = /* @__PURE__ */ new Map();
+    this.defaultDriver = null;
+    // Hooks Registry
+    this.hooks = {
+      "beforeFind": [],
+      "afterFind": [],
+      "beforeInsert": [],
+      "afterInsert": [],
+      "beforeUpdate": [],
+      "afterUpdate": [],
+      "beforeDelete": [],
+      "afterDelete": []
+    };
+    // Host provided context additions (e.g. Server router)
+    this.hostContext = {};
+    this.hostContext = hostContext;
+    this.logger = hostContext.logger || createLogger({ level: "info", format: "pretty" });
+    this.logger.info("ObjectQL Engine Instance Created");
+  }
+  /**
+   * Service Status Report
+   * Used by Kernel to verify health and capabilities.
+   */
+  getStatus() {
+    return {
+      name: CoreServiceName.enum.data,
+      status: "running",
+      version: "0.9.0",
+      features: ["crud", "query", "aggregate", "transactions", "metadata"]
+    };
+  }
+  /**
+   * Expose the SchemaRegistry for plugins to register metadata
+   */
+  get registry() {
+    return SchemaRegistry;
+  }
+  /**
+   * Load and Register a Plugin
+   */
+  async use(manifestPart, runtimePart) {
+    this.logger.debug("Loading plugin", {
+      hasManifest: !!manifestPart,
+      hasRuntime: !!runtimePart
+    });
+    if (manifestPart) {
+      this.registerApp(manifestPart);
+    }
+    if (runtimePart) {
+      const pluginDef = runtimePart.default || runtimePart;
+      if (pluginDef.onEnable) {
+        this.logger.debug("Executing plugin runtime onEnable");
+        const context = {
+          ql: this,
+          logger: this.logger,
+          // Expose the driver registry helper explicitly if needed
+          drivers: {
+            register: (driver) => this.registerDriver(driver)
+          },
+          ...this.hostContext
+        };
+        await pluginDef.onEnable(context);
+        this.logger.debug("Plugin runtime onEnable completed");
+      }
+    }
+  }
+  /**
+   * Register a hook
+   * @param event The event name (e.g. 'beforeFind', 'afterInsert')
+   * @param handler The handler function
+   */
+  registerHook(event, handler) {
+    if (!this.hooks[event]) {
+      this.hooks[event] = [];
+    }
+    this.hooks[event].push(handler);
+    this.logger.debug("Registered hook", { event, totalHandlers: this.hooks[event].length });
+  }
+  async triggerHooks(event, context) {
+    const handlers = this.hooks[event] || [];
+    if (handlers.length === 0) {
+      this.logger.debug("No hooks registered for event", { event });
+      return;
+    }
+    this.logger.debug("Triggering hooks", { event, count: handlers.length });
+    for (const handler of handlers) {
+      await handler(context);
+    }
+  }
+  /**
+   * Register contribution (Manifest)
+   */
+  registerApp(manifest) {
+    const id = manifest.id;
+    this.logger.debug("Registering app manifest", { id });
+    if (manifest.objects) {
+      if (Array.isArray(manifest.objects)) {
+        this.logger.debug("Registering objects from manifest (Array)", { id, objectCount: manifest.objects.length });
+        for (const objDef of manifest.objects) {
+          SchemaRegistry.registerObject(objDef);
+          this.logger.debug("Registered Object", { object: objDef.name, from: id });
+        }
+      } else {
+        this.logger.debug("Registering objects from manifest (Map)", { id, objectCount: Object.keys(manifest.objects).length });
+        for (const [name, objDef] of Object.entries(manifest.objects)) {
+          objDef.name = name;
+          SchemaRegistry.registerObject(objDef);
+          this.logger.debug("Registered Object", { object: name, from: id });
+        }
+      }
+    }
+    if (manifest.contributes?.kinds) {
+      this.logger.debug("Registering kinds from manifest", { id, kindCount: manifest.contributes.kinds.length });
+      for (const kind of manifest.contributes.kinds) {
+        SchemaRegistry.registerKind(kind);
+        this.logger.debug("Registered Kind", { kind: kind.name || kind.type, from: id });
+      }
+    }
+  }
+  /**
+   * Register a new storage driver
+   */
+  registerDriver(driver, isDefault = false) {
+    if (this.drivers.has(driver.name)) {
+      this.logger.warn("Driver already registered, skipping", { driverName: driver.name });
+      return;
+    }
+    this.drivers.set(driver.name, driver);
+    this.logger.info("Registered driver", {
+      driverName: driver.name,
+      version: driver.version
+    });
+    if (isDefault || this.drivers.size === 1) {
+      this.defaultDriver = driver.name;
+      this.logger.info("Set default driver", { driverName: driver.name });
+    }
+  }
+  /**
+   * Helper to get object definition
+   */
+  getSchema(objectName) {
+    return SchemaRegistry.getObject(objectName);
+  }
+  /**
+   * Helper to get the target 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);
+        }
+        throw new Error(`[ObjectQL] Datasource '${datasourceName}' configured for object '${objectName}' is not registered.`);
+      }
+    }
+    if (this.defaultDriver) {
+      return this.drivers.get(this.defaultDriver);
+    }
+    throw new Error(`[ObjectQL] No driver available for object '${objectName}'`);
+  }
+  /**
+   * Initialize the engine and all registered drivers
+   */
+  async init() {
+    this.logger.info("Initializing ObjectQL engine", {
+      driverCount: this.drivers.size,
+      drivers: Array.from(this.drivers.keys())
+    });
+    for (const [name, driver] of this.drivers) {
+      try {
+        await driver.connect();
+        this.logger.info("Driver connected successfully", { driverName: name });
+      } catch (e) {
+        this.logger.error("Failed to connect driver", e, { driverName: name });
+      }
+    }
+    this.logger.info("ObjectQL engine initialization complete");
+  }
+  async destroy() {
+    this.logger.info("Destroying ObjectQL engine", { driverCount: this.drivers.size });
+    for (const [name, driver] of this.drivers.entries()) {
+      try {
+        await driver.disconnect();
+      } catch (e) {
+        this.logger.error("Error disconnecting driver", e, { driverName: name });
+      }
+    }
+    this.logger.info("ObjectQL engine destroyed");
+  }
+  // ============================================
+  // Helper: Query Conversion
+  // ============================================
+  toQueryAST(object, options) {
+    const ast = { object };
+    if (!options) return ast;
+    if (options.filter) {
+      ast.where = options.filter;
+    }
+    if (options.select) {
+      ast.fields = options.select;
+    }
+    if (options.sort) {
+      if (Array.isArray(options.sort)) {
+        ast.orderBy = options.sort;
+      } else {
+        ast.orderBy = Object.entries(options.sort).map(([field, order]) => ({
+          field,
+          order: order === -1 || order === "desc" ? "desc" : "asc"
+        }));
+      }
+    }
+    if (options.top !== void 0) ast.limit = options.top;
+    else if (options.limit !== void 0) ast.limit = options.limit;
+    if (options.skip !== void 0) ast.offset = options.skip;
+    return ast;
+  }
+  // ============================================
+  // Data Access Methods (IDataEngine Interface)
+  // ============================================
+  async find(object, query) {
+    this.logger.debug("Find operation starting", { object, query });
+    const driver = this.getDriver(object);
+    const ast = this.toQueryAST(object, query);
+    const hookContext = {
+      object,
+      event: "beforeFind",
+      input: { ast, options: void 0 },
+      // Should map options?
+      ql: this
+    };
+    await this.triggerHooks("beforeFind", hookContext);
+    try {
+      const result = await driver.find(object, hookContext.input.ast, hookContext.input.options);
+      hookContext.event = "afterFind";
+      hookContext.result = result;
+      await this.triggerHooks("afterFind", hookContext);
+      return hookContext.result;
+    } catch (e) {
+      this.logger.error("Find operation failed", e, { object });
+      throw e;
+    }
+  }
+  async findOne(objectName, query) {
+    this.logger.debug("FindOne operation", { objectName });
+    const driver = this.getDriver(objectName);
+    const ast = this.toQueryAST(objectName, query);
+    ast.limit = 1;
+    return driver.findOne(objectName, ast);
+  }
+  async insert(object, data, options) {
+    this.logger.debug("Insert operation starting", { object, isBatch: Array.isArray(data) });
+    const driver = this.getDriver(object);
+    const hookContext = {
+      object,
+      event: "beforeInsert",
+      input: { data, options },
+      ql: this
+    };
+    await this.triggerHooks("beforeInsert", hookContext);
+    try {
+      let result;
+      if (Array.isArray(hookContext.input.data)) {
+        if (driver.bulkCreate) {
+          result = await driver.bulkCreate(object, hookContext.input.data, hookContext.input.options);
+        } else {
+          result = await Promise.all(hookContext.input.data.map((item) => driver.create(object, item, hookContext.input.options)));
+        }
+      } else {
+        result = await driver.create(object, hookContext.input.data, hookContext.input.options);
+      }
+      hookContext.event = "afterInsert";
+      hookContext.result = result;
+      await this.triggerHooks("afterInsert", hookContext);
+      return hookContext.result;
+    } catch (e) {
+      this.logger.error("Insert operation failed", e, { object });
+      throw e;
+    }
+  }
+  async update(object, data, options) {
+    this.logger.debug("Update operation starting", { object });
+    const driver = this.getDriver(object);
+    let id = data.id || data._id;
+    if (!id && options?.filter) {
+      if (typeof options.filter === "string") id = options.filter;
+      else if (options.filter._id) id = options.filter._id;
+      else if (options.filter.id) id = options.filter.id;
+    }
+    const hookContext = {
+      object,
+      event: "beforeUpdate",
+      input: { id, data, options },
+      ql: this
+    };
+    await this.triggerHooks("beforeUpdate", hookContext);
+    try {
+      let result;
+      if (hookContext.input.id) {
+        result = await driver.update(object, hookContext.input.id, hookContext.input.data, hookContext.input.options);
+      } else if (options?.multi && driver.updateMany) {
+        const ast = this.toQueryAST(object, { filter: options.filter });
+        result = await driver.updateMany(object, ast, hookContext.input.data, hookContext.input.options);
+      } else {
+        throw new Error("Update requires an ID or options.multi=true");
+      }
+      hookContext.event = "afterUpdate";
+      hookContext.result = result;
+      await this.triggerHooks("afterUpdate", hookContext);
+      return hookContext.result;
+    } catch (e) {
+      this.logger.error("Update operation failed", e, { object });
+      throw e;
+    }
+  }
+  async delete(object, options) {
+    this.logger.debug("Delete operation starting", { object });
+    const driver = this.getDriver(object);
+    let id = void 0;
+    if (options?.filter) {
+      if (typeof options.filter === "string") id = options.filter;
+      else if (options.filter._id) id = options.filter._id;
+      else if (options.filter.id) id = options.filter.id;
+    }
+    const hookContext = {
+      object,
+      event: "beforeDelete",
+      input: { id, options },
+      ql: this
+    };
+    await this.triggerHooks("beforeDelete", hookContext);
+    try {
+      let result;
+      if (hookContext.input.id) {
+        result = await driver.delete(object, hookContext.input.id, hookContext.input.options);
+      } else if (options?.multi && driver.deleteMany) {
+        const ast = this.toQueryAST(object, { filter: options.filter });
+        result = await driver.deleteMany(object, ast, hookContext.input.options);
+      } else {
+        throw new Error("Delete requires an ID or options.multi=true");
+      }
+      hookContext.event = "afterDelete";
+      hookContext.result = result;
+      await this.triggerHooks("afterDelete", hookContext);
+      return hookContext.result;
+    } catch (e) {
+      this.logger.error("Delete operation failed", e, { object });
+      throw e;
+    }
+  }
+  async count(object, query) {
+    const driver = this.getDriver(object);
+    if (driver.count) {
+      const ast = this.toQueryAST(object, { filter: query?.filter });
+      return driver.count(object, ast);
+    }
+    const res = await this.find(object, { filter: query?.filter, select: ["_id"] });
+    return res.length;
+  }
+  async aggregate(object, query) {
+    const driver = this.getDriver(object);
+    this.logger.debug(`Aggregate on ${object} using ${driver.name}`, query);
+    throw new Error("Aggregate not yet fully implemented in ObjectQL->Driver mapping");
+  }
+  async execute(command, options) {
+    if (options?.object) {
+      const driver = this.getDriver(options.object);
+      if (driver.execute) {
+        return driver.execute(command, void 0, options);
+      }
+    }
+    throw new Error("Execute requires options.object to select driver");
+  }
+};
+
+// src/plugin.ts
+var ObjectQLPlugin = class {
+  constructor(ql, hostContext) {
+    this.name = "com.objectstack.engine.objectql";
+    this.type = "objectql";
+    this.version = "1.0.0";
+    this.init = async (ctx) => {
+      if (!this.ql) {
+        this.ql = new ObjectQL(this.hostContext);
+      }
+      ctx.registerService("objectql", this.ql);
+      ctx.registerService("metadata", this.ql);
+      ctx.registerService("data", this.ql);
+      ctx.registerService("auth", this.ql);
+      ctx.logger.info("ObjectQL engine registered as service", {
+        provides: ["objectql", "metadata", "data", "auth"]
+      });
+      const protocolShim = new ObjectStackProtocolImplementation(this.ql);
+      ctx.registerService("protocol", protocolShim);
+      ctx.logger.info("Protocol service registered");
+    };
+    this.start = async (ctx) => {
+      ctx.logger.info("ObjectQL engine initialized");
+      if (ctx.getServices && this.ql) {
+        const services = ctx.getServices();
+        for (const [name, service] of services.entries()) {
+          if (name.startsWith("driver.")) {
+            this.ql.registerDriver(service);
+            ctx.logger.debug("Discovered and registered driver service", { serviceName: name });
+          }
+          if (name.startsWith("app.")) {
+            this.ql.registerApp(service);
+            ctx.logger.debug("Discovered and registered app service", { serviceName: name });
+          }
+        }
+      }
+    };
+    if (ql) {
+      this.ql = ql;
+    } else {
+      this.hostContext = hostContext;
+    }
+  }
+};
+export {
+  ObjectQL,
+  ObjectQLPlugin,
+  ObjectStackProtocolImplementation,
+  SchemaRegistry
+};
+//# sourceMappingURL=index.mjs.map