@objectql/core 4.0.4 → 4.0.6

package/src/protocol.ts

@@ -0,0 +1,291 @@
+/**
+ * ObjectStack Protocol Implementation
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { ObjectStackProtocol } from '@objectstack/spec/api';
+import { IObjectQL } from '@objectql/types';
+
+/**
+ * Bridges the ObjectStack Protocol (Specification) to the ObjectQL Engine (Implementation)
+ */
+export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
+    constructor(private engine: IObjectQL) {}
+
+    /**
+     * Get API Discovery Document
+     */
+    async getDiscovery(args: any): Promise<any> {
+        return {
+            name: 'ObjectQL Engine',
+            version: '4.0.0',
+            protocols: ['rest', 'graphql', 'json-rpc', 'odata'],
+            auth: {
+                type: 'bearer',
+                url: '/auth/token'
+            }
+        };
+    }
+
+    /**
+     * Get Metadata Types (e.g., ['object', 'action'])
+     */
+    async getMetaTypes(args: any): Promise<{ types: string[] }> {
+        let types = ['object'];
+        if (this.engine.metadata && typeof this.engine.metadata.getTypes === 'function') {
+            types = this.engine.metadata.getTypes();
+        }
+        return { types };
+    }
+
+    /**
+     * Get Metadata Items for a Type
+     */
+    async getMetaItems(args: { type: string }): Promise<{ type: string; items: any[] }> {
+        const { type } = args;
+        let items: any[] = [];
+        if (this.engine.metadata && typeof this.engine.metadata.list === 'function') {
+            items = this.engine.metadata.list(type);
+        }
+        return { type, items };
+    }
+
+    /**
+     * Get Metadata Item
+     */
+    async getMetaItem(args: { type: string; name: string }): Promise<any> {
+        const { type, name } = args;
+        if (this.engine.metadata && typeof this.engine.metadata.get === 'function') {
+            return this.engine.metadata.get(type, name);
+        }
+        return null;
+    }
+
+    /**
+     * Get Cached Metadata Item
+     */
+    async getMetaItemCached(args: { type: string; name: string }): Promise<any> {
+        // Fallback to non-cached version for now
+        return this.getMetaItem(args);
+    }
+
+    /**
+     * Get UI View
+     */
+    async getUiView(args: { object: string; type: 'list' | 'form' }): Promise<any> {
+        return null;
+    }
+
+    /**
+     * Find Data Records
+     */
+    async findData(args: { object: string; query?: any }): Promise<any> {
+        const { object, query } = args;
+        
+        // Use direct kernel method if available (preferred)
+        if (typeof (this.engine as any).find === 'function') {
+            const result = await (this.engine as any).find(object, query || {});
+            return result;
+        }
+
+        // Fallback to createContext (if engine is IObjectQL)
+        if (typeof (this.engine as any).createContext === 'function') {
+            const ctx = (this.engine as any).createContext({ isSystem: true });
+            try {
+                const repo = ctx.object(object);
+                return await repo.find(query || {});
+            } catch (error: any) {
+                throw new Error(`Data access failed: ${error.message}`);
+            }
+        }
+
+        throw new Error('Engine does not support find operation');
+    }
+
+    /**
+     * Count Data Records
+     */
+    async countData(args: { object: string; query?: any }): Promise<number> {
+        const { object, query } = args;
+        // Basic fallback
+        const result = await this.findData(args);
+        return Array.isArray(result) ? result.length : (result.value ? result.value.length : 0);
+    }
+
+
+    /**
+     * Get Single Data Record
+     */
+    async getData(args: { object: string; id: string }): Promise<any> {
+        const { object, id } = args;
+        
+        if (typeof (this.engine as any).get === 'function') {
+            return await (this.engine as any).get(object, id);
+        }
+        
+        if (typeof (this.engine as any).createContext === 'function') {
+            const ctx = (this.engine as any).createContext({ isSystem: true });
+            try {
+                const repo = ctx.object(object);
+                return await repo.findOne(id);
+            } catch (error: any) {
+                throw new Error(`Data retrieval failed: ${error.message}`);
+            }
+        }
+        
+        throw new Error('Engine does not support get operation');
+    }
+
+    /**
+     * Create Data Record
+     */
+    async createData(args: { object: string; data: any }): Promise<any> {
+        const { object, data } = args;
+
+        if (typeof (this.engine as any).create === 'function') {
+            return await (this.engine as any).create(object, data);
+        }
+        
+        if (typeof (this.engine as any).createContext === 'function') {
+            const ctx = (this.engine as any).createContext({ isSystem: true });
+            try {
+                const repo = ctx.object(object);
+                // Protocol expects returned data
+                return await repo.create(data);
+            } catch (error: any) {
+                throw new Error(`Data creation failed: ${error.message}`);
+            }
+        }
+        
+        throw new Error('Engine does not support create operation');
+    }
+
+    /**
+     * Update Data Record
+     */
+    async updateData(args: { object: string; id: string; data: any }): Promise<any> {
+        const { object, id, data } = args;
+
+        if (typeof (this.engine as any).update === 'function') {
+            return await (this.engine as any).update(object, id, data);
+        }
+
+        if (typeof (this.engine as any).createContext === 'function') {
+            const ctx = (this.engine as any).createContext({ isSystem: true });
+            try {
+                const repo = ctx.object(object);
+                return await repo.update(id, data);
+            } catch (error: any) {
+                 throw new Error(`Data update failed: ${error.message}`);
+            }
+        }
+
+        throw new Error('Engine does not support update operation');
+    }
+
+    /**
+     * Delete Data Record
+     */
+    async deleteData(args: { object: string; id: string }): Promise<{ object: string; id: string; success: boolean }> {
+        const { object, id } = args;
+
+        if (typeof (this.engine as any).delete === 'function') {
+            const success = await (this.engine as any).delete(object, id);
+            return { object, id, success: !!success };
+        }
+
+        if (typeof (this.engine as any).createContext === 'function') {
+            const ctx = (this.engine as any).createContext({ isSystem: true });
+            try {
+                const repo = ctx.object(object);
+                await repo.delete(id);
+                return { object, id, success: true };
+            } catch (error: any) {
+                throw new Error(`Data deletion failed: ${error.message}`);
+            }
+        }
+
+        throw new Error('Engine does not support delete operation');
+    }
+
+    /**
+     * Create Many Data Records
+     */
+    async createManyData(args: { object: string; records: any[]; options?: any }): Promise<any> {
+        throw new Error('createManyData not implemented');
+    }
+
+    /**
+     * Update Many Data Records
+     */
+    async updateManyData(args: { object: string; records: { id: string; data: any }[]; options?: any }): Promise<any> {
+        throw new Error('updateManyData not implemented');
+    }
+
+    /**
+     * Delete Many Data Records
+     */
+    async deleteManyData(args: { object: string; ids: string[]; options?: any }): Promise<any> {
+         throw new Error('deleteManyData not implemented');
+    }
+
+    /**
+     * Batch Operations
+     */
+    async batchData(args: { object: string; request: { operation: 'create' | 'update' | 'delete' | 'upsert'; records: any[] } }): Promise<any> {
+        throw new Error('batchData not implemented');
+    }
+
+    /**
+     * Execute Action/Operation
+     */
+    async performAction(args: { object: string; id?: string; action: string; args?: any }): Promise<any> {
+        // Not implemented in this shim yet
+        throw new Error('Action execution not implemented in protocol shim');
+    }
+
+    /**
+     * Analytics Query - Execute analytics query
+     */
+    async analyticsQuery(args: any): Promise<any> {
+        throw new Error('analyticsQuery not implemented');
+    }
+
+    /**
+     * Get Analytics Metadata
+     */
+    async getAnalyticsMeta(args: any): Promise<any> {
+        throw new Error('getAnalyticsMeta not implemented');
+    }
+
+    /**
+     * Trigger Automation
+     */
+    async triggerAutomation(args: { trigger: string; payload: Record<string, any> }): Promise<{ success: boolean; jobId?: string; result?: any }> {
+        throw new Error('triggerAutomation not implemented');
+    }
+
+    /**
+     * List Spaces (Hub/Workspace Management)
+     */
+    async listSpaces(args: any): Promise<any> {
+        throw new Error('listSpaces not implemented');
+    }
+
+    /**
+     * Create Space (Hub/Workspace Management)
+     */
+    async createSpace(args: any): Promise<any> {
+        throw new Error('createSpace not implemented');
+    }
+
+    /**
+     * Install Plugin (Hub/Extension Management)
+     */
+    async installPlugin(args: any): Promise<any> {
+        throw new Error('installPlugin not implemented');
+    }
+}

package/test/__mocks__/@objectstack/core.ts

@@ -0,0 +1,27 @@
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Mock for @objectstack/core to enable Jest testing
+ * 
+ * Since @objectstack/core@0.9.2 uses ES modules with import.meta,
+ * which Jest doesn't support well, we provide this mock for testing.
+ */
+
+export const createLogger = jest.fn(() => ({
+  trace: jest.fn(),
+  debug: jest.fn(),
+  info: jest.fn(),
+  warn: jest.fn(),
+  error: jest.fn(),
+  fatal: jest.fn(),
+}));
+
+export const ObjectKernel = jest.fn();
+export const LiteKernel = jest.fn();
+export const createApiRegistryPlugin = jest.fn();

package/test/__mocks__/@objectstack/objectql.ts

@@ -0,0 +1,45 @@
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Mock for @objectstack/objectql to enable Jest testing
+ */
+
+export class ObjectQL {
+  constructor(public config: any) {}
+  async connect() {}
+  async disconnect() {}
+}
+
+const mockStore = new Map<string, Map<string, any>>();
+
+export const SchemaRegistry = {
+  register: jest.fn(),
+  get: jest.fn(),
+  registerItem: jest.fn((type: string, item: any, keyField: string = 'name') => {
+    if (!mockStore.has(type)) {
+      mockStore.set(type, new Map());
+    }
+    const key = item[keyField];
+    mockStore.get(type)!.set(key, item);
+  }),
+  unregisterItem: jest.fn((type: string, name: string) => {
+    const collection = mockStore.get(type);
+    if (collection) {
+      collection.delete(name);
+    }
+  }),
+  getItem: jest.fn((type: string, name: string) => {
+    return mockStore.get(type)?.get(name);
+  }),
+  listItems: jest.fn((type: string) => {
+    const items = mockStore.get(type);
+    return items ? Array.from(items.values()) : [];
+  }),
+  metadata: mockStore,
+};

package/test/gateway.test.ts

@@ -0,0 +1,88 @@
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { ObjectGateway } from '../src/gateway';
+import { ApiRequest, ApiResponse, GatewayProtocol } from '@objectql/types';
+
+describe('ObjectGateway', () => {
+    let gateway: ObjectGateway;
+    let mockProtocol: GatewayProtocol;
+
+    beforeEach(() => {
+        gateway = new ObjectGateway();
+        mockProtocol = {
+            name: 'mock',
+            route: jest.fn().mockReturnValue(true),
+            handle: jest.fn().mockResolvedValue({ status: 200, body: 'ok' })
+        };
+        gateway.registerProtocol(mockProtocol);
+    });
+
+    it('should route request to registered protocol', async () => {
+        const req: ApiRequest = {
+            path: '/test',
+            method: 'GET',
+            headers: {},
+            query: {}
+        };
+        
+        const response = await gateway.handle(req);
+        
+        expect(mockProtocol.route).toHaveBeenCalledWith(req);
+        expect(mockProtocol.handle).toHaveBeenCalledWith(req);
+        expect(response.status).toBe(200);
+    });
+
+    it('should return 404 if no protocol matches', async () => {
+        const specializedGateway = new ObjectGateway();
+        const response = await specializedGateway.handle({
+            path: '/unknown',
+            method: 'GET',
+            headers: {},
+            query: {}
+        });
+        
+        expect(response.status).toBe(404);
+        expect(response.body.error.code).toBe('PROTOCOL_NOT_FOUND');
+    });
+
+    it('should apply request transformers', async () => {
+        const req: ApiRequest = {
+            path: '/original',
+            method: 'GET',
+            headers: {},
+            query: {}
+        };
+
+        gateway.addRequestTransform(async (r) => {
+            return { ...r, path: '/transformed' };
+        });
+
+        await gateway.handle(req);
+        
+        // Protocol should see the transformed request
+        expect(mockProtocol.route).toHaveBeenCalledWith(expect.objectContaining({ path: '/transformed' }));
+    });
+
+    it('should apply response transformers', async () => {
+        const req: ApiRequest = {
+            path: '/test',
+            method: 'GET',
+            headers: {},
+            query: {}
+        };
+
+        gateway.addResponseTransform(async (res) => {
+            return { ...res, headers: { ...res.headers, 'X-Custom': 'Added' } };
+        });
+
+        const response = await gateway.handle(req);
+        
+        expect(response.headers?.['X-Custom']).toBe('Added');
+    });
+});

package/test/protocol.test.ts

@@ -0,0 +1,143 @@
+/**
+ * ObjectQL
+ * Copyright (c) 2026-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import { ObjectStackProtocolImplementation } from '../src/protocol';
+import { IObjectQL } from '@objectql/types';
+
+describe('ObjectStackProtocolImplementation', () => {
+    let mockEngine: Partial<IObjectQL>;
+    let protocol: ObjectStackProtocolImplementation;
+
+    beforeEach(() => {
+        mockEngine = {
+            metadata: {
+                getTypes: jest.fn().mockReturnValue(['object']),
+                list: jest.fn().mockReturnValue([{ name: 'testObject', label: 'Test Object' }]),
+                get: jest.fn().mockReturnValue({ name: 'testObject', fields: {} }),
+            } as any,
+            // Mock kernel-like direct methods
+            find: jest.fn(),
+            get: jest.fn(),
+            create: jest.fn(),
+            update: jest.fn(),
+            delete: jest.fn(),
+        };
+        protocol = new ObjectStackProtocolImplementation(mockEngine as IObjectQL);
+    });
+
+    describe('Meta Operations', () => {
+        it('getMetaTypes should return types from engine metadata', async () => {
+            const result = await protocol.getMetaTypes({});
+            expect(result).toEqual({ types: ['object'] });
+            expect(mockEngine.metadata?.getTypes).toHaveBeenCalled();
+        });
+
+        it('getMetaItems should return items for a type', async () => {
+            const result = await protocol.getMetaItems({ type: 'object' });
+            expect(result).toEqual({ 
+                type: 'object', 
+                items: [{ name: 'testObject', label: 'Test Object' }] 
+            });
+            expect(mockEngine.metadata?.list).toHaveBeenCalledWith('object');
+        });
+
+        it('getMetaItem should return specific item definition', async () => {
+            const result = await protocol.getMetaItem({ type: 'object', name: 'testObject' });
+            expect(result).toEqual({ name: 'testObject', fields: {} });
+            expect(mockEngine.metadata?.get).toHaveBeenCalledWith('object', 'testObject');
+        });
+    });
+
+    describe('Data Operations (Direct Kernel Mode)', () => {
+        it('findData should delegate to engine.find', async () => {
+            const mockData = [{ id: '1', name: 'Test' }];
+            (mockEngine as any).find.mockResolvedValue(mockData);
+
+            const result = await protocol.findData({ object: 'testObject', query: {} });
+            expect(result).toBe(mockData);
+            expect((mockEngine as any).find).toHaveBeenCalledWith('testObject', {});
+        });
+
+        it('getData should delegate to engine.get', async () => {
+            const mockRecord = { id: '1', name: 'Test' };
+            (mockEngine as any).get.mockResolvedValue(mockRecord);
+
+            const result = await protocol.getData({ object: 'testObject', id: '1' });
+            expect(result).toBe(mockRecord);
+            expect((mockEngine as any).get).toHaveBeenCalledWith('testObject', '1');
+        });
+
+        it('createData should delegate to engine.create', async () => {
+            const newData = { name: 'New' };
+            const createdRecord = { id: '2', ...newData };
+            (mockEngine as any).create.mockResolvedValue(createdRecord);
+
+            const result = await protocol.createData({ object: 'testObject', data: newData });
+            expect(result).toBe(createdRecord);
+            expect((mockEngine as any).create).toHaveBeenCalledWith('testObject', newData);
+        });
+
+        it('updateData should delegate to engine.update', async () => {
+            const updateData = { name: 'Updated' };
+            const updatedRecord = { id: '1', ...updateData };
+            (mockEngine as any).update.mockResolvedValue(updatedRecord);
+
+            const result = await protocol.updateData({ object: 'testObject', id: '1', data: updateData });
+            expect(result).toBe(updatedRecord);
+            expect((mockEngine as any).update).toHaveBeenCalledWith('testObject', '1', updateData);
+        });
+
+        it('deleteData should delegate to engine.delete', async () => {
+            (mockEngine as any).delete.mockResolvedValue(true);
+
+            const result = await protocol.deleteData({ object: 'testObject', id: '1' });
+            expect(result).toEqual({ object: 'testObject', id: '1', success: true });
+            expect((mockEngine as any).delete).toHaveBeenCalledWith('testObject', '1');
+        });
+    });
+
+    describe('Legacy Mode (IObjectQL Context)', () => {
+        let mockRepo: any;
+        
+        beforeEach(() => {
+            // Remove direct methods to force legacy path
+            delete (mockEngine as any).find;
+            delete (mockEngine as any).get;
+            delete (mockEngine as any).create;
+            delete (mockEngine as any).update;
+            delete (mockEngine as any).delete;
+
+            mockRepo = {
+                find: jest.fn(),
+                findOne: jest.fn(),
+                create: jest.fn(),
+                update: jest.fn(),
+                delete: jest.fn(),
+            };
+
+            (mockEngine as any).createContext = jest.fn().mockReturnValue({
+                object: jest.fn().mockReturnValue(mockRepo)
+            });
+        });
+
+        it('findData should use repo.find in legacy mode', async () => {
+            const mockData = [{ id: '1' }];
+            mockRepo.find.mockResolvedValue(mockData);
+
+            await protocol.findData({ object: 'testObject' });
+            expect(mockRepo.find).toHaveBeenCalled();
+        });
+
+        it('deleteData should use repo.delete in legacy mode', async () => {
+            mockRepo.delete.mockResolvedValue(true);
+            const result = await protocol.deleteData({ object: 'testObject', id: '1' });
+            expect(result.success).toBe(true);
+            expect(mockRepo.delete).toHaveBeenCalledWith('1');
+        });
+    });
+});