s3db.js 10.0.19 → 11.0.0

package/src/plugins/eventual-consistency/{setup.js → install.js}

@@ -1,6 +1,6 @@
 /**
- * Setup logic for EventualConsistencyPlugin
- * @module eventual-consistency/setup
+ * Install logic for EventualConsistencyPlugin
+ * @module eventual-consistency/install
  */
 
 import tryFn from "../../concerns/try-fn.js";
@@ -11,14 +11,14 @@ import { startConsolidationTimer } from "./consolidation.js";
 import { startGarbageCollectionTimer } from "./garbage-collection.js";
 
 /**
- * Setup plugin for all configured resources
+ * Install plugin for all configured resources
  *
  * @param {Object} database - Database instance
  * @param {Map} fieldHandlers - Field handlers map
- * @param {Function} completeFieldSetupFn - Function to complete setup for a field
+ * @param {Function} completeFieldSetupFn - Function to complete field setup for a field
  * @param {Function} watchForResourceFn - Function to watch for resource creation
  */
-export async function onSetup(database, fieldHandlers, completeFieldSetupFn, watchForResourceFn) {
+export async function onInstall(database, fieldHandlers, completeFieldSetupFn, watchForResourceFn) {
   // Iterate over all resource/field combinations
   for (const [resourceName, resourceHandlers] of fieldHandlers) {
     const targetResource = database.resources[resourceName];
@@ -70,7 +70,7 @@ export function watchForResource(resourceName, database, fieldHandlers, complete
 }
 
 /**
- * Complete setup for a single field handler
+ * Complete field setup for a single field handler
  *
  * @param {Object} handler - Field handler
  * @param {Object} database - Database instance
@@ -174,6 +174,7 @@ async function createAnalyticsResource(handler, database, resourceName, fieldNam
       name: analyticsResourceName,
       attributes: {
         id: 'string|required',
+        field: 'string|required',
         period: 'string|required',
         cohort: 'string|required',
         transactionCount: 'number|required',

package/src/plugins/fulltext.plugin.js

@@ -13,11 +13,10 @@ export class FullTextPlugin extends Plugin {
     this.indexes = new Map(); // In-memory index for simplicity
   }
 
-  async setup(database) {
-    this.database = database;
+  async onInstall() {
     
     // Create index resource if it doesn't exist
-    const [ok, err, indexResource] = await tryFn(() => database.createResource({
+    const [ok, err, indexResource] = await tryFn(() => this.database.createResource({
         name: 'plg_fulltext_indexes',
         attributes: {
           id: 'string|required',
@@ -29,7 +28,7 @@ export class FullTextPlugin extends Plugin {
           lastUpdated: 'string|required'
         }
       }));
-    this.indexResource = ok ? indexResource : database.resources.fulltext_indexes;
+    this.indexResource = ok ? indexResource : this.database.resources.fulltext_indexes;
 
     // Load existing indexes
     await this.loadIndexes();

package/src/plugins/metrics.plugin.js

@@ -31,12 +31,11 @@ export class MetricsPlugin extends Plugin {
     this.flushTimer = null;
   }
 
-  async setup(database) {
-    this.database = database;
+  async onInstall() {
     if (typeof process !== 'undefined' && process.env.NODE_ENV === 'test') return;
 
     const [ok, err] = await tryFn(async () => {
-      const [ok1, err1, metricsResource] = await tryFn(() => database.createResource({
+      const [ok1, err1, metricsResource] = await tryFn(() => this.database.createResource({
         name: 'plg_metrics',
         attributes: {
           id: 'string|required',
@@ -51,9 +50,9 @@ export class MetricsPlugin extends Plugin {
           metadata: 'json'
         }
       }));
-      this.metricsResource = ok1 ? metricsResource : database.resources.plg_metrics;
+      this.metricsResource = ok1 ? metricsResource : this.database.resources.plg_metrics;
 
-      const [ok2, err2, errorsResource] = await tryFn(() => database.createResource({
+      const [ok2, err2, errorsResource] = await tryFn(() => this.database.createResource({
         name: 'plg_error_logs',
         attributes: {
           id: 'string|required',
@@ -64,9 +63,9 @@ export class MetricsPlugin extends Plugin {
           metadata: 'json'
         }
       }));
-      this.errorsResource = ok2 ? errorsResource : database.resources.plg_error_logs;
+      this.errorsResource = ok2 ? errorsResource : this.database.resources.plg_error_logs;
 
-      const [ok3, err3, performanceResource] = await tryFn(() => database.createResource({
+      const [ok3, err3, performanceResource] = await tryFn(() => this.database.createResource({
         name: 'plg_performance_logs',
         attributes: {
           id: 'string|required',
@@ -77,13 +76,13 @@ export class MetricsPlugin extends Plugin {
           metadata: 'json'
         }
       }));
-      this.performanceResource = ok3 ? performanceResource : database.resources.plg_performance_logs;
+      this.performanceResource = ok3 ? performanceResource : this.database.resources.plg_performance_logs;
     });
     if (!ok) {
       // Resources might already exist
-      this.metricsResource = database.resources.plg_metrics;
-      this.errorsResource = database.resources.plg_error_logs;
-      this.performanceResource = database.resources.plg_performance_logs;
+      this.metricsResource = this.database.resources.plg_metrics;
+      this.errorsResource = this.database.resources.plg_error_logs;
+      this.performanceResource = this.database.resources.plg_performance_logs;
     }
 
     // Use database hooks for automatic resource discovery

package/src/plugins/plugin.class.js

@@ -1,4 +1,5 @@
 import EventEmitter from "events";
+import { PluginStorage } from "../concerns/plugin-storage.js";
 
 export class Plugin extends EventEmitter {
   constructor(options = {}) {
@@ -6,13 +7,50 @@ export class Plugin extends EventEmitter {
     this.name = this.constructor.name;
     this.options = options;
     this.hooks = new Map();
+
+    // Auto-generate slug from class name (CamelCase -> kebab-case)
+    // e.g., EventualConsistencyPlugin -> eventual-consistency-plugin
+    this.slug = options.slug || this._generateSlug();
+
+    // Storage instance (lazy-loaded)
+    this._storage = null;
+  }
+
+  /**
+   * Generate kebab-case slug from class name
+   * @private
+   * @returns {string}
+   */
+  _generateSlug() {
+    return this.name
+      .replace(/Plugin$/, '') // Remove "Plugin" suffix
+      .replace(/([a-z])([A-Z])/g, '$1-$2') // CamelCase -> kebab-case
+      .toLowerCase();
   }
 
-  async setup(database) {
+  /**
+   * Get PluginStorage instance (lazy-loaded)
+   * @returns {PluginStorage}
+   */
+  getStorage() {
+    if (!this._storage) {
+      if (!this.database || !this.database.client) {
+        throw new Error('Plugin must be installed before accessing storage');
+      }
+      this._storage = new PluginStorage(this.database.client, this.slug);
+    }
+    return this._storage;
+  }
+
+  /**
+   * Install plugin
+   * @param {Database} database - Database instance
+   */
+  async install(database) {
     this.database = database;
-    this.beforeSetup();
-    await this.onSetup();
-    this.afterSetup();
+    this.beforeInstall();
+    await this.onInstall();
+    this.afterInstall();
   }
 
   async start() {
@@ -27,8 +65,28 @@ export class Plugin extends EventEmitter {
     this.afterStop();
   }
 
+  /**
+   * Uninstall plugin and cleanup all data
+   * @param {Object} options - Uninstall options
+   * @param {boolean} options.purgeData - Delete all plugin data from S3 (default: false)
+   */
+  async uninstall(options = {}) {
+    const { purgeData = false } = options;
+
+    this.beforeUninstall();
+    await this.onUninstall(options);
+
+    // Purge all plugin data if requested
+    if (purgeData && this._storage) {
+      const deleted = await this._storage.deleteAll();
+      this.emit('plugin.dataPurged', { deleted });
+    }
+
+    this.afterUninstall();
+  }
+
   // Override these methods in subclasses
-  async onSetup() {
+  async onInstall() {
     // Override in subclasses
   }
 
@@ -40,6 +98,10 @@ export class Plugin extends EventEmitter {
     // Override in subclasses
   }
 
+  async onUninstall(options) {
+    // Override in subclasses
+  }
+
   // Hook management methods
   addHook(resource, event, handler) {
     if (!this.hooks.has(resource)) {
@@ -182,12 +244,12 @@ export class Plugin extends EventEmitter {
   }
 
   // Event emission methods
-  beforeSetup() {
-    this.emit("plugin.beforeSetup", new Date());
+  beforeInstall() {
+    this.emit("plugin.beforeInstall", new Date());
   }
 
-  afterSetup() {
-    this.emit("plugin.afterSetup", new Date());
+  afterInstall() {
+    this.emit("plugin.afterInstall", new Date());
   }
 
   beforeStart() {
@@ -205,6 +267,14 @@ export class Plugin extends EventEmitter {
   afterStop() {
     this.emit("plugin.afterStop", new Date());
   }
+
+  beforeUninstall() {
+    this.emit("plugin.beforeUninstall", new Date());
+  }
+
+  afterUninstall() {
+    this.emit("plugin.afterUninstall", new Date());
+  }
 }
 
 export default Plugin;

package/src/plugins/queue-consumer.plugin.js

@@ -1,3 +1,4 @@
+import { Plugin } from './plugin.class.js';
 import { createConsumer } from './consumers/index.js';
 import tryFn from "../concerns/try-fn.js";
 
@@ -20,16 +21,16 @@ import tryFn from "../concerns/try-fn.js";
 //   reconnectInterval: 2000,
 // });
 
-export class QueueConsumerPlugin {
+export class QueueConsumerPlugin extends Plugin {
   constructor(options = {}) {
+    super(options);
     this.options = options;
     // New pattern: consumers = [{ driver, config, consumers: [{ queueUrl, resources, ... }] }]
     this.driversConfig = Array.isArray(options.consumers) ? options.consumers : [];
     this.consumers = [];
   }
 
-  async setup(database) {
-    this.database = database;
+  async onInstall() {
     
     for (const driverDef of this.driversConfig) {
       const { driver, config: driverConfig = {}, consumers: consumerDefs = [] } = driverDef;

package/src/plugins/replicator.plugin.js

@@ -236,12 +236,10 @@ export class ReplicatorPlugin extends Plugin {
     this.eventListenersInstalled.add(resource.name);
   }
 
-  async setup(database) {
-    this.database = database;
-    
+  async onInstall() {
     // Create replicator log resource if enabled
     if (this.config.persistReplicatorLog) {
-      const [ok, err, logResource] = await tryFn(() => database.createResource({
+      const [ok, err, logResource] = await tryFn(() => this.database.createResource({
         name: this.config.replicatorLogResource || 'plg_replicator_logs',
         attributes: {
           id: 'string|required',
@@ -253,24 +251,24 @@ export class ReplicatorPlugin extends Plugin {
         },
         behavior: 'truncate-data'
       }));
-      
+
       if (ok) {
         this.replicatorLogResource = logResource;
       } else {
-        this.replicatorLogResource = database.resources[this.config.replicatorLogResource || 'plg_replicator_logs'];
+        this.replicatorLogResource = this.database.resources[this.config.replicatorLogResource || 'plg_replicator_logs'];
       }
     }
 
     // Initialize replicators
-    await this.initializeReplicators(database);
-    
+    await this.initializeReplicators(this.database);
+
     // Use database hooks for automatic resource discovery
     this.installDatabaseHooks();
-    
+
     // Install event listeners for existing resources
-    for (const resource of Object.values(database.resources)) {
+    for (const resource of Object.values(this.database.resources)) {
       if (resource.name !== (this.config.replicatorLogResource || 'plg_replicator_logs')) {
-        this.installEventListeners(resource, database, this);
+        this.installEventListeners(resource, this.database, this);
       }
     }
   }
@@ -334,8 +332,8 @@ export class ReplicatorPlugin extends Plugin {
   }
 
   async uploadMetadataFile(database) {
-    if (typeof database.uploadMetadataFile === 'function') {
-      await database.uploadMetadataFile();
+    if (typeof this.database.uploadMetadataFile === 'function') {
+      await this.database.uploadMetadataFile();
     }
   }
 

package/src/plugins/s3-queue.plugin.js

@@ -97,7 +97,7 @@ export class S3QueuePlugin extends Plugin {
     this.lockCleanupInterval = null;
   }
 
-  async onSetup() {
+  async onInstall() {
     // Get target resource
     this.targetResource = this.database.resources[this.config.resource];
     if (!this.targetResource) {

package/src/plugins/scheduler.plugin.js

@@ -29,11 +29,11 @@ import { idGenerator } from "../concerns/id.js";
  *       schedule: '0 3 * * *',
  *       description: 'Clean up expired records',
  *       action: async (database, context) => {
- *         const expired = await database.resource('sessions')
+ *         const expired = await this.database.resource('sessions')
  *           .list({ where: { expiresAt: { $lt: new Date() } } });
  *         
  *         for (const record of expired) {
- *           await database.resource('sessions').delete(record.id);
+ *           await this.database.resource('sessions').delete(record.id);
  *         }
  *         
  *         return { deleted: expired.length };
@@ -48,8 +48,8 @@ import { idGenerator } from "../concerns/id.js";
  *       schedule: '0 9 * * MON',
  *       description: 'Generate weekly analytics report',
  *       action: async (database, context) => {
- *         const users = await database.resource('users').count();
- *         const orders = await database.resource('orders').count({
+ *         const users = await this.database.resource('users').count();
+ *         const orders = await this.database.resource('orders').count({
  *           where: { 
  *             createdAt: { 
  *               $gte: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000) 
@@ -64,7 +64,7 @@ import { idGenerator } from "../concerns/id.js";
  *           createdAt: new Date().toISOString()
  *         };
  *         
- *         await database.resource('reports').insert(report);
+ *         await this.database.resource('reports').insert(report);
  *         return report;
  *       }
  *     },
@@ -106,7 +106,7 @@ import { idGenerator } from "../concerns/id.js";
  *         const hourAgo = new Date(now.getTime() - 60 * 60 * 1000);
  *         
  *         // Aggregate metrics from the last hour
- *         const events = await database.resource('events').list({
+ *         const events = await this.database.resource('events').list({
  *           where: { 
  *             timestamp: { 
  *               $gte: hourAgo.getTime(),
@@ -120,7 +120,7 @@ import { idGenerator } from "../concerns/id.js";
  *           return acc;
  *         }, {});
  *         
- *         await database.resource('hourly_metrics').insert({
+ *         await this.database.resource('hourly_metrics').insert({
  *           hour: hourAgo.toISOString().slice(0, 13),
  *           metrics: aggregated,
  *           total: events.length,
@@ -217,8 +217,7 @@ export class SchedulerPlugin extends Plugin {
     return true; // Simplified validation
   }
 
-  async setup(database) {
-    this.database = database;
+  async onInstall() {
 
     // Create lock resource for distributed locking
     await this._createLockResource();

package/src/plugins/state-machine.plugin.js

@@ -61,7 +61,7 @@ import tryFn from "../concerns/try-fn.js";
  *   
  *   actions: {
  *     onConfirmed: async (context, event, machine) => {
- *       await machine.database.resource('inventory').update(context.productId, {
+ *       await machine.this.database.resource('inventory').update(context.productId, {
  *         quantity: { $decrement: context.quantity }
  *       });
  *       await machine.sendNotification(context.customerEmail, 'order_confirmed');
@@ -73,7 +73,7 @@ import tryFn from "../concerns/try-fn.js";
  *   
  *   guards: {
  *     canShip: async (context, event, machine) => {
- *       const inventory = await machine.database.resource('inventory').get(context.productId);
+ *       const inventory = await machine.this.database.resource('inventory').get(context.productId);
  *       return inventory.quantity >= context.quantity;
  *     }
  *   },
@@ -138,8 +138,7 @@ export class StateMachinePlugin extends Plugin {
     }
   }
 
-  async setup(database) {
-    this.database = database;
+  async onInstall() {
     
     // Create state storage resource if persistence is enabled
     if (this.config.persistTransitions) {