s3db.js 11.2.2 → 11.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s3db.js",
-  "version": "11.2.2",
+  "version": "11.2.4",
   "description": "Use AWS S3, the world's most reliable document storage, as a database with this ORM.",
   "main": "dist/s3db.cjs.js",
   "module": "dist/s3db.es.js",

package/src/behaviors/enforce-limits.js

@@ -1,5 +1,6 @@
 import { calculateTotalSize } from '../concerns/calculator.js';
 import { calculateEffectiveLimit } from '../concerns/calculator.js';
+import { MetadataLimitError } from '../errors.js';
 
 export const S3_METADATA_LIMIT_BYTES = 2047;
 
@@ -146,9 +147,16 @@ export async function handleInsert({ resource, data, mappedData, originalData })
   });
   
   if (totalSize > effectiveLimit) {
-    throw new Error(`S3 metadata size exceeds 2KB limit. Current size: ${totalSize} bytes, effective limit: ${effectiveLimit} bytes, absolute limit: ${S3_METADATA_LIMIT_BYTES} bytes`);
+    throw new MetadataLimitError('Metadata size exceeds 2KB limit on insert', {
+      totalSize,
+      effectiveLimit,
+      absoluteLimit: S3_METADATA_LIMIT_BYTES,
+      excess: totalSize - effectiveLimit,
+      resourceName: resource.name,
+      operation: 'insert'
+    });
   }
-  
+
   // If data fits in metadata, store only in metadata
   return { mappedData, body: "" };
 }
@@ -167,7 +175,15 @@ export async function handleUpdate({ resource, id, data, mappedData, originalDat
   });
   
   if (totalSize > effectiveLimit) {
-    throw new Error(`S3 metadata size exceeds 2KB limit. Current size: ${totalSize} bytes, effective limit: ${effectiveLimit} bytes, absolute limit: ${S3_METADATA_LIMIT_BYTES} bytes`);
+    throw new MetadataLimitError('Metadata size exceeds 2KB limit on update', {
+      totalSize,
+      effectiveLimit,
+      absoluteLimit: S3_METADATA_LIMIT_BYTES,
+      excess: totalSize - effectiveLimit,
+      resourceName: resource.name,
+      operation: 'update',
+      id
+    });
   }
   return { mappedData, body: JSON.stringify(mappedData) };
 }
@@ -186,7 +202,15 @@ export async function handleUpsert({ resource, id, data, mappedData }) {
   });
   
   if (totalSize > effectiveLimit) {
-    throw new Error(`S3 metadata size exceeds 2KB limit. Current size: ${totalSize} bytes, effective limit: ${effectiveLimit} bytes, absolute limit: ${S3_METADATA_LIMIT_BYTES} bytes`);
+    throw new MetadataLimitError('Metadata size exceeds 2KB limit on upsert', {
+      totalSize,
+      effectiveLimit,
+      absoluteLimit: S3_METADATA_LIMIT_BYTES,
+      excess: totalSize - effectiveLimit,
+      resourceName: resource.name,
+      operation: 'upsert',
+      id
+    });
   }
   return { mappedData, body: "" };
 }

package/src/behaviors/index.js

@@ -3,6 +3,7 @@ import * as enforceLimits from './enforce-limits.js';
 import * as dataTruncate from './truncate-data.js';
 import * as bodyOverflow from './body-overflow.js';
 import * as bodyOnly from './body-only.js';
+import { BehaviorError } from '../errors.js';
 
 /**
  * Available behaviors for Resource metadata handling
@@ -23,7 +24,11 @@ export const behaviors = {
 export function getBehavior(behaviorName) {
   const behavior = behaviors[behaviorName];
   if (!behavior) {
-    throw new Error(`Unknown behavior: ${behaviorName}. Available behaviors: ${Object.keys(behaviors).join(', ')}`);
+    throw new BehaviorError(`Unknown behavior: ${behaviorName}`, {
+      behavior: behaviorName,
+      availableBehaviors: Object.keys(behaviors),
+      operation: 'getBehavior'
+    });
   }
   return behavior;
 }

package/src/client.class.js

@@ -544,7 +544,17 @@ export class Client extends EventEmitter {
       });
     this.emit("moveAllObjects", { results, errors }, { prefixFrom, prefixTo });
     if (errors.length > 0) {
-      throw new Error("Some objects could not be moved");
+      throw new UnknownError("Some objects could not be moved", {
+        bucket: this.config.bucket,
+        operation: 'moveAllObjects',
+        prefixFrom,
+        prefixTo,
+        totalKeys: keys.length,
+        failedCount: errors.length,
+        successCount: results.length,
+        errors: errors.map(e => ({ message: e.message, raw: e.raw })),
+        suggestion: 'Check S3 permissions and retry failed objects individually'
+      });
     }
     return results;
   }

package/src/concerns/partition-queue.js

@@ -1,4 +1,5 @@
 import { EventEmitter } from 'events';
+import { PartitionDriverError } from '../errors.js';
 
 /**
  * Robust partition operation queue with retry and persistence
@@ -107,7 +108,12 @@ export class PartitionQueue extends EventEmitter {
       case 'delete':
         return await resource.deletePartitionReferences(data);
       default:
-        throw new Error(`Unknown operation type: ${type}`);
+        throw new PartitionDriverError(`Unknown partition operation type: ${type}`, {
+          driver: 'PartitionQueue',
+          operation: type,
+          availableOperations: ['create', 'update', 'delete'],
+          suggestion: 'Use one of the supported partition operations: create, update, or delete'
+        });
     }
   }
 

package/src/concerns/plugin-storage.js

@@ -31,6 +31,7 @@
 import { metadataEncode, metadataDecode } from './metadata-encoding.js';
 import { calculateEffectiveLimit, calculateUTF8Bytes } from './calculator.js';
 import { tryFn } from './try-fn.js';
+import { PluginStorageError, MetadataLimitError, BehaviorError } from '../errors.js';
 
 const S3_METADATA_LIMIT = 2047; // AWS S3 metadata limit in bytes
 
@@ -41,10 +42,17 @@ export class PluginStorage {
    */
   constructor(client, pluginSlug) {
     if (!client) {
-      throw new Error('PluginStorage requires a client instance');
+      throw new PluginStorageError('PluginStorage requires a client instance', {
+        operation: 'constructor',
+        pluginSlug,
+        suggestion: 'Pass a valid S3db Client instance when creating PluginStorage'
+      });
     }
     if (!pluginSlug) {
-      throw new Error('PluginStorage requires a pluginSlug');
+      throw new PluginStorageError('PluginStorage requires a pluginSlug', {
+        operation: 'constructor',
+        suggestion: 'Provide a plugin slug (e.g., "eventual-consistency", "cache", "audit")'
+      });
     }
 
     this.client = client;
@@ -113,7 +121,15 @@ export class PluginStorage {
     const [ok, err] = await tryFn(() => this.client.putObject(putParams));
 
     if (!ok) {
-      throw new Error(`PluginStorage.set failed for key ${key}: ${err.message}`);
+      throw new PluginStorageError(`Failed to save plugin data`, {
+        pluginSlug: this.pluginSlug,
+        key,
+        operation: 'set',
+        behavior,
+        ttl,
+        original: err,
+        suggestion: 'Check S3 permissions and key format'
+      });
     }
   }
 
@@ -139,7 +155,13 @@ export class PluginStorage {
       if (err.name === 'NoSuchKey' || err.Code === 'NoSuchKey') {
         return null;
       }
-      throw new Error(`PluginStorage.get failed for key ${key}: ${err.message}`);
+      throw new PluginStorageError(`Failed to retrieve plugin data`, {
+        pluginSlug: this.pluginSlug,
+        key,
+        operation: 'get',
+        original: err,
+        suggestion: 'Check if the key exists and S3 permissions are correct'
+      });
     }
 
     // Metadata is already decoded by Client, but values are strings
@@ -162,7 +184,13 @@ export class PluginStorage {
           data = { ...parsedMetadata, ...body };
         }
       } catch (parseErr) {
-        throw new Error(`PluginStorage.get failed to parse body for key ${key}: ${parseErr.message}`);
+        throw new PluginStorageError(`Failed to parse JSON body`, {
+          pluginSlug: this.pluginSlug,
+          key,
+          operation: 'get',
+          original: parseErr,
+          suggestion: 'Body content may be corrupted. Check S3 object integrity'
+        });
       }
     }
 
@@ -248,7 +276,15 @@ export class PluginStorage {
     );
 
     if (!ok) {
-      throw new Error(`PluginStorage.list failed: ${err.message}`);
+      throw new PluginStorageError(`Failed to list plugin data`, {
+        pluginSlug: this.pluginSlug,
+        operation: 'list',
+        prefix,
+        fullPrefix,
+        limit,
+        original: err,
+        suggestion: 'Check S3 permissions and bucket configuration'
+      });
     }
 
     // Remove keyPrefix from keys
@@ -277,7 +313,16 @@ export class PluginStorage {
     );
 
     if (!ok) {
-      throw new Error(`PluginStorage.listForResource failed: ${err.message}`);
+      throw new PluginStorageError(`Failed to list resource data`, {
+        pluginSlug: this.pluginSlug,
+        operation: 'listForResource',
+        resourceName,
+        subPrefix,
+        fullPrefix,
+        limit,
+        original: err,
+        suggestion: 'Check resource name and S3 permissions'
+      });
     }
 
     // Remove keyPrefix from keys
@@ -456,7 +501,13 @@ export class PluginStorage {
     const [ok, err] = await tryFn(() => this.client.deleteObject(key));
 
     if (!ok) {
-      throw new Error(`PluginStorage.delete failed for key ${key}: ${err.message}`);
+      throw new PluginStorageError(`Failed to delete plugin data`, {
+        pluginSlug: this.pluginSlug,
+        key,
+        operation: 'delete',
+        original: err,
+        suggestion: 'Check S3 delete permissions'
+      });
     }
   }
 
@@ -686,10 +737,15 @@ export class PluginStorage {
           currentSize += keySize + valueSize;
 
           if (currentSize > effectiveLimit) {
-            throw new Error(
-              `Data exceeds metadata limit (${currentSize} > ${effectiveLimit} bytes). ` +
-              `Use 'body-overflow' or 'body-only' behavior.`
-            );
+            throw new MetadataLimitError(`Data exceeds metadata limit with enforce-limits behavior`, {
+              totalSize: currentSize,
+              effectiveLimit,
+              absoluteLimit: S3_METADATA_LIMIT,
+              excess: currentSize - effectiveLimit,
+              operation: 'PluginStorage.set',
+              pluginSlug: this.pluginSlug,
+              suggestion: "Use 'body-overflow' or 'body-only' behavior to handle large data"
+            });
           }
 
           metadata[key] = jsonValue;
@@ -698,7 +754,13 @@ export class PluginStorage {
       }
 
       default:
-        throw new Error(`Unknown behavior: ${behavior}. Use 'body-overflow', 'body-only', or 'enforce-limits'.`);
+        throw new BehaviorError(`Unknown behavior: ${behavior}`, {
+          behavior,
+          availableBehaviors: ['body-overflow', 'body-only', 'enforce-limits'],
+          operation: 'PluginStorage._applyBehavior',
+          pluginSlug: this.pluginSlug,
+          suggestion: "Use 'body-overflow', 'body-only', or 'enforce-limits'"
+        });
     }
 
     return { metadata, body };

package/src/database.class.js

@@ -6,7 +6,7 @@ import jsonStableStringify from "json-stable-stringify";
 import Client from "./client.class.js";
 import tryFn from "./concerns/try-fn.js";
 import Resource from "./resource.class.js";
-import { ResourceNotFound } from "./errors.js";
+import { ResourceNotFound, DatabaseError } from "./errors.js";
 import { idGenerator } from "./concerns/id.js";
 import { streamToString } from "./stream/index.js";
 
@@ -35,6 +35,7 @@ export class Database extends EventEmitter {
     this.passphrase = options.passphrase || "secret";
     this.versioningEnabled = options.versioningEnabled || false;
     this.persistHooks = options.persistHooks || false; // New configuration for hook persistence
+    this.strictValidation = options.strictValidation !== false; // Enable strict validation by default
 
     // Initialize hooks system
     this._initHooks();
@@ -199,6 +200,7 @@ export class Database extends EventEmitter {
           asyncEvents: versionData.asyncEvents !== undefined ? versionData.asyncEvents : true,
           hooks: this.persistHooks ? this._deserializeHooks(versionData.hooks || {}) : (versionData.hooks || {}),
           versioningEnabled: this.versioningEnabled,
+          strictValidation: this.strictValidation,
           map: versionData.map,
           idGenerator: restoredIdGenerator,
           idSize: restoredIdSize
@@ -450,7 +452,12 @@ export class Database extends EventEmitter {
     const plugin = this.plugins[pluginName] || this.pluginRegistry[pluginName];
 
     if (!plugin) {
-      throw new Error(`Plugin '${name}' not found`);
+      throw new DatabaseError(`Plugin '${name}' not found`, {
+        operation: 'uninstallPlugin',
+        pluginName: name,
+        availablePlugins: Object.keys(this.pluginRegistry),
+        suggestion: 'Check plugin name or list available plugins using Object.keys(db.pluginRegistry)'
+      });
     }
 
     // Stop the plugin first
@@ -999,6 +1006,7 @@ export class Database extends EventEmitter {
       autoDecrypt: config.autoDecrypt !== undefined ? config.autoDecrypt : true,
       hooks: hooks || {},
       versioningEnabled: this.versioningEnabled,
+      strictValidation: this.strictValidation,
       map: config.map,
       idGenerator: config.idGenerator,
       idSize: config.idSize,
@@ -1215,10 +1223,20 @@ export class Database extends EventEmitter {
   addHook(event, fn) {
     if (!this._hooks) this._initHooks();
     if (!this._hooks.has(event)) {
-      throw new Error(`Unknown hook event: ${event}. Available events: ${this._hookEvents.join(', ')}`);
+      throw new DatabaseError(`Unknown hook event: ${event}`, {
+        operation: 'addHook',
+        invalidEvent: event,
+        availableEvents: this._hookEvents,
+        suggestion: `Use one of the available hook events: ${this._hookEvents.join(', ')}`
+      });
     }
     if (typeof fn !== 'function') {
-      throw new Error('Hook function must be a function');
+      throw new DatabaseError('Hook function must be a function', {
+        operation: 'addHook',
+        event,
+        receivedType: typeof fn,
+        suggestion: 'Provide a function that will be called when the hook event occurs'
+      });
     }
     this._hooks.get(event).push(fn);
   }