s3db.js 11.2.3 → 11.2.4

package/src/plugins/backup/filesystem-backup-driver.class.js

@@ -5,6 +5,7 @@ import { pipeline } from 'stream/promises';
 import path from 'path';
 import crypto from 'crypto';
 import tryFn from '../../concerns/try-fn.js';
+import { BackupError } from '../backup.errors.js';
 
 /**
  * FilesystemBackupDriver - Stores backups on local/network filesystem
@@ -31,7 +32,11 @@ export default class FilesystemBackupDriver extends BaseBackupDriver {
   async onSetup() {
     // Validate path configuration
     if (!this.config.path) {
-      throw new Error('FilesystemBackupDriver: path configuration is required');
+      throw new BackupError('FilesystemBackupDriver: path configuration is required', {
+        operation: 'onSetup',
+        driver: 'filesystem',
+        suggestion: 'Provide a path in config: new FilesystemBackupDriver({ path: "/path/to/backups" })'
+      });
     }
 
     this.log(`Initialized with path: ${this.config.path}`);
@@ -69,13 +74,28 @@ export default class FilesystemBackupDriver extends BaseBackupDriver {
     );
     
     if (!createDirOk) {
-      throw new Error(`Failed to create backup directory: ${createDirErr.message}`);
+      throw new BackupError('Failed to create backup directory', {
+        operation: 'upload',
+        driver: 'filesystem',
+        backupId,
+        targetDir,
+        original: createDirErr,
+        suggestion: 'Check directory permissions and disk space'
+      });
     }
 
     // Copy backup file
     const [copyOk, copyErr] = await tryFn(() => copyFile(filePath, targetPath));
     if (!copyOk) {
-      throw new Error(`Failed to copy backup file: ${copyErr.message}`);
+      throw new BackupError('Failed to copy backup file', {
+        operation: 'upload',
+        driver: 'filesystem',
+        backupId,
+        filePath,
+        targetPath,
+        original: copyErr,
+        suggestion: 'Check file permissions and disk space'
+      });
     }
 
     // Write manifest
@@ -90,7 +110,14 @@ export default class FilesystemBackupDriver extends BaseBackupDriver {
     if (!manifestOk) {
       // Clean up backup file if manifest fails
       await tryFn(() => unlink(targetPath));
-      throw new Error(`Failed to write manifest: ${manifestErr.message}`);
+      throw new BackupError('Failed to write manifest file', {
+        operation: 'upload',
+        driver: 'filesystem',
+        backupId,
+        manifestPath,
+        original: manifestErr,
+        suggestion: 'Check directory permissions and disk space'
+      });
     }
 
     // Get file stats
@@ -116,7 +143,13 @@ export default class FilesystemBackupDriver extends BaseBackupDriver {
     // Check if source exists
     const [existsOk] = await tryFn(() => access(sourcePath));
     if (!existsOk) {
-      throw new Error(`Backup file not found: ${sourcePath}`);
+      throw new BackupError('Backup file not found', {
+        operation: 'download',
+        driver: 'filesystem',
+        backupId,
+        sourcePath,
+        suggestion: 'Check if backup exists using list() method'
+      });
     }
 
     // Create target directory if needed
@@ -126,7 +159,15 @@ export default class FilesystemBackupDriver extends BaseBackupDriver {
     // Copy file
     const [copyOk, copyErr] = await tryFn(() => copyFile(sourcePath, targetPath));
     if (!copyOk) {
-      throw new Error(`Failed to download backup: ${copyErr.message}`);
+      throw new BackupError('Failed to download backup', {
+        operation: 'download',
+        driver: 'filesystem',
+        backupId,
+        sourcePath,
+        targetPath,
+        original: copyErr,
+        suggestion: 'Check file permissions and disk space'
+      });
     }
 
     this.log(`Downloaded backup ${backupId} from ${sourcePath} to ${targetPath}`);
@@ -150,7 +191,14 @@ export default class FilesystemBackupDriver extends BaseBackupDriver {
     const [deleteManifestOk] = await tryFn(() => unlink(manifestPath));
 
     if (!deleteBackupOk && !deleteManifestOk) {
-      throw new Error(`Failed to delete backup files for ${backupId}`);
+      throw new BackupError('Failed to delete backup files', {
+        operation: 'delete',
+        driver: 'filesystem',
+        backupId,
+        backupPath,
+        manifestPath,
+        suggestion: 'Check file permissions'
+      });
     }
 
     this.log(`Deleted backup ${backupId}`);

package/src/plugins/backup/index.js

@@ -2,6 +2,7 @@ import BaseBackupDriver from './base-backup-driver.class.js';
 import FilesystemBackupDriver from './filesystem-backup-driver.class.js';
 import S3BackupDriver from './s3-backup-driver.class.js';
 import MultiBackupDriver from './multi-backup-driver.class.js';
+import { BackupError } from '../backup.errors.js';
 
 export { 
   BaseBackupDriver, 
@@ -27,11 +28,16 @@ export const BACKUP_DRIVERS = {
  */
 export function createBackupDriver(driver, config = {}) {
   const DriverClass = BACKUP_DRIVERS[driver];
-  
+
   if (!DriverClass) {
-    throw new Error(`Unknown backup driver: ${driver}. Available drivers: ${Object.keys(BACKUP_DRIVERS).join(', ')}`);
+    throw new BackupError(`Unknown backup driver: ${driver}`, {
+      operation: 'createBackupDriver',
+      driver,
+      availableDrivers: Object.keys(BACKUP_DRIVERS),
+      suggestion: `Use one of the available drivers: ${Object.keys(BACKUP_DRIVERS).join(', ')}`
+    });
   }
-  
+
   return new DriverClass(config);
 }
 
@@ -43,18 +49,32 @@ export function createBackupDriver(driver, config = {}) {
  */
 export function validateBackupConfig(driver, config = {}) {
   if (!driver || typeof driver !== 'string') {
-    throw new Error('Driver type must be a non-empty string');
+    throw new BackupError('Driver type must be a non-empty string', {
+      operation: 'validateBackupConfig',
+      driver,
+      suggestion: 'Provide a valid driver type string (filesystem, s3, or multi)'
+    });
   }
 
   if (!BACKUP_DRIVERS[driver]) {
-    throw new Error(`Unknown backup driver: ${driver}. Available drivers: ${Object.keys(BACKUP_DRIVERS).join(', ')}`);
+    throw new BackupError(`Unknown backup driver: ${driver}`, {
+      operation: 'validateBackupConfig',
+      driver,
+      availableDrivers: Object.keys(BACKUP_DRIVERS),
+      suggestion: `Use one of the available drivers: ${Object.keys(BACKUP_DRIVERS).join(', ')}`
+    });
   }
 
   // Driver-specific validation
   switch (driver) {
     case 'filesystem':
       if (!config.path) {
-        throw new Error('FilesystemBackupDriver requires "path" configuration');
+        throw new BackupError('FilesystemBackupDriver requires "path" configuration', {
+          operation: 'validateBackupConfig',
+          driver: 'filesystem',
+          config,
+          suggestion: 'Provide a "path" property in config: { path: "/path/to/backups" }'
+        });
       }
       break;
 
@@ -64,13 +84,24 @@ export function validateBackupConfig(driver, config = {}) {
 
     case 'multi':
       if (!Array.isArray(config.destinations) || config.destinations.length === 0) {
-        throw new Error('MultiBackupDriver requires non-empty "destinations" array');
+        throw new BackupError('MultiBackupDriver requires non-empty "destinations" array', {
+          operation: 'validateBackupConfig',
+          driver: 'multi',
+          config,
+          suggestion: 'Provide destinations array: { destinations: [{ driver: "s3", config: {...} }] }'
+        });
       }
-      
+
       // Validate each destination
       config.destinations.forEach((dest, index) => {
         if (!dest.driver) {
-          throw new Error(`Destination ${index} must have a "driver" property`);
+          throw new BackupError(`Destination ${index} must have a "driver" property`, {
+            operation: 'validateBackupConfig',
+            driver: 'multi',
+            destinationIndex: index,
+            destination: dest,
+            suggestion: 'Each destination must have a driver property: { driver: "s3", config: {...} }'
+          });
         }
         
         // Recursive validation for nested drivers

package/src/plugins/backup/multi-backup-driver.class.js

@@ -1,6 +1,7 @@
 import BaseBackupDriver from './base-backup-driver.class.js';
 import { createBackupDriver } from './index.js';
 import tryFn from '../../concerns/try-fn.js';
+import { BackupError } from '../backup.errors.js';
 
 /**
  * MultiBackupDriver - Manages multiple backup destinations
@@ -34,13 +35,24 @@ export default class MultiBackupDriver extends BaseBackupDriver {
 
   async onSetup() {
     if (!Array.isArray(this.config.destinations) || this.config.destinations.length === 0) {
-      throw new Error('MultiBackupDriver: destinations array is required and must not be empty');
+      throw new BackupError('MultiBackupDriver requires non-empty destinations array', {
+        operation: 'onSetup',
+        driver: 'multi',
+        destinationsProvided: this.config.destinations,
+        suggestion: 'Provide destinations array: { destinations: [{ driver: "s3", config: {...} }, { driver: "filesystem", config: {...} }] }'
+      });
     }
 
     // Create and setup all driver instances
     for (const [index, destConfig] of this.config.destinations.entries()) {
       if (!destConfig.driver) {
-        throw new Error(`MultiBackupDriver: destination[${index}] must have a driver type`);
+        throw new BackupError(`Destination ${index} missing driver type`, {
+          operation: 'onSetup',
+          driver: 'multi',
+          destinationIndex: index,
+          destination: destConfig,
+          suggestion: 'Each destination must have a driver property: { driver: "s3", config: {...} } or { driver: "filesystem", config: {...} }'
+        });
       }
 
       try {
@@ -51,10 +63,18 @@ export default class MultiBackupDriver extends BaseBackupDriver {
           config: destConfig,
           index
         });
-        
+
         this.log(`Setup destination ${index}: ${destConfig.driver}`);
       } catch (error) {
-        throw new Error(`Failed to setup destination ${index} (${destConfig.driver}): ${error.message}`);
+        throw new BackupError(`Failed to setup destination ${index}`, {
+          operation: 'onSetup',
+          driver: 'multi',
+          destinationIndex: index,
+          destinationDriver: destConfig.driver,
+          destinationConfig: destConfig.config,
+          original: error,
+          suggestion: 'Check destination driver configuration and ensure dependencies are available'
+        });
       }
     }
 
@@ -92,7 +112,15 @@ export default class MultiBackupDriver extends BaseBackupDriver {
         }
       }
 
-      throw new Error(`All priority destinations failed: ${errors.map(e => `${e.destination}: ${e.error}`).join('; ')}`);
+      throw new BackupError('All priority destinations failed', {
+        operation: 'upload',
+        driver: 'multi',
+        strategy: 'priority',
+        backupId,
+        totalDestinations: this.drivers.length,
+        failures: errors,
+        suggestion: 'Check destination configurations and ensure at least one destination is accessible'
+      });
     }
 
     // For 'all' and 'any' strategies, upload to all destinations
@@ -128,11 +156,29 @@ export default class MultiBackupDriver extends BaseBackupDriver {
     const failedResults = allResults.filter(r => r.status === 'failed');
 
     if (strategy === 'all' && failedResults.length > 0) {
-      throw new Error(`Some destinations failed: ${failedResults.map(r => `${r.destination}: ${r.error}`).join('; ')}`);
+      throw new BackupError('Some destinations failed with strategy "all"', {
+        operation: 'upload',
+        driver: 'multi',
+        strategy: 'all',
+        backupId,
+        totalDestinations: this.drivers.length,
+        successCount: successResults.length,
+        failedCount: failedResults.length,
+        failures: failedResults,
+        suggestion: 'All destinations must succeed with "all" strategy. Use "any" strategy to tolerate failures, or fix failing destinations.'
+      });
     }
 
     if (strategy === 'any' && successResults.length === 0) {
-      throw new Error(`All destinations failed: ${failedResults.map(r => `${r.destination}: ${r.error}`).join('; ')}`);
+      throw new BackupError('All destinations failed with strategy "any"', {
+        operation: 'upload',
+        driver: 'multi',
+        strategy: 'any',
+        backupId,
+        totalDestinations: this.drivers.length,
+        failures: failedResults,
+        suggestion: 'At least one destination must succeed with "any" strategy. Check all destination configurations.'
+      });
     }
 
     return allResults;
@@ -160,7 +206,14 @@ export default class MultiBackupDriver extends BaseBackupDriver {
       }
     }
 
-    throw new Error(`Failed to download backup from any destination`);
+    throw new BackupError('Failed to download backup from any destination', {
+      operation: 'download',
+      driver: 'multi',
+      backupId,
+      targetPath,
+      attemptedDestinations: destinations.length,
+      suggestion: 'Check if backup exists in at least one destination and destinations are accessible'
+    });
   }
 
   async delete(backupId, metadata) {
@@ -188,7 +241,14 @@ export default class MultiBackupDriver extends BaseBackupDriver {
     }
 
     if (successCount === 0 && errors.length > 0) {
-      throw new Error(`Failed to delete from any destination: ${errors.join('; ')}`);
+      throw new BackupError('Failed to delete from any destination', {
+        operation: 'delete',
+        driver: 'multi',
+        backupId,
+        attemptedDestinations: destinations.length,
+        failures: errors,
+        suggestion: 'Check if backup exists in destinations and destinations are accessible with delete permissions'
+      });
     }
 
     if (errors.length > 0) {

package/src/plugins/backup/s3-backup-driver.class.js

@@ -4,6 +4,7 @@ import { stat } from 'fs/promises';
 import path from 'path';
 import crypto from 'crypto';
 import tryFn from '../../concerns/try-fn.js';
+import { BackupError } from '../backup.errors.js';
 
 /**
  * S3BackupDriver - Stores backups in S3-compatible storage
@@ -43,11 +44,19 @@ export default class S3BackupDriver extends BaseBackupDriver {
     }
 
     if (!this.config.client) {
-      throw new Error('S3BackupDriver: client is required (either via config or database)');
+      throw new BackupError('S3BackupDriver: client is required', {
+        operation: 'onSetup',
+        driver: 's3',
+        suggestion: 'Provide a client in config or ensure database has a client configured'
+      });
     }
 
     if (!this.config.bucket) {
-      throw new Error('S3BackupDriver: bucket is required (either via config or database)');
+      throw new BackupError('S3BackupDriver: bucket is required', {
+        operation: 'onSetup',
+        driver: 's3',
+        suggestion: 'Provide a bucket in config or ensure database has a bucket configured'
+      });
     }
 
     this.log(`Initialized with bucket: ${this.config.bucket}, path: ${this.config.path}`);
@@ -108,7 +117,15 @@ export default class S3BackupDriver extends BaseBackupDriver {
     });
 
     if (!uploadOk) {
-      throw new Error(`Failed to upload backup file: ${uploadErr.message}`);
+      throw new BackupError('Failed to upload backup file to S3', {
+        operation: 'upload',
+        driver: 's3',
+        backupId,
+        bucket: this.config.bucket,
+        key: backupKey,
+        original: uploadErr,
+        suggestion: 'Check S3 permissions and bucket configuration'
+      });
     }
 
     // Upload manifest
@@ -133,7 +150,15 @@ export default class S3BackupDriver extends BaseBackupDriver {
         bucket: this.config.bucket,
         key: backupKey
       }));
-      throw new Error(`Failed to upload manifest: ${manifestErr.message}`);
+      throw new BackupError('Failed to upload manifest to S3', {
+        operation: 'upload',
+        driver: 's3',
+        backupId,
+        bucket: this.config.bucket,
+        manifestKey,
+        original: manifestErr,
+        suggestion: 'Check S3 permissions and bucket configuration'
+      });
     }
 
     this.log(`Uploaded backup ${backupId} to s3://${this.config.bucket}/${backupKey} (${fileSize} bytes)`);
@@ -161,7 +186,16 @@ export default class S3BackupDriver extends BaseBackupDriver {
     );
 
     if (!downloadOk) {
-      throw new Error(`Failed to download backup: ${downloadErr.message}`);
+      throw new BackupError('Failed to download backup from S3', {
+        operation: 'download',
+        driver: 's3',
+        backupId,
+        bucket: this.config.bucket,
+        key: backupKey,
+        targetPath,
+        original: downloadErr,
+        suggestion: 'Check if backup exists and S3 permissions are correct'
+      });
     }
 
     this.log(`Downloaded backup ${backupId} from s3://${this.config.bucket}/${backupKey} to ${targetPath}`);
@@ -189,7 +223,15 @@ export default class S3BackupDriver extends BaseBackupDriver {
     );
 
     if (!deleteBackupOk && !deleteManifestOk) {
-      throw new Error(`Failed to delete backup objects for ${backupId}`);
+      throw new BackupError('Failed to delete backup from S3', {
+        operation: 'delete',
+        driver: 's3',
+        backupId,
+        bucket: this.config.bucket,
+        backupKey,
+        manifestKey,
+        suggestion: 'Check S3 delete permissions'
+      });
     }
 
     this.log(`Deleted backup ${backupId} from S3`);

package/src/plugins/backup.errors.js

@@ -0,0 +1,45 @@
+import { S3dbError } from '../errors.js';
+
+/**
+ * BackupError - Errors related to backup operations
+ *
+ * Used for backup driver operations including:
+ * - Driver initialization and setup
+ * - Backup upload/download/delete operations
+ * - Driver configuration validation
+ * - Multi-destination backup strategies
+ *
+ * @extends S3dbError
+ */
+export class BackupError extends S3dbError {
+  constructor(message, details = {}) {
+    const { driver = 'unknown', operation = 'unknown', backupId, ...rest } = details;
+
+    let description = details.description;
+    if (!description) {
+      description = `
+Backup Operation Error
+
+Driver: ${driver}
+Operation: ${operation}
+${backupId ? `Backup ID: ${backupId}` : ''}
+
+Common causes:
+1. Invalid backup driver configuration
+2. Destination storage not accessible
+3. Insufficient permissions
+4. Network connectivity issues
+5. Invalid backup file format
+
+Solution:
+Check driver configuration and ensure destination storage is accessible.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/backup.md
+`.trim();
+    }
+
+    super(message, { ...rest, driver, operation, backupId, description });
+  }
+}
+
+export default BackupError;

package/src/plugins/cache/cache.class.js

@@ -1,4 +1,5 @@
 import EventEmitter from "events";
+import { CacheError } from "../cache.errors.js";
 
 export class Cache extends EventEmitter {
   constructor(config = {}) {
@@ -13,7 +14,13 @@ export class Cache extends EventEmitter {
 
   validateKey(key) {
     if (key === null || key === undefined || typeof key !== 'string' || !key) {
-      throw new Error('Invalid key');
+      throw new CacheError('Invalid cache key', {
+        operation: 'validateKey',
+        driver: this.constructor.name,
+        key,
+        keyType: typeof key,
+        suggestion: 'Cache key must be a non-empty string'
+      });
     }
   }
 

package/src/plugins/cache.errors.js

@@ -0,0 +1,47 @@
+import { S3dbError } from '../errors.js';
+
+/**
+ * CacheError - Errors related to cache operations
+ *
+ * Used for cache operations including:
+ * - Cache driver initialization and setup
+ * - Cache get/set/delete operations
+ * - Cache invalidation and warming
+ * - Driver-specific operations (memory, filesystem, S3)
+ * - Resource-level caching
+ *
+ * @extends S3dbError
+ */
+export class CacheError extends S3dbError {
+  constructor(message, details = {}) {
+    const { driver = 'unknown', operation = 'unknown', resourceName, key, ...rest } = details;
+
+    let description = details.description;
+    if (!description) {
+      description = `
+Cache Operation Error
+
+Driver: ${driver}
+Operation: ${operation}
+${resourceName ? `Resource: ${resourceName}` : ''}
+${key ? `Key: ${key}` : ''}
+
+Common causes:
+1. Invalid cache key format
+2. Cache driver not properly initialized
+3. Resource not found or not cached
+4. Memory limits exceeded
+5. Filesystem permissions issues
+
+Solution:
+Check cache configuration and ensure the cache driver is properly initialized.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/cache.md
+`.trim();
+    }
+
+    super(message, { ...rest, driver, operation, resourceName, key, description });
+  }
+}
+
+export default CacheError;

package/src/plugins/cache.plugin.js

@@ -8,6 +8,7 @@ import MemoryCache from "./cache/memory-cache.class.js";
 import { FilesystemCache } from "./cache/filesystem-cache.class.js";
 import { PartitionAwareFilesystemCache } from "./cache/partition-aware-filesystem-cache.class.js";
 import tryFn from "../concerns/try-fn.js";
+import { CacheError } from "./cache.errors.js";
 
 /**
  * Cache Plugin Configuration
@@ -555,7 +556,13 @@ export class CachePlugin extends Plugin {
   async warmCache(resourceName, options = {}) {
     const resource = this.database.resources[resourceName];
     if (!resource) {
-      throw new Error(`Resource '${resourceName}' not found`);
+      throw new CacheError('Resource not found for cache warming', {
+        operation: 'warmCache',
+        driver: this.driver?.constructor.name,
+        resourceName,
+        availableResources: Object.keys(this.database.resources),
+        suggestion: 'Check resource name spelling or ensure resource has been created'
+      });
     }
 
     const { includePartitions = true, sampleSize = 100 } = options;

package/src/plugins/fulltext.errors.js

@@ -0,0 +1,46 @@
+import { S3dbError } from '../errors.js';
+
+/**
+ * FulltextError - Errors related to fulltext search operations
+ *
+ * Used for fulltext search operations including:
+ * - Index creation and updates
+ * - Search query execution
+ * - Index configuration
+ * - Text analysis and tokenization
+ * - Search result ranking
+ *
+ * @extends S3dbError
+ */
+export class FulltextError extends S3dbError {
+  constructor(message, details = {}) {
+    const { resourceName, query, operation = 'unknown', ...rest } = details;
+
+    let description = details.description;
+    if (!description) {
+      description = `
+Fulltext Search Operation Error
+
+Operation: ${operation}
+${resourceName ? `Resource: ${resourceName}` : ''}
+${query ? `Query: ${query}` : ''}
+
+Common causes:
+1. Resource not indexed for fulltext search
+2. Invalid query syntax
+3. Index not built yet
+4. Search configuration missing
+5. Field not indexed
+
+Solution:
+Ensure resource is configured for fulltext search and index is built.
+
+Docs: https://github.com/forattini-dev/s3db.js/blob/main/docs/plugins/fulltext.md
+`.trim();
+    }
+
+    super(message, { ...rest, resourceName, query, operation, description });
+  }
+}
+
+export default FulltextError;

package/src/plugins/fulltext.plugin.js

@@ -1,5 +1,6 @@
 import Plugin from "./plugin.class.js";
 import tryFn from "../concerns/try-fn.js";
+import { FulltextError } from "./fulltext.errors.js";
 
 export class FullTextPlugin extends Plugin {
   constructor(options = {}) {
@@ -399,14 +400,20 @@ export class FullTextPlugin extends Plugin {
   // Search and return full records
   async searchRecords(resourceName, query, options = {}) {
     const searchResults = await this.search(resourceName, query, options);
-    
+
     if (searchResults.length === 0) {
       return [];
     }
 
     const resource = this.database.resources[resourceName];
     if (!resource) {
-      throw new Error(`Resource '${resourceName}' not found`);
+      throw new FulltextError(`Resource '${resourceName}' not found`, {
+        operation: 'searchRecords',
+        resourceName,
+        query,
+        availableResources: Object.keys(this.database.resources),
+        suggestion: 'Check resource name or ensure resource is created before searching'
+      });
     }
 
     const recordIds = searchResults.map(result => result.recordId);
@@ -430,7 +437,12 @@ export class FullTextPlugin extends Plugin {
   async rebuildIndex(resourceName) {
     const resource = this.database.resources[resourceName];
     if (!resource) {
-      throw new Error(`Resource '${resourceName}' not found`);
+      throw new FulltextError(`Resource '${resourceName}' not found`, {
+        operation: 'rebuildIndex',
+        resourceName,
+        availableResources: Object.keys(this.database.resources),
+        suggestion: 'Check resource name or ensure resource is created before rebuilding index'
+      });
     }
 
     // Clear existing indexes for this resource