@objectstack/objectql 3.3.0 → 4.0.0

package/src/protocol-meta.test.ts

@@ -0,0 +1,440 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { ObjectStackProtocolImplementation } from './protocol.js';
+import { SchemaRegistry } from './registry.js';
+
+/**
+ * Tests for the Protocol Implementation's metadata persistence methods.
+ * Validates dual-write strategy (SchemaRegistry + database), DB fallback for reads,
+ * graceful degradation when DB is unavailable, and the loadMetaFromDb() bootstrap method.
+ */
+describe('ObjectStackProtocolImplementation - Metadata Persistence', () => {
+    let protocol: ObjectStackProtocolImplementation;
+    let mockEngine: any;
+
+    const sampleApp = {
+        name: 'test_app',
+        label: 'Test App',
+        description: 'A test application',
+    };
+
+    beforeEach(() => {
+        // Reset SchemaRegistry state between tests
+        SchemaRegistry.reset();
+
+        mockEngine = {
+            find: vi.fn().mockResolvedValue([]),
+            findOne: vi.fn().mockResolvedValue(null),
+            insert: vi.fn().mockResolvedValue({ id: 'new-uuid' }),
+            update: vi.fn().mockResolvedValue({ id: 'existing-uuid' }),
+            delete: vi.fn().mockResolvedValue({ deleted: 1 }),
+            count: vi.fn().mockResolvedValue(0),
+            aggregate: vi.fn().mockResolvedValue([]),
+        };
+        protocol = new ObjectStackProtocolImplementation(mockEngine);
+    });
+
+    afterEach(() => {
+        vi.clearAllMocks();
+        SchemaRegistry.reset();
+    });
+
+    // ═══════════════════════════════════════════════════════════════
+    // saveMetaItem — dual-write (registry + database)
+    // ═══════════════════════════════════════════════════════════════
+
+    describe('saveMetaItem', () => {
+        it('should throw when item data is missing', async () => {
+            await expect(
+                protocol.saveMetaItem({ type: 'app', name: 'test_app' })
+            ).rejects.toThrow('Item data is required');
+        });
+
+        it('should register item in SchemaRegistry', async () => {
+            await protocol.saveMetaItem({ type: 'app', name: 'test_app', item: sampleApp });
+
+            const stored = SchemaRegistry.getItem('app', 'test_app');
+            expect(stored).toEqual(sampleApp);
+        });
+
+        it('should insert a new record in the database when item does not exist', async () => {
+            mockEngine.findOne.mockResolvedValue(null); // not existing
+
+            await protocol.saveMetaItem({ type: 'app', name: 'test_app', item: sampleApp });
+
+            expect(mockEngine.findOne).toHaveBeenCalledWith('sys_metadata', {
+                where: { type: 'app', name: 'test_app' }
+            });
+            expect(mockEngine.insert).toHaveBeenCalledWith('sys_metadata', expect.objectContaining({
+                name: 'test_app',
+                type: 'app',
+                scope: 'platform',
+                state: 'active',
+                version: 1,
+                metadata: JSON.stringify(sampleApp),
+            }));
+        });
+
+        it('should update an existing record in the database and increment version', async () => {
+            const existingRecord = { id: 'existing-uuid', version: 2 };
+            mockEngine.findOne.mockResolvedValue(existingRecord);
+
+            await protocol.saveMetaItem({ type: 'app', name: 'test_app', item: sampleApp });
+
+            expect(mockEngine.update).toHaveBeenCalledWith('sys_metadata', expect.objectContaining({
+                metadata: JSON.stringify(sampleApp),
+                version: 3, // incremented from 2
+            }), {
+                where: { id: 'existing-uuid' }
+            });
+            expect(mockEngine.insert).not.toHaveBeenCalled();
+        });
+
+        it('should return success=true and "Saved to database and registry" on DB success', async () => {
+            const result = await protocol.saveMetaItem({ type: 'app', name: 'test_app', item: sampleApp });
+
+            expect(result.success).toBe(true);
+            expect(result.message).toBe('Saved to database and registry');
+        });
+
+        it('should degrade gracefully when DB is unavailable', async () => {
+            mockEngine.findOne.mockRejectedValue(new Error('Connection refused'));
+
+            const result = await protocol.saveMetaItem({ type: 'app', name: 'test_app', item: sampleApp });
+
+            expect(result.success).toBe(true);
+            expect(result.message).toContain('memory registry');
+            expect((result as any).warning).toContain('Connection refused');
+
+            // Registry should still be updated
+            const stored = SchemaRegistry.getItem('app', 'test_app');
+            expect(stored).toEqual(sampleApp);
+        });
+
+        it('should degrade gracefully when DB insert fails', async () => {
+            mockEngine.findOne.mockResolvedValue(null);
+            mockEngine.insert.mockRejectedValue(new Error('Table not found'));
+
+            const result = await protocol.saveMetaItem({ type: 'app', name: 'test_app', item: sampleApp });
+
+            expect(result.success).toBe(true);
+            expect(result.message).toContain('memory registry');
+        });
+
+        it('should use version=1 for initial insert when existing record has no version', async () => {
+            mockEngine.findOne.mockResolvedValue(null);
+
+            await protocol.saveMetaItem({ type: 'app', name: 'test_app', item: sampleApp });
+
+            expect(mockEngine.insert).toHaveBeenCalledWith('sys_metadata', expect.objectContaining({
+                version: 1,
+            }));
+        });
+
+        it('should handle existing record with version=0 and increment to 1', async () => {
+            mockEngine.findOne.mockResolvedValue({ id: 'uuid', version: 0 });
+
+            await protocol.saveMetaItem({ type: 'app', name: 'test_app', item: sampleApp });
+
+            expect(mockEngine.update).toHaveBeenCalledWith('sys_metadata', expect.objectContaining({
+                version: 1,
+            }), expect.anything());
+        });
+    });
+
+    // ═══════════════════════════════════════════════════════════════
+    // getMetaItem — registry-first, DB fallback
+    // ═══════════════════════════════════════════════════════════════
+
+    describe('getMetaItem', () => {
+        it('should return item from SchemaRegistry when it exists', async () => {
+            SchemaRegistry.registerItem('app', sampleApp, 'name');
+
+            const result = await protocol.getMetaItem({ type: 'app', name: 'test_app' });
+
+            expect(result.item).toEqual(sampleApp);
+            // DB should NOT be queried
+            expect(mockEngine.findOne).not.toHaveBeenCalled();
+        });
+
+        it('should fall back to DB when item is not in registry', async () => {
+            mockEngine.findOne.mockResolvedValue({
+                type: 'app',
+                name: 'test_app',
+                state: 'active',
+                metadata: JSON.stringify(sampleApp),
+            });
+
+            const result = await protocol.getMetaItem({ type: 'app', name: 'test_app' });
+
+            expect(result.item).toEqual(sampleApp);
+            expect(mockEngine.findOne).toHaveBeenCalledWith('sys_metadata', {
+                where: { type: 'app', name: 'test_app', state: 'active' }
+            });
+        });
+
+        it('should hydrate registry after DB fallback', async () => {
+            mockEngine.findOne.mockResolvedValue({
+                type: 'app',
+                name: 'test_app',
+                state: 'active',
+                metadata: JSON.stringify(sampleApp),
+            });
+
+            await protocol.getMetaItem({ type: 'app', name: 'test_app' });
+
+            // Should now be in registry
+            const cached = SchemaRegistry.getItem('app', 'test_app');
+            expect(cached).toEqual(sampleApp);
+        });
+
+        it('should try alternate type name in DB when primary type not found', async () => {
+            // 'app' not found, try 'apps'
+            mockEngine.findOne
+                .mockResolvedValueOnce(null) // first call: type='app' not found
+                .mockResolvedValueOnce({    // second call: type='apps' found
+                    type: 'apps',
+                    name: 'test_app',
+                    state: 'active',
+                    metadata: JSON.stringify(sampleApp),
+                });
+
+            const result = await protocol.getMetaItem({ type: 'app', name: 'test_app' });
+
+            expect(result.item).toEqual(sampleApp);
+            expect(mockEngine.findOne).toHaveBeenCalledTimes(2);
+        });
+
+        it('should return undefined item when not in registry or DB', async () => {
+            mockEngine.findOne.mockResolvedValue(null);
+
+            const result = await protocol.getMetaItem({ type: 'app', name: 'nonexistent' });
+
+            expect(result.item).toBeUndefined();
+        });
+
+        it('should handle DB errors gracefully and return undefined item', async () => {
+            mockEngine.findOne.mockRejectedValue(new Error('DB down'));
+
+            const result = await protocol.getMetaItem({ type: 'app', name: 'test_app' });
+
+            expect(result.item).toBeUndefined();
+            expect(result.type).toBe('app');
+            expect(result.name).toBe('test_app');
+        });
+
+        it('should parse metadata JSON string from DB record', async () => {
+            const complexData = { name: 'complex', nested: { value: 42 } };
+            mockEngine.findOne.mockResolvedValue({
+                type: 'object',
+                name: 'complex',
+                state: 'active',
+                metadata: JSON.stringify(complexData),
+            });
+
+            const result = await protocol.getMetaItem({ type: 'object', name: 'complex' });
+
+            expect(result.item).toEqual(complexData);
+        });
+
+        it('should handle metadata already parsed as object from DB', async () => {
+            mockEngine.findOne.mockResolvedValue({
+                type: 'app',
+                name: 'test_app',
+                state: 'active',
+                metadata: sampleApp, // already an object, not a string
+            });
+
+            const result = await protocol.getMetaItem({ type: 'app', name: 'test_app' });
+
+            expect(result.item).toEqual(sampleApp);
+        });
+    });
+
+    // ═══════════════════════════════════════════════════════════════
+    // getMetaItems — registry-first, DB fallback
+    // ═══════════════════════════════════════════════════════════════
+
+    describe('getMetaItems', () => {
+        it('should return items from SchemaRegistry when they exist', async () => {
+            SchemaRegistry.registerItem('app', sampleApp, 'name');
+            SchemaRegistry.registerItem('app', { name: 'app2', label: 'App 2' }, 'name');
+
+            const result = await protocol.getMetaItems({ type: 'app' });
+
+            expect(result.items).toHaveLength(2);
+            // DB should NOT be queried
+            expect(mockEngine.find).not.toHaveBeenCalled();
+        });
+
+        it('should fall back to DB when registry is empty for type', async () => {
+            mockEngine.find.mockResolvedValue([
+                {
+                    type: 'app',
+                    name: 'test_app',
+                    state: 'active',
+                    metadata: JSON.stringify(sampleApp),
+                }
+            ]);
+
+            const result = await protocol.getMetaItems({ type: 'app' });
+
+            expect(result.items).toHaveLength(1);
+            expect(result.items[0]).toEqual(sampleApp);
+            expect(mockEngine.find).toHaveBeenCalledWith('sys_metadata', {
+                where: { type: 'app', state: 'active' }
+            });
+        });
+
+        it('should hydrate registry after DB fallback for getMetaItems', async () => {
+            mockEngine.find.mockResolvedValue([
+                {
+                    type: 'app',
+                    name: 'test_app',
+                    state: 'active',
+                    metadata: JSON.stringify(sampleApp),
+                }
+            ]);
+
+            await protocol.getMetaItems({ type: 'app' });
+
+            // Should now be in registry
+            const cached = SchemaRegistry.getItem('app', 'test_app');
+            expect(cached).toEqual(sampleApp);
+        });
+
+        it('should try alternate type name in DB when primary type has no records', async () => {
+            mockEngine.find
+                .mockResolvedValueOnce([]) // 'app' returns nothing
+                .mockResolvedValueOnce([ // 'apps' returns results
+                    { type: 'apps', name: 'test_app', state: 'active', metadata: JSON.stringify(sampleApp) }
+                ]);
+
+            const result = await protocol.getMetaItems({ type: 'app' });
+
+            expect(result.items).toHaveLength(1);
+            expect(mockEngine.find).toHaveBeenCalledTimes(2);
+        });
+
+        it('should return empty items array when DB also has no records', async () => {
+            mockEngine.find.mockResolvedValue([]);
+
+            const result = await protocol.getMetaItems({ type: 'app' });
+
+            expect(result.items).toHaveLength(0);
+        });
+
+        it('should handle DB errors gracefully and return empty items', async () => {
+            mockEngine.find.mockRejectedValue(new Error('DB down'));
+
+            const result = await protocol.getMetaItems({ type: 'app' });
+
+            expect(result.items).toHaveLength(0);
+            expect(result.type).toBe('app');
+        });
+    });
+
+    // ═══════════════════════════════════════════════════════════════
+    // loadMetaFromDb — startup hydration
+    // ═══════════════════════════════════════════════════════════════
+
+    describe('loadMetaFromDb', () => {
+        it('should load all active records from DB into SchemaRegistry', async () => {
+            const app2 = { name: 'app2', label: 'App 2' };
+            mockEngine.find.mockResolvedValue([
+                { type: 'app', name: 'test_app', state: 'active', metadata: JSON.stringify(sampleApp) },
+                { type: 'app', name: 'app2', state: 'active', metadata: JSON.stringify(app2) },
+            ]);
+
+            const result = await protocol.loadMetaFromDb();
+
+            expect(result.loaded).toBe(2);
+            expect(result.errors).toBe(0);
+
+            expect(SchemaRegistry.getItem('app', 'test_app')).toEqual(sampleApp);
+            expect(SchemaRegistry.getItem('app', 'app2')).toEqual(app2);
+        });
+
+        it('should query only active state records', async () => {
+            mockEngine.find.mockResolvedValue([]);
+
+            await protocol.loadMetaFromDb();
+
+            expect(mockEngine.find).toHaveBeenCalledWith('sys_metadata', {
+                where: { state: 'active' }
+            });
+        });
+
+        it('should count parse errors and continue loading other records', async () => {
+            mockEngine.find.mockResolvedValue([
+                { type: 'app', name: 'test_app', state: 'active', metadata: JSON.stringify(sampleApp) },
+                { type: 'object', name: 'bad', state: 'active', metadata: 'not-valid-json{{{' },
+            ]);
+
+            const result = await protocol.loadMetaFromDb();
+
+            expect(result.loaded).toBe(1);
+            expect(result.errors).toBe(1);
+        });
+
+        it('should return loaded=0 errors=0 when DB returns empty results', async () => {
+            mockEngine.find.mockResolvedValue([]);
+
+            const result = await protocol.loadMetaFromDb();
+
+            expect(result.loaded).toBe(0);
+            expect(result.errors).toBe(0);
+        });
+
+        it('should gracefully skip DB hydration when DB is unavailable', async () => {
+            mockEngine.find.mockRejectedValue(new Error('Connection refused'));
+
+            const result = await protocol.loadMetaFromDb();
+
+            expect(result.loaded).toBe(0);
+            expect(result.errors).toBe(0);
+        });
+
+        it('should handle metadata already parsed as an object (not string)', async () => {
+            mockEngine.find.mockResolvedValue([
+                { type: 'app', name: 'test_app', state: 'active', metadata: sampleApp }, // object, not string
+            ]);
+
+            const result = await protocol.loadMetaFromDb();
+
+            expect(result.loaded).toBe(1);
+            expect(result.errors).toBe(0);
+            expect(SchemaRegistry.getItem('app', 'test_app')).toEqual(sampleApp);
+        });
+
+        it('should load records of different types', async () => {
+            const objDef = { name: 'task', label: 'Task', fields: {} };
+            mockEngine.find.mockResolvedValue([
+                { type: 'app', name: 'test_app', state: 'active', metadata: JSON.stringify(sampleApp) },
+                { type: 'object', name: 'task', state: 'active', metadata: JSON.stringify(objDef) },
+            ]);
+
+            const result = await protocol.loadMetaFromDb();
+
+            expect(result.loaded).toBe(2);
+            expect(SchemaRegistry.getItem('app', 'test_app')).toEqual(sampleApp);
+            expect(SchemaRegistry.getItem('object', 'task')).toEqual(objDef);
+        });
+    });
+
+    // ═══════════════════════════════════════════════════════════════
+    // Discovery — metadata service status
+    // ═══════════════════════════════════════════════════════════════
+
+    describe('getDiscovery - metadata service status', () => {
+        it('should report metadata service as available (not degraded)', async () => {
+            const discovery = await protocol.getDiscovery();
+
+            expect(discovery.services.metadata).toBeDefined();
+            expect(discovery.services.metadata.enabled).toBe(true);
+            expect(discovery.services.metadata.status).toBe('available');
+            expect(discovery.services.metadata.message).toBeUndefined();
+        });
+    });
+});