s3db.js 12.0.1 → 12.2.0

package/src/plugins/concerns/plugin-dependencies.js

@@ -16,81 +16,97 @@
 export const PLUGIN_DEPENDENCIES = {
   'postgresql-replicator': {
     name: 'PostgreSQL Replicator',
+    docsUrl: 'https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/replicator.md',
     dependencies: {
       'pg': {
         version: '^8.0.0',
         description: 'PostgreSQL client for Node.js',
-        installCommand: 'pnpm add pg'
+        installCommand: 'pnpm add pg',
+        npmUrl: 'https://www.npmjs.com/package/pg'
       }
     }
   },
   'bigquery-replicator': {
     name: 'BigQuery Replicator',
+    docsUrl: 'https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/replicator.md',
     dependencies: {
       '@google-cloud/bigquery': {
         version: '^7.0.0',
         description: 'Google Cloud BigQuery SDK',
-        installCommand: 'pnpm add @google-cloud/bigquery'
+        installCommand: 'pnpm add @google-cloud/bigquery',
+        npmUrl: 'https://www.npmjs.com/package/@google-cloud/bigquery'
       }
     }
   },
   'sqs-replicator': {
     name: 'SQS Replicator',
+    docsUrl: 'https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/replicator.md',
     dependencies: {
       '@aws-sdk/client-sqs': {
         version: '^3.0.0',
         description: 'AWS SDK for SQS',
-        installCommand: 'pnpm add @aws-sdk/client-sqs'
+        installCommand: 'pnpm add @aws-sdk/client-sqs',
+        npmUrl: 'https://www.npmjs.com/package/@aws-sdk/client-sqs'
       }
     }
   },
   'sqs-consumer': {
     name: 'SQS Queue Consumer',
+    docsUrl: 'https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/queue-consumer.md',
     dependencies: {
       '@aws-sdk/client-sqs': {
         version: '^3.0.0',
         description: 'AWS SDK for SQS',
-        installCommand: 'pnpm add @aws-sdk/client-sqs'
+        installCommand: 'pnpm add @aws-sdk/client-sqs',
+        npmUrl: 'https://www.npmjs.com/package/@aws-sdk/client-sqs'
       }
     }
   },
   'rabbitmq-consumer': {
     name: 'RabbitMQ Queue Consumer',
+    docsUrl: 'https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/queue-consumer.md',
     dependencies: {
       'amqplib': {
         version: '^0.10.0',
         description: 'AMQP 0-9-1 library for RabbitMQ',
-        installCommand: 'pnpm add amqplib'
+        installCommand: 'pnpm add amqplib',
+        npmUrl: 'https://www.npmjs.com/package/amqplib'
       }
     }
   },
   'tfstate-plugin': {
-    name: 'Terraform State Plugin',
+    name: 'Tfstate Plugin',
+    docsUrl: 'https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/tfstate.md',
     dependencies: {
       'node-cron': {
         version: '^4.0.0',
         description: 'Cron job scheduler for auto-sync functionality',
-        installCommand: 'pnpm add node-cron'
+        installCommand: 'pnpm add node-cron',
+        npmUrl: 'https://www.npmjs.com/package/node-cron'
       }
     }
   },
   'api-plugin': {
     name: 'API Plugin',
+    docsUrl: 'https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/api.md',
     dependencies: {
       'hono': {
         version: '^4.0.0',
         description: 'Ultra-light HTTP server framework',
-        installCommand: 'pnpm add hono'
+        installCommand: 'pnpm add hono',
+        npmUrl: 'https://www.npmjs.com/package/hono'
       },
       '@hono/node-server': {
         version: '^1.0.0',
         description: 'Node.js adapter for Hono',
-        installCommand: 'pnpm add @hono/node-server'
+        installCommand: 'pnpm add @hono/node-server',
+        npmUrl: 'https://www.npmjs.com/package/@hono/node-server'
       },
       '@hono/swagger-ui': {
         version: '^0.4.0',
         description: 'Swagger UI integration for Hono',
-        installCommand: 'pnpm add @hono/swagger-ui'
+        installCommand: 'pnpm add @hono/swagger-ui',
+        npmUrl: 'https://www.npmjs.com/package/@hono/swagger-ui'
       }
     }
   }
@@ -229,22 +245,60 @@ export async function requirePluginDependency(pluginId, options = {}) {
 
   // Throw comprehensive error if validation failed
   if (!valid && throwOnError) {
+    const depCount = Object.keys(pluginDef.dependencies).length;
+    const missingCount = missing.length;
+    const incompatCount = incompatible.length;
+
     const errorMsg = [
-      `\n${pluginDef.name} - Missing dependencies detected!\n`,
-      `Plugin ID: ${pluginId}`,
       '',
+      '╔══════════════════════════════════════════════════════════════════════╗',
+      `║  ❌ ${pluginDef.name} - Missing Dependencies  ║`,
+      '╚══════════════════════════════════════════════════════════════════════╝',
+      '',
+      `📦 Plugin: ${pluginId}`,
+      `📊 Status: ${depCount - missingCount - incompatCount}/${depCount} dependencies satisfied`,
+      '',
+      '🔍 Dependency Status:',
+      '─────────────────────────────────────────────────────────────────────',
       ...messages,
       '',
-      'Quick fix - Run all install commands:',
-      Object.values(pluginDef.dependencies)
-        .map(dep => `  ${dep.installCommand}`)
-        .join('\n'),
+      '🚀 Quick Fix - Install Missing Dependencies:',
+      '─────────────────────────────────────────────────────────────────────',
+      '',
+      '  Option 1: Install individually',
+      ...Object.entries(pluginDef.dependencies)
+        .filter(([pkg]) => missing.includes(pkg) || incompatible.includes(pkg))
+        .map(([pkg, info]) => `    ${info.installCommand}`),
+      '',
+      '  Option 2: Install all at once',
+      `    pnpm add ${Object.keys(pluginDef.dependencies).join(' ')}`,
       '',
-      'Or install all peer dependencies at once:',
-      `  pnpm add ${Object.keys(pluginDef.dependencies).join(' ')}`
+      '📚 Documentation:',
+      `    ${pluginDef.docsUrl}`,
+      '',
+      '💡 Troubleshooting:',
+      '  • If packages are installed but not detected, try:',
+      '    1. Delete node_modules and reinstall: rm -rf node_modules && pnpm install',
+      '    2. Check Node.js version: node --version (requires Node 18+)',
+      '    3. Verify pnpm version: pnpm --version (requires pnpm 8+)',
+      '',
+      '  • Still having issues? Check:',
+      '    - Package.json has correct dependencies listed',
+      '    - No conflicting versions in pnpm-lock.yaml',
+      '    - File permissions (especially in node_modules/)',
+      '',
+      '═══════════════════════════════════════════════════════════════════════',
+      ''
     ].join('\n');
 
-    throw new Error(errorMsg);
+    const error = new Error(errorMsg);
+    error.pluginId = pluginId;
+    error.pluginName = pluginDef.name;
+    error.missing = missing;
+    error.incompatible = incompatible;
+    error.docsUrl = pluginDef.docsUrl;
+
+    throw error;
   }
 
   return { valid, missing, incompatible, messages };

package/src/plugins/eventual-consistency/analytics.js

@@ -559,8 +559,6 @@ async function getAnalyticsForRecord(resourceName, field, recordId, options, han
     return [];
   }
 
-  // ✅ FIX BUG #2: Ensure all transactions have cohortHour calculated
-  // This handles legacy data that may be missing cohortHour
   allTransactions = ensureCohortHours(allTransactions, handler.config?.cohort?.timezone || 'UTC', false);
 
   // Filter transactions by temporal range

package/src/plugins/eventual-consistency/consolidation.js

@@ -286,9 +286,7 @@ export async function consolidateRecord(
 
         if (!hasSetInApplied) {
           // No 'set' operation in applied transactions means we're missing the base value
-          // This can only happen if:
-          // 1. Record had an initial value before first transaction
-          // 2. First consolidation didn't create an anchor transaction (legacy behavior)
+          // This can happen if record had an initial value before first transaction
           // Solution: Get the current record value and create an anchor transaction now
           const recordValue = recordExists[config.field] || 0;
 
@@ -525,7 +523,6 @@ export async function consolidateRecord(
       updateResult = result[2];
     }
 
-    // For backward compatibility, return the value of the main field
     const consolidatedValue = consolidatedValues[config.field] ||
                              (record ? lodash.get(record, config.field, 0) : 0);
 
@@ -610,13 +607,10 @@ export async function consolidateRecord(
 
       const { results, errors } = await PromisePool
         .for(transactionsToUpdate)
-        .withConcurrency(markAppliedConcurrency) // ✅ Configurável e maior!
+        .withConcurrency(markAppliedConcurrency)
         .process(async (txn) => {
-          // ✅ FIX BUG #3: Ensure cohort fields exist before marking as applied
-          // This handles legacy transactions missing cohortHour, cohortDate, etc.
           const txnWithCohorts = ensureCohortHour(txn, config.cohort.timezone, false);
 
-          // Build update data with applied flag
           const updateData = { applied: true };
 
           // Add missing cohort fields if they were calculated
@@ -633,11 +627,6 @@ export async function consolidateRecord(
             updateData.cohortMonth = txnWithCohorts.cohortMonth;
           }
 
-          // Handle null value field (legacy data might have null)
-          if (txn.value === null || txn.value === undefined) {
-            updateData.value = 1; // Default to 1 for backward compatibility
-          }
-
           const [ok, err] = await tryFn(() =>
             transactionResource.update(txn.id, updateData)
           );

package/src/plugins/eventual-consistency/index.js

@@ -183,7 +183,6 @@ export class EventualConsistencyPlugin extends Plugin {
    * @private
    */
   async _syncModeConsolidate(handler, id, field) {
-    // Temporarily set config for legacy methods
     const oldResource = this.config.resource;
     const oldField = this.config.field;
     const oldTransactionResource = this.transactionResource;

package/src/plugins/eventual-consistency/install.js

@@ -100,7 +100,7 @@ export async function completeFieldSetup(handler, database, config, plugin) {
         operation: 'string|required',
         timestamp: 'string|required',
         cohortDate: 'string|required',
-        cohortHour: 'string|optional',  // ✅ FIX BUG #2: Changed from required to optional for migration compatibility
+        cohortHour: 'string|required',
         cohortWeek: 'string|optional',
         cohortMonth: 'string|optional',
         source: 'string|optional',

package/src/plugins/geo.plugin.js

@@ -127,7 +127,7 @@ class GeoPlugin extends Plugin {
       return;
     }
 
-    const resource = this.database.resource(resourceName);
+    const resource = this.database.resources[resourceName];
     if (!resource || typeof resource.addHook !== 'function') {
       if (this.verbose) {
         console.warn(`[GeoPlugin] Resource "${resourceName}" not found or invalid`);
@@ -325,14 +325,13 @@ class GeoPlugin extends Plugin {
      * Find nearby locations within radius
      * Automatically selects optimal zoom level if multi-zoom enabled
      */
-    resource.findNearby = async function({ lat, lon, lng, radius = 10, limit = 100 }) {
-      // Support both 'lon' and 'lng' for backward compatibility
-      const longitude = lon !== undefined ? lon : lng;
-
-      if (lat === undefined || longitude === undefined) {
+    resource.findNearby = async function({ lat, lon, radius = 10, limit = 100 }) {
+      if (lat === undefined || lon === undefined) {
         throw new Error('lat and lon are required for findNearby');
       }
 
+      const longitude = lon; // Alias for internal use
+
       let allRecords = [];
 
       // Use partitions if enabled for efficient queries

package/src/plugins/importer/index.js

@@ -739,7 +739,7 @@ export class ImporterPlugin extends Plugin {
   async onInstall() {
     // Get resource - database.resource() returns a rejected Promise if not found
     try {
-      this.resource = this.database.resource(this.resourceName);
+      this.resource = this.database.resources[this.resourceName];
       // If resource() returns a Promise, await it
       if (this.resource && typeof this.resource.then === 'function') {
         this.resource = await this.resource;

package/src/plugins/plugin.class.js

@@ -176,6 +176,11 @@ export class Plugin extends EventEmitter {
    * - Pode modificar argumentos/resultados.
    */
   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'}"`);
+    }
+
     if (!resource._pluginMiddlewares) {
       resource._pluginMiddlewares = {};
     }