s3db.js 13.6.0 → 14.0.2

package/src/plugins/ttl.plugin.js

@@ -1,6 +1,8 @@
 import { Plugin } from "./plugin.class.js";
 import tryFn from "../concerns/try-fn.js";
 import { idGenerator } from "../concerns/id.js";
+import { resolveResourceName } from "./concerns/resource-names.js";
+import { PluginError } from "../errors.js";
 
 // Time constants (in seconds)
 const ONE_MINUTE_SEC = 60;
@@ -171,7 +173,13 @@ export class TTLPlugin extends Plugin {
     this.isRunning = false;
 
     // Expiration index (plugin storage)
+    const resourceNamesOption = config.resourceNames || {};
     this.expirationIndex = null;
+    this._indexResourceDescriptor = {
+      defaultName: 'plg_ttl_expiration_index',
+      override: resourceNamesOption.index || config.indexResourceName
+    };
+    this.indexResourceName = this._resolveIndexResourceName();
   }
 
   /**
@@ -206,23 +214,44 @@ export class TTLPlugin extends Plugin {
     });
   }
 
+  _resolveIndexResourceName() {
+    return resolveResourceName('ttl', this._indexResourceDescriptor, {
+      namespace: this.namespace
+    });
+  }
+
+  onNamespaceChanged() {
+    if (!this._indexResourceDescriptor) return;
+    this.indexResourceName = this._resolveIndexResourceName();
+  }
+
   /**
    * Validate resource configuration
    */
   _validateResourceConfig(resourceName, config) {
     // Must have either ttl or field
     if (!config.ttl && !config.field) {
-      throw new Error(
-        `[TTLPlugin] Resource "${resourceName}" must have either "ttl" (seconds) or "field" (timestamp field name)`
-      );
+      throw new PluginError('[TTLPlugin] Missing TTL configuration', {
+        pluginName: 'TTLPlugin',
+        operation: 'validateResourceConfig',
+        resourceName,
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Provide either ttl (in seconds) or field (absolute expiration timestamp) for each resource.'
+      });
     }
 
     const validStrategies = ['soft-delete', 'hard-delete', 'archive', 'callback'];
     if (!config.onExpire || !validStrategies.includes(config.onExpire)) {
-      throw new Error(
-        `[TTLPlugin] Resource "${resourceName}" must have an "onExpire" value. ` +
-        `Valid options: ${validStrategies.join(', ')}`
-      );
+      throw new PluginError('[TTLPlugin] Invalid onExpire strategy', {
+        pluginName: 'TTLPlugin',
+        operation: 'validateResourceConfig',
+        resourceName,
+        statusCode: 400,
+        retriable: false,
+        suggestion: `Set onExpire to one of: ${validStrategies.join(', ')}`,
+        onExpire: config.onExpire
+      });
     }
 
     if (config.onExpire === 'soft-delete' && !config.deleteField) {
@@ -230,15 +259,27 @@ export class TTLPlugin extends Plugin {
     }
 
     if (config.onExpire === 'archive' && !config.archiveResource) {
-      throw new Error(
-        `[TTLPlugin] Resource "${resourceName}" with onExpire="archive" must have an "archiveResource" specified`
-      );
+      throw new PluginError('[TTLPlugin] Archive resource required', {
+        pluginName: 'TTLPlugin',
+        operation: 'validateResourceConfig',
+        resourceName,
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Provide archiveResource pointing to the resource that stores archived records.',
+        onExpire: config.onExpire
+      });
     }
 
     if (config.onExpire === 'callback' && typeof config.callback !== 'function') {
-      throw new Error(
-        `[TTLPlugin] Resource "${resourceName}" with onExpire="callback" must have a "callback" function`
-      );
+      throw new PluginError('[TTLPlugin] Callback handler required', {
+        pluginName: 'TTLPlugin',
+        operation: 'validateResourceConfig',
+        resourceName,
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Provide a callback function: { onExpire: "callback", callback: async (ctx) => {...} }',
+        onExpire: config.onExpire
+      });
     }
 
     // Set default field if not specified
@@ -249,7 +290,7 @@ export class TTLPlugin extends Plugin {
     // Validate timestamp field availability
     if (config.field === '_createdAt' && this.database) {
       const resource = this.database.resources[resourceName];
-      if (resource && resource.config && resource.config.timestamps === false) {
+      if (resource && resource.$schema.timestamps === false) {
         console.warn(
           `[TTLPlugin] WARNING: Resource "${resourceName}" uses TTL with field "_createdAt" ` +
           `but timestamps are disabled. TTL will be calculated from indexing time, not creation time.`
@@ -266,7 +307,7 @@ export class TTLPlugin extends Plugin {
    */
   async _createExpirationIndex() {
     this.expirationIndex = await this.database.createResource({
-      name: 'plg_ttl_expiration_index',
+      name: this.indexResourceName,
       attributes: {
         resourceName: 'string|required',
         recordId: 'string|required',
@@ -626,7 +667,14 @@ export class TTLPlugin extends Plugin {
   async _archive(resource, record, config) {
     // Check if archive resource exists
     if (!this.database.resources[config.archiveResource]) {
-      throw new Error(`Archive resource "${config.archiveResource}" not found`);
+      throw new PluginError(`Archive resource "${config.archiveResource}" not found`, {
+        pluginName: 'TTLPlugin',
+        operation: '_archive',
+        resourceName: config.archiveResource,
+        statusCode: 404,
+        retriable: false,
+        suggestion: 'Create the archive resource before using onExpire: "archive" or update archiveResource config.'
+      });
     }
 
     const archiveResource = this.database.resources[config.archiveResource];
@@ -666,7 +714,14 @@ export class TTLPlugin extends Plugin {
   async cleanupResource(resourceName) {
     const config = this.resources[resourceName];
     if (!config) {
-      throw new Error(`Resource "${resourceName}" not configured in TTLPlugin`);
+      throw new PluginError(`Resource "${resourceName}" not configured in TTLPlugin`, {
+        pluginName: 'TTLPlugin',
+        operation: 'cleanupResource',
+        resourceName,
+        statusCode: 404,
+        retriable: false,
+        suggestion: 'Add the resource under TTLPlugin configuration before invoking cleanupResource.'
+      });
     }
 
     const granularity = config.granularity;

package/src/plugins/vector/distances.js

@@ -1,3 +1,5 @@
+import { ValidationError } from '../../errors.js';
+
 /**
  * Vector Distance Functions
  *
@@ -5,6 +7,18 @@
  * All distance functions return lower values for more similar vectors.
  */
 
+function assertSameDimensions(a, b, operation) {
+  if (a.length !== b.length) {
+    throw new ValidationError(`Dimension mismatch: ${a.length} vs ${b.length}`, {
+      operation,
+      pluginName: 'VectorPlugin',
+      retriable: false,
+      suggestion: 'Ensure both vectors have identical lengths before calling distance utilities.',
+      metadata: { vectorALength: a.length, vectorBLength: b.length }
+    });
+  }
+}
+
 /**
  * Calculate cosine distance between two vectors
  *
@@ -17,9 +31,7 @@
  * @throws {Error} If vectors have different dimensions
  */
 export function cosineDistance(a, b) {
-  if (a.length !== b.length) {
-    throw new Error(`Dimension mismatch: ${a.length} vs ${b.length}`);
-  }
+  assertSameDimensions(a, b, 'cosineDistance');
 
   let dotProduct = 0;
   let normA = 0;
@@ -56,9 +68,7 @@ export function cosineDistance(a, b) {
  * @throws {Error} If vectors have different dimensions
  */
 export function euclideanDistance(a, b) {
-  if (a.length !== b.length) {
-    throw new Error(`Dimension mismatch: ${a.length} vs ${b.length}`);
-  }
+  assertSameDimensions(a, b, 'euclideanDistance');
 
   let sum = 0;
   for (let i = 0; i < a.length; i++) {
@@ -81,9 +91,7 @@ export function euclideanDistance(a, b) {
  * @throws {Error} If vectors have different dimensions
  */
 export function manhattanDistance(a, b) {
-  if (a.length !== b.length) {
-    throw new Error(`Dimension mismatch: ${a.length} vs ${b.length}`);
-  }
+  assertSameDimensions(a, b, 'manhattanDistance');
 
   let sum = 0;
   for (let i = 0; i < a.length; i++) {
@@ -104,9 +112,7 @@ export function manhattanDistance(a, b) {
  * @throws {Error} If vectors have different dimensions
  */
 export function dotProduct(a, b) {
-  if (a.length !== b.length) {
-    throw new Error(`Dimension mismatch: ${a.length} vs ${b.length}`);
-  }
+  assertSameDimensions(a, b, 'dotProduct');
 
   let sum = 0;
   for (let i = 0; i < a.length; i++) {

package/src/plugins/vector/kmeans.js

@@ -5,6 +5,7 @@
  * and comprehensive optimal K analysis using multiple metrics.
  */
 
+import { ValidationError } from '../../errors.js';
 import { euclideanDistance } from './distances.js';
 
 /**
@@ -31,15 +32,27 @@ export function kmeans(vectors, k, options = {}) {
   } = options;
 
   if (vectors.length === 0) {
-    throw new Error('Cannot cluster empty vector array');
+    throw new ValidationError('Cannot cluster empty vector array', {
+      operation: 'kmeans',
+      retriable: false,
+      suggestion: 'Provide at least one vector before invoking k-means.'
+    });
   }
 
   if (k < 1) {
-    throw new Error(`k must be at least 1, got ${k}`);
+    throw new ValidationError(`k must be at least 1, got ${k}`, {
+      operation: 'kmeans',
+      retriable: false,
+      suggestion: 'Use a positive integer for the number of clusters.'
+    });
   }
 
   if (k > vectors.length) {
-    throw new Error(`k (${k}) cannot be greater than number of vectors (${vectors.length})`);
+    throw new ValidationError(`k (${k}) cannot be greater than number of vectors (${vectors.length})`, {
+      operation: 'kmeans',
+      retriable: false,
+      suggestion: 'Reduce k or provide more vectors before clustering.'
+    });
   }
 
   const dimensions = vectors[0].length;
@@ -47,7 +60,16 @@ export function kmeans(vectors, k, options = {}) {
   // Validate all vectors have same dimensions
   for (let i = 1; i < vectors.length; i++) {
     if (vectors[i].length !== dimensions) {
-      throw new Error(`All vectors must have same dimensions. Expected ${dimensions}, got ${vectors[i].length} at index ${i}`);
+      throw new ValidationError('All vectors must have same dimensions.', {
+        operation: 'kmeans',
+        retriable: false,
+        suggestion: 'Pad or trim vectors so every row has identical dimensionality.',
+        metadata: {
+          expectedDimensions: dimensions,
+          actualDimensions: vectors[i].length,
+          index: i
+        }
+      });
     }
   }
 

package/src/resource.class.js

@@ -191,6 +191,15 @@ export class Resource extends AsyncEventEmitter {
       createdBy,
     };
 
+    // Store raw schema definition (accessible as resource.$schema)
+    // This is the LITERAL object passed to createResource()
+    // Useful for plugins, documentation, and introspection
+    this.$schema = cloneDeep(config);
+
+    // Add metadata timestamps
+    this.$schema._createdAt = Date.now();
+    this.$schema._updatedAt = Date.now();
+
     // Initialize hooks system - expanded to cover ALL methods
     this.hooks = {
       // Insert hooks
@@ -1175,7 +1184,14 @@ export class Resource extends AsyncEventEmitter {
     // LOG: body e contentType antes do putObject
     // Only throw if behavior is 'body-only' and body is empty
     if (this.behavior === 'body-only' && (!body || body === "")) {
-      throw new Error(`[Resource.insert] Attempt to save object without body! Data: id=${finalId}, resource=${this.name}`);
+      throw new ResourceError('Body required for body-only behavior', {
+        resourceName: this.name,
+        operation: 'insert',
+        id: finalId,
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Include a request body when using behavior "body-only" or switch to "body-overflow".'
+      });
     }
     // For other behaviors, allow empty body (all data in metadata)
 
@@ -1272,8 +1288,22 @@ export class Resource extends AsyncEventEmitter {
    * const user = await resource.get('user-123');
    */
   async get(id) {
-    if (isObject(id)) throw new Error(`id cannot be an object`);
-    if (isEmpty(id)) throw new Error('id cannot be empty');
+    if (isObject(id)) {
+      throw new ValidationError('Resource id must be a string', {
+        field: 'id',
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Pass the resource id as a string value (e.g. "user-123").'
+      });
+    }
+    if (isEmpty(id)) {
+      throw new ValidationError('Resource id cannot be empty', {
+        field: 'id',
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Provide a non-empty id when calling resource methods.'
+      });
+    }
 
     // Execute beforeGet hooks
     await this.executeHooks('beforeGet', { id });
@@ -1454,12 +1484,23 @@ export class Resource extends AsyncEventEmitter {
       */
   async update(id, attributes) {
     if (isEmpty(id)) {
-      throw new Error('id cannot be empty');
+      throw new ValidationError('Resource id cannot be empty', {
+        field: 'id',
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Provide the target id when calling update().'
+      });
     }
     // Garante que o recurso existe antes de atualizar
     const exists = await this.exists(id);
     if (!exists) {
-      throw new Error(`Resource with id '${id}' does not exist`);
+      throw new ResourceError(`Resource with id '${id}' does not exist`, {
+        resourceName: this.name,
+        id,
+        statusCode: 404,
+        retriable: false,
+        suggestion: 'Ensure the record exists or create it before attempting an update.'
+      });
     }
     const originalData = await this.get(id);
     const attributesClone = cloneDeep(attributes);
@@ -1685,11 +1726,21 @@ export class Resource extends AsyncEventEmitter {
    */
   async patch(id, fields, options = {}) {
     if (isEmpty(id)) {
-      throw new Error('id cannot be empty');
+      throw new ValidationError('Resource id cannot be empty', {
+        field: 'id',
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Provide the target id when calling patch().'
+      });
     }
 
     if (!fields || typeof fields !== 'object') {
-      throw new Error('fields must be a non-empty object');
+      throw new ValidationError('fields must be a non-empty object', {
+        field: 'fields',
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Pass a plain object with the fields to update (e.g. { status: "active" }).'
+      });
     }
 
     // Execute beforePatch hooks
@@ -1843,11 +1894,21 @@ export class Resource extends AsyncEventEmitter {
    */
   async replace(id, fullData, options = {}) {
     if (isEmpty(id)) {
-      throw new Error('id cannot be empty');
+      throw new ValidationError('Resource id cannot be empty', {
+        field: 'id',
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Provide the target id when calling replace().'
+      });
     }
 
     if (!fullData || typeof fullData !== 'object') {
-      throw new Error('fullData must be a non-empty object');
+      throw new ValidationError('fullData must be a non-empty object', {
+        field: 'fullData',
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Pass a plain object containing the full resource payload to replace().'
+      });
     }
 
     // Execute beforeReplace hooks
@@ -1921,7 +1982,14 @@ export class Resource extends AsyncEventEmitter {
 
     // Only throw if behavior is 'body-only' and body is empty
     if (this.behavior === 'body-only' && (!body || body === "")) {
-      throw new Error(`[Resource.replace] Attempt to save object without body! Data: id=${id}, resource=${this.name}`);
+      throw new ResourceError('Body required for body-only behavior', {
+        resourceName: this.name,
+        operation: 'replace',
+        id,
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Include a request body when using behavior "body-only" or switch to "body-overflow".'
+      });
     }
 
     // Store to S3 (overwrites if exists, creates if not - true replace/upsert)
@@ -2000,12 +2068,22 @@ export class Resource extends AsyncEventEmitter {
    */
   async updateConditional(id, attributes, options = {}) {
     if (isEmpty(id)) {
-      throw new Error('id cannot be empty');
+      throw new ValidationError('Resource id cannot be empty', {
+        field: 'id',
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Provide the target id when calling updateConditional().'
+      });
     }
 
     const { ifMatch } = options;
     if (!ifMatch) {
-      throw new Error('updateConditional requires ifMatch option with ETag value');
+      throw new ValidationError('updateConditional requires ifMatch option with ETag value', {
+        field: 'ifMatch',
+        statusCode: 428,
+        retriable: false,
+        suggestion: 'Pass the current object ETag in options.ifMatch to enable conditional updates.'
+      });
     }
 
     // Check if resource exists
@@ -2214,7 +2292,12 @@ export class Resource extends AsyncEventEmitter {
    */
   async delete(id) {
     if (isEmpty(id)) {
-      throw new Error('id cannot be empty');
+      throw new ValidationError('Resource id cannot be empty', {
+        field: 'id',
+        statusCode: 400,
+        retriable: false,
+        suggestion: 'Provide the target id when calling delete().'
+      });
     }
     
     let objectData;
@@ -3006,7 +3089,8 @@ export class Resource extends AsyncEventEmitter {
     const key = this.getResourceKey(id);
     const [ok, err, response] = await tryFn(() => this.client.getObject(key));
     if (!ok) {
-      if (err.name === "NoSuchKey") {
+      // Check multiple ways the error might indicate "not found"
+      if (err.name === "NoSuchKey" || err.code === "NoSuchKey" || err.Code === "NoSuchKey" || err.statusCode === 404) {
         return {
           buffer: null,
           contentType: null
@@ -3801,7 +3885,15 @@ export class Resource extends AsyncEventEmitter {
           let idx = -1;
           const stack = this._middlewares.get(method);
           const dispatch = async (i) => {
-            if (i <= idx) throw new Error('next() called multiple times');
+            if (i <= idx) {
+              throw new ResourceError('Resource middleware next() called multiple times', {
+                resourceName: this.name,
+                operation: method,
+                statusCode: 500,
+                retriable: false,
+                suggestion: 'Ensure each middleware awaits next() at most once.'
+              });
+            }
             idx = i;
             if (i < stack.length) {
               return await stack[i](ctx, () => dispatch(i + 1));
@@ -3866,10 +3958,14 @@ export class Resource extends AsyncEventEmitter {
 
     const throwIfNoStateMachine = () => {
       if (!resource._stateMachine) {
-        throw new Error(
-          `No state machine configured for resource '${resource.name}'. ` +
-          `Ensure StateMachinePlugin is installed and configured for this resource.`
-        );
+        throw new ResourceError(`State machine not configured for resource '${resource.name}'`, {
+          resourceName: resource.name,
+          operation: 'stateMachine',
+          statusCode: 400,
+          retriable: false,
+          suggestion: 'Install and configure the StateMachinePlugin before calling resource.state.* methods.',
+          docs: 'https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/state-machine.md'
+        });
       }
     };
 

package/src/testing/factory.class.js

@@ -19,6 +19,8 @@
  * const users = await UserFactory.createMany(10);
  */
 
+import { ValidationError } from '../errors.js';
+
 export class Factory {
   /**
    * Global sequence counter
@@ -161,7 +163,13 @@ export class Factory {
     for (const traitName of traits) {
       const trait = this.traits.get(traitName);
       if (!trait) {
-        throw new Error(`Trait '${traitName}' not found in factory '${this.resourceName}'`);
+        throw new ValidationError(`Trait '${traitName}' not found in factory '${this.resourceName}'`, {
+          field: 'trait',
+          value: traitName,
+          resourceName: this.resourceName,
+          retriable: false,
+          suggestion: `Define the trait with Factory.define('${this.resourceName}').trait('${traitName}', ...) before using it.`
+        });
       }
 
       const traitAttrs = typeof trait === 'function'
@@ -194,7 +202,11 @@ export class Factory {
     const { database = Factory._database } = options;
 
     if (!database) {
-      throw new Error('Database not set. Use Factory.setDatabase(db) or pass database option');
+      throw new ValidationError('Database not set for factory', {
+        field: 'database',
+        retriable: false,
+        suggestion: 'Call Factory.setDatabase(db) globally or pass { database } when invoking create().'
+      });
     }
 
     // Build attributes
@@ -208,7 +220,12 @@ export class Factory {
     // Get resource
     const resource = database.resources[this.resourceName];
     if (!resource) {
-      throw new Error(`Resource '${this.resourceName}' not found in database`);
+      throw new ValidationError(`Resource '${this.resourceName}' not found in database`, {
+        field: 'resourceName',
+        value: this.resourceName,
+        retriable: false,
+        suggestion: `Ensure the resource is created in the database before using Factory '${this.resourceName}'.`
+      });
     }
 
     // Create in database

package/src/testing/seeder.class.js

@@ -16,6 +16,7 @@
  */
 
 import { Factory } from './factory.class.js';
+import { ValidationError } from '../errors.js';
 
 export class Seeder {
   /**
@@ -59,7 +60,12 @@ export class Seeder {
 
       const factory = Factory.get(resourceName);
       if (!factory) {
-        throw new Error(`Factory for '${resourceName}' not found. Define it with Factory.define()`);
+        throw new ValidationError(`Factory for '${resourceName}' not found`, {
+          field: 'resourceName',
+          value: resourceName,
+          retriable: false,
+          suggestion: `Register a factory with Factory.define('${resourceName}', ...) before seeding.`
+        });
       }
 
       created[resourceName] = await factory.createMany(count, {}, { database: this.database });