s3db.js 13.6.1 → 14.0.2

package/src/plugins/plugin.class.js

@@ -1,5 +1,8 @@
 import EventEmitter from "events";
 import { PluginStorage } from "../concerns/plugin-storage.js";
+import { FilesystemStorageDriver } from "../concerns/storage-drivers/filesystem-driver.js";
+import { PluginError } from "../errors.js";
+import { listPluginNamespaces } from "./namespace.js";
 
 export class Plugin extends EventEmitter {
   constructor(options = {}) {
@@ -10,10 +13,20 @@ export class Plugin extends EventEmitter {
 
     // Auto-generate slug from class name (CamelCase -> kebab-case)
     // e.g., EventualConsistencyPlugin -> eventual-consistency-plugin
-    this.slug = options.slug || this._generateSlug();
+    this.baseSlug = options.slug || this._generateSlug();
+    this.slug = this.baseSlug;
 
     // Storage instance (lazy-loaded)
     this._storage = null;
+
+    // Multi-instance & namespacing
+    this.instanceName = null;
+    this.namespace = null;
+    this._namespaceExplicit = false;
+
+    if (options.namespace || options.instanceId) {
+      this.setNamespace(options.namespace || options.instanceId, { explicit: true });
+    }
   }
 
   /**
@@ -29,19 +42,166 @@ export class Plugin extends EventEmitter {
   }
 
   /**
-   * Get PluginStorage instance (lazy-loaded)
-   * @returns {PluginStorage}
+   * Normalize namespace into kebab-case
+   * @private
+   */
+  _normalizeNamespace(value) {
+    if (value === null || value === undefined) return null;
+    const text = String(value).trim();
+    if (!text) return null;
+    return text
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+/, '')
+      .replace(/-+$/, '') || null;
+  }
+
+  /**
+   * Update plugin namespace (affects storage slug & helpers)
+   * @param {string|null} value
+   * @param {Object} options
+   * @param {boolean} options.explicit - Whether namespace was set explicitly by the user
+   */
+  setNamespace(value, { explicit = false } = {}) {
+    const normalized = this._normalizeNamespace(value);
+
+    if (!normalized) {
+      if (explicit) {
+        this.namespace = null;
+        this.slug = this.baseSlug;
+        this._namespaceExplicit = true;
+        this._storage = null;
+        if (typeof this.onNamespaceChanged === 'function') {
+          this.onNamespaceChanged(this.namespace);
+        }
+      }
+      return;
+    }
+
+    if (this.namespace === normalized && (explicit === false || this._namespaceExplicit)) {
+      return;
+    }
+
+    this.namespace = normalized;
+    if (explicit) {
+      this._namespaceExplicit = true;
+    }
+
+    this.slug = `${this.baseSlug}--${normalized}`;
+    this._storage = null; // Recreate storage with new slug on next access
+
+    if (typeof this.onNamespaceChanged === 'function') {
+      this.onNamespaceChanged(this.namespace);
+    }
+  }
+
+  /**
+   * Set instance name (called by Database when registering the plugin)
+   * Automatically derives namespace when not explicitly provided.
+   */
+  setInstanceName(name) {
+    if (!name) return;
+    this.instanceName = name;
+
+    if (!this._namespaceExplicit) {
+      const normalized = this._normalizeNamespace(name);
+      if (normalized && normalized !== this.baseSlug) {
+        this.setNamespace(normalized);
+      }
+    }
+  }
+
+  /**
+   * Hook for subclasses to react to namespace changes
+   * @param {string|null} namespace
+   */
+  // eslint-disable-next-line no-unused-vars
+  onNamespaceChanged(namespace) {
+    // Subclasses may override
+  }
+
+  /**
+   * Get storage instance (lazy-loaded)
+   * Supports both S3 and filesystem drivers based on options.storage configuration
+   * @returns {PluginStorage|FilesystemStorageDriver}
    */
   getStorage() {
     if (!this._storage) {
-      if (!this.database || !this.database.client) {
-        throw new Error('Plugin must be installed before accessing storage');
+      // Get storage configuration from options
+      const storageConfig = this.options.storage || {};
+      const driver = storageConfig.driver || 's3'; // Default to S3
+      const config = storageConfig.config || {};
+
+      if (driver === 'filesystem') {
+        // Use filesystem driver
+        this._storage = new FilesystemStorageDriver(config, this.slug);
+      } else if (driver === 's3') {
+        // Use S3-based PluginStorage (default)
+        if (!this.database || !this.database.client) {
+          throw new PluginError('Plugin storage unavailable until plugin is installed', {
+            pluginName: this.name,
+            operation: 'getStorage',
+            statusCode: 400,
+            retriable: false,
+            suggestion: 'Call db.installPlugin(new Plugin()) or ensure db.connect() completed before accessing storage.'
+          });
+        }
+        this._storage = new PluginStorage(this.database.client, this.slug);
+      } else {
+        throw new PluginError(`Unsupported storage driver: ${driver}`, {
+          pluginName: this.name,
+          operation: 'getStorage',
+          statusCode: 400,
+          retriable: false,
+          suggestion: 'Use "s3" or "filesystem" as storage driver'
+        });
       }
-      this._storage = new PluginStorage(this.database.client, this.slug);
     }
     return this._storage;
   }
 
+  /**
+   * Detect and warn about existing namespaces
+   *
+   * Automatically called during install() if plugin uses namespaces.
+   * Scans storage to find existing namespaces and emits console warnings.
+   *
+   * @returns {Promise<string[]>} Array of detected namespaces
+   */
+  async detectAndWarnNamespaces() {
+    // Only run if plugin explicitly uses namespaces
+    if (!this._namespaceExplicit && !this.namespace) {
+      return [];
+    }
+
+    try {
+      // Get plugin prefix from slug (e.g., 'recon', 'scheduler', 'cache')
+      const pluginPrefix = this.baseSlug;
+      const currentNamespace = this.namespace || '';
+
+      // List existing namespaces in storage
+      const existingNamespaces = await listPluginNamespaces(
+        this.getStorage(),
+        pluginPrefix
+      );
+
+      // Emit console warnings (standardized format)
+      if (existingNamespaces.length > 0) {
+        console.warn(
+          `[${this.name}] Detected ${existingNamespaces.length} existing namespace(s): ${existingNamespaces.join(', ')}`
+        );
+      }
+
+      const namespaceDisplay = currentNamespace === '' ? '(none)' : `"${currentNamespace}"`;
+      console.warn(`[${this.name}] Using namespace: ${namespaceDisplay}`);
+
+      return existingNamespaces;
+    } catch (error) {
+      // Silently fail if storage is not available
+      return [];
+    }
+  }
+
   /**
    * Install plugin
    * @param {Database} database - Database instance
@@ -49,6 +209,10 @@ export class Plugin extends EventEmitter {
   async install(database) {
     this.database = database;
     this.beforeInstall();
+
+    // Auto-detect and warn about namespaces if plugin uses them
+    await this.detectAndWarnNamespaces();
+
     await this.onInstall();
     this.afterInstall();
   }
@@ -178,7 +342,15 @@ export class Plugin extends EventEmitter {
   addMiddleware(resource, methodName, middleware) {
     // Safety check: verify method exists
     if (typeof resource[methodName] !== 'function') {
-      throw new Error(`Cannot add middleware to "${methodName}": method does not exist on resource "${resource.name || 'unknown'}"`);
+      throw new PluginError(`Cannot add middleware to "${methodName}"`, {
+        pluginName: this.name,
+        operation: 'addMiddleware',
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Ensure the resource exposes the method before registering middleware.',
+        resourceName: resource.name || 'unknown',
+        methodName
+      });
     }
 
     if (!resource._pluginMiddlewares) {
@@ -280,4 +452,4 @@ export class Plugin extends EventEmitter {
   afterUninstall() {
     this.emit("plugin.afterUninstall", new Date());
   }
-}
+}