@objectstack/objectql 3.3.0 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/objectql",
-  "version": "3.3.0",
+  "version": "4.0.0",
   "license": "Apache-2.0",
   "description": "Isomorphic ObjectQL Engine for ObjectStack",
   "main": "dist/index.js",
@@ -13,13 +13,13 @@
     }
   },
   "dependencies": {
-    "@objectstack/core": "3.3.0",
-    "@objectstack/spec": "3.3.0",
-    "@objectstack/types": "3.3.0"
+    "@objectstack/core": "4.0.0",
+    "@objectstack/spec": "4.0.0",
+    "@objectstack/types": "4.0.0"
   },
   "devDependencies": {
-    "typescript": "^5.0.0",
-    "vitest": "^4.1.0"
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
   },
   "scripts": {
     "build": "tsup --config ../../tsup.config.ts",

package/src/engine.test.ts

@@ -248,7 +248,7 @@ describe('ObjectQL Engine', () => {
                     { id: 'u2', name: 'Bob' },
                 ]);
 
-            const result = await engine.find('task', { populate: ['assignee'] });
+            const result = await engine.find('task', { expand: { assignee: { object: 'assignee' } } });
 
             expect(result).toHaveLength(2);
             expect(result[0].assignee).toEqual({ id: 'u1', name: 'Alice' });
@@ -288,7 +288,7 @@ describe('ObjectQL Engine', () => {
                     { id: 'o1', total: 100 },
                 ]);
 
-            const result = await engine.find('order_item', { populate: ['order'] });
+            const result = await engine.find('order_item', { expand: { order: { object: 'order' } } });
             expect(result[0].order).toEqual({ id: 'o1', total: 100 });
         });
 
@@ -304,7 +304,7 @@ describe('ObjectQL Engine', () => {
                 { id: 't1', title: 'Task 1' },
             ]);
 
-            const result = await engine.find('task', { populate: ['title'] });
+            const result = await engine.find('task', { expand: { title: { object: 'title' } } });
             expect(result[0].title).toBe('Task 1'); // Unchanged
             expect(mockDriver.find).toHaveBeenCalledTimes(1); // No expand query
         });
@@ -316,7 +316,7 @@ describe('ObjectQL Engine', () => {
                 { id: 't1', assignee: 'u1' },
             ]);
 
-            const result = await engine.find('task', { populate: ['assignee'] });
+            const result = await engine.find('task', { expand: { assignee: { object: 'assignee' } } });
             expect(result[0].assignee).toBe('u1'); // Unchanged — raw ID
             expect(mockDriver.find).toHaveBeenCalledTimes(1);
         });
@@ -345,7 +345,7 @@ describe('ObjectQL Engine', () => {
                     { id: 'u1', name: 'Alice' },
                 ]);
 
-            const result = await engine.find('task', { populate: ['assignee'] });
+            const result = await engine.find('task', { expand: { assignee: { object: 'assignee' } } });
             expect(result[0].assignee).toBeNull();
             expect(result[1].assignee).toEqual({ id: 'u1', name: 'Alice' });
         });
@@ -376,7 +376,7 @@ describe('ObjectQL Engine', () => {
                     { id: 'u2', name: 'Bob' },
                 ]);
 
-            const result = await engine.find('task', { populate: ['assignee'] });
+            const result = await engine.find('task', { expand: { assignee: { object: 'assignee' } } });
 
             // Verify only 2 unique IDs queried
             expect(mockDriver.find).toHaveBeenLastCalledWith(
@@ -410,7 +410,7 @@ describe('ObjectQL Engine', () => {
                 ])
                 .mockResolvedValueOnce([]); // No records found
 
-            const result = await engine.find('task', { populate: ['assignee'] });
+            const result = await engine.find('task', { expand: { assignee: { object: 'assignee' } } });
             expect(result[0].assignee).toBe('u_deleted'); // Fallback to raw ID
         });
 
@@ -441,7 +441,7 @@ describe('ObjectQL Engine', () => {
                 .mockResolvedValueOnce([{ id: 'u1', name: 'Alice' }])
                 .mockResolvedValueOnce([{ id: 'p1', name: 'Project X' }]);
 
-            const result = await engine.find('task', { populate: ['assignee', 'project'] });
+            const result = await engine.find('task', { expand: { assignee: { object: 'assignee' }, project: { object: 'project' } } });
 
             expect(result[0].assignee).toEqual({ id: 'u1', name: 'Alice' });
             expect(result[0].project).toEqual({ id: 'p1', name: 'Project X' });
@@ -470,7 +470,7 @@ describe('ObjectQL Engine', () => {
                 { id: 'u1', name: 'Alice' },
             ]);
 
-            const result = await engine.findOne('task', { populate: ['assignee'] });
+            const result = await engine.findOne('task', { expand: { assignee: { object: 'assignee' } } });
 
             expect(result.assignee).toEqual({ id: 'u1', name: 'Alice' });
         });
@@ -495,7 +495,7 @@ describe('ObjectQL Engine', () => {
                 { id: 't1', assignee: { id: 'u1', name: 'Alice' } },
             ]);
 
-            const result = await engine.find('task', { populate: ['assignee'] });
+            const result = await engine.find('task', { expand: { assignee: { object: 'assignee' } } });
 
             // No expand query should have been made — the value was already an object
             expect(mockDriver.find).toHaveBeenCalledTimes(1);
@@ -523,7 +523,7 @@ describe('ObjectQL Engine', () => {
                 ])
                 .mockRejectedValueOnce(new Error('Driver connection failed'));
 
-            const result = await engine.find('task', { populate: ['assignee'] });
+            const result = await engine.find('task', { expand: { assignee: { object: 'assignee' } } });
             expect(result[0].assignee).toBe('u1'); // Kept raw ID
         });
 
@@ -551,7 +551,7 @@ describe('ObjectQL Engine', () => {
                     { id: 'u2', name: 'Bob' },
                 ]);
 
-            const result = await engine.find('task', { populate: ['watchers'] });
+            const result = await engine.find('task', { expand: { watchers: { object: 'watchers' } } });
             expect(result[0].watchers).toEqual([
                 { id: 'u1', name: 'Alice' },
                 { id: 'u2', name: 'Bob' },
@@ -574,7 +574,7 @@ describe('ObjectQL Engine', () => {
                 .mockResolvedValueOnce([{ id: 'p1', org: 'o1' }]);     // expand project (depth 0)
                 // org should NOT be expanded further — flat populate doesn't create nested expand
 
-            const result = await engine.find('task', { populate: ['project'] });
+            const result = await engine.find('task', { expand: { project: { object: 'project' } } });
 
             // Project expanded, but org inside project remains as raw ID
             expect(result[0].project).toEqual({ id: 'p1', org: 'o1' });

package/src/engine.ts

@@ -2,12 +2,12 @@
 
 import { QueryAST, HookContext, ServiceObject } from '@objectstack/spec/data';
 import { 
-  DataEngineQueryOptions, 
+  EngineQueryOptions,
   DataEngineInsertOptions, 
-  DataEngineUpdateOptions, 
-  DataEngineDeleteOptions,
-  DataEngineAggregateOptions,
-  DataEngineCountOptions 
+  EngineUpdateOptions, 
+  EngineDeleteOptions,
+  EngineAggregateOptions,
+  EngineCountOptions 
 } from '@objectstack/spec/data';
 import { ExecutionContext, ExecutionContextSchema } from '@objectstack/spec/kernel';
 import { DriverInterface, IDataEngine, Logger, createLogger } from '@objectstack/core';
@@ -741,59 +741,22 @@ export class ObjectQL implements IDataEngine {
     return records;
   }
 
-  // ============================================
-  // Helper: Query Conversion
-  // ============================================
-
-  private toQueryAST(object: string, options?: DataEngineQueryOptions): QueryAST {
-    const ast: QueryAST = { object };
-    if (!options) return ast;
-
-    if (options.filter) {
-      ast.where = options.filter;
-    }
-    if (options.select) {
-      ast.fields = options.select;
-    }
-    if (options.sort) {
-       // Support DataEngineSortSchema variant
-       if (Array.isArray(options.sort)) {
-           // [{ field: 'a', order: 'asc' }]
-           ast.orderBy = options.sort; 
-       } else {
-           // Record<string, 'asc' | 'desc' | 1 | -1>
-           ast.orderBy = Object.entries(options.sort).map(([field, order]) => ({
-             field,
-             order: (order === -1 || order === 'desc') ? 'desc' : 'asc'
-           }));
-       }
-    }
-    
-    if (options.top !== undefined) ast.limit = options.top;
-    else if (options.limit !== undefined) ast.limit = options.limit;
-    
-    if (options.skip !== undefined) ast.offset = options.skip;
-
-    // Map populate (relationship field names) to QueryAST expand entries
-    if (options.populate && options.populate.length > 0) {
-      ast.expand = {};
-      for (const rel of options.populate) {
-        ast.expand[rel] = { object: rel };
-      }
-    }
-
-    return ast;
-  }
-
   // ============================================
   // Data Access Methods (IDataEngine Interface)
   // ============================================
 
-  async find(object: string, query?: DataEngineQueryOptions): Promise<any[]> {
+  async find(object: string, query?: EngineQueryOptions): Promise<any[]> {
     object = this.resolveObjectName(object);
     this.logger.debug('Find operation starting', { object, query });
     const driver = this.getDriver(object);
-    const ast = this.toQueryAST(object, query);
+    const ast: QueryAST = { object, ...query };
+    // Remove context from the AST — it's not a driver concern
+    delete (ast as any).context;
+    // Normalize OData `top` alias → standard `limit`
+    if ((ast as any).top != null && ast.limit == null) {
+      ast.limit = (ast as any).top;
+    }
+    delete (ast as any).top;
 
     const opCtx: OperationContext = {
       object,
@@ -836,12 +799,14 @@ export class ObjectQL implements IDataEngine {
     return opCtx.result as any[];
   }
 
-  async findOne(objectName: string, query?: DataEngineQueryOptions): Promise<any> {
+  async findOne(objectName: string, query?: EngineQueryOptions): Promise<any> {
     objectName = this.resolveObjectName(objectName);
     this.logger.debug('FindOne operation', { objectName });
     const driver = this.getDriver(objectName);
-    const ast = this.toQueryAST(objectName, query);
-    ast.limit = 1;
+    const ast: QueryAST = { object: objectName, ...query, limit: 1 };
+    // Remove context and top alias from the AST
+    delete (ast as any).context;
+    delete (ast as any).top;
 
     const opCtx: OperationContext = {
       object: objectName,
@@ -918,16 +883,15 @@ export class ObjectQL implements IDataEngine {
     return opCtx.result;
   }
 
-  async update(object: string, data: any, options?: DataEngineUpdateOptions): Promise<any> {
+  async update(object: string, data: any, options?: EngineUpdateOptions): Promise<any> {
      object = this.resolveObjectName(object);
      this.logger.debug('Update operation starting', { object });
      const driver = this.getDriver(object);
      
-     // 1. Extract ID from data or filter if it's a single update by ID
+     // 1. Extract ID from data or where if it's a single update by ID
      let id = data.id;
-     if (!id && options?.filter) {
-         if (typeof options.filter === 'string') id = options.filter;
-         else if (options.filter.id) id = options.filter.id;
+     if (!id && options?.where && typeof options.where === 'object' && 'id' in options.where) {
+         id = (options.where as Record<string, unknown>).id;
      }
 
      const opCtx: OperationContext = {
@@ -954,7 +918,7 @@ export class ObjectQL implements IDataEngine {
            if (hookContext.input.id) {
                result = await driver.update(object, hookContext.input.id as string, hookContext.input.data as Record<string, unknown>, hookContext.input.options as any);
            } else if (options?.multi && driver.updateMany) {
-               const ast = this.toQueryAST(object, { filter: options.filter });
+               const ast: QueryAST = { object, where: options.where };
                result = await driver.updateMany(object, ast, hookContext.input.data as Record<string, unknown>, hookContext.input.options as any);
            } else {
                throw new Error('Update requires an ID or options.multi=true');
@@ -973,16 +937,15 @@ export class ObjectQL implements IDataEngine {
      return opCtx.result;
   }
 
-  async delete(object: string, options?: DataEngineDeleteOptions): Promise<any> {
+  async delete(object: string, options?: EngineDeleteOptions): Promise<any> {
     object = this.resolveObjectName(object);
     this.logger.debug('Delete operation starting', { object });
     const driver = this.getDriver(object);
 
     // Extract ID logic similar to update
     let id: any = undefined;
-    if (options?.filter) {
-         if (typeof options.filter === 'string') id = options.filter;
-         else if (options.filter.id) id = options.filter.id;
+    if (options?.where && typeof options.where === 'object' && 'id' in options.where) {
+        id = (options.where as Record<string, unknown>).id;
     }
 
     const opCtx: OperationContext = {
@@ -1008,7 +971,7 @@ export class ObjectQL implements IDataEngine {
           if (hookContext.input.id) {
               result = await driver.delete(object, hookContext.input.id as string, hookContext.input.options as any);
           } else if (options?.multi && driver.deleteMany) {
-               const ast = this.toQueryAST(object, { filter: options.filter });
+               const ast: QueryAST = { object, where: options.where };
                result = await driver.deleteMany(object, ast, hookContext.input.options as any);
           } else {
                throw new Error('Delete requires an ID or options.multi=true');
@@ -1027,7 +990,7 @@ export class ObjectQL implements IDataEngine {
     return opCtx.result;
   }
 
-  async count(object: string, query?: DataEngineCountOptions): Promise<number> {
+  async count(object: string, query?: EngineCountOptions): Promise<number> {
      object = this.resolveObjectName(object);
      const driver = this.getDriver(object);
 
@@ -1040,18 +1003,18 @@ export class ObjectQL implements IDataEngine {
 
      await this.executeWithMiddleware(opCtx, async () => {
        if (driver.count) {
-           const ast = this.toQueryAST(object, { filter: query?.filter });
+           const ast: QueryAST = { object, where: query?.where };
            return driver.count(object, ast);
        }
        // Fallback to find().length
-       const res = await this.find(object, { filter: query?.filter, select: ['id'] });
+       const res = await this.find(object, { where: query?.where, fields: ['id'] });
        return res.length;
      });
 
      return opCtx.result as number;
   }
 
-  async aggregate(object: string, query: DataEngineAggregateOptions): Promise<any[]> {
+  async aggregate(object: string, query: EngineAggregateOptions): Promise<any[]> {
       object = this.resolveObjectName(object);
       const driver = this.getDriver(object);
       this.logger.debug(`Aggregate on ${object} using ${driver.name}`, query);
@@ -1066,13 +1029,9 @@ export class ObjectQL implements IDataEngine {
       await this.executeWithMiddleware(opCtx, async () => {
         const ast: QueryAST = {
             object,
-            where: query.filter,
+            where: query.where,
             groupBy: query.groupBy,
-            aggregations: query.aggregations?.map(agg => ({
-                function: agg.method,
-                field: agg.field,
-                alias: agg.alias || `${agg.method}_${agg.field || 'all'}`,
-            })),
+            aggregations: query.aggregations,
         };
 
         return driver.find(object, ast);
@@ -1355,7 +1314,7 @@ export class ObjectRepository {
   /** Update a single record by ID */
   async updateById(id: string | number, data: any): Promise<any> {
     return this.engine.update(this.objectName, { ...data, id: id }, {
-      filter: { id: id },
+      where: { id: id },
       context: this.context,
     });
   }
@@ -1370,7 +1329,7 @@ export class ObjectRepository {
   /** Delete a single record by ID */
   async deleteById(id: string | number): Promise<any> {
     return this.engine.delete(this.objectName, {
-      filter: { id: id },
+      where: { id: id },
       context: this.context,
     });
   }

package/src/plugin.integration.test.ts

@@ -547,5 +547,217 @@ describe('ObjectQLPlugin - Metadata Service Integration', () => {
       expect(syncedNames).not.toContain('sys__user');
       expect(syncedNames).not.toContain('sys__session');
     });
+
+    it('should use syncSchemasBatch when driver supports batchSchemaSync', async () => {
+      // Arrange - driver that supports batch schema sync
+      const batchCalls: Array<{ object: string; schema: any }[]> = [];
+      const singleCalls: Array<{ object: string; schema: any }> = [];
+      const mockDriver = {
+        name: 'batch-driver',
+        version: '1.0.0',
+        supports: { batchSchemaSync: true },
+        connect: async () => {},
+        disconnect: async () => {},
+        find: async () => [],
+        findOne: async () => null,
+        create: async (_o: string, d: any) => d,
+        update: async (_o: string, _i: any, d: any) => d,
+        delete: async () => true,
+        syncSchema: async (object: string, schema: any) => {
+          singleCalls.push({ object, schema });
+        },
+        syncSchemasBatch: async (schemas: Array<{ object: string; schema: any }>) => {
+          batchCalls.push(schemas);
+        },
+      };
+
+      await kernel.use({
+        name: 'mock-batch-driver-plugin',
+        type: 'driver',
+        version: '1.0.0',
+        init: async (ctx) => {
+          ctx.registerService('driver.batch', mockDriver);
+        },
+      });
+
+      const appManifest = {
+        id: 'com.test.batchapp',
+        name: 'batchapp',
+        namespace: 'bat',
+        version: '1.0.0',
+        objects: [
+          {
+            name: 'alpha',
+            label: 'Alpha',
+            fields: { a: { name: 'a', label: 'A', type: 'text' } },
+          },
+          {
+            name: 'beta',
+            label: 'Beta',
+            fields: { b: { name: 'b', label: 'B', type: 'text' } },
+          },
+          {
+            name: 'gamma',
+            label: 'Gamma',
+            fields: { c: { name: 'c', label: 'C', type: 'text' } },
+          },
+        ],
+      };
+
+      await kernel.use({
+        name: 'mock-batch-app-plugin',
+        type: 'app',
+        version: '1.0.0',
+        init: async (ctx) => {
+          ctx.registerService('app.batchapp', appManifest);
+        },
+      });
+
+      const plugin = new ObjectQLPlugin();
+      await kernel.use(plugin);
+
+      // Act
+      await kernel.bootstrap();
+
+      // Assert - syncSchemasBatch should have been called once with all objects
+      expect(batchCalls.length).toBe(1);
+      const batchedObjects = batchCalls[0].map((s) => s.object).sort();
+      expect(batchedObjects).toContain('bat__alpha');
+      expect(batchedObjects).toContain('bat__beta');
+      expect(batchedObjects).toContain('bat__gamma');
+      // syncSchema should NOT have been called individually
+      expect(singleCalls.length).toBe(0);
+    });
+
+    it('should fall back to sequential syncSchema when batch fails', async () => {
+      // Arrange - driver where batch fails
+      const singleCalls: Array<{ object: string; schema: any }> = [];
+      const mockDriver = {
+        name: 'fallback-driver',
+        version: '1.0.0',
+        supports: { batchSchemaSync: true },
+        connect: async () => {},
+        disconnect: async () => {},
+        find: async () => [],
+        findOne: async () => null,
+        create: async (_o: string, d: any) => d,
+        update: async (_o: string, _i: any, d: any) => d,
+        delete: async () => true,
+        syncSchema: async (object: string, schema: any) => {
+          singleCalls.push({ object, schema });
+        },
+        syncSchemasBatch: async () => {
+          throw new Error('batch not supported at runtime');
+        },
+      };
+
+      await kernel.use({
+        name: 'mock-fallback-driver-plugin',
+        type: 'driver',
+        version: '1.0.0',
+        init: async (ctx) => {
+          ctx.registerService('driver.fallback', mockDriver);
+        },
+      });
+
+      const appManifest = {
+        id: 'com.test.fallback',
+        name: 'fallback',
+        namespace: 'fb',
+        version: '1.0.0',
+        objects: [
+          {
+            name: 'one',
+            label: 'One',
+            fields: { x: { name: 'x', label: 'X', type: 'text' } },
+          },
+          {
+            name: 'two',
+            label: 'Two',
+            fields: { y: { name: 'y', label: 'Y', type: 'text' } },
+          },
+        ],
+      };
+
+      await kernel.use({
+        name: 'mock-fallback-app-plugin',
+        type: 'app',
+        version: '1.0.0',
+        init: async (ctx) => {
+          ctx.registerService('app.fallback', appManifest);
+        },
+      });
+
+      const plugin = new ObjectQLPlugin();
+      await kernel.use(plugin);
+
+      // Act - should not throw
+      await expect(kernel.bootstrap()).resolves.not.toThrow();
+
+      // Assert - sequential fallback should have been used
+      const syncedObjects = singleCalls.map((s) => s.object).sort();
+      expect(syncedObjects).toContain('fb__one');
+      expect(syncedObjects).toContain('fb__two');
+    });
+
+    it('should not use batch when driver does not support batchSchemaSync', async () => {
+      // Arrange - driver without batch support (but with syncSchema)
+      const singleCalls: string[] = [];
+      const mockDriver = {
+        name: 'nobatch-driver',
+        version: '1.0.0',
+        connect: async () => {},
+        disconnect: async () => {},
+        find: async () => [],
+        findOne: async () => null,
+        create: async (_o: string, d: any) => d,
+        update: async (_o: string, _i: any, d: any) => d,
+        delete: async () => true,
+        syncSchema: async (object: string) => {
+          singleCalls.push(object);
+        },
+      };
+
+      await kernel.use({
+        name: 'mock-nobatch-driver-plugin',
+        type: 'driver',
+        version: '1.0.0',
+        init: async (ctx) => {
+          ctx.registerService('driver.nobatch', mockDriver);
+        },
+      });
+
+      const appManifest = {
+        id: 'com.test.nobatch',
+        name: 'nobatch',
+        namespace: 'nb',
+        version: '1.0.0',
+        objects: [
+          {
+            name: 'item',
+            label: 'Item',
+            fields: { z: { name: 'z', label: 'Z', type: 'text' } },
+          },
+        ],
+      };
+
+      await kernel.use({
+        name: 'mock-nobatch-app-plugin',
+        type: 'app',
+        version: '1.0.0',
+        init: async (ctx) => {
+          ctx.registerService('app.nobatch', appManifest);
+        },
+      });
+
+      const plugin = new ObjectQLPlugin();
+      await kernel.use(plugin);
+
+      // Act
+      await kernel.bootstrap();
+
+      // Assert - sequential syncSchema should have been used
+      expect(singleCalls).toContain('nb__item');
+    });
   });
 });