@objectstack/objectql 3.2.9 → 3.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/objectql",
-  "version": "3.2.9",
+  "version": "3.3.1",
   "license": "Apache-2.0",
   "description": "Isomorphic ObjectQL Engine for ObjectStack",
   "main": "dist/index.js",
@@ -13,9 +13,9 @@
     }
   },
   "dependencies": {
-    "@objectstack/core": "3.2.9",
-    "@objectstack/spec": "3.2.9",
-    "@objectstack/types": "3.2.9"
+    "@objectstack/core": "3.3.1",
+    "@objectstack/spec": "3.3.1",
+    "@objectstack/types": "3.3.1"
   },
   "devDependencies": {
     "typescript": "^5.0.0",

package/src/engine.test.ts

@@ -1,7 +1,7 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { ObjectQL } from './engine';
 import { SchemaRegistry } from './registry';
-import { DriverInterface } from '@objectstack/spec/data';
+import type { IDataDriver } from '@objectstack/spec/contracts';
 
 // Mock the SchemaRegistry to avoid side effects between tests
 vi.mock('./registry', () => {
@@ -35,8 +35,8 @@ vi.mock('./registry', () => {
 
 describe('ObjectQL Engine', () => {
     let engine: ObjectQL;
-    let mockDriver: DriverInterface;
-    let mockDriver2: DriverInterface;
+    let mockDriver: IDataDriver;
+    let mockDriver2: IDataDriver;
 
     beforeEach(() => {
         // Clear Registry Mocks
@@ -54,7 +54,7 @@ describe('ObjectQL Engine', () => {
             delete: vi.fn(),
             count: vi.fn(),
             capabilities: {} as any // Simplified
-        } as unknown as DriverInterface;
+        } as unknown as IDataDriver;
 
         mockDriver2 = {
             name: 'mongo',
@@ -67,7 +67,7 @@ describe('ObjectQL Engine', () => {
             delete: vi.fn(),
             count: vi.fn(),
             capabilities: {} as any
-        } as unknown as DriverInterface;
+        } as unknown as IDataDriver;
 
         engine = new ObjectQL();
     });

package/src/engine.ts

@@ -545,7 +545,10 @@ export class ObjectQL implements IDataEngine {
   private resolveObjectName(name: string): string {
     const schema = SchemaRegistry.getObject(name);
     if (schema) {
-      return schema.name; // FQN from registry (e.g., 'todo__task')
+      // Prefer the physical table name (e.g., 'sys_user') over the FQN
+      // (e.g., 'sys__user'). ObjectSchema.create() auto-derives tableName
+      // as {namespace}_{name} which matches the storage convention.
+      return schema.tableName || schema.name;
     }
     return name; // Ad-hoc object, keep as-is
   }
@@ -898,7 +901,7 @@ export class ObjectQL implements IDataEngine {
                result = await Promise.all((hookContext.input.data as any[]).map((item: any) => driver.create(object, item, hookContext.input.options as any)));
           }
         } else {
-          result = await driver.create(object, hookContext.input.data, hookContext.input.options as any);
+          result = await driver.create(object, hookContext.input.data as Record<string, unknown>, hookContext.input.options as any);
         }
 
         hookContext.event = 'afterInsert';
@@ -949,10 +952,10 @@ export class ObjectQL implements IDataEngine {
        try {
            let result;
            if (hookContext.input.id) {
-               result = await driver.update(object, hookContext.input.id as string, hookContext.input.data, hookContext.input.options as any);
+               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 });
-               result = await driver.updateMany(object, ast, hookContext.input.data, hookContext.input.options as any);
+               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');
            }

package/src/plugin.integration.test.ts

@@ -468,5 +468,296 @@ describe('ObjectQLPlugin - Metadata Service Integration', () => {
       // Act & Assert - should not throw
       await expect(kernel.bootstrap()).resolves.not.toThrow();
     });
+
+    it('should use tableName for syncSchema when objects have auto-derived tableName', async () => {
+      // Arrange - driver that tracks syncSchema calls
+      const synced: Array<{ object: string; schema: any }> = [];
+      const mockDriver = {
+        name: 'table-name-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, schema: any) => {
+          synced.push({ object, schema });
+        },
+      };
+
+      await kernel.use({
+        name: 'mock-driver-plugin',
+        type: 'driver',
+        version: '1.0.0',
+        init: async (ctx) => {
+          ctx.registerService('driver.table-name', mockDriver);
+        },
+      });
+
+      // Objects with tableName (simulating ObjectSchema.create() output)
+      const appManifest = {
+        id: 'com.test.system',
+        name: 'system',
+        namespace: 'sys',
+        version: '1.0.0',
+        objects: [
+          {
+            name: 'user',
+            label: 'User',
+            namespace: 'sys',
+            tableName: 'sys_user',
+            fields: {
+              email: { name: 'email', label: 'Email', type: 'text' },
+            },
+          },
+          {
+            name: 'session',
+            label: 'Session',
+            namespace: 'sys',
+            tableName: 'sys_session',
+            fields: {
+              token: { name: 'token', label: 'Token', type: 'text' },
+            },
+          },
+        ],
+      };
+
+      await kernel.use({
+        name: 'mock-app-plugin',
+        type: 'app',
+        version: '1.0.0',
+        init: async (ctx) => {
+          ctx.registerService('app.system', appManifest);
+        },
+      });
+
+      const plugin = new ObjectQLPlugin();
+      await kernel.use(plugin);
+
+      // Act
+      await kernel.bootstrap();
+
+      // Assert - syncSchema should use tableName (single underscore) not FQN (double underscore)
+      const syncedNames = synced.map((s) => s.object).sort();
+      expect(syncedNames).toContain('sys_user');
+      expect(syncedNames).toContain('sys_session');
+      // Should NOT contain double-underscore FQN
+      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');
+    });
   });
 });

package/src/plugin.ts

@@ -239,9 +239,13 @@ export class ObjectQLPlugin implements Plugin {
   /**
    * Synchronize all registered object schemas to the database.
    *
-   * Iterates every object in the SchemaRegistry and calls the
-   * responsible driver's `syncSchema()` for each one.  This is
-   * idempotent — drivers must tolerate repeated calls without
+   * Groups objects by their responsible driver, then:
+   * - If the driver advertises `supports.batchSchemaSync` and implements
+   *   `syncSchemasBatch()`, submits all schemas in a single call (reducing
+   *   network round-trips for remote drivers like Turso).
+   * - Otherwise falls back to sequential `syncSchema()` per object.
+   *
+   * This is idempotent — drivers must tolerate repeated calls without
    * duplicating tables or erroring out.
    *
    * Drivers that do not implement `syncSchema` are silently skipped.
@@ -255,6 +259,9 @@ export class ObjectQLPlugin implements Plugin {
     let synced = 0;
     let skipped = 0;
 
+    // Group objects by driver for potential batch optimization
+    const driverGroups = new Map<any, Array<{ obj: any; tableName: string }>>();
+
     for (const obj of allObjects) {
       const driver = this.ql.getDriverForObject(obj.name);
       if (!driver) {
@@ -274,15 +281,69 @@ export class ObjectQLPlugin implements Plugin {
         continue;
       }
 
-      try {
-        await driver.syncSchema(obj.name, obj);
-        synced++;
-      } catch (e: unknown) {
-        ctx.logger.warn('Failed to sync schema for object', {
-          object: obj.name,
-          driver: driver.name,
-          error: e instanceof Error ? e.message : String(e),
-        });
+      const tableName = obj.tableName || obj.name;
+
+      let group = driverGroups.get(driver);
+      if (!group) {
+        group = [];
+        driverGroups.set(driver, group);
+      }
+      group.push({ obj, tableName });
+    }
+
+    // Process each driver group
+    for (const [driver, entries] of driverGroups) {
+      // Batch path: driver supports batch schema sync
+      if (
+        driver.supports?.batchSchemaSync &&
+        typeof driver.syncSchemasBatch === 'function'
+      ) {
+        const batchPayload = entries.map((e) => ({
+          object: e.tableName,
+          schema: e.obj,
+        }));
+        try {
+          await driver.syncSchemasBatch(batchPayload);
+          synced += entries.length;
+          ctx.logger.debug('Batch schema sync succeeded', {
+            driver: driver.name,
+            count: entries.length,
+          });
+        } catch (e: unknown) {
+          ctx.logger.warn('Batch schema sync failed, falling back to sequential', {
+            driver: driver.name,
+            error: e instanceof Error ? e.message : String(e),
+          });
+          // Fallback: sequential sync for this driver's objects
+          for (const { obj, tableName } of entries) {
+            try {
+              await driver.syncSchema(tableName, obj);
+              synced++;
+            } catch (seqErr: unknown) {
+              ctx.logger.warn('Failed to sync schema for object', {
+                object: obj.name,
+                tableName,
+                driver: driver.name,
+                error: seqErr instanceof Error ? seqErr.message : String(seqErr),
+              });
+            }
+          }
+        }
+      } else {
+        // Sequential path: no batch support
+        for (const { obj, tableName } of entries) {
+          try {
+            await driver.syncSchema(tableName, obj);
+            synced++;
+          } catch (e: unknown) {
+            ctx.logger.warn('Failed to sync schema for object', {
+              object: obj.name,
+              tableName,
+              driver: driver.name,
+              error: e instanceof Error ? e.message : String(e),
+            });
+          }
+        }
       }
     }
 

package/src/registry.test.ts

@@ -187,6 +187,31 @@ describe('SchemaRegistry', () => {
             expect(SchemaRegistry.getObject('task')).toBeDefined();
         });
 
+        it('should resolve by tableName (protocol name fallback)', () => {
+            // Simulates ObjectSchema.create() which auto-derives tableName
+            // as {namespace}_{name} (single underscore)
+            const obj = { name: 'user', tableName: 'sys_user', namespace: 'sys', fields: {} };
+            SchemaRegistry.registerObject(obj as any, 'com.objectstack.system', 'sys', 'own');
+            
+            // FQN is 'sys__user' (double underscore)
+            expect(SchemaRegistry.getObject('sys__user')).toBeDefined();
+            
+            // Protocol name 'sys_user' (single underscore) should also resolve
+            const resolved = SchemaRegistry.getObject('sys_user');
+            expect(resolved).toBeDefined();
+            expect(resolved?.name).toBe('sys__user');
+            expect((resolved as any).tableName).toBe('sys_user');
+        });
+
+        it('should resolve by tableName for any namespace', () => {
+            const obj = { name: 'account', tableName: 'crm_account', namespace: 'crm', fields: {} };
+            SchemaRegistry.registerObject(obj as any, 'com.crm', 'crm', 'own');
+            
+            // FQN: 'crm__account', tableName: 'crm_account'
+            expect(SchemaRegistry.getObject('crm__account')).toBeDefined();
+            expect(SchemaRegistry.getObject('crm_account')).toBeDefined();
+        });
+
         it('should cache merged objects', () => {
             const obj = { name: 'cached', fields: {} };
             SchemaRegistry.registerObject(obj as any, 'com.test', 'test', 'own');

package/src/registry.ts

@@ -314,8 +314,14 @@ export class SchemaRegistry {
   }
 
   /**
-   * Get object by name (FQN or short name with fallback scan).
-   * For compatibility, tries exact match first, then scans for suffix match.
+   * Get object by name (FQN, short name, or physical table name).
+   *
+   * Resolution order:
+   * 1. Exact FQN match (e.g., 'crm__account')
+   * 2. Short name fallback (e.g., 'account' → 'crm__account')
+   * 3. Physical table name match (e.g., 'sys_user' → 'sys__user')
+   *    ObjectSchema.create() auto-derives tableName as {namespace}_{name},
+   *    which uses a single underscore — different from the FQN double underscore.
    */
   static getObject(name: string): ServiceObject | undefined {
     // Direct FQN lookup
@@ -331,6 +337,15 @@ export class SchemaRegistry {
       }
     }
 
+    // Fallback: match by physical table name (e.g., 'sys_user' → FQN 'sys__user')
+    // This bridges the gap between protocol names (SystemObjectName) and FQN.
+    for (const fqn of this.objectContributors.keys()) {
+      const resolved = this.resolveObject(fqn);
+      if (resolved?.tableName === name) {
+        return resolved;
+      }
+    }
+
     return undefined;
   }