s3db.js 13.1.0 → 13.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s3db.js",
-  "version": "13.1.0",
+  "version": "13.2.2",
   "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",
@@ -133,6 +133,7 @@
     "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-replace": "^6.0.2",
     "@rollup/plugin-terser": "^0.4.4",
+    "@tensorflow/tfjs-node": "^4.22.0",
     "@types/node": "24.7.0",
     "@xenova/transformers": "^2.17.2",
     "@yao-pkg/pkg": "^6.9.0",

package/src/clients/memory-client.class.js

@@ -73,7 +73,7 @@ export class MemoryClient extends EventEmitter {
     const commandName = command.constructor.name;
     const input = command.input || {};
 
-    this.emit('command.request', commandName, input);
+    this.emit('cl:request', commandName, input);
 
     let response;
 
@@ -105,7 +105,7 @@ export class MemoryClient extends EventEmitter {
           throw new Error(`Unsupported command: ${commandName}`);
       }
 
-      this.emit('command.response', commandName, response, input);
+      this.emit('cl:response', commandName, response, input);
       return response;
 
     } catch (error) {
@@ -237,7 +237,7 @@ export class MemoryClient extends EventEmitter {
       ifMatch
     });
 
-    this.emit('putObject', null, { key, metadata, contentType, body, contentEncoding, contentLength });
+    this.emit('cl:PutObject', null, { key, metadata, contentType, body, contentEncoding, contentLength });
 
     return response;
   }
@@ -257,7 +257,7 @@ export class MemoryClient extends EventEmitter {
       }
     }
 
-    this.emit('getObject', null, { key });
+    this.emit('cl:GetObject', null, { key });
 
     return {
       ...response,
@@ -280,7 +280,7 @@ export class MemoryClient extends EventEmitter {
       }
     }
 
-    this.emit('headObject', null, { key });
+    this.emit('cl:HeadObject', null, { key });
 
     return {
       ...response,
@@ -311,7 +311,7 @@ export class MemoryClient extends EventEmitter {
       contentType
     });
 
-    this.emit('copyObject', null, { from, to, metadata, metadataDirective });
+    this.emit('cl:CopyObject', null, { from, to, metadata, metadataDirective });
 
     return response;
   }
@@ -331,7 +331,7 @@ export class MemoryClient extends EventEmitter {
     const fullKey = this.keyPrefix ? path.join(this.keyPrefix, key) : key;
     const response = await this.storage.delete(fullKey);
 
-    this.emit('deleteObject', null, { key });
+    this.emit('cl:DeleteObject', null, { key });
 
     return response;
   }
@@ -380,7 +380,7 @@ export class MemoryClient extends EventEmitter {
       continuationToken
     });
 
-    this.emit('listObjects', null, { prefix, count: response.Contents.length });
+    this.emit('cl:ListObjects', null, { prefix, count: response.Contents.length });
 
     return response;
   }
@@ -431,7 +431,7 @@ export class MemoryClient extends EventEmitter {
         .map(x => (x.startsWith('/') ? x.replace('/', '') : x));
     }
 
-    this.emit('getKeysPage', keys, params);
+    this.emit('cl:GetKeysPage', keys, params);
     return keys;
   }
 
@@ -454,7 +454,7 @@ export class MemoryClient extends EventEmitter {
         .map(x => (x.startsWith('/') ? x.replace('/', '') : x));
     }
 
-    this.emit('getAllKeys', keys, { prefix });
+    this.emit('cl:GetAllKeys', keys, { prefix });
     return keys;
   }
 
@@ -464,7 +464,7 @@ export class MemoryClient extends EventEmitter {
   async count({ prefix = '' } = {}) {
     const keys = await this.getAllKeys({ prefix });
     const count = keys.length;
-    this.emit('count', count, { prefix });
+    this.emit('cl:Count', count, { prefix });
     return count;
   }
 
@@ -479,14 +479,14 @@ export class MemoryClient extends EventEmitter {
       const result = await this.deleteObjects(keys);
       totalDeleted = result.Deleted.length;
 
-      this.emit('deleteAll', {
+      this.emit('cl:DeleteAll', {
         prefix,
         batch: totalDeleted,
         total: totalDeleted
       });
     }
 
-    this.emit('deleteAllComplete', {
+    this.emit('cl:DeleteAllComplete', {
       prefix,
       totalDeleted
     });
@@ -504,13 +504,13 @@ export class MemoryClient extends EventEmitter {
 
     // If offset is beyond available keys, return null
     if (offset >= keys.length) {
-      this.emit('getContinuationTokenAfterOffset', null, { prefix, offset });
+      this.emit('cl:GetContinuationTokenAfterOffset', null, { prefix, offset });
       return null;
     }
 
     // Return the key at offset position as continuation token
     const token = keys[offset];
-    this.emit('getContinuationTokenAfterOffset', token, { prefix, offset });
+    this.emit('cl:GetContinuationTokenAfterOffset', token, { prefix, offset });
     return token;
   }
 
@@ -544,7 +544,7 @@ export class MemoryClient extends EventEmitter {
       }
     }
 
-    this.emit('moveAllObjects', { results, errors }, { prefixFrom, prefixTo });
+    this.emit('cl:MoveAllObjects', { results, errors }, { prefixFrom, prefixTo });
 
     if (errors.length > 0) {
       const error = new Error('Some objects could not be moved');

package/src/clients/s3-client.class.js

@@ -100,7 +100,7 @@ export class S3Client extends EventEmitter {
   }
 
   async sendCommand(command) {
-    this.emit("command.request", command.constructor.name, command.input);
+    this.emit("cl:request", command.constructor.name, command.input);
     const [ok, err, response] = await tryFn(() => this.client.send(command));
     if (!ok) {
       const bucket = this.config.bucket;
@@ -112,7 +112,7 @@ export class S3Client extends EventEmitter {
         commandInput: command.input,
       });
     }
-    this.emit("command.response", command.constructor.name, response, command.input);
+    this.emit("cl:response", command.constructor.name, response, command.input);
     return response;
   }
 
@@ -146,7 +146,7 @@ export class S3Client extends EventEmitter {
     if (ifMatch !== undefined) options.IfMatch = ifMatch
 
     const [ok, err, response] = await tryFn(() => this.sendCommand(new PutObjectCommand(options)));
-    this.emit('putObject', err || response, { key, metadata, contentType, body, contentEncoding, contentLength });
+    this.emit('cl:PutObject', err || response, { key, metadata, contentType, body, contentEncoding, contentLength });
 
     if (!ok) {
       throw mapAwsError(err, {
@@ -182,7 +182,7 @@ export class S3Client extends EventEmitter {
       return res;
     });
 
-    this.emit('getObject', err || response, { key });
+    this.emit('cl:GetObject', err || response, { key });
 
     if (!ok) {
       throw mapAwsError(err, {
@@ -218,7 +218,7 @@ export class S3Client extends EventEmitter {
       return res;
     });
 
-    this.emit('headObject', err || response, { key });
+    this.emit('cl:HeadObject', err || response, { key });
 
     if (!ok) {
       throw mapAwsError(err, {
@@ -261,7 +261,7 @@ export class S3Client extends EventEmitter {
     }
 
     const [ok, err, response] = await tryFn(() => this.sendCommand(new CopyObjectCommand(options)));
-    this.emit('copyObject', err || response, { from, to, metadataDirective });
+    this.emit('cl:CopyObject', err || response, { from, to, metadataDirective });
 
     if (!ok) {
       throw mapAwsError(err, {
@@ -291,7 +291,7 @@ export class S3Client extends EventEmitter {
     };
 
     const [ok, err, response] = await tryFn(() => this.sendCommand(new DeleteObjectCommand(options)));
-    this.emit('deleteObject', err || response, { key });
+    this.emit('cl:DeleteObject', err || response, { key });
 
     if (!ok) {
       throw mapAwsError(err, {
@@ -346,7 +346,7 @@ export class S3Client extends EventEmitter {
       notFound: errors,
     }
 
-    this.emit("deleteObjects", report, keys);
+    this.emit("cl:DeleteObjects", report, keys);
     return report;
   }
 
@@ -382,7 +382,7 @@ export class S3Client extends EventEmitter {
         const deletedCount = deleteResponse.Deleted ? deleteResponse.Deleted.length : 0;
         totalDeleted += deletedCount;
 
-        this.emit("deleteAll", {
+        this.emit("cl:DeleteAll", {
           prefix,
           batch: deletedCount,
           total: totalDeleted
@@ -392,7 +392,7 @@ export class S3Client extends EventEmitter {
       continuationToken = listResponse.IsTruncated ? listResponse.NextContinuationToken : undefined;
     } while (continuationToken);
 
-    this.emit("deleteAllComplete", {
+    this.emit("cl:DeleteAllComplete", {
       prefix,
       totalDeleted
     });
@@ -428,7 +428,7 @@ export class S3Client extends EventEmitter {
     if (!ok) {
       throw new UnknownError("Unknown error in listObjects", { prefix, bucket: this.config.bucket, original: err });
     }
-      this.emit("listObjects", response, options);
+      this.emit("cl:ListObjects", response, options);
       return response;
   }
 
@@ -446,7 +446,7 @@ export class S3Client extends EventEmitter {
       truncated = response.IsTruncated || false;
       continuationToken = response.NextContinuationToken;
     }
-    this.emit("count", count, { prefix });
+    this.emit("cl:Count", count, { prefix });
     return count;
   }
 
@@ -471,7 +471,7 @@ export class S3Client extends EventEmitter {
         .map((x) => x.replace(this.config.keyPrefix, ""))
         .map((x) => (x.startsWith("/") ? x.replace(`/`, "") : x));
     }
-    this.emit("getAllKeys", keys, { prefix });
+    this.emit("cl:GetAllKeys", keys, { prefix });
     return keys;
   }
 
@@ -506,7 +506,7 @@ export class S3Client extends EventEmitter {
         break;
       }
     }
-    this.emit("getContinuationTokenAfterOffset", continuationToken || null, params);
+    this.emit("cl:GetContinuationTokenAfterOffset", continuationToken || null, params);
     return continuationToken || null;
   }
 
@@ -525,7 +525,7 @@ export class S3Client extends EventEmitter {
         offset,
       });
       if (!continuationToken) {
-        this.emit("getKeysPage", [], params);
+        this.emit("cl:GetKeysPage", [], params);
         return [];
       }
     }
@@ -550,7 +550,7 @@ export class S3Client extends EventEmitter {
         .map((x) => x.replace(this.config.keyPrefix, ""))
         .map((x) => (x.startsWith("/") ? x.replace(`/`, "") : x));
     }
-    this.emit("getKeysPage", keys, params);
+    this.emit("cl:GetKeysPage", keys, params);
     return keys;
   }
 
@@ -572,7 +572,7 @@ export class S3Client extends EventEmitter {
         }
         return to;
       });
-    this.emit("moveAllObjects", { results, errors }, { prefixFrom, prefixTo });
+    this.emit("cl:MoveAllObjects", { results, errors }, { prefixFrom, prefixTo });
     if (errors.length > 0) {
       throw new UnknownError("Some objects could not be moved", {
         bucket: this.config.bucket,

package/src/concerns/error-classifier.js

@@ -0,0 +1,204 @@
+/**
+ * Error Classifier - Determines if errors should be retried
+ *
+ * Classifies errors into RETRIABLE or NON_RETRIABLE categories
+ * based on error codes, HTTP status codes, and error properties.
+ *
+ * @example
+ * const classification = ErrorClassifier.classify(error);
+ * if (classification === 'RETRIABLE') {
+ *   // Retry the operation
+ * }
+ */
+
+const RETRIABLE = 'RETRIABLE';
+const NON_RETRIABLE = 'NON_RETRIABLE';
+
+/**
+ * Network and timeout error codes (retriable)
+ */
+const RETRIABLE_NETWORK_CODES = new Set([
+  'ECONNREFUSED',
+  'ETIMEDOUT',
+  'ECONNRESET',
+  'EPIPE',
+  'ENOTFOUND',
+  'NetworkError',
+  'NETWORK_ERROR',
+  'TimeoutError',
+  'TIMEOUT'
+]);
+
+/**
+ * AWS throttling and rate limit codes (retriable)
+ */
+const RETRIABLE_AWS_CODES = new Set([
+  'ThrottlingException',
+  'TooManyRequestsException',
+  'RequestLimitExceeded',
+  'ProvisionedThroughputExceededException',
+  'RequestThrottledException',
+  'SlowDown',
+  'ServiceUnavailable'
+]);
+
+/**
+ * AWS conflict and conditional check failures (retriable)
+ */
+const RETRIABLE_AWS_CONFLICTS = new Set([
+  'ConditionalCheckFailedException',
+  'TransactionConflictException'
+]);
+
+/**
+ * Retriable HTTP status codes (5xx server errors, 429 rate limit)
+ */
+const RETRIABLE_STATUS_CODES = new Set([
+  429, // Too Many Requests
+  500, // Internal Server Error
+  502, // Bad Gateway
+  503, // Service Unavailable
+  504, // Gateway Timeout
+  507, // Insufficient Storage
+  509  // Bandwidth Limit Exceeded
+]);
+
+/**
+ * Non-retriable error names (validation, business logic)
+ */
+const NON_RETRIABLE_ERROR_NAMES = new Set([
+  'ValidationError',
+  'StateMachineError',
+  'SchemaError',
+  'AuthenticationError',
+  'PermissionError',
+  'BusinessLogicError',
+  'InvalidStateTransition'
+]);
+
+/**
+ * Non-retriable HTTP status codes (client errors)
+ */
+const NON_RETRIABLE_STATUS_CODES = new Set([
+  400, // Bad Request
+  401, // Unauthorized
+  403, // Forbidden
+  404, // Not Found
+  405, // Method Not Allowed
+  406, // Not Acceptable
+  409, // Conflict
+  410, // Gone
+  422  // Unprocessable Entity
+]);
+
+export class ErrorClassifier {
+  /**
+   * Classify an error as RETRIABLE or NON_RETRIABLE
+   *
+   * @param {Error} error - The error to classify
+   * @param {Object} options - Classification options
+   * @param {Array<string>} options.retryableErrors - Custom retriable error names/codes
+   * @param {Array<string>} options.nonRetriableErrors - Custom non-retriable error names/codes
+   * @returns {string} 'RETRIABLE' or 'NON_RETRIABLE'
+   */
+  static classify(error, options = {}) {
+    if (!error) return NON_RETRIABLE;
+
+    const {
+      retryableErrors = [],
+      nonRetriableErrors = []
+    } = options;
+
+    // Check custom error lists first
+    if (retryableErrors.length > 0) {
+      const isCustomRetriable = retryableErrors.some(errType =>
+        error.code === errType ||
+        error.name === errType ||
+        error.message?.includes(errType)
+      );
+      if (isCustomRetriable) return RETRIABLE;
+    }
+
+    if (nonRetriableErrors.length > 0) {
+      const isCustomNonRetriable = nonRetriableErrors.some(errType =>
+        error.code === errType ||
+        error.name === errType ||
+        error.message?.includes(errType)
+      );
+      if (isCustomNonRetriable) return NON_RETRIABLE;
+    }
+
+    // Check explicit retriable property on error
+    if (error.retriable === false) return NON_RETRIABLE;
+    if (error.retriable === true) return RETRIABLE;
+
+    // Check for non-retriable error names
+    if (NON_RETRIABLE_ERROR_NAMES.has(error.name)) {
+      return NON_RETRIABLE;
+    }
+
+    // Check for non-retriable HTTP status codes
+    if (error.statusCode && NON_RETRIABLE_STATUS_CODES.has(error.statusCode)) {
+      return NON_RETRIABLE;
+    }
+
+    // Check for retriable network errors
+    if (error.code && RETRIABLE_NETWORK_CODES.has(error.code)) {
+      return RETRIABLE;
+    }
+
+    // Check for retriable AWS errors
+    if (error.code && RETRIABLE_AWS_CODES.has(error.code)) {
+      return RETRIABLE;
+    }
+
+    // Check for retriable AWS conflicts
+    if (error.code && RETRIABLE_AWS_CONFLICTS.has(error.code)) {
+      return RETRIABLE;
+    }
+
+    // Check for retriable HTTP status codes
+    if (error.statusCode && RETRIABLE_STATUS_CODES.has(error.statusCode)) {
+      return RETRIABLE;
+    }
+
+    // Check for timeout in error message
+    if (error.message && typeof error.message === 'string') {
+      const lowerMessage = error.message.toLowerCase();
+      if (lowerMessage.includes('timeout') ||
+          lowerMessage.includes('timed out') ||
+          lowerMessage.includes('network') ||
+          lowerMessage.includes('connection')) {
+        return RETRIABLE;
+      }
+    }
+
+    // Default: treat as retriable (conservative approach)
+    // This ensures transient failures are retried by default
+    return RETRIABLE;
+  }
+
+  /**
+   * Check if an error is retriable
+   *
+   * @param {Error} error - The error to check
+   * @param {Object} options - Classification options
+   * @returns {boolean} true if retriable
+   */
+  static isRetriable(error, options = {}) {
+    return this.classify(error, options) === RETRIABLE;
+  }
+
+  /**
+   * Check if an error is non-retriable
+   *
+   * @param {Error} error - The error to check
+   * @param {Object} options - Classification options
+   * @returns {boolean} true if non-retriable
+   */
+  static isNonRetriable(error, options = {}) {
+    return this.classify(error, options) === NON_RETRIABLE;
+  }
+}
+
+export { RETRIABLE, NON_RETRIABLE };

package/src/database.class.js

@@ -255,13 +255,13 @@ export class Database extends EventEmitter {
 
     // Emit definition changes if any were detected
     if (definitionChanges.length > 0) {
-      this.emit("resourceDefinitionsChanged", {
+      this.emit("db:resource-definitions-changed", {
         changes: definitionChanges,
         metadata: this.savedMetadata
       });
     }
 
-    this.emit("connected", new Date());
+    this.emit("db:connected", new Date());
   }
 
   /**
@@ -527,7 +527,7 @@ export class Database extends EventEmitter {
       this.pluginList.splice(index, 1);
     }
 
-    this.emit('plugin.uninstalled', { name: pluginName, plugin });
+    this.emit('db:plugin:uninstalled', { name: pluginName, plugin });
   }
 
   async uploadMetadataFile() {
@@ -598,7 +598,7 @@ export class Database extends EventEmitter {
     });
 
     this.savedMetadata = metadata;
-    this.emit('metadataUploaded', metadata);
+    this.emit('db:metadata-uploaded', metadata);
   }
 
   blankMetadataStructure() {
@@ -918,7 +918,7 @@ export class Database extends EventEmitter {
         contentType: 'application/json'
       });
 
-      this.emit('metadataHealed', { healingLog, metadata });
+      this.emit('db:metadata-healed', { healingLog, metadata });
 
       if (this.verbose) {
         console.warn('S3DB: Successfully uploaded healed metadata');
@@ -1091,7 +1091,7 @@ export class Database extends EventEmitter {
       if (!existingVersionData || existingVersionData.hash !== newHash) {
         await this.uploadMetadataFile();
       }
-      this.emit("s3db.resourceUpdated", name);
+      this.emit("db:resource:updated", name);
       return existingResource;
     }
     const existingMetadata = this.savedMetadata?.resources?.[name];
@@ -1131,7 +1131,7 @@ export class Database extends EventEmitter {
     }
 
     await this.uploadMetadataFile();
-    this.emit("s3db.resourceCreated", name);
+    this.emit("db:resource:created", name);
     return resource;
   }
 
@@ -1290,7 +1290,7 @@ export class Database extends EventEmitter {
 
       // 4. Emit disconnected event BEFORE removing database listeners (race condition fix)
       // This ensures listeners can actually receive the event
-      await this.emit('disconnected', new Date());
+      await this.emit('db:disconnected', new Date());
 
       // 5. Remove all listeners from the database itself
       this.removeAllListeners();
@@ -1427,7 +1427,7 @@ export class Database extends EventEmitter {
       const [ok, error] = await tryFn(() => hook({ database: this, ...context }));
       if (!ok) {
         // Emit error event
-        this.emit('hookError', { event, error, context });
+        this.emit('db:hook-error', { event, error, context });
 
         // In strict mode, throw on first error instead of continuing
         if (this.strictHooks) {

package/src/plugins/backup.plugin.js

@@ -149,7 +149,7 @@ export class BackupPlugin extends Plugin {
       console.log(`[BackupPlugin] Initialized with driver: ${storageInfo.type}`);
     }
 
-    this.emit('initialized', {
+    this.emit('db:plugin:initialized', {
       driver: this.driver.getType(),
       config: this.driver.getStorageInfo()
     });
@@ -205,7 +205,7 @@ export class BackupPlugin extends Plugin {
         await this._executeHook(this.config.onBackupStart, type, { backupId });
       }
       
-      this.emit('backup_start', { id: backupId, type });
+      this.emit('plg:backup:start', { id: backupId, type });
       
       // Create backup metadata
       const metadata = await this._createBackupMetadata(backupId, type);
@@ -262,7 +262,7 @@ export class BackupPlugin extends Plugin {
           await this._executeHook(this.config.onBackupComplete, type, stats);
         }
         
-        this.emit('backup_complete', { 
+        this.emit('plg:backup:complete', { 
           id: backupId, 
           type, 
           size: totalSize, 
@@ -300,7 +300,7 @@ export class BackupPlugin extends Plugin {
         duration: Date.now() - startTime
       });
       
-      this.emit('backup_error', { id: backupId, type, error: error.message });
+      this.emit('plg:backup:error', { id: backupId, type, error: error.message });
       throw error;
       
     } finally {
@@ -579,7 +579,7 @@ export class BackupPlugin extends Plugin {
         await this._executeHook(this.config.onRestoreStart, backupId, options);
       }
       
-      this.emit('restore_start', { id: backupId, options });
+      this.emit('plg:backup:restore-start', { id: backupId, options });
       
       // Get backup metadata
       const backup = await this.getBackupStatus(backupId);
@@ -616,7 +616,7 @@ export class BackupPlugin extends Plugin {
           await this._executeHook(this.config.onRestoreComplete, backupId, { restored: restoredResources });
         }
         
-        this.emit('restore_complete', { 
+        this.emit('plg:backup:restore-complete', { 
           id: backupId, 
           restored: restoredResources 
         });
@@ -637,7 +637,7 @@ export class BackupPlugin extends Plugin {
         await this._executeHook(this.config.onRestoreError, backupId, { error });
       }
       
-      this.emit('restore_error', { id: backupId, error: error.message });
+      this.emit('plg:backup:restore-error', { id: backupId, error: error.message });
       throw error;
     }
   }
@@ -973,7 +973,7 @@ export class BackupPlugin extends Plugin {
   async stop() {
     // Cancel any active backups
     for (const backupId of this.activeBackups) {
-      this.emit('backup_cancelled', { id: backupId });
+      this.emit('plg:backup:cancelled', { id: backupId });
     }
     this.activeBackups.clear();
     

package/src/plugins/cache.plugin.js

@@ -434,7 +434,7 @@ export class CachePlugin extends Plugin {
         const [ok, err] = await this.clearCacheWithRetry(resource.cache, specificKey);
 
         if (!ok) {
-          this.emit('cache_clear_error', {
+          this.emit('plg:cache:clear-error', {
             resource: resource.name,
             method,
             id: data.id,
@@ -456,7 +456,7 @@ export class CachePlugin extends Plugin {
             const [ok, err] = await this.clearCacheWithRetry(resource.cache, partitionKeyPrefix);
 
             if (!ok) {
-              this.emit('cache_clear_error', {
+              this.emit('plg:cache:clear-error', {
                 resource: resource.name,
                 partition: partitionName,
                 error: err.message
@@ -475,7 +475,7 @@ export class CachePlugin extends Plugin {
     const [ok, err] = await this.clearCacheWithRetry(resource.cache, keyPrefix);
 
     if (!ok) {
-      this.emit('cache_clear_error', {
+      this.emit('plg:cache:clear-error', {
         resource: resource.name,
         type: 'broad',
         error: err.message