Merge pull request #619 from objectstack-ai/copilot/upgrade-metadata-datasource

Author: hotlong

packages/objectql/src/metadata-facade.ts

@@ -8,12 +8,18 @@ import { SchemaRegistry } from './registry.js';
  * Provides a clean, injectable interface over SchemaRegistry.
  * Registered as the 'metadata' kernel service to eliminate
  * downstream packages needing to manually wrap SchemaRegistry.
+ * 
+ * Implements the async IMetadataService interface.
+ * Internally delegates to SchemaRegistry (in-memory) with Promise wrappers.
  */
 export class MetadataFacade {
   /**
    * Register a metadata item
    */
-  register(type: string, definition: any): void {
+  async register(type: string, name: string, data: any): Promise<void> {
+    const definition = typeof data === 'object' && data !== null
+      ? { ...data, name: data.name ?? name }
+      : data;
     if (type === 'object') {
       SchemaRegistry.registerItem(type, definition, 'name' as any);
     } else {
@@ -24,7 +30,7 @@ export class MetadataFacade {
   /**
    * Get a metadata item by type and name
    */
-  get(type: string, name: string): any {
+  async get(type: string, name: string): Promise<any> {
     const item = SchemaRegistry.getItem(type, name) as any;
     return item?.content ?? item;
   }
@@ -39,36 +45,52 @@ export class MetadataFacade {
   /**
    * List all items of a type
    */
-  list(type: string): any[] {
+  async list(type: string): Promise<any[]> {
     const items = SchemaRegistry.listItems(type);
     return items.map((item: any) => item?.content ?? item);
   }
 
   /**
    * Unregister a metadata item
    */
-  unregister(type: string, name: string): void {
+  async unregister(type: string, name: string): Promise<void> {
     SchemaRegistry.unregisterItem(type, name);
   }
 
+  /**
+   * Check if a metadata item exists
+   */
+  async exists(type: string, name: string): Promise<boolean> {
+    const item = SchemaRegistry.getItem(type, name);
+    return item !== undefined && item !== null;
+  }
+
+  /**
+   * List all names of metadata items of a given type
+   */
+  async listNames(type: string): Promise<string[]> {
+    const items = SchemaRegistry.listItems(type);
+    return items.map((item: any) => item?.name ?? item?.content?.name ?? '').filter(Boolean);
+  }
+
   /**
    * Unregister all metadata from a package
    */
-  unregisterPackage(packageName: string): void {
+  async unregisterPackage(packageName: string): Promise<void> {
     SchemaRegistry.unregisterObjectsByPackage(packageName);
   }
 
   /**
    * Convenience: get object definition
    */
-  getObject(name: string): any {
+  async getObject(name: string): Promise<any> {
     return SchemaRegistry.getObject(name);
   }
 
   /**
    * Convenience: list all objects
    */
-  listObjects(): any[] {
+  async listObjects(): Promise<any[]> {
     return SchemaRegistry.getAllObjects();
   }
 }

packages/plugins/plugin-dev/src/dev-plugin.ts

@@ -276,16 +276,18 @@ function createMetadataStub() {
   const store = new Map<string, Map<string, unknown>>(); // type → (name → def)
   return {
     _dev: true, _serviceName: 'metadata',
-    register(type: string, definition: any) {
+    async register(type: string, name: string, data: unknown) {
       if (!store.has(type)) store.set(type, new Map());
-      store.get(type)!.set(definition.name ?? '', definition);
+      store.get(type)!.set(name, data);
     },
-    get(type: string, name: string) { return store.get(type)?.get(name); },
-    list(type: string) { return [...(store.get(type)?.values() ?? [])]; },
-    unregister(type: string, name: string) { store.get(type)?.delete(name); },
-    getObject(name: string) { return store.get('object')?.get(name); },
-    listObjects() { return [...(store.get('object')?.values() ?? [])]; },
-    unregisterPackage() {},
+    async get(type: string, name: string) { return store.get(type)?.get(name); },
+    async list(type: string) { return [...(store.get(type)?.values() ?? [])]; },
+    async unregister(type: string, name: string) { store.get(type)?.delete(name); },
+    async exists(type: string, name: string) { return store.get(type)?.has(name) ?? false; },
+    async listNames(type: string) { return [...(store.get(type)?.keys() ?? [])]; },
+    async getObject(name: string) { return store.get('object')?.get(name); },
+    async listObjects() { return [...(store.get('object')?.values() ?? [])]; },
+    async unregisterPackage() {},
   };
 }
 

packages/spec/src/contracts/metadata-service.test.ts

@@ -4,85 +4,97 @@ import type { IMetadataService } from './metadata-service';
 describe('Metadata Service Contract', () => {
   it('should allow a minimal IMetadataService implementation with required methods', () => {
     const service: IMetadataService = {
-      register: (_type, _definition) => {},
-      get: (_type, _name) => undefined,
-      list: (_type) => [],
-      unregister: (_type, _name) => {},
-      getObject: (_name) => undefined,
-      listObjects: () => [],
+      register: async (_type, _name, _data) => {},
+      get: async (_type, _name) => undefined,
+      list: async (_type) => [],
+      unregister: async (_type, _name) => {},
+      exists: async (_type, _name) => false,
+      listNames: async (_type) => [],
+      getObject: async (_name) => undefined,
+      listObjects: async () => [],
     };
 
     expect(typeof service.register).toBe('function');
     expect(typeof service.get).toBe('function');
     expect(typeof service.list).toBe('function');
     expect(typeof service.unregister).toBe('function');
+    expect(typeof service.exists).toBe('function');
+    expect(typeof service.listNames).toBe('function');
     expect(typeof service.getObject).toBe('function');
     expect(typeof service.listObjects).toBe('function');
   });
 
   it('should allow a full implementation with optional methods', () => {
     const service: IMetadataService = {
-      register: () => {},
-      get: () => undefined,
-      list: () => [],
-      unregister: () => {},
-      getObject: () => undefined,
-      listObjects: () => [],
-      unregisterPackage: (_packageName) => {},
+      register: async () => {},
+      get: async () => undefined,
+      list: async () => [],
+      unregister: async () => {},
+      exists: async () => false,
+      listNames: async () => [],
+      getObject: async () => undefined,
+      listObjects: async () => [],
+      unregisterPackage: async (_packageName) => {},
     };
 
     expect(service.unregisterPackage).toBeDefined();
   });
 
-  it('should register and retrieve metadata items', () => {
+  it('should register and retrieve metadata items asynchronously', async () => {
     const store = new Map<string, Map<string, unknown>>();
 
     const service: IMetadataService = {
-      register: (type, definition) => {
+      register: async (type, name, data) => {
         if (!store.has(type)) store.set(type, new Map());
-        const def = definition as { name: string };
-        store.get(type)!.set(def.name, definition);
+        store.get(type)!.set(name, data);
       },
-      get: (type, name) => store.get(type)?.get(name),
-      list: (type) => Array.from(store.get(type)?.values() ?? []),
-      unregister: (type, name) => { store.get(type)?.delete(name); },
-      getObject: (name) => store.get('object')?.get(name),
-      listObjects: () => Array.from(store.get('object')?.values() ?? []),
+      get: async (type, name) => store.get(type)?.get(name),
+      list: async (type) => Array.from(store.get(type)?.values() ?? []),
+      unregister: async (type, name) => { store.get(type)?.delete(name); },
+      exists: async (type, name) => store.get(type)?.has(name) ?? false,
+      listNames: async (type) => Array.from(store.get(type)?.keys() ?? []),
+      getObject: async (name) => store.get('object')?.get(name),
+      listObjects: async () => Array.from(store.get('object')?.values() ?? []),
     };
 
     const objectDef = { name: 'account', label: 'Account', fields: {} };
-    service.register('object', objectDef);
+    await service.register('object', 'account', objectDef);
 
-    expect(service.get('object', 'account')).toEqual(objectDef);
-    expect(service.getObject('account')).toEqual(objectDef);
-    expect(service.listObjects()).toHaveLength(1);
+    expect(await service.get('object', 'account')).toEqual(objectDef);
+    expect(await service.getObject('account')).toEqual(objectDef);
+    expect(await service.listObjects()).toHaveLength(1);
+    expect(await service.exists('object', 'account')).toBe(true);
+    expect(await service.listNames('object')).toEqual(['account']);
 
-    service.unregister('object', 'account');
-    expect(service.get('object', 'account')).toBeUndefined();
+    await service.unregister('object', 'account');
+    expect(await service.get('object', 'account')).toBeUndefined();
+    expect(await service.exists('object', 'account')).toBe(false);
   });
 
-  it('should list items by type', () => {
+  it('should list items by type', async () => {
     const store = new Map<string, Map<string, unknown>>();
 
     const service: IMetadataService = {
-      register: (type, definition) => {
+      register: async (type, name, data) => {
         if (!store.has(type)) store.set(type, new Map());
-        const def = definition as { name: string };
-        store.get(type)!.set(def.name, definition);
+        store.get(type)!.set(name, data);
       },
-      get: (type, name) => store.get(type)?.get(name),
-      list: (type) => Array.from(store.get(type)?.values() ?? []),
-      unregister: (type, name) => { store.get(type)?.delete(name); },
-      getObject: (name) => store.get('object')?.get(name),
-      listObjects: () => Array.from(store.get('object')?.values() ?? []),
+      get: async (type, name) => store.get(type)?.get(name),
+      list: async (type) => Array.from(store.get(type)?.values() ?? []),
+      unregister: async (type, name) => { store.get(type)?.delete(name); },
+      exists: async (type, name) => store.get(type)?.has(name) ?? false,
+      listNames: async (type) => Array.from(store.get(type)?.keys() ?? []),
+      getObject: async (name) => store.get('object')?.get(name),
+      listObjects: async () => Array.from(store.get('object')?.values() ?? []),
     };
 
-    service.register('object', { name: 'account', label: 'Account' });
-    service.register('object', { name: 'contact', label: 'Contact' });
-    service.register('view', { name: 'account_list', label: 'Account List' });
+    await service.register('object', 'account', { name: 'account', label: 'Account' });
+    await service.register('object', 'contact', { name: 'contact', label: 'Contact' });
+    await service.register('view', 'account_list', { name: 'account_list', label: 'Account List' });
 
-    expect(service.list('object')).toHaveLength(2);
-    expect(service.list('view')).toHaveLength(1);
-    expect(service.list('flow')).toHaveLength(0);
+    expect(await service.list('object')).toHaveLength(2);
+    expect(await service.list('view')).toHaveLength(1);
+    expect(await service.list('flow')).toHaveLength(0);
+    expect(await service.listNames('object')).toEqual(['account', 'contact']);
   });
 });

packages/spec/src/contracts/metadata-service.ts

@@ -3,10 +3,12 @@
 /**
  * IMetadataService - Metadata Service Contract
  *
- * Defines the interface for managing object/field definitions in ObjectStack.
+ * Defines the async interface for managing object/field definitions in ObjectStack.
  * Concrete implementations (SchemaRegistry, Database-backed, etc.)
  * should implement this interface.
  *
+ * All methods are async to support database-backed persistence via datasource.
+ *
  * Follows Dependency Inversion Principle - plugins depend on this interface,
  * not on concrete metadata storage implementations.
  *
@@ -15,50 +17,66 @@
 
 export interface IMetadataService {
     /**
-     * Register a metadata item by type
+     * Register/save a metadata item by type
      * @param type - Metadata type (e.g. 'object', 'view', 'flow')
-     * @param definition - The metadata definition to register
+     * @param name - Item name/identifier (snake_case)
+     * @param data - The metadata definition to register
      */
-    register(type: string, definition: unknown): void;
+    register(type: string, name: string, data: unknown): Promise<void>;
 
     /**
      * Get a metadata item by type and name
      * @param type - Metadata type
      * @param name - Item name/identifier
      * @returns The metadata definition, or undefined if not found
      */
-    get(type: string, name: string): unknown | undefined;
+    get(type: string, name: string): Promise<unknown | undefined>;
 
     /**
      * List all metadata items of a given type
      * @param type - Metadata type
      * @returns Array of metadata definitions
      */
-    list(type: string): unknown[];
+    list(type: string): Promise<unknown[]>;
+
+    /**
+     * Unregister/remove a metadata item by type and name
+     * @param type - Metadata type
+     * @param name - Item name/identifier
+     */
+    unregister(type: string, name: string): Promise<void>;
 
     /**
-     * Unregister a metadata item by type and name
+     * Check if a metadata item exists
      * @param type - Metadata type
      * @param name - Item name/identifier
+     * @returns True if the item exists
+     */
+    exists(type: string, name: string): Promise<boolean>;
+
+    /**
+     * List all names of metadata items of a given type
+     * @param type - Metadata type
+     * @returns Array of item names
      */
-    unregister(type: string, name: string): void;
+    listNames(type: string): Promise<string[]>;
 
     /**
      * Convenience: get an object definition by name
      * @param name - Object name (snake_case)
      * @returns The object definition, or undefined if not found
      */
-    getObject(name: string): unknown | undefined;
+    getObject(name: string): Promise<unknown | undefined>;
 
     /**
      * Convenience: list all object definitions
      * @returns Array of object definitions
      */
-    listObjects(): unknown[];
+    listObjects(): Promise<unknown[]>;
 
     /**
      * Unregister all metadata items from a specific package
      * @param packageName - The package name whose items should be removed
      */
-    unregisterPackage?(packageName: string): void;
+    unregisterPackage?(packageName: string): Promise<void>;
 }