@objectstack/objectql 4.0.1 → 4.0.2

package/package.json

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

package/src/plugin.integration.test.ts

@@ -15,7 +15,7 @@ describe('ObjectQLPlugin - Metadata Service Integration', () => {
   });
 
   describe('Simple Mode (ObjectQL-only)', () => {
-    it('should register ObjectQL as metadata service provider', async () => {
+    it('should register objectql, data, and protocol services', async () => {
       // Arrange
       const plugin = new ObjectQLPlugin();
       await kernel.use(plugin);
@@ -23,16 +23,15 @@ describe('ObjectQLPlugin - Metadata Service Integration', () => {
       // Act
       await kernel.bootstrap();
 
-      // Assert
-      const metadataService = kernel.getService('metadata');
-      expect(metadataService).toBeDefined();
-
-      // ObjectQL registers a MetadataFacade as the metadata service;
-      // it is separate from (but backed by the same registry as) the objectql service.
+      // Assert — ObjectQL no longer registers metadata (kernel provides fallback)
       const objectql = kernel.getService('objectql');
       expect(objectql).toBeDefined();
-      // metadata and objectql are distinct service instances
-      expect(metadataService).not.toBe(objectql);
+      expect(kernel.getService('data')).toBeDefined();
+      expect(kernel.getService('protocol')).toBeDefined();
+      // metadata is provided by kernel's core fallback, not ObjectQL
+      const metadataService = kernel.getService('metadata');
+      expect(metadataService).toBeDefined();
+      expect((metadataService as any)._fallback).toBe(true);
     });
 
     it('should serve in-memory metadata definitions', async () => {
@@ -65,7 +64,7 @@ describe('ObjectQLPlugin - Metadata Service Integration', () => {
   });
 
   describe('Service Registration', () => {
-    it('should register objectql, data, and protocol services', async () => {
+    it('should register manifest service', async () => {
       // Arrange
       const plugin = new ObjectQLPlugin();
       await kernel.use(plugin);
@@ -77,6 +76,7 @@ describe('ObjectQLPlugin - Metadata Service Integration', () => {
       expect(kernel.getService('objectql')).toBeDefined();
       expect(kernel.getService('data')).toBeDefined();
       expect(kernel.getService('protocol')).toBeDefined();
+      expect(kernel.getService('manifest')).toBeDefined();
     });
 
     it('should respect existing metadata service', async () => {
@@ -146,8 +146,71 @@ describe('ObjectQLPlugin - Metadata Service Integration', () => {
       expect(objectql.drivers?.has('mock-driver')).toBe(true);
     });
 
-    it('should discover and register apps from kernel services', async () => {
+    it('should register apps via manifest service', async () => {
       // Arrange
+      const plugin = new ObjectQLPlugin();
+      await kernel.use(plugin);
+
+      // Plugin that uses the manifest service directly
+      await kernel.use({
+        name: 'mock-app-plugin',
+        type: 'app',
+        version: '1.0.0',
+        dependencies: ['com.objectstack.engine.objectql'],
+        init: async (ctx) => {
+          ctx.getService<{ register(m: any): void }>('manifest').register({
+            id: 'test-app',
+            name: 'test_app',
+            version: '1.0.0',
+            type: 'app',
+            apps: [{ name: 'Test App' }],
+          });
+        }
+      });
+
+      // Act
+      await kernel.bootstrap();
+
+      // Assert
+      const objectql = kernel.getService('objectql') as any;
+      expect(objectql.registry).toBeDefined();
+      const apps = objectql.registry.getAllApps();
+      expect(apps.some((a: any) => a.name === 'Test App')).toBe(true);
+    });
+
+    it('should register manifests from start() phase via manifest service', async () => {
+      // Arrange — simulates SetupPlugin's pattern (registers in start, not init)
+      const plugin = new ObjectQLPlugin();
+      await kernel.use(plugin);
+
+      await kernel.use({
+        name: 'late-registerer',
+        type: 'standard',
+        version: '1.0.0',
+        dependencies: ['com.objectstack.engine.objectql'],
+        init: async () => {},
+        start: async (ctx) => {
+          ctx.getService<{ register(m: any): void }>('manifest').register({
+            id: 'late-app',
+            name: 'late_app',
+            version: '1.0.0',
+            type: 'plugin',
+            apps: [{ name: 'Late App' }],
+          });
+        }
+      });
+
+      // Act
+      await kernel.bootstrap();
+
+      // Assert
+      const objectql = kernel.getService('objectql') as any;
+      const apps = objectql.registry.getAllApps();
+      expect(apps.some((a: any) => a.name === 'Late App')).toBe(true);
+    });
+
+    it('should still discover apps registered via legacy app.* convention', async () => {
+      // Arrange — legacy pattern for backward compatibility
       const mockApp = {
         manifest: {
           id: 'test-app',
@@ -172,9 +235,8 @@ describe('ObjectQLPlugin - Metadata Service Integration', () => {
       // Act
       await kernel.bootstrap();
 
-      // Assert
+      // Assert — legacy pattern still works
       const objectql = kernel.getService('objectql') as any;
-      // App should be registered (check via registry or apps list)
       expect(objectql.registry).toBeDefined();
     });
   });

package/src/plugin.ts

@@ -1,7 +1,6 @@
 // Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { ObjectQL } from './engine.js';
-import { MetadataFacade } from './metadata-facade.js';
 import { ObjectStackProtocolImplementation } from './protocol.js';
 import { Plugin, PluginContext } from '@objectstack/core';
 
@@ -33,45 +32,24 @@ export class ObjectQLPlugin implements Plugin {
     
     // Register as provider for Core Kernel Services
     ctx.registerService('objectql', this.ql);
-    
-    // Register MetadataFacade as metadata service (unless external service exists)
-    let hasMetadata = false;
-    let metadataProvider = 'objectql';
-    try {
-        if (ctx.getService('metadata')) {
-            hasMetadata = true;
-            metadataProvider = 'external';
-        }
-    } catch (e: any) {
-        // Ignore errors during check (e.g. "Service is async")
-    }
 
-    if (!hasMetadata) {
-        try {
-            const metadataFacade = new MetadataFacade();
-            ctx.registerService('metadata', metadataFacade);
-            ctx.logger.info('MetadataFacade registered as metadata service', {
-                mode: 'in-memory',
-                features: ['registry', 'fast-lookup']
-            });
-        } catch (e: any) {
-             // Ignore if already registered (race condition or async mis-detection)
-             if (!e.message?.includes('already registered')) {
-                 throw e;
-             }
-        }
-    } else {
-        ctx.logger.info('External metadata service detected', {
-            provider: metadataProvider,
-            mode: 'will-sync-in-start-phase'
-        });
-    }
-    
     ctx.registerService('data', this.ql); // ObjectQL implements IDataEngine
-    
-    ctx.logger.info('ObjectQL engine registered', { 
-        services: ['objectql', 'data'],
-        metadataProvider: metadataProvider
+
+    // Register manifest service for direct app/package registration.
+    // Plugins call ctx.getService('manifest').register(manifestData)
+    // instead of the legacy ctx.registerService('app.<id>', manifestData) convention.
+    const ql = this.ql;
+    ctx.registerService('manifest', {
+      register: (manifest: any) => {
+        ql.registerApp(manifest);
+        ctx.logger.debug('Manifest registered via manifest service', {
+          id: manifest.id || manifest.name
+        });
+      }
+    });
+
+    ctx.logger.info('ObjectQL engine registered', {
+        services: ['objectql', 'data', 'manifest'],
     });
 
     // Register Protocol Implementation
@@ -86,16 +64,14 @@ export class ObjectQLPlugin implements Plugin {
 
   start = async (ctx: PluginContext) => {
     ctx.logger.info('ObjectQL engine starting...');
-    
-    // Check if we should load from external metadata service
+
+    // Sync from external metadata service (e.g. MetadataPlugin) if available
     try {
         const metadataService = ctx.getService('metadata') as any;
-        // Only sync if metadata service is external (not our own MetadataFacade)
-        if (metadataService && !(metadataService instanceof MetadataFacade) && this.ql) {
+        if (metadataService && typeof metadataService.loadMany === 'function' && this.ql) {
             await this.loadMetadataFromService(metadataService, ctx);
         }
     } catch (e: any) {
-        // No external metadata service or error accessing it
         ctx.logger.debug('No external metadata service to sync from');
     }
     
@@ -109,9 +85,13 @@ export class ObjectQLPlugin implements Plugin {
                  ctx.logger.debug('Discovered and registered driver service', { serviceName: name });
             }
             if (name.startsWith('app.')) {
-                // Register App
+                // Legacy fallback: discover app.* services (DEPRECATED)
+                ctx.logger.warn(
+                    `[DEPRECATED] Service "${name}" uses legacy app.* convention. ` +
+                    `Migrate to ctx.getService('manifest').register(data).`
+                );
                 this.ql.registerApp(service); // service is Manifest
-                ctx.logger.debug('Discovered and registered app service', { serviceName: name });
+                ctx.logger.debug('Discovered and registered app service (legacy)', { serviceName: name });
             }
         }
     }

package/src/protocol.ts

@@ -185,19 +185,22 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         };
     }
 
-    async getMetaItems(request: { type: string }) {
-        let items = SchemaRegistry.listItems(request.type);
+    async getMetaItems(request: { type: string; packageId?: string }) {
+        const { packageId } = request;
+        let items = SchemaRegistry.listItems(request.type, packageId);
         // Normalize singular/plural: REST uses singular ('app') but registry may store as plural ('apps')
         if (items.length === 0) {
             const alt = request.type.endsWith('s') ? request.type.slice(0, -1) : request.type + 's';
-            items = SchemaRegistry.listItems(alt);
+            items = SchemaRegistry.listItems(alt, packageId);
         }
 
         // Fallback to database if registry is empty for this type
         if (items.length === 0) {
             try {
+                const whereClause: any = { type: request.type, state: 'active' };
+                if (packageId) whereClause._packageId = packageId;
                 const allRecords = await this.engine.find('sys_metadata', {
-                    where: { type: request.type, state: 'active' }
+                    where: whereClause
                 });
                 if (allRecords && allRecords.length > 0) {
                     items = allRecords.map((record: any) => {
@@ -235,7 +238,7 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         };
     }
 
-    async getMetaItem(request: { type: string, name: string }) {
+    async getMetaItem(request: { type: string, name: string, packageId?: string }) {
         let item = SchemaRegistry.getItem(request.type, request.name);
         // Normalize singular/plural
         if (item === undefined) {
@@ -481,10 +484,11 @@ export class ObjectStackProtocolImplementation implements ObjectStackProtocol {
         }
         
         const records = await this.engine.find(request.object, options);
+        // Spec: FindDataResponseSchema — only `records` is returned.
+        // OData `value` adaptation (if needed) is handled in the HTTP dispatch layer.
         return {
             object: request.object,
-            value: records, // OData compatibility
-            records, // Legacy
+            records,
             total: records.length,
             hasMore: false
         };

package/src/registry.test.ts

@@ -53,11 +53,15 @@ describe('SchemaRegistry', () => {
             }).not.toThrow();
         });
 
-        it('should throw on namespace conflict', () => {
-            SchemaRegistry.registerNamespace('crm', 'com.example.crm');
-            expect(() => {
-                SchemaRegistry.registerNamespace('crm', 'com.other.crm');
-            }).toThrow(/already registered/);
+        it('should allow multiple packages to share a namespace', () => {
+            SchemaRegistry.registerNamespace('sys', 'com.objectstack.auth');
+            SchemaRegistry.registerNamespace('sys', 'com.objectstack.security');
+            // First registered package returned for backwards compat
+            expect(SchemaRegistry.getNamespaceOwner('sys')).toBe('com.objectstack.auth');
+            expect(SchemaRegistry.getNamespaceOwners('sys')).toEqual([
+                'com.objectstack.auth',
+                'com.objectstack.security',
+            ]);
         });
 
         it('should unregister namespace', () => {
@@ -65,6 +69,13 @@ describe('SchemaRegistry', () => {
             SchemaRegistry.unregisterNamespace('crm', 'com.example.crm');
             expect(SchemaRegistry.getNamespaceOwner('crm')).toBeUndefined();
         });
+
+        it('should keep namespace when one of multiple packages unregisters', () => {
+            SchemaRegistry.registerNamespace('sys', 'com.objectstack.auth');
+            SchemaRegistry.registerNamespace('sys', 'com.objectstack.setup');
+            SchemaRegistry.unregisterNamespace('sys', 'com.objectstack.setup');
+            expect(SchemaRegistry.getNamespaceOwner('sys')).toBe('com.objectstack.auth');
+        });
     });
 
     // ==========================================

package/src/registry.ts

@@ -144,8 +144,8 @@ export class SchemaRegistry {
   /** FQN → Merged ServiceObject (cached, invalidated on changes) */
   private static mergedObjectCache = new Map<string, ServiceObject>();
   
-  /** Namespace → PackageId (ensures namespace uniqueness) */
-  private static namespaceRegistry = new Map<string, string>();
+  /** Namespace → Set<PackageId> (multiple packages can share a namespace) */
+  private static namespaceRegistry = new Map<string, Set<string>>();
 
   // ==========================================
   // Generic metadata storage (non-object types)
@@ -160,22 +160,17 @@ export class SchemaRegistry {
 
   /**
    * Register a namespace for a package.
-   * Enforces namespace uniqueness within the instance.
-   * 
-   * @throws Error if namespace is already registered to a different package
+   * Multiple packages can share the same namespace (e.g. 'sys').
    */
   static registerNamespace(namespace: string, packageId: string): void {
     if (!namespace) return;
-    
-    const existing = this.namespaceRegistry.get(namespace);
-    if (existing && existing !== packageId) {
-      throw new Error(
-        `Namespace "${namespace}" is already registered to package "${existing}". ` +
-        `Package "${packageId}" cannot use the same namespace.`
-      );
+
+    let owners = this.namespaceRegistry.get(namespace);
+    if (!owners) {
+      owners = new Set();
+      this.namespaceRegistry.set(namespace, owners);
     }
-    
-    this.namespaceRegistry.set(namespace, packageId);
+    owners.add(packageId);
     this.log(`[Registry] Registered namespace: ${namespace} → ${packageId}`);
   }
 
@@ -183,18 +178,32 @@ export class SchemaRegistry {
    * Unregister a namespace when a package is uninstalled.
    */
   static unregisterNamespace(namespace: string, packageId: string): void {
-    const existing = this.namespaceRegistry.get(namespace);
-    if (existing === packageId) {
-      this.namespaceRegistry.delete(namespace);
-      this.log(`[Registry] Unregistered namespace: ${namespace}`);
+    const owners = this.namespaceRegistry.get(namespace);
+    if (owners) {
+      owners.delete(packageId);
+      if (owners.size === 0) {
+        this.namespaceRegistry.delete(namespace);
+      }
+      this.log(`[Registry] Unregistered namespace: ${namespace} ← ${packageId}`);
     }
   }
 
   /**
-   * Get the package that owns a namespace.
+   * Get the packages that use a namespace.
    */
   static getNamespaceOwner(namespace: string): string | undefined {
-    return this.namespaceRegistry.get(namespace);
+    const owners = this.namespaceRegistry.get(namespace);
+    if (!owners || owners.size === 0) return undefined;
+    // Return the first registered package for backwards compatibility
+    return owners.values().next().value;
+  }
+
+  /**
+   * Get all packages that share a namespace.
+   */
+  static getNamespaceOwners(namespace: string): string[] {
+    const owners = this.namespaceRegistry.get(namespace);
+    return owners ? Array.from(owners) : [];
   }
 
   // ==========================================
@@ -541,7 +550,7 @@ export class SchemaRegistry {
     if (type === 'object' || type === 'objects') {
       return this.getAllObjects(packageId) as unknown as T[];
     }
-    
+
     const items = Array.from(this.metadata.get(type)?.values() || []) as T[];
     if (packageId) {
       return items.filter((item: any) => item._packageId === packageId);