@objectstack/metadata 0.9.2 → 1.0.1

package/dist/node-metadata-manager.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Node Metadata Manager
+ *
+ * Extends MetadataManager with Filesystem capabilities (Watching, default loader)
+ */
+import { MetadataManager, type MetadataManagerOptions } from './metadata-manager.js';
+/**
+ * Node metadata manager class
+ */
+export declare class NodeMetadataManager extends MetadataManager {
+    private watcher?;
+    constructor(config: MetadataManagerOptions);
+    /**
+     * Stop all watching
+     */
+    stopWatching(): Promise<void>;
+    /**
+     * Start watching for file changes
+     */
+    private startWatching;
+    /**
+     * Handle file change events
+     */
+    private handleFileEvent;
+}
+//# sourceMappingURL=node-metadata-manager.d.ts.map

package/dist/node-metadata-manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-metadata-manager.d.ts","sourceRoot":"","sources":["../src/node-metadata-manager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAErF;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,eAAe;IACtD,OAAO,CAAC,OAAO,CAAC,CAAY;gBAEhB,MAAM,EAAE,sBAAsB;IAgB1C;;OAEG;IACG,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAQnC;;OAEG;IACH,OAAO,CAAC,aAAa;IA0BrB;;OAEG;YACW,eAAe;CA4C9B"}

package/dist/node-metadata-manager.js

@@ -0,0 +1,98 @@
+/**
+ * Node Metadata Manager
+ *
+ * Extends MetadataManager with Filesystem capabilities (Watching, default loader)
+ */
+import * as path from 'node:path';
+import { watch as chokidarWatch } from 'chokidar';
+import { FilesystemLoader } from './loaders/filesystem-loader.js';
+import { MetadataManager } from './metadata-manager.js';
+/**
+ * Node metadata manager class
+ */
+export class NodeMetadataManager extends MetadataManager {
+    constructor(config) {
+        super(config);
+        // Initialize Default Filesystem Loader if no loaders provided
+        // This logic replaces the removed logic from base class
+        if (!config.loaders || config.loaders.length === 0) {
+            const rootDir = config.rootDir || process.cwd();
+            this.registerLoader(new FilesystemLoader(rootDir, this.serializers, this.logger));
+        }
+        // Start watching if enabled
+        if (config.watch) {
+            this.startWatching();
+        }
+    }
+    /**
+     * Stop all watching
+     */
+    async stopWatching() {
+        if (this.watcher) {
+            await this.watcher.close();
+            this.watcher = undefined;
+        }
+        // Call base cleanup if any
+    }
+    /**
+     * Start watching for file changes
+     */
+    startWatching() {
+        const rootDir = this.config.rootDir || process.cwd();
+        const { ignored = ['**/node_modules/**', '**/*.test.*'], persistent = true } = this.config.watchOptions || {};
+        this.watcher = chokidarWatch(rootDir, {
+            ignored,
+            persistent,
+            ignoreInitial: true,
+        });
+        this.watcher.on('add', async (filePath) => {
+            await this.handleFileEvent('added', filePath);
+        });
+        this.watcher.on('change', async (filePath) => {
+            await this.handleFileEvent('changed', filePath);
+        });
+        this.watcher.on('unlink', async (filePath) => {
+            await this.handleFileEvent('deleted', filePath);
+        });
+        this.logger.info('File watcher started', { rootDir });
+    }
+    /**
+     * Handle file change events
+     */
+    async handleFileEvent(eventType, filePath) {
+        const rootDir = this.config.rootDir || process.cwd();
+        const relativePath = path.relative(rootDir, filePath);
+        const parts = relativePath.split(path.sep);
+        if (parts.length < 2) {
+            return; // Not a metadata file
+        }
+        const type = parts[0];
+        const fileName = parts[parts.length - 1];
+        const name = path.basename(fileName, path.extname(fileName));
+        // We can't access private watchCallbacks from parent.
+        // We need a protected method to trigger watch event or access it.
+        // OPTION: Add a method `triggerWatchEvent` to MetadataManager
+        let data = undefined;
+        if (eventType !== 'deleted') {
+            try {
+                data = await this.load(type, name, { useCache: false });
+            }
+            catch (error) {
+                this.logger.error('Failed to load changed file', undefined, {
+                    filePath,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                return;
+            }
+        }
+        const event = {
+            type: eventType,
+            metadataType: type,
+            name,
+            path: filePath,
+            data,
+            timestamp: new Date(),
+        };
+        this.notifyWatchers(type, event);
+    }
+}

package/dist/node.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Node.js specific exports for @objectstack/metadata
+ */
+export * from './index.js';
+export { NodeMetadataManager } from './node-metadata-manager.js';
+export { FilesystemLoader } from './loaders/filesystem-loader.js';
+export { MetadataPlugin } from './plugin.js';
+//# sourceMappingURL=node.d.ts.map

package/dist/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC"}

package/dist/node.js

@@ -0,0 +1,7 @@
+/**
+ * Node.js specific exports for @objectstack/metadata
+ */
+export * from './index.js';
+export { NodeMetadataManager } from './node-metadata-manager.js';
+export { FilesystemLoader } from './loaders/filesystem-loader.js';
+export { MetadataPlugin } from './plugin.js';

package/dist/plugin.d.ts

@@ -9,7 +9,7 @@ export declare class MetadataPlugin implements Plugin {
     private manager;
     private options;
     constructor(options?: MetadataPluginOptions);
-    init(ctx: PluginContext): Promise<void>;
-    start(ctx: PluginContext): Promise<void>;
+    init: (ctx: PluginContext) => Promise<void>;
+    start: (ctx: PluginContext) => Promise<void>;
 }
 //# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAI1D,MAAM,WAAW,qBAAqB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,cAAe,YAAW,MAAM;IACzC,IAAI,SAA8B;IAClC,OAAO,SAAW;IAElB,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,OAAO,CAAwB;gBAE3B,OAAO,GAAE,qBAA0B;IAezC,IAAI,CAAC,GAAG,EAAE,aAAa;IAQvB,KAAK,CAAC,GAAG,EAAE,aAAa;CAiDjC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAI1D,MAAM,WAAW,qBAAqB;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,qBAAa,cAAe,YAAW,MAAM;IACzC,IAAI,SAA8B;IAClC,OAAO,SAAW;IAElB,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,OAAO,CAAwB;gBAE3B,OAAO,GAAE,qBAA0B;IAe/C,IAAI,GAAU,KAAK,aAAa,mBAM/B;IAED,KAAK,GAAU,KAAK,aAAa,mBAgDhC;CACJ"}

package/dist/plugin.js

@@ -1,71 +1,71 @@
-import { MetadataManager } from './metadata-manager.js';
+import { NodeMetadataManager } from './node-metadata-manager.js';
 import { ObjectStackDefinitionSchema } from '@objectstack/spec';
 export class MetadataPlugin {
     constructor(options = {}) {
         this.name = 'com.objectstack.metadata';
         this.version = '1.0.0';
+        this.init = async (ctx) => {
+            ctx.logger.info('Initializing Metadata Manager', { root: this.options.rootDir || process.cwd() });
+            // Register Metadata Manager as a service
+            // This allows other plugins to query raw metadata or listen to changes
+            ctx.registerService('metadata', this.manager);
+        };
+        this.start = async (ctx) => {
+            ctx.logger.info('Loading metadata...');
+            // Define metadata types directly from the Protocol Definition
+            // This ensures the loader is always in sync with the Spec
+            const metadataTypes = Object.keys(ObjectStackDefinitionSchema.shape)
+                .filter(key => key !== 'manifest'); // Manifest is handled separately
+            for (const type of metadataTypes) {
+                try {
+                    // Try to load metadata of this type
+                    const items = await this.manager.loadMany(type, {
+                        recursive: true
+                    });
+                    if (items.length > 0) {
+                        ctx.logger.info(`Loaded ${items.length} ${type}`);
+                        // Helper: Register with ObjectQL Registry
+                        const ql = ctx.getService('objectql');
+                        if (ql && ql.registry) {
+                            items.forEach((item) => {
+                                // Determine key field (id or name)
+                                const keyField = item.id ? 'id' : 'name';
+                                // Map plural type to singular/registry type if needed
+                                // For now, we use the singular form for standard types: 
+                                // objects -> object, apps -> app, etc.
+                                // But Registry seems to accept arbitrary strings.
+                                // To match Protocol standard, we might want to normalize.
+                                // Let's use the directory name (plural) as the type for now,
+                                // OR map 'objects' -> 'object' specifically.
+                                let registryType = type;
+                                if (type === 'objects')
+                                    registryType = 'object';
+                                if (type === 'apps')
+                                    registryType = 'app';
+                                if (type === 'plugins')
+                                    registryType = 'plugin';
+                                if (type === 'functions')
+                                    registryType = 'function';
+                                ql.registry.registerItem(registryType, item, keyField);
+                            });
+                        }
+                    }
+                }
+                catch (e) {
+                    // Ignore missing directories or errors
+                    // ctx.logger.debug(`No metadata found for type: ${type}`);
+                }
+            }
+        };
         this.options = {
             watch: true,
             ...options
         };
         const rootDir = this.options.rootDir || process.cwd();
-        this.manager = new MetadataManager({
+        this.manager = new NodeMetadataManager({
             rootDir,
             watch: this.options.watch ?? true,
             formats: ['yaml', 'json', 'typescript', 'javascript']
         });
     }
-    async init(ctx) {
-        ctx.logger.info('Initializing Metadata Manager', { root: this.options.rootDir || process.cwd() });
-        // Register Metadata Manager as a service
-        // This allows other plugins to query raw metadata or listen to changes
-        ctx.registerService('metadata', this.manager);
-    }
-    async start(ctx) {
-        ctx.logger.info('Loading metadata...');
-        // Define metadata types directly from the Protocol Definition
-        // This ensures the loader is always in sync with the Spec
-        const metadataTypes = Object.keys(ObjectStackDefinitionSchema.shape)
-            .filter(key => key !== 'manifest'); // Manifest is handled separately
-        for (const type of metadataTypes) {
-            try {
-                // Try to load metadata of this type
-                const items = await this.manager.loadMany(type, {
-                    recursive: true
-                });
-                if (items.length > 0) {
-                    ctx.logger.info(`Loaded ${items.length} ${type}`);
-                    // Helper: Register with ObjectQL Registry
-                    const ql = ctx.getService('objectql');
-                    if (ql && ql.registry) {
-                        items.forEach((item) => {
-                            // Determine key field (id or name)
-                            const keyField = item.id ? 'id' : 'name';
-                            // Map plural type to singular/registry type if needed
-                            // For now, we use the singular form for standard types: 
-                            // objects -> object, apps -> app, etc.
-                            // But Registry seems to accept arbitrary strings.
-                            // To match Protocol standard, we might want to normalize.
-                            // Let's use the directory name (plural) as the type for now,
-                            // OR map 'objects' -> 'object' specifically.
-                            let registryType = type;
-                            if (type === 'objects')
-                                registryType = 'object';
-                            if (type === 'apps')
-                                registryType = 'app';
-                            if (type === 'plugins')
-                                registryType = 'plugin';
-                            if (type === 'functions')
-                                registryType = 'function';
-                            ql.registry.registerItem(registryType, item, keyField);
-                        });
-                    }
-                }
-            }
-            catch (e) {
-                // Ignore missing directories or errors
-                // ctx.logger.debug(`No metadata found for type: ${type}`);
-            }
-        }
-    }
 }

package/package.json

@@ -1,9 +1,22 @@
 {
   "name": "@objectstack/metadata",
-  "version": "0.9.2",
+  "version": "1.0.1",
+  "license": "Apache-2.0",
   "description": "Metadata loading, saving, and persistence for ObjectStack",
   "main": "src/index.ts",
   "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts",
+      "default": "./src/index.ts"
+    },
+    "./node": {
+      "types": "./src/node.ts",
+      "import": "./src/node.ts",
+      "default": "./src/node.ts"
+    }
+  },
   "keywords": [
     "objectstack",
     "metadata",
@@ -16,9 +29,9 @@
     "js-yaml": "^4.1.0",
     "chokidar": "^3.5.3",
     "zod": "^4.3.6",
-    "@objectstack/core": "0.9.2",
-    "@objectstack/spec": "0.9.2",
-    "@objectstack/types": "0.9.2"
+    "@objectstack/core": "1.0.1",
+    "@objectstack/spec": "1.0.1",
+    "@objectstack/types": "1.0.1"
   },
   "devDependencies": {
     "@types/js-yaml": "^4.0.9",

package/src/index.ts

@@ -5,14 +5,15 @@
  */
 
 // Main Manager
-export { MetadataManager, type WatchCallback } from './metadata-manager.js';
+export { MetadataManager, type WatchCallback, type MetadataManagerOptions } from './metadata-manager.js';
 
 // Plugin
 export { MetadataPlugin } from './plugin.js';
 
 // Loaders
 export { type MetadataLoader } from './loaders/loader-interface.js';
-export { FilesystemLoader } from './loaders/filesystem-loader.js';
+export { MemoryLoader } from './loaders/memory-loader.js';
+export { RemoteLoader } from './loaders/remote-loader.js';
 
 // Serializers
 export { type MetadataSerializer, type SerializeOptions } from './serializers/serializer-interface.js';

package/src/loaders/filesystem-loader.ts

@@ -14,6 +14,8 @@ import type {
   MetadataStats,
   MetadataLoaderContract,
   MetadataFormat,
+  MetadataSaveOptions,
+  MetadataSaveResult,
 } from '@objectstack/spec/system';
 import type { Logger } from '@objectstack/core';
 import type { MetadataLoader } from './loader-interface.js';
@@ -22,6 +24,13 @@ import type { MetadataSerializer } from '../serializers/serializer-interface.js'
 export class FilesystemLoader implements MetadataLoader {
   readonly contract: MetadataLoaderContract = {
     name: 'filesystem',
+    protocol: 'file',
+    capabilities: {
+      read: true,
+      write: true,
+      watch: true,
+      list: true,
+    },
     supportedFormats: ['json', 'yaml', 'typescript', 'javascript'],
     supportsWatch: true,
     supportsWrite: true,
@@ -99,7 +108,7 @@ export class FilesystemLoader implements MetadataLoader {
 
       // Load and deserialize
       const content = await fs.readFile(filePath, 'utf-8');
-      const serializer = this.getSerializer(stats.format);
+      const serializer = this.getSerializer(stats.format!);
 
       if (!serializer) {
         throw new Error(`No serializer found for format: ${stats.format}`);
@@ -111,7 +120,7 @@ export class FilesystemLoader implements MetadataLoader {
       if (useCache) {
         this.cache.set(cacheKey, {
           data,
-          etag: stats.etag,
+          etag: stats.etag || '',
           timestamp: Date.now(),
         });
       }
@@ -253,6 +262,101 @@ export class FilesystemLoader implements MetadataLoader {
     }
   }
 
+  async save(
+    type: string,
+    name: string,
+    data: any,
+    options?: MetadataSaveOptions
+  ): Promise<MetadataSaveResult> {
+    const startTime = Date.now();
+    const {
+      format = 'typescript',
+      prettify = true,
+      indent = 2,
+      sortKeys = false,
+      backup = false,
+      overwrite = true,
+      atomic = true,
+      path: customPath,
+    } = options || {};
+
+    try {
+      // Get serializer
+      const serializer = this.getSerializer(format);
+      if (!serializer) {
+        throw new Error(`No serializer found for format: ${format}`);
+      }
+
+      // Determine file path
+      const typeDir = path.join(this.rootDir, type);
+      const fileName = `${name}${serializer.getExtension()}`;
+      const filePath = customPath || path.join(typeDir, fileName);
+
+      // Check if file exists
+      if (!overwrite) {
+        try {
+          await fs.access(filePath);
+          throw new Error(`File already exists: ${filePath}`);
+        } catch (error) {
+          // File doesn't exist, continue
+          if ((error as NodeJS.ErrnoException).code !== 'ENOENT') {
+            throw error;
+          }
+        }
+      }
+
+      // Create directory if it doesn't exist
+      await fs.mkdir(path.dirname(filePath), { recursive: true });
+
+      // Create backup if requested
+      let backupPath: string | undefined;
+      if (backup) {
+        try {
+          await fs.access(filePath);
+          backupPath = `${filePath}.bak`;
+          await fs.copyFile(filePath, backupPath);
+        } catch {
+          // File doesn't exist, no backup needed
+        }
+      }
+
+      // Serialize data
+      const content = serializer.serialize(data, {
+        prettify,
+        indent,
+        sortKeys,
+      });
+
+      // Write to disk (atomic or direct)
+      if (atomic) {
+        const tempPath = `${filePath}.tmp`;
+        await fs.writeFile(tempPath, content, 'utf-8');
+        await fs.rename(tempPath, filePath);
+      } else {
+        await fs.writeFile(filePath, content, 'utf-8');
+      }
+
+      // Update cache logic if needed (e.g., invalidate or update)
+      // For now, we rely on the watcher to pick up changes
+
+      return {
+        success: true,
+        path: filePath,
+        // format, // Not in schema
+        size: Buffer.byteLength(content, 'utf-8'),
+        backupPath,
+        saveTime: Date.now() - startTime,
+      };
+    } catch (error) {
+      this.logger?.error('Failed to save metadata', undefined, {
+        type,
+        name,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      throw error;
+    }
+  }
+
   /**
    * Find file for a given type and name
    */

package/src/loaders/loader-interface.ts

@@ -9,6 +9,8 @@ import type {
   MetadataLoadResult,
   MetadataStats,
   MetadataLoaderContract,
+  MetadataSaveOptions,
+  MetadataSaveResult,
 } from '@objectstack/spec/system';
 
 /**
@@ -67,4 +69,19 @@ export interface MetadataLoader {
    * @returns Array of item names
    */
   list(type: string): Promise<string[]>;
+
+  /**
+   * Save metadata item
+   * @param type The metadata type
+   * @param name The item name
+   * @param data The data to save
+   * @param options Save options
+   */
+  save?(
+    type: string,
+    name: string,
+    data: any,
+    options?: MetadataSaveOptions
+  ): Promise<MetadataSaveResult>;
 }
+

package/src/loaders/memory-loader.ts

@@ -0,0 +1,101 @@
+/**
+ * Memory Metadata Loader
+ * 
+ * Stores metadata in memory only. Changes are lost when process restarts.
+ * Useful for testing, temporary overrides, or "dirty" edits.
+ */
+
+import type {
+  MetadataLoadOptions,
+  MetadataLoadResult,
+  MetadataStats,
+  MetadataLoaderContract,
+  MetadataSaveOptions,
+  MetadataSaveResult,
+} from '@objectstack/spec/system';
+import type { MetadataLoader } from './loader-interface.js';
+
+export class MemoryLoader implements MetadataLoader {
+  readonly contract: MetadataLoaderContract = {
+    name: 'memory',
+    protocol: 'memory',
+    capabilities: {
+      read: true,
+      write: true,
+      watch: false,
+      list: true,
+    },
+  };
+
+  // Storage: Type -> Name -> Data
+  private storage = new Map<string, Map<string, any>>();
+
+  async load(
+    type: string,
+    name: string,
+    _options?: MetadataLoadOptions
+  ): Promise<MetadataLoadResult> {
+    const typeStore = this.storage.get(type);
+    const data = typeStore?.get(name);
+
+    if (data) {
+      return {
+        data,
+        source: 'memory',
+        format: 'json',
+        loadTime: 0,
+      };
+    }
+
+    return { data: null };
+  }
+
+  async loadMany<T = any>(
+    type: string,
+    _options?: MetadataLoadOptions
+  ): Promise<T[]> {
+    const typeStore = this.storage.get(type);
+    if (!typeStore) return [];
+    return Array.from(typeStore.values()) as T[];
+  }
+
+  async exists(type: string, name: string): Promise<boolean> {
+    return this.storage.get(type)?.has(name) ?? false;
+  }
+
+  async stat(type: string, name: string): Promise<MetadataStats | null> {
+    if (await this.exists(type, name)) {
+      return {
+        size: 0, // In-memory
+        mtime: new Date(),
+        format: 'json',
+      };
+    }
+    return null;
+  }
+
+  async list(type: string): Promise<string[]> {
+    const typeStore = this.storage.get(type);
+    if (!typeStore) return [];
+    return Array.from(typeStore.keys());
+  }
+
+  async save(
+    type: string,
+    name: string,
+    data: any,
+    _options?: MetadataSaveOptions
+  ): Promise<MetadataSaveResult> {
+    if (!this.storage.has(type)) {
+      this.storage.set(type, new Map());
+    }
+    
+    this.storage.get(type)!.set(name, data);
+
+    return {
+      success: true,
+      path: `memory://${type}/${name}`,
+      saveTime: 0,
+    };
+  }
+}