@objectstack/objectql 3.3.1 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/objectql",
-  "version": "3.3.1",
+  "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.1",
-    "@objectstack/spec": "3.3.1",
-    "@objectstack/types": "3.3.1"
+    "@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.ts

@@ -175,7 +175,7 @@ export class ObjectQLPlugin implements Plugin {
       if (hookCtx.input?.id && !hookCtx.previous) {
         try {
           const existing = await this.ql!.findOne(hookCtx.object, {
-            filter: { id: hookCtx.input.id }
+            where: { id: hookCtx.input.id }
           });
           if (existing) {
             hookCtx.previous = existing;
@@ -191,7 +191,7 @@ export class ObjectQLPlugin implements Plugin {
       if (hookCtx.input?.id && !hookCtx.previous) {
         try {
           const existing = await this.ql!.findOne(hookCtx.object, {
-            filter: { id: hookCtx.input.id }
+            where: { id: hookCtx.input.id }
           });
           if (existing) {
             hookCtx.previous = existing;

package/src/protocol-data.test.ts

@@ -25,87 +25,88 @@ describe('ObjectStackProtocolImplementation - Data Operations', () => {
     // ═══════════════════════════════════════════════════════════════
 
     describe('findData', () => {
-        it('should normalize expand string to populate array', async () => {
-            await protocol.findData({ object: 'order_item', query: { expand: 'order,product' } });
+        it('should normalize $expand (OData) string to expand Record', async () => {
+            await protocol.findData({ object: 'order_item', query: { $expand: 'order,product' } });
 
             expect(mockEngine.find).toHaveBeenCalledWith(
                 'order_item',
                 expect.objectContaining({
-                    populate: ['order', 'product'],
+                    expand: { order: { object: 'order' }, product: { object: 'product' } },
                 }),
             );
-            // expand should be deleted from options
+            // $expand should be deleted from options
             const callArgs = mockEngine.find.mock.calls[0][1];
-            expect(callArgs.expand).toBeUndefined();
             expect(callArgs.$expand).toBeUndefined();
         });
 
-        it('should normalize $expand (OData) to populate array', async () => {
+        it('should normalize $expand (OData) with different fields to expand Record', async () => {
             await protocol.findData({ object: 'task', query: { $expand: 'assignee,project' } });
 
             expect(mockEngine.find).toHaveBeenCalledWith(
                 'task',
                 expect.objectContaining({
-                    populate: ['assignee', 'project'],
+                    expand: { assignee: { object: 'assignee' }, project: { object: 'project' } },
                 }),
             );
         });
 
-        it('should pass populate array as-is if already an array', async () => {
+        it('should normalize populate array to expand Record', async () => {
             await protocol.findData({ object: 'task', query: { populate: ['assignee'] } });
 
             expect(mockEngine.find).toHaveBeenCalledWith(
                 'task',
                 expect.objectContaining({
-                    populate: ['assignee'],
+                    expand: { assignee: { object: 'assignee' } },
                 }),
             );
         });
 
-        it('should normalize populate string to array', async () => {
+        it('should normalize populate string to expand Record', async () => {
             await protocol.findData({ object: 'task', query: { populate: 'assignee,project' } });
 
             expect(mockEngine.find).toHaveBeenCalledWith(
                 'task',
                 expect.objectContaining({
-                    populate: ['assignee', 'project'],
+                    expand: { assignee: { object: 'assignee' }, project: { object: 'project' } },
                 }),
             );
         });
 
-        it('should prefer explicit populate over expand', async () => {
+        it('should prefer populate names over expand string when both provided', async () => {
             await protocol.findData({
                 object: 'task',
                 query: { populate: ['assignee'], expand: 'project' },
             });
 
-            // populate takes precedence; expand is not converted
-            expect(mockEngine.find).toHaveBeenCalledWith(
-                'task',
-                expect.objectContaining({
-                    populate: ['assignee'],
-                }),
-            );
+            // populate names take precedence; the non-object expand string is
+            // cleaned up first, then populate-derived names create the Record.
+            const callArgs = mockEngine.find.mock.calls[0][1];
+            expect(callArgs.populate).toBeUndefined();
+            expect(callArgs.$expand).toBeUndefined();
+            expect(callArgs.expand).toEqual({ assignee: { object: 'assignee' } });
         });
 
-        it('should normalize expand array to populate array', async () => {
-            await protocol.findData({ object: 'task', query: { expand: ['owner', 'team'] } });
+        it('should pass expand Record object through as-is', async () => {
+            await protocol.findData({
+                object: 'task',
+                query: { expand: { owner: { object: 'owner' }, team: { object: 'team' } } },
+            });
 
             expect(mockEngine.find).toHaveBeenCalledWith(
                 'task',
                 expect.objectContaining({
-                    populate: ['owner', 'team'],
+                    expand: { owner: { object: 'owner' }, team: { object: 'team' } },
                 }),
             );
         });
 
-        it('should normalize select string to array', async () => {
+        it('should normalize select string to fields array', async () => {
             await protocol.findData({ object: 'task', query: { select: 'name,status,assignee' } });
 
             expect(mockEngine.find).toHaveBeenCalledWith(
                 'task',
                 expect.objectContaining({
-                    select: ['name', 'status', 'assignee'],
+                    fields: ['name', 'status', 'assignee'],
                 }),
             );
         });
@@ -116,8 +117,8 @@ describe('ObjectStackProtocolImplementation - Data Operations', () => {
             expect(mockEngine.find).toHaveBeenCalledWith(
                 'task',
                 expect.objectContaining({
-                    top: 10,
-                    skip: 20,
+                    limit: 10,
+                    offset: 20,
                 }),
             );
         });
@@ -148,7 +149,7 @@ describe('ObjectStackProtocolImplementation - Data Operations', () => {
     // ═══════════════════════════════════════════════════════════════
 
     describe('getData', () => {
-        it('should convert expand string to populate array', async () => {
+        it('should convert expand string to expand Record', async () => {
             mockEngine.findOne.mockResolvedValue({ id: 'oi_1', name: 'Item 1' });
 
             await protocol.getData({ object: 'order_item', id: 'oi_1', expand: 'order,product' });
@@ -156,13 +157,13 @@ describe('ObjectStackProtocolImplementation - Data Operations', () => {
             expect(mockEngine.findOne).toHaveBeenCalledWith(
                 'order_item',
                 expect.objectContaining({
-                    filter: { id: 'oi_1' },
-                    populate: ['order', 'product'],
+                    where: { id: 'oi_1' },
+                    expand: { order: { object: 'order' }, product: { object: 'product' } },
                 }),
             );
         });
 
-        it('should convert expand array to populate array', async () => {
+        it('should convert expand array to expand Record', async () => {
             mockEngine.findOne.mockResolvedValue({ id: 't1' });
 
             await protocol.getData({ object: 'task', id: 't1', expand: ['assignee', 'project'] });
@@ -170,12 +171,13 @@ describe('ObjectStackProtocolImplementation - Data Operations', () => {
             expect(mockEngine.findOne).toHaveBeenCalledWith(
                 'task',
                 expect.objectContaining({
-                    populate: ['assignee', 'project'],
+                    where: { id: 't1' },
+                    expand: { assignee: { object: 'assignee' }, project: { object: 'project' } },
                 }),
             );
         });
 
-        it('should convert select string to array', async () => {
+        it('should convert select string to fields array', async () => {
             mockEngine.findOne.mockResolvedValue({ id: 't1', name: 'Test' });
 
             await protocol.getData({ object: 'task', id: 't1', select: 'name,status' });
@@ -183,12 +185,13 @@ describe('ObjectStackProtocolImplementation - Data Operations', () => {
             expect(mockEngine.findOne).toHaveBeenCalledWith(
                 'task',
                 expect.objectContaining({
-                    select: ['name', 'status'],
+                    where: { id: 't1' },
+                    fields: ['name', 'status'],
                 }),
             );
         });
 
-        it('should pass both expand and select together', async () => {
+        it('should pass both expand and fields together', async () => {
             mockEngine.findOne.mockResolvedValue({ id: 'oi_1' });
 
             await protocol.getData({
@@ -201,9 +204,9 @@ describe('ObjectStackProtocolImplementation - Data Operations', () => {
             expect(mockEngine.findOne).toHaveBeenCalledWith(
                 'order_item',
                 expect.objectContaining({
-                    filter: { id: 'oi_1' },
-                    populate: ['order'],
-                    select: ['name', 'total'],
+                    where: { id: 'oi_1' },
+                    expand: { order: { object: 'order' } },
+                    fields: ['name', 'total'],
                 }),
             );
         });
@@ -215,7 +218,7 @@ describe('ObjectStackProtocolImplementation - Data Operations', () => {
 
             expect(mockEngine.findOne).toHaveBeenCalledWith(
                 'task',
-                { filter: { id: 't1' } },
+                { where: { id: 't1' } },
             );
         });