s3db.js 13.6.1 → 14.0.2

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 });