@objectstack/metadata 1.0.0 → 1.0.2

package/dist/metadata-manager.js

@@ -1,14 +1,10 @@
 /**
  * Metadata Manager
  *
- * Main orchestrator for metadata loading, saving, and persistence
+ * Main orchestrator for metadata loading, saving, and persistence.
+ * Browser-compatible (Pure).
  */
-import * as fs from 'node:fs/promises';
-import * as path from 'node:path';
-import { createHash } from 'node:crypto';
-import { watch as chokidarWatch } from 'chokidar';
 import { createLogger } from '@objectstack/core';
-import { FilesystemLoader } from './loaders/filesystem-loader.js';
 import { JSONSerializer } from './serializers/json-serializer.js';
 import { YAMLSerializer } from './serializers/yaml-serializer.js';
 import { TypeScriptSerializer } from './serializers/typescript-serializer.js';
@@ -17,8 +13,9 @@ import { TypeScriptSerializer } from './serializers/typescript-serializer.js';
  */
 export class MetadataManager {
     constructor(config) {
-        this.config = config;
+        this.loaders = new Map();
         this.watchCallbacks = new Map();
+        this.config = config;
         this.logger = createLogger({ level: 'info', format: 'pretty' });
         // Initialize serializers
         this.serializers = new Map();
@@ -35,117 +32,138 @@ export class MetadataManager {
         if (formats.includes('javascript')) {
             this.serializers.set('javascript', new TypeScriptSerializer('javascript'));
         }
-        // Initialize loader
-        const rootDir = config.rootDir || process.cwd();
-        this.loader = new FilesystemLoader(rootDir, this.serializers, this.logger);
-        // Start watching if enabled
-        if (config.watch) {
-            this.startWatching();
+        // Initialize Loaders
+        if (config.loaders && config.loaders.length > 0) {
+            config.loaders.forEach(loader => this.registerLoader(loader));
         }
+        // Note: No default loader in base class. Subclasses (NodeMetadataManager) or caller must provide one.
+    }
+    /**
+     * Register a new metadata loader (data source)
+     */
+    registerLoader(loader) {
+        this.loaders.set(loader.contract.name, loader);
+        this.logger.info(`Registered metadata loader: ${loader.contract.name} (${loader.contract.protocol})`);
     }
     /**
      * Load a single metadata item
+     * Iterates through registered loaders until found
      */
     async load(type, name, options) {
-        const result = await this.loader.load(type, name, options);
-        return result.data;
+        // Priority: Database > Filesystem (Implementation-dependent)
+        // For now, we just iterate.
+        for (const loader of this.loaders.values()) {
+            try {
+                const result = await loader.load(type, name, options);
+                if (result.data) {
+                    return result.data;
+                }
+            }
+            catch (e) {
+                this.logger.warn(`Loader ${loader.contract.name} failed to load ${type}:${name}`, { error: e });
+            }
+        }
+        return null;
     }
     /**
      * Load multiple metadata items
+     * Aggregates results from all loaders
      */
     async loadMany(type, options) {
-        return this.loader.loadMany(type, options);
+        const results = [];
+        for (const loader of this.loaders.values()) {
+            try {
+                const items = await loader.loadMany(type, options);
+                for (const item of items) {
+                    // TODO: Deduplicate based on 'name' if property exists
+                    results.push(item);
+                }
+            }
+            catch (e) {
+                this.logger.warn(`Loader ${loader.contract.name} failed to loadMany ${type}`, { error: e });
+            }
+        }
+        return results;
     }
     /**
      * Save metadata to disk
      */
+    /**
+     * Save metadata item
+     */
     async save(type, name, data, options) {
-        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.serializers.get(format);
-            if (!serializer) {
-                throw new Error(`No serializer found for format: ${format}`);
+        const targetLoader = options?.loader;
+        // Find suitable loader
+        let loader;
+        if (targetLoader) {
+            loader = this.loaders.get(targetLoader);
+            if (!loader) {
+                throw new Error(`Loader not found: ${targetLoader}`);
             }
-            // Determine file path
-            const typeDir = path.join(this.config.rootDir || process.cwd(), type);
-            const fileName = `${name}${serializer.getExtension()}`;
-            const filePath = customPath || path.join(typeDir, fileName);
-            // Check if file exists
-            if (!overwrite) {
+        }
+        else {
+            // 1. Try to find existing writable loader containing this item (Update existing)
+            for (const l of this.loaders.values()) {
+                // Skip if loader is strictly read-only
+                if (!l.save)
+                    continue;
                 try {
-                    await fs.access(filePath);
-                    throw new Error(`File already exists: ${filePath}`);
-                }
-                catch (error) {
-                    // File doesn't exist, continue
-                    if (error.code !== 'ENOENT') {
-                        throw error;
+                    if (await l.exists(type, name)) {
+                        loader = l;
+                        this.logger.info(`Updating existing metadata in loader: ${l.contract.name}`);
+                        break;
                     }
                 }
-            }
-            // Create directory if it doesn't exist
-            await fs.mkdir(path.dirname(filePath), { recursive: true });
-            // Create backup if requested
-            let backupPath;
-            if (backup) {
-                try {
-                    await fs.access(filePath);
-                    backupPath = `${filePath}.bak`;
-                    await fs.copyFile(filePath, backupPath);
-                }
-                catch {
-                    // File doesn't exist, no backup needed
+                catch (e) {
+                    // Ignore existence check errors (e.g. network down)
                 }
             }
-            // 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);
+            // 2. Default to 'filesystem' if available (Create new)
+            if (!loader) {
+                const fsLoader = this.loaders.get('filesystem');
+                if (fsLoader && fsLoader.save) {
+                    loader = fsLoader;
+                }
             }
-            else {
-                await fs.writeFile(filePath, content, 'utf-8');
+            // 3. Fallback to any writable loader
+            if (!loader) {
+                for (const l of this.loaders.values()) {
+                    if (l.save) {
+                        loader = l;
+                        break;
+                    }
+                }
             }
-            // Get stats
-            const stats = await fs.stat(filePath);
-            const etag = this.generateETag(content);
-            return {
-                success: true,
-                path: filePath,
-                etag,
-                size: stats.size,
-                saveTime: Date.now() - startTime,
-                backupPath,
-            };
         }
-        catch (error) {
-            this.logger.error('Failed to save metadata', undefined, {
-                type,
-                name,
-                error: error instanceof Error ? error.message : String(error),
-            });
-            throw error;
+        if (!loader) {
+            throw new Error(`No loader available for saving type: ${type}`);
+        }
+        if (!loader.save) {
+            throw new Error(`Loader '${loader.contract?.name}' does not support saving`);
         }
+        return loader.save(type, name, data, options);
     }
     /**
      * Check if metadata item exists
      */
     async exists(type, name) {
-        return this.loader.exists(type, name);
+        for (const loader of this.loaders.values()) {
+            if (await loader.exists(type, name)) {
+                return true;
+            }
+        }
+        return false;
     }
     /**
      * List all items of a type
      */
     async list(type) {
-        return this.loader.list(type);
+        const items = new Set();
+        for (const loader of this.loaders.values()) {
+            const result = await loader.list(type);
+            result.forEach(item => items.add(item));
+        }
+        return Array.from(items);
     }
     /**
      * Watch for metadata changes
@@ -172,92 +190,22 @@ export class MetadataManager {
      * Stop all watching
      */
     async stopWatching() {
-        if (this.watcher) {
-            await this.watcher.close();
-            this.watcher = undefined;
-            this.watchCallbacks.clear();
-        }
+        // Override in subclass
     }
-    /**
-     * 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));
+    notifyWatchers(type, event) {
         const callbacks = this.watchCallbacks.get(type);
-        if (!callbacks || callbacks.size === 0) {
+        if (!callbacks)
             return;
-        }
-        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(),
-        };
         for (const callback of callbacks) {
             try {
-                await callback(event);
+                void callback(event);
             }
             catch (error) {
                 this.logger.error('Watch callback error', undefined, {
                     type,
-                    name,
                     error: error instanceof Error ? error.message : String(error),
                 });
             }
         }
     }
-    /**
-     * Generate ETag for content
-     * Uses SHA-256 hash truncated to 32 characters for reasonable collision resistance
-     * while keeping ETag headers compact (full 64-char hash is overkill for this use case)
-     */
-    generateETag(content) {
-        const hash = createHash('sha256').update(content).digest('hex').substring(0, 32);
-        return `"${hash}"`;
-    }
 }

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.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;IAe/C,IAAI,GAAU,KAAK,aAAa,mBAM/B;IAED,KAAK,GAAU,KAAK,aAAa,mBAgDhC;CACJ"}
+{"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,4 +1,4 @@
-import { MetadataManager } from './metadata-manager.js';
+import { NodeMetadataManager } from './node-metadata-manager.js';
 import { ObjectStackDefinitionSchema } from '@objectstack/spec';
 export class MetadataPlugin {
     constructor(options = {}) {
@@ -62,7 +62,7 @@ export class MetadataPlugin {
             ...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']

package/package.json

@@ -1,10 +1,22 @@
 {
   "name": "@objectstack/metadata",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "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",
@@ -17,9 +29,9 @@
     "js-yaml": "^4.1.0",
     "chokidar": "^3.5.3",
     "zod": "^4.3.6",
-    "@objectstack/core": "1.0.0",
-    "@objectstack/spec": "1.0.0",
-    "@objectstack/types": "1.0.0"
+    "@objectstack/core": "1.0.2",
+    "@objectstack/spec": "1.0.2",
+    "@objectstack/types": "1.0.2"
   },
   "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';
@@ -260,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
    */