@objectstack/metadata 0.9.2 → 1.0.1

package/src/loaders/remote-loader.ts

@@ -0,0 +1,138 @@
+/**
+ * Remote Metadata Loader
+ * 
+ * Loads metadata from an HTTP API.
+ * This loader is stateless and delegates storage to the remote server.
+ */
+
+import type {
+  MetadataLoadOptions,
+  MetadataLoadResult,
+  MetadataStats,
+  MetadataLoaderContract,
+  MetadataSaveOptions,
+  MetadataSaveResult,
+} from '@objectstack/spec/system';
+import type { MetadataLoader } from './loader-interface.js';
+
+export class RemoteLoader implements MetadataLoader {
+  readonly contract: MetadataLoaderContract = {
+    name: 'remote',
+    protocol: 'http',
+    capabilities: {
+      read: true,
+      write: true,
+      watch: false, // Could implement SSE/WebSocket in future
+      list: true,
+    },
+  };
+
+  constructor(private baseUrl: string, private authToken?: string) {}
+
+  private get headers() {
+    return {
+      'Content-Type': 'application/json',
+      ...(this.authToken ? { Authorization: `Bearer ${this.authToken}` } : {}),
+    };
+  }
+
+  async load(
+    type: string,
+    name: string,
+    _options?: MetadataLoadOptions
+  ): Promise<MetadataLoadResult> {
+    try {
+      const response = await fetch(`${this.baseUrl}/${type}/${name}`, {
+        method: 'GET',
+        headers: this.headers,
+      });
+
+      if (response.status === 404) {
+        return { data: null };
+      }
+
+      if (!response.ok) {
+        throw new Error(`Remote load failed: ${response.statusText}`);
+      }
+
+      const data = await response.json();
+      return {
+        data,
+        source: this.baseUrl,
+        format: 'json',
+        loadTime: 0, 
+      };
+    } catch (error) {
+      console.error(`RemoteLoader error loading ${type}/${name}`, error);
+      throw error;
+    }
+  }
+
+  async loadMany<T = any>(
+    type: string,
+    _options?: MetadataLoadOptions
+  ): Promise<T[]> {
+    const response = await fetch(`${this.baseUrl}/${type}`, {
+      method: 'GET',
+      headers: this.headers,
+    });
+
+    if (!response.ok) {
+      return [];
+    }
+
+    return (await response.json()) as T[];
+  }
+
+  async exists(type: string, name: string): Promise<boolean> {
+    const response = await fetch(`${this.baseUrl}/${type}/${name}`, {
+      method: 'HEAD',
+      headers: this.headers,
+    });
+    return response.ok;
+  }
+
+  async stat(type: string, name: string): Promise<MetadataStats | null> {
+    // Basic implementation using HEAD
+    const response = await fetch(`${this.baseUrl}/${type}/${name}`, {
+      method: 'HEAD',
+      headers: this.headers,
+    });
+    
+    if (!response.ok) return null;
+
+    return {
+      size: Number(response.headers.get('content-length') || 0),
+      mtime: new Date(response.headers.get('last-modified') || Date.now()),
+      format: 'json',
+    };
+  }
+
+  async list(type: string): Promise<string[]> {
+    const items = await this.loadMany<{ name: string }>(type);
+    return items.map(i => i.name);
+  }
+
+  async save(
+    type: string,
+    name: string,
+    data: any,
+    _options?: MetadataSaveOptions
+  ): Promise<MetadataSaveResult> {
+    const response = await fetch(`${this.baseUrl}/${type}/${name}`, {
+      method: 'PUT',
+      headers: this.headers,
+      body: JSON.stringify(data),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Remote save failed: ${response.statusText}`);
+    }
+
+    return {
+      success: true,
+      path: `${this.baseUrl}/${type}/${name}`,
+      saveTime: 0,
+    };
+  }
+}

package/src/metadata-manager.ts

@@ -1,13 +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, type FSWatcher } from 'chokidar';
 import type {
   MetadataManagerConfig,
   MetadataLoadOptions,
@@ -17,7 +14,6 @@ import type {
   MetadataFormat,
 } from '@objectstack/spec/system';
 import { createLogger, type Logger } 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';
@@ -29,17 +25,23 @@ import type { MetadataLoader } from './loaders/loader-interface.js';
  */
 export type WatchCallback = (event: MetadataWatchEvent) => void | Promise<void>;
 
+export interface MetadataManagerOptions extends MetadataManagerConfig {
+  loaders?: MetadataLoader[];
+}
+
 /**
  * Main metadata manager class
  */
 export class MetadataManager {
-  private loader: MetadataLoader;
-  private serializers: Map<MetadataFormat, MetadataSerializer>;
-  private logger: Logger;
-  private watcher?: FSWatcher;
-  private watchCallbacks = new Map<string, Set<WatchCallback>>();
-
-  constructor(private config: MetadataManagerConfig) {
+  private loaders: Map<string, MetadataLoader> = new Map();
+  // Protected so subclasses can access serializers if needed
+  protected serializers: Map<MetadataFormat, MetadataSerializer>;
+  protected logger: Logger;
+  protected watchCallbacks = new Map<string, Set<WatchCallback>>();
+  protected config: MetadataManagerOptions;
+
+  constructor(config: MetadataManagerOptions) {
+    this.config = config;
     this.logger = createLogger({ level: 'info', format: 'pretty' });
 
     // Initialize serializers
@@ -59,149 +61,160 @@ export class MetadataManager {
       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: MetadataLoader) {
+    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<T = any>(
     type: string,
     name: string,
     options?: MetadataLoadOptions
   ): Promise<T | null> {
-    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<T = any>(
     type: string,
     options?: MetadataLoadOptions
   ): Promise<T[]> {
-    return this.loader.loadMany<T>(type, options);
+    const results: T[] = [];
+
+    for (const loader of this.loaders.values()) {
+        try {
+            const items = await loader.loadMany<T>(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<T = any>(
     type: string,
     name: string,
     data: T,
     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.serializers.get(format);
-      if (!serializer) {
-        throw new Error(`No serializer found for format: ${format}`);
+    const targetLoader = (options as any)?.loader;
+
+    // Find suitable loader
+    let loader: MetadataLoader | undefined;
+    
+    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) {
-        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;
+    } 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 {
+            if (await l.exists(type, name)) {
+                loader = l;
+                this.logger.info(`Updating existing metadata in loader: ${l.contract.name}`);
+                break;
+            }
+          } catch (e) {
+            // Ignore existence check errors (e.g. network down)
           }
-        }
       }
 
-      // 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
+      // 2. Default to 'filesystem' if available (Create new)
+      if (!loader) {
+        const fsLoader = this.loaders.get('filesystem');
+        if (fsLoader && fsLoader.save) {
+           loader = fsLoader;
         }
       }
 
-      // 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');
+      // 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);
+    if (!loader) {
+      throw new Error(`No loader available for saving type: ${type}`);
+    }
 
-      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.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: string, name: string): Promise<boolean> {
-    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: string): Promise<string[]> {
-    return this.loader.list(type);
+    const items = new Set<string>();
+    for (const loader of this.loaders.values()) {
+      const result = await loader.list(type);
+      result.forEach(item => items.add(item));
+    }
+    return Array.from(items);
   }
 
   /**
@@ -231,108 +244,23 @@ export class MetadataManager {
    * Stop all watching
    */
   async stopWatching(): Promise<void> {
-    if (this.watcher) {
-      await this.watcher.close();
-      this.watcher = undefined;
-      this.watchCallbacks.clear();
-    }
-  }
-
-  /**
-   * Start watching for file changes
-   */
-  private startWatching(): void {
-    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 });
+    // Override in subclass
   }
 
-  /**
-   * Handle file change events
-   */
-  private async handleFileEvent(
-    eventType: 'added' | 'changed' | 'deleted',
-    filePath: string
-  ): Promise<void> {
-    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));
-
+  protected notifyWatchers(type: string, event: MetadataWatchEvent) {
     const callbacks = this.watchCallbacks.get(type);
-    if (!callbacks || callbacks.size === 0) {
-      return;
-    }
-
-    let data: any = 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: MetadataWatchEvent = {
-      type: eventType,
-      metadataType: type,
-      name,
-      path: filePath,
-      data,
-      timestamp: new Date(),
-    };
-
+    if (!callbacks) return;
+    
     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)
-   */
-  private generateETag(content: string): string {
-    const hash = createHash('sha256').update(content).digest('hex').substring(0, 32);
-    return `"${hash}"`;
-  }
 }
+

package/src/node-metadata-manager.ts

@@ -0,0 +1,124 @@
+/**
+ * Node Metadata Manager
+ * 
+ * Extends MetadataManager with Filesystem capabilities (Watching, default loader)
+ */
+
+import * as path from 'node:path';
+import { watch as chokidarWatch, type FSWatcher } from 'chokidar';
+import type {
+  MetadataWatchEvent,
+} from '@objectstack/spec/system';
+import { FilesystemLoader } from './loaders/filesystem-loader.js';
+import { MetadataManager, type MetadataManagerOptions } from './metadata-manager.js';
+
+/**
+ * Node metadata manager class
+ */
+export class NodeMetadataManager extends MetadataManager {
+  private watcher?: FSWatcher;
+
+  constructor(config: MetadataManagerOptions) {
+    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(): Promise<void> {
+    if (this.watcher) {
+      await this.watcher.close();
+      this.watcher = undefined;
+    }
+    // Call base cleanup if any
+  }
+
+  /**
+   * Start watching for file changes
+   */
+  private startWatching(): void {
+    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
+   */
+  private async handleFileEvent(
+    eventType: 'added' | 'changed' | 'deleted',
+    filePath: string
+  ): Promise<void> {
+    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: any = 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: MetadataWatchEvent = {
+      type: eventType,
+      metadataType: type,
+      name,
+      path: filePath,
+      data,
+      timestamp: new Date(),
+    };
+
+    this.notifyWatchers(type, event);
+  }
+}

package/src/node.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';