@objectstack/objectql 3.0.11 → 3.1.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @objectstack/objectql@3.0.11 build /home/runner/work/spec/spec/packages/objectql
+> @objectstack/objectql@3.1.0 build /home/runner/work/spec/spec/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     90.75 KB
-CJS dist/index.js.map 184.04 KB
-CJS ⚡️ Build success in 144ms
-ESM dist/index.mjs     89.01 KB
-ESM dist/index.mjs.map 182.74 KB
-ESM ⚡️ Build success in 151ms
+CJS dist/index.js     95.52 KB
+CJS dist/index.js.map 193.28 KB
+CJS ⚡️ Build success in 187ms
+ESM dist/index.mjs     93.78 KB
+ESM dist/index.mjs.map 191.98 KB
+ESM ⚡️ Build success in 191ms
 DTS Build start
-DTS ⚡️ Build success in 11115ms
-DTS dist/index.d.mts 73.43 KB
-DTS dist/index.d.ts  73.43 KB
+DTS ⚡️ Build success in 23689ms
+DTS dist/index.d.mts 74.26 KB
+DTS dist/index.d.ts  74.26 KB

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @objectstack/objectql
 
+## 3.1.0
+
+### Patch Changes
+
+- Updated dependencies [0088830]
+  - @objectstack/spec@3.1.0
+  - @objectstack/core@3.1.0
+  - @objectstack/types@3.1.0
+
 ## 3.0.11
 
 ### Patch Changes

package/dist/index.d.mts

@@ -1329,6 +1329,8 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     getData(request: {
         object: string;
         id: string;
+        expand?: string | string[];
+        select?: string | string[];
     }): Promise<{
         object: string;
         id: string;
@@ -1569,6 +1571,21 @@ declare class ObjectQL implements IDataEngine {
      */
     init(): Promise<void>;
     destroy(): Promise<void>;
+    /** Maximum depth for recursive expand to prevent infinite loops */
+    private static readonly MAX_EXPAND_DEPTH;
+    /**
+     * Post-process expand: resolve lookup/master_detail fields by batch-loading related records.
+     *
+     * This is a driver-agnostic implementation that uses secondary queries ($in batches)
+     * to load related records, then injects them into the result set.
+     *
+     * @param objectName - The source object name
+     * @param records - The records returned by the driver
+     * @param expand - The expand map from QueryAST (field name → nested QueryAST)
+     * @param depth - Current recursion depth (0-based)
+     * @returns Records with expanded lookup fields (IDs replaced by full objects)
+     */
+    private expandRelatedRecords;
     private toQueryAST;
     find(object: string, query?: DataEngineQueryOptions): Promise<any[]>;
     findOne(objectName: string, query?: DataEngineQueryOptions): Promise<any>;

package/dist/index.d.ts

@@ -1329,6 +1329,8 @@ declare class ObjectStackProtocolImplementation implements ObjectStackProtocol {
     getData(request: {
         object: string;
         id: string;
+        expand?: string | string[];
+        select?: string | string[];
     }): Promise<{
         object: string;
         id: string;
@@ -1569,6 +1571,21 @@ declare class ObjectQL implements IDataEngine {
      */
     init(): Promise<void>;
     destroy(): Promise<void>;
+    /** Maximum depth for recursive expand to prevent infinite loops */
+    private static readonly MAX_EXPAND_DEPTH;
+    /**
+     * Post-process expand: resolve lookup/master_detail fields by batch-loading related records.
+     *
+     * This is a driver-agnostic implementation that uses secondary queries ($in batches)
+     * to load related records, then injects them into the result set.
+     *
+     * @param objectName - The source object name
+     * @param records - The records returned by the driver
+     * @param expand - The expand map from QueryAST (field name → nested QueryAST)
+     * @param depth - Current recursion depth (0-based)
+     * @returns Records with expanded lookup fields (IDs replaced by full objects)
+     */
+    private expandRelatedRecords;
     private toQueryAST;
     find(object: string, query?: DataEngineQueryOptions): Promise<any[]>;
     findOne(objectName: string, query?: DataEngineQueryOptions): Promise<any>;

package/dist/index.js

@@ -774,6 +774,16 @@ var ObjectStackProtocolImplementation = class {
     if (typeof options.populate === "string") {
       options.populate = options.populate.split(",").map((s) => s.trim()).filter(Boolean);
     }
+    const expandValue = options.$expand ?? options.expand;
+    if (expandValue && !options.populate) {
+      if (typeof expandValue === "string") {
+        options.populate = expandValue.split(",").map((s) => s.trim()).filter(Boolean);
+      } else if (Array.isArray(expandValue)) {
+        options.populate = expandValue;
+      }
+    }
+    delete options.$expand;
+    delete options.expand;
     for (const key of ["distinct", "count"]) {
       if (options[key] === "true") options[key] = true;
       else if (options[key] === "false") options[key] = false;
@@ -790,9 +800,16 @@ var ObjectStackProtocolImplementation = class {
     };
   }
   async getData(request) {
-    const result = await this.engine.findOne(request.object, {
+    const queryOptions = {
       filter: { _id: request.id }
-    });
+    };
+    if (request.select) {
+      queryOptions.select = typeof request.select === "string" ? request.select.split(",").map((s) => s.trim()).filter(Boolean) : request.select;
+    }
+    if (request.expand) {
+      queryOptions.populate = typeof request.expand === "string" ? request.expand.split(",").map((s) => s.trim()).filter(Boolean) : request.expand;
+    }
+    const result = await this.engine.findOne(request.object, queryOptions);
     if (result) {
       return {
         object: request.object,
@@ -1270,7 +1287,7 @@ var ObjectStackProtocolImplementation = class {
 var import_kernel2 = require("@objectstack/spec/kernel");
 var import_core = require("@objectstack/core");
 var import_system = require("@objectstack/spec/system");
-var ObjectQL = class _ObjectQL {
+var _ObjectQL = class _ObjectQL {
   constructor(hostContext = {}) {
     this.drivers = /* @__PURE__ */ new Map();
     this.defaultDriver = null;
@@ -1765,6 +1782,89 @@ var ObjectQL = class _ObjectQL {
     }
     this.logger.info("ObjectQL engine destroyed");
   }
+  /**
+   * Post-process expand: resolve lookup/master_detail fields by batch-loading related records.
+   * 
+   * This is a driver-agnostic implementation that uses secondary queries ($in batches)
+   * to load related records, then injects them into the result set.
+   * 
+   * @param objectName - The source object name
+   * @param records - The records returned by the driver
+   * @param expand - The expand map from QueryAST (field name → nested QueryAST)
+   * @param depth - Current recursion depth (0-based)
+   * @returns Records with expanded lookup fields (IDs replaced by full objects)
+   */
+  async expandRelatedRecords(objectName, records, expand, depth = 0) {
+    if (!records || records.length === 0) return records;
+    if (depth >= _ObjectQL.MAX_EXPAND_DEPTH) return records;
+    const objectSchema = SchemaRegistry.getObject(objectName);
+    if (!objectSchema || !objectSchema.fields) return records;
+    for (const [fieldName, nestedAST] of Object.entries(expand)) {
+      const fieldDef = objectSchema.fields[fieldName];
+      if (!fieldDef || !fieldDef.reference) continue;
+      if (fieldDef.type !== "lookup" && fieldDef.type !== "master_detail") continue;
+      const referenceObject = fieldDef.reference;
+      const allIds = [];
+      for (const record of records) {
+        const val = record[fieldName];
+        if (val == null) continue;
+        if (Array.isArray(val)) {
+          allIds.push(...val.filter((id) => id != null));
+        } else if (typeof val === "object") {
+          continue;
+        } else {
+          allIds.push(val);
+        }
+      }
+      const uniqueIds = [...new Set(allIds)];
+      if (uniqueIds.length === 0) continue;
+      try {
+        const relatedQuery = {
+          object: referenceObject,
+          where: { _id: { $in: uniqueIds } },
+          ...nestedAST.fields ? { fields: nestedAST.fields } : {},
+          ...nestedAST.orderBy ? { orderBy: nestedAST.orderBy } : {}
+        };
+        const driver = this.getDriver(referenceObject);
+        const relatedRecords = await driver.find(referenceObject, relatedQuery) ?? [];
+        const recordMap = /* @__PURE__ */ new Map();
+        for (const rec of relatedRecords) {
+          const id = rec._id ?? rec.id;
+          if (id != null) recordMap.set(String(id), rec);
+        }
+        if (nestedAST.expand && Object.keys(nestedAST.expand).length > 0) {
+          const expandedRelated = await this.expandRelatedRecords(
+            referenceObject,
+            relatedRecords,
+            nestedAST.expand,
+            depth + 1
+          );
+          recordMap.clear();
+          for (const rec of expandedRelated) {
+            const id = rec._id ?? rec.id;
+            if (id != null) recordMap.set(String(id), rec);
+          }
+        }
+        for (const record of records) {
+          const val = record[fieldName];
+          if (val == null) continue;
+          if (Array.isArray(val)) {
+            record[fieldName] = val.map((id) => recordMap.get(String(id)) ?? id);
+          } else if (typeof val !== "object") {
+            record[fieldName] = recordMap.get(String(val)) ?? val;
+          }
+        }
+      } catch (e) {
+        this.logger.warn("Failed to expand relationship field; retaining foreign key IDs", {
+          object: objectName,
+          field: fieldName,
+          reference: referenceObject,
+          error: e.message
+        });
+      }
+    }
+    return records;
+  }
   // ============================================
   // Helper: Query Conversion
   // ============================================
@@ -1824,7 +1924,10 @@ var ObjectQL = class _ObjectQL {
       };
       await this.triggerHooks("beforeFind", hookContext);
       try {
-        const result = await driver.find(object, hookContext.input.ast, hookContext.input.options);
+        let result = await driver.find(object, hookContext.input.ast, hookContext.input.options);
+        if (ast.expand && Object.keys(ast.expand).length > 0 && Array.isArray(result)) {
+          result = await this.expandRelatedRecords(object, result, ast.expand, 0);
+        }
         hookContext.event = "afterFind";
         hookContext.result = result;
         await this.triggerHooks("afterFind", hookContext);
@@ -1850,7 +1953,12 @@ var ObjectQL = class _ObjectQL {
       context: query?.context
     };
     await this.executeWithMiddleware(opCtx, async () => {
-      return driver.findOne(objectName, opCtx.ast);
+      let result = await driver.findOne(objectName, opCtx.ast);
+      if (ast.expand && Object.keys(ast.expand).length > 0 && result != null) {
+        const expanded = await this.expandRelatedRecords(objectName, [result], ast.expand, 0);
+        result = expanded[0];
+      }
+      return result;
     });
     return opCtx.result;
   }
@@ -2199,6 +2307,12 @@ var ObjectQL = class _ObjectQL {
     return ql;
   }
 };
+// ============================================
+// Helper: Expand Related Records
+// ============================================
+/** Maximum depth for recursive expand to prevent infinite loops */
+_ObjectQL.MAX_EXPAND_DEPTH = 3;
+var ObjectQL = _ObjectQL;
 var ObjectRepository = class {
   constructor(objectName, context, engine) {
     this.objectName = objectName;