s3db.js 10.0.18 → 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) {

package/src/s3db.d.ts

@@ -1069,11 +1069,207 @@ declare module 's3db.js' {
     deleteBackup(backupId: string): Promise<void>;
   }
 
+  /** Eventual Consistency Plugin Config */
+  export interface EventualConsistencyPluginConfig extends PluginConfig {
+    /** Resource name to field names mapping (required) */
+    resources: Record<string, string[]>;
+
+    /** Consolidation settings */
+    consolidation?: {
+      /** Consolidation mode: 'sync' or 'async' (default: 'async') */
+      mode?: 'sync' | 'async';
+      /** Consolidation interval in seconds (default: 300) */
+      interval?: number;
+      /** Consolidation concurrency (default: 5) */
+      concurrency?: number;
+      /** Consolidation window in hours (default: 24) */
+      window?: number;
+      /** Enable auto-consolidation (default: true) */
+      auto?: boolean;
+    };
+
+    /** Lock settings */
+    locks?: {
+      /** Lock timeout in seconds (default: 300) */
+      timeout?: number;
+    };
+
+    /** Garbage collection settings */
+    garbageCollection?: {
+      /** Transaction retention in days (default: 30) */
+      retention?: number;
+      /** GC interval in seconds (default: 86400) */
+      interval?: number;
+    };
+
+    /** Analytics settings */
+    analytics?: {
+      /** Enable analytics (default: false) */
+      enabled?: boolean;
+      /** Time periods to track (default: ['hour', 'day', 'month']) */
+      periods?: Array<'hour' | 'day' | 'month'>;
+      /** Metrics to track (default: ['count', 'sum', 'avg', 'min', 'max']) */
+      metrics?: Array<'count' | 'sum' | 'avg' | 'min' | 'max'>;
+      /** Rollup strategy (default: 'incremental') */
+      rollupStrategy?: 'incremental' | 'full';
+      /** Analytics retention in days (default: 365) */
+      retentionDays?: number;
+    };
+
+    /** Batch transaction settings */
+    batch?: {
+      /** Enable batch transactions (default: false) */
+      enabled?: boolean;
+      /** Batch size (default: 100) */
+      size?: number;
+    };
+
+    /** Late arrivals handling */
+    lateArrivals?: {
+      /** Strategy for late arrivals (default: 'warn') */
+      strategy?: 'warn' | 'ignore' | 'error';
+    };
+
+    /** Checkpoint settings */
+    checkpoints?: {
+      /** Enable checkpoints (default: true) */
+      enabled?: boolean;
+      /** Checkpoint strategy (default: 'hourly') */
+      strategy?: 'hourly' | 'daily' | 'threshold';
+      /** Checkpoint retention in days (default: 90) */
+      retention?: number;
+      /** Checkpoint threshold (default: 1000) */
+      threshold?: number;
+      /** Delete consolidated transactions (default: true) */
+      deleteConsolidated?: boolean;
+      /** Enable auto-checkpoint (default: true) */
+      auto?: boolean;
+    };
+
+    /** Cohort settings */
+    cohort?: {
+      /** Timezone for cohorts (default: UTC or TZ env var) */
+      timezone?: string;
+    };
+
+    /** Custom reducer function */
+    reducer?: (transactions: any[]) => number;
+
+    /** Enable verbose logging (default: false) */
+    verbose?: boolean;
+  }
+
+  /** Analytics query options */
+  export interface EventualConsistencyAnalyticsOptions {
+    /** Period to query */
+    period?: 'hour' | 'day' | 'month';
+    /** Start date (YYYY-MM-DD or YYYY-MM-DD HH:00) */
+    startDate?: string;
+    /** End date (YYYY-MM-DD or YYYY-MM-DD HH:00) */
+    endDate?: string;
+    /** Single date (YYYY-MM-DD) */
+    date?: string;
+    /** Operation breakdown */
+    breakdown?: 'operations';
+    /** Fill gaps with zeros for continuous data (default: false) */
+    fillGaps?: boolean;
+  }
+
+  /** Top records query options */
+  export interface EventualConsistencyTopRecordsOptions {
+    /** Period to query */
+    period?: 'hour' | 'day' | 'month';
+    /** Date for the query */
+    date?: string;
+    /** Metric to sort by: 'transactionCount' or 'totalValue' */
+    metric?: 'transactionCount' | 'totalValue';
+    /** Limit results (default: 10) */
+    limit?: number;
+  }
+
+  /** Analytics result */
+  export interface EventualConsistencyAnalyticsResult {
+    /** Cohort identifier (date/hour/month string) */
+    cohort: string;
+    /** Number of transactions */
+    count: number;
+    /** Sum of values */
+    sum: number;
+    /** Average value */
+    avg: number;
+    /** Minimum value */
+    min: number;
+    /** Maximum value */
+    max: number;
+    /** Number of distinct records */
+    recordCount: number;
+    /** Breakdown by operation (if requested) */
+    add?: { count: number; sum: number };
+    sub?: { count: number; sum: number };
+    set?: { count: number; sum: number };
+  }
+
+  /** Top record result */
+  export interface EventualConsistencyTopRecordResult {
+    /** Record ID */
+    recordId: string;
+    /** Number of transactions or total value */
+    count: number;
+    /** Total value */
+    sum: number;
+  }
+
+  /** Cohort information */
+  export interface EventualConsistencyCohortInfo {
+    /** Date in YYYY-MM-DD format */
+    date: string;
+    /** Hour in YYYY-MM-DD HH:00 format */
+    hour: string;
+    /** Month in YYYY-MM format */
+    month: string;
+  }
+
   /** Eventual Consistency Plugin */
   export class EventualConsistencyPlugin extends Plugin {
-    constructor(config?: any);
+    constructor(config: EventualConsistencyPluginConfig);
+
+    // Lifecycle methods
     setup(database: Database): Promise<void>;
-    createTransaction(resourceName: string): any;
+
+    // Analytics methods
+    getAnalytics(resourceName: string, field: string, options?: EventualConsistencyAnalyticsOptions): Promise<EventualConsistencyAnalyticsResult[]>;
+    getMonthByDay(resourceName: string, field: string, month: string, options?: EventualConsistencyAnalyticsOptions): Promise<EventualConsistencyAnalyticsResult[]>;
+    getDayByHour(resourceName: string, field: string, date: string, options?: EventualConsistencyAnalyticsOptions): Promise<EventualConsistencyAnalyticsResult[]>;
+    getLastNDays(resourceName: string, field: string, days?: number, options?: EventualConsistencyAnalyticsOptions): Promise<EventualConsistencyAnalyticsResult[]>;
+    getYearByMonth(resourceName: string, field: string, year: number, options?: EventualConsistencyAnalyticsOptions): Promise<EventualConsistencyAnalyticsResult[]>;
+    getMonthByHour(resourceName: string, field: string, month: string, options?: EventualConsistencyAnalyticsOptions): Promise<EventualConsistencyAnalyticsResult[]>;
+    getTopRecords(resourceName: string, field: string, options?: EventualConsistencyTopRecordsOptions): Promise<EventualConsistencyTopRecordResult[]>;
+
+    // Utility methods
+    getCohortInfo(date: Date): EventualConsistencyCohortInfo;
+    createPartitionConfig(): any;
+    createTransaction(handler: any, data: any): Promise<any>;
+  }
+
+  /** Resource extensions added by EventualConsistencyPlugin */
+  export interface EventualConsistencyResourceExtensions {
+    /** Set field value (replaces current value) */
+    set(id: string, field: string, value: number): Promise<number>;
+
+    /** Increment field value */
+    add(id: string, field: string, amount: number): Promise<number>;
+
+    /** Decrement field value */
+    sub(id: string, field: string, amount: number): Promise<number>;
+
+    /** Manually trigger consolidation */
+    consolidate(id: string, field: string): Promise<number>;
+
+    /** Get consolidated value without applying */
+    getConsolidatedValue(id: string, field: string, options?: any): Promise<number>;
+
+    /** Recalculate from scratch (rebuilds from transaction log) */
+    recalculate(id: string, field: string): Promise<number>;
   }
 
   /** Scheduler Plugin */