s3db.js 9.2.0 → 9.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s3db.js",
-  "version": "9.2.0",
+  "version": "9.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",
@@ -103,23 +103,23 @@
     "@rollup/plugin-terser": "^0.4.4",
     "@types/node": "24.3.0",
     "babel-loader": "^10.0.0",
-    "chalk": "^5.5.0",
+    "chalk": "^5.6.0",
     "cli-table3": "^0.6.5",
     "commander": "^14.0.0",
     "esbuild": "^0.25.9",
-    "inquirer": "^12.9.2",
+    "inquirer": "^12.9.3",
     "jest": "^30.0.5",
     "node-loader": "^2.1.0",
     "ora": "^8.2.0",
     "pkg": "^5.8.1",
-    "rollup": "^4.46.2",
+    "rollup": "^4.46.4",
     "rollup-plugin-copy": "^3.5.0",
     "rollup-plugin-esbuild": "^6.2.1",
     "rollup-plugin-polyfill-node": "^0.13.0",
     "rollup-plugin-shebang-bin": "^0.1.0",
     "rollup-plugin-terser": "^7.0.2",
     "typescript": "5.9.2",
-    "webpack": "^5.101.2",
+    "webpack": "^5.101.3",
     "webpack-cli": "^6.0.1"
   },
   "funding": [

package/src/concerns/async-event-emitter.js

@@ -0,0 +1,46 @@
+import EventEmitter from 'events';
+
+class AsyncEventEmitter extends EventEmitter {
+  constructor() {
+    super();
+    this._asyncMode = true;
+  }
+
+  emit(event, ...args) {
+    if (!this._asyncMode) {
+      return super.emit(event, ...args);
+    }
+
+    const listeners = this.listeners(event);
+    
+    if (listeners.length === 0) {
+      return false;
+    }
+
+    setImmediate(async () => {
+      for (const listener of listeners) {
+        try {
+          await listener(...args);
+        } catch (error) {
+          if (event !== 'error') {
+            this.emit('error', error);
+          } else {
+            console.error('Error in error handler:', error);
+          }
+        }
+      }
+    });
+
+    return true;
+  }
+
+  emitSync(event, ...args) {
+    return super.emit(event, ...args);
+  }
+
+  setAsyncMode(enabled) {
+    this._asyncMode = enabled;
+  }
+}
+
+export default AsyncEventEmitter;

package/src/database.class.js

@@ -74,6 +74,9 @@ export class Database extends EventEmitter {
       parallelism: this.parallelism,
       connectionString: connectionString,
     });
+    
+    // Store connection string for CLI access
+    this.connectionString = connectionString;
 
     this.bucket = this.client.bucket;
     this.keyPrefix = this.client.keyPrefix;
@@ -193,6 +196,7 @@ export class Database extends EventEmitter {
           paranoid: versionData.paranoid !== undefined ? versionData.paranoid : true,
           allNestedObjectsOptional: versionData.allNestedObjectsOptional !== undefined ? versionData.allNestedObjectsOptional : true,
           autoDecrypt: versionData.autoDecrypt !== undefined ? versionData.autoDecrypt : true,
+          asyncEvents: versionData.asyncEvents !== undefined ? versionData.asyncEvents : true,
           hooks: this.persistHooks ? this._deserializeHooks(versionData.hooks || {}) : (versionData.hooks || {}),
           versioningEnabled: this.versioningEnabled,
           map: versionData.map,
@@ -483,6 +487,7 @@ export class Database extends EventEmitter {
             allNestedObjectsOptional: resource.config.allNestedObjectsOptional,
             autoDecrypt: resource.config.autoDecrypt,
             cache: resource.config.cache,
+            asyncEvents: resource.config.asyncEvents,
             hooks: this.persistHooks ? this._serializeHooks(resource.config.hooks) : resource.config.hooks,
             idSize: resource.idSize,
             idGenerator: resource.idGeneratorType,
@@ -886,6 +891,23 @@ export class Database extends EventEmitter {
     };
   }
 
+  /**
+   * Create or update a resource in the database
+   * @param {Object} config - Resource configuration
+   * @param {string} config.name - Resource name
+   * @param {Object} config.attributes - Resource attributes schema
+   * @param {string} [config.behavior='user-managed'] - Resource behavior strategy
+   * @param {Object} [config.hooks] - Resource hooks
+   * @param {boolean} [config.asyncEvents=true] - Whether events should be emitted asynchronously
+   * @param {boolean} [config.timestamps=false] - Enable automatic timestamps
+   * @param {Object} [config.partitions={}] - Partition definitions
+   * @param {boolean} [config.paranoid=true] - Security flag for dangerous operations
+   * @param {boolean} [config.cache=false] - Enable caching
+   * @param {boolean} [config.autoDecrypt=true] - Auto-decrypt secret fields
+   * @param {Function|number} [config.idGenerator] - Custom ID generator or size
+   * @param {number} [config.idSize=22] - Size for auto-generated IDs
+   * @returns {Promise<Resource>} The created or updated resource
+   */
   async createResource({ name, attributes, behavior = 'user-managed', hooks, ...config }) {
     if (this.resources[name]) {
       const existingResource = this.resources[name];
@@ -945,6 +967,7 @@ export class Database extends EventEmitter {
       map: config.map,
       idGenerator: config.idGenerator,
       idSize: config.idSize,
+      asyncEvents: config.asyncEvents,
       events: config.events || {}
     });
     resource.database = this;

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

@@ -0,0 +1,119 @@
+/**
+ * BaseBackupDriver - Abstract base class for backup drivers
+ *
+ * Defines the interface that all backup drivers must implement.
+ * Each driver handles a specific destination type (filesystem, S3, etc.)
+ */
+export default class BaseBackupDriver {
+  constructor(config = {}) {
+    this.config = {
+      compression: 'gzip',
+      encryption: null,
+      verbose: false,
+      ...config
+    };
+  }
+
+  /**
+   * Initialize the driver
+   * @param {Database} database - S3DB database instance
+   */
+  async setup(database) {
+    this.database = database;
+    await this.onSetup();
+  }
+
+  /**
+   * Override this method to perform driver-specific setup
+   */
+  async onSetup() {
+    // Override in subclasses
+  }
+
+  /**
+   * Upload a backup file to the destination
+   * @param {string} filePath - Path to the backup file
+   * @param {string} backupId - Unique backup identifier
+   * @param {Object} manifest - Backup manifest with metadata
+   * @returns {Object} Upload result with destination info
+   */
+  async upload(filePath, backupId, manifest) {
+    throw new Error('upload() method must be implemented by subclass');
+  }
+
+  /**
+   * Download a backup file from the destination
+   * @param {string} backupId - Unique backup identifier
+   * @param {string} targetPath - Local path to save the backup
+   * @param {Object} metadata - Backup metadata
+   * @returns {string} Path to downloaded file
+   */
+  async download(backupId, targetPath, metadata) {
+    throw new Error('download() method must be implemented by subclass');
+  }
+
+  /**
+   * Delete a backup from the destination
+   * @param {string} backupId - Unique backup identifier
+   * @param {Object} metadata - Backup metadata
+   */
+  async delete(backupId, metadata) {
+    throw new Error('delete() method must be implemented by subclass');
+  }
+
+  /**
+   * List backups available in the destination
+   * @param {Object} options - List options (limit, prefix, etc.)
+   * @returns {Array} List of backup metadata
+   */
+  async list(options = {}) {
+    throw new Error('list() method must be implemented by subclass');
+  }
+
+  /**
+   * Verify backup integrity
+   * @param {string} backupId - Unique backup identifier
+   * @param {string} expectedChecksum - Expected file checksum
+   * @param {Object} metadata - Backup metadata
+   * @returns {boolean} True if backup is valid
+   */
+  async verify(backupId, expectedChecksum, metadata) {
+    throw new Error('verify() method must be implemented by subclass');
+  }
+
+  /**
+   * Get driver type identifier
+   * @returns {string} Driver type
+   */
+  getType() {
+    throw new Error('getType() method must be implemented by subclass');
+  }
+
+  /**
+   * Get driver-specific storage info
+   * @returns {Object} Storage information
+   */
+  getStorageInfo() {
+    return {
+      type: this.getType(),
+      config: this.config
+    };
+  }
+
+  /**
+   * Clean up resources
+   */
+  async cleanup() {
+    // Override in subclasses if needed
+  }
+
+  /**
+   * Log message if verbose mode is enabled
+   * @param {string} message - Message to log
+   */
+  log(message) {
+    if (this.config.verbose) {
+      console.log(`[${this.getType()}BackupDriver] ${message}`);
+    }
+  }
+}

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

@@ -0,0 +1,254 @@
+import BaseBackupDriver from './base-backup-driver.class.js';
+import { mkdir, copyFile, unlink, readdir, stat, access } from 'fs/promises';
+import { createReadStream, createWriteStream } from 'fs';
+import { pipeline } from 'stream/promises';
+import path from 'path';
+import crypto from 'crypto';
+import tryFn from '../../concerns/try-fn.js';
+
+/**
+ * FilesystemBackupDriver - Stores backups on local/network filesystem
+ *
+ * Configuration:
+ * - path: Base directory for backups (supports template variables)
+ * - permissions: File permissions (default: 0o644)
+ * - directoryPermissions: Directory permissions (default: 0o755)
+ */
+export default class FilesystemBackupDriver extends BaseBackupDriver {
+  constructor(config = {}) {
+    super({
+      path: './backups/{date}/',
+      permissions: 0o644,
+      directoryPermissions: 0o755,
+      ...config
+    });
+  }
+
+  getType() {
+    return 'filesystem';
+  }
+
+  async onSetup() {
+    // Validate path configuration
+    if (!this.config.path) {
+      throw new Error('FilesystemBackupDriver: path configuration is required');
+    }
+
+    this.log(`Initialized with path: ${this.config.path}`);
+  }
+
+  /**
+   * Resolve path template variables
+   * @param {string} backupId - Backup identifier
+   * @param {Object} manifest - Backup manifest
+   * @returns {string} Resolved path
+   */
+  resolvePath(backupId, manifest = {}) {
+    const now = new Date();
+    const dateStr = now.toISOString().slice(0, 10); // YYYY-MM-DD
+    const timeStr = now.toISOString().slice(11, 19).replace(/:/g, '-'); // HH-MM-SS
+    
+    return this.config.path
+      .replace('{date}', dateStr)
+      .replace('{time}', timeStr)
+      .replace('{year}', now.getFullYear().toString())
+      .replace('{month}', (now.getMonth() + 1).toString().padStart(2, '0'))
+      .replace('{day}', now.getDate().toString().padStart(2, '0'))
+      .replace('{backupId}', backupId)
+      .replace('{type}', manifest.type || 'backup');
+  }
+
+  async upload(filePath, backupId, manifest) {
+    const targetDir = this.resolvePath(backupId, manifest);
+    const targetPath = path.join(targetDir, `${backupId}.backup`);
+    const manifestPath = path.join(targetDir, `${backupId}.manifest.json`);
+
+    // Create target directory
+    const [createDirOk, createDirErr] = await tryFn(() => 
+      mkdir(targetDir, { recursive: true, mode: this.config.directoryPermissions })
+    );
+    
+    if (!createDirOk) {
+      throw new Error(`Failed to create backup directory: ${createDirErr.message}`);
+    }
+
+    // Copy backup file
+    const [copyOk, copyErr] = await tryFn(() => copyFile(filePath, targetPath));
+    if (!copyOk) {
+      throw new Error(`Failed to copy backup file: ${copyErr.message}`);
+    }
+
+    // Write manifest
+    const [manifestOk, manifestErr] = await tryFn(() => 
+      import('fs/promises').then(fs => fs.writeFile(
+        manifestPath, 
+        JSON.stringify(manifest, null, 2),
+        { mode: this.config.permissions }
+      ))
+    );
+    
+    if (!manifestOk) {
+      // Clean up backup file if manifest fails
+      await tryFn(() => unlink(targetPath));
+      throw new Error(`Failed to write manifest: ${manifestErr.message}`);
+    }
+
+    // Get file stats
+    const [statOk, , stats] = await tryFn(() => stat(targetPath));
+    const size = statOk ? stats.size : 0;
+
+    this.log(`Uploaded backup ${backupId} to ${targetPath} (${size} bytes)`);
+
+    return {
+      path: targetPath,
+      manifestPath,
+      size,
+      uploadedAt: new Date().toISOString()
+    };
+  }
+
+  async download(backupId, targetPath, metadata) {
+    const sourcePath = metadata.path || path.join(
+      this.resolvePath(backupId, metadata), 
+      `${backupId}.backup`
+    );
+
+    // Check if source exists
+    const [existsOk] = await tryFn(() => access(sourcePath));
+    if (!existsOk) {
+      throw new Error(`Backup file not found: ${sourcePath}`);
+    }
+
+    // Create target directory if needed
+    const targetDir = path.dirname(targetPath);
+    await tryFn(() => mkdir(targetDir, { recursive: true }));
+
+    // Copy file
+    const [copyOk, copyErr] = await tryFn(() => copyFile(sourcePath, targetPath));
+    if (!copyOk) {
+      throw new Error(`Failed to download backup: ${copyErr.message}`);
+    }
+
+    this.log(`Downloaded backup ${backupId} from ${sourcePath} to ${targetPath}`);
+    return targetPath;
+  }
+
+  async delete(backupId, metadata) {
+    const backupPath = metadata.path || path.join(
+      this.resolvePath(backupId, metadata), 
+      `${backupId}.backup`
+    );
+    const manifestPath = metadata.manifestPath || path.join(
+      this.resolvePath(backupId, metadata), 
+      `${backupId}.manifest.json`
+    );
+
+    // Delete backup file
+    const [deleteBackupOk] = await tryFn(() => unlink(backupPath));
+    
+    // Delete manifest file
+    const [deleteManifestOk] = await tryFn(() => unlink(manifestPath));
+
+    if (!deleteBackupOk && !deleteManifestOk) {
+      throw new Error(`Failed to delete backup files for ${backupId}`);
+    }
+
+    this.log(`Deleted backup ${backupId}`);
+  }
+
+  async list(options = {}) {
+    const { limit = 50, prefix = '' } = options;
+    const basePath = this.resolvePath('*').replace('*', '');
+    
+    try {
+      const results = [];
+      await this._scanDirectory(path.dirname(basePath), prefix, results, limit);
+      
+      // Sort by creation time (newest first)
+      results.sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt));
+      
+      return results.slice(0, limit);
+    } catch (error) {
+      this.log(`Error listing backups: ${error.message}`);
+      return [];
+    }
+  }
+
+  async _scanDirectory(dirPath, prefix, results, limit) {
+    if (results.length >= limit) return;
+
+    const [readDirOk, , files] = await tryFn(() => readdir(dirPath));
+    if (!readDirOk) return;
+
+    for (const file of files) {
+      if (results.length >= limit) break;
+
+      const fullPath = path.join(dirPath, file);
+      const [statOk, , stats] = await tryFn(() => stat(fullPath));
+      
+      if (!statOk) continue;
+
+      if (stats.isDirectory()) {
+        await this._scanDirectory(fullPath, prefix, results, limit);
+      } else if (file.endsWith('.manifest.json')) {
+        // Read manifest to get backup info
+        const [readOk, , content] = await tryFn(() => 
+          import('fs/promises').then(fs => fs.readFile(fullPath, 'utf8'))
+        );
+        
+        if (readOk) {
+          try {
+            const manifest = JSON.parse(content);
+            const backupId = file.replace('.manifest.json', '');
+            
+            if (!prefix || backupId.includes(prefix)) {
+              results.push({
+                id: backupId,
+                path: fullPath.replace('.manifest.json', '.backup'),
+                manifestPath: fullPath,
+                size: stats.size,
+                createdAt: manifest.createdAt || stats.birthtime.toISOString(),
+                ...manifest
+              });
+            }
+          } catch (parseErr) {
+            this.log(`Failed to parse manifest ${fullPath}: ${parseErr.message}`);
+          }
+        }
+      }
+    }
+  }
+
+  async verify(backupId, expectedChecksum, metadata) {
+    const backupPath = metadata.path || path.join(
+      this.resolvePath(backupId, metadata), 
+      `${backupId}.backup`
+    );
+
+    const [readOk, readErr] = await tryFn(async () => {
+      const hash = crypto.createHash('sha256');
+      const stream = createReadStream(backupPath);
+      
+      await pipeline(stream, hash);
+      const actualChecksum = hash.digest('hex');
+      
+      return actualChecksum === expectedChecksum;
+    });
+
+    if (!readOk) {
+      this.log(`Verification failed for ${backupId}: ${readErr.message}`);
+      return false;
+    }
+
+    return readOk;
+  }
+
+  getStorageInfo() {
+    return {
+      ...super.getStorageInfo(),
+      path: this.config.path,
+      permissions: this.config.permissions,
+      directoryPermissions: this.config.directoryPermissions
+    };
+  }
+}

package/src/plugins/backup/index.js

@@ -0,0 +1,85 @@
+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';
+
+export { 
+  BaseBackupDriver, 
+  FilesystemBackupDriver, 
+  S3BackupDriver, 
+  MultiBackupDriver 
+};
+
+/**
+ * Available backup drivers
+ */
+export const BACKUP_DRIVERS = {
+  filesystem: FilesystemBackupDriver,
+  s3: S3BackupDriver,
+  multi: MultiBackupDriver
+};
+
+/**
+ * Create a backup driver instance based on driver type
+ * @param {string} driver - Driver type (filesystem, s3, multi)
+ * @param {Object} config - Driver configuration
+ * @returns {BaseBackupDriver} Driver instance
+ */
+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(', ')}`);
+  }
+  
+  return new DriverClass(config);
+}
+
+/**
+ * Validate backup driver configuration
+ * @param {string} driver - Driver type
+ * @param {Object} config - Driver configuration
+ * @throws {Error} If configuration is invalid
+ */
+export function validateBackupConfig(driver, config = {}) {
+  if (!driver || typeof driver !== 'string') {
+    throw new Error('Driver type must be a non-empty string');
+  }
+
+  if (!BACKUP_DRIVERS[driver]) {
+    throw new Error(`Unknown backup driver: ${driver}. Available drivers: ${Object.keys(BACKUP_DRIVERS).join(', ')}`);
+  }
+
+  // Driver-specific validation
+  switch (driver) {
+    case 'filesystem':
+      if (!config.path) {
+        throw new Error('FilesystemBackupDriver requires "path" configuration');
+      }
+      break;
+
+    case 's3':
+      // S3 driver can use database client/bucket, so no strict validation here
+      break;
+
+    case 'multi':
+      if (!Array.isArray(config.destinations) || config.destinations.length === 0) {
+        throw new Error('MultiBackupDriver requires non-empty "destinations" array');
+      }
+      
+      // Validate each destination
+      config.destinations.forEach((dest, index) => {
+        if (!dest.driver) {
+          throw new Error(`Destination ${index} must have a "driver" property`);
+        }
+        
+        // Recursive validation for nested drivers
+        if (dest.driver !== 'multi') { // Prevent infinite recursion
+          validateBackupConfig(dest.driver, dest.config || {});
+        }
+      });
+      break;
+  }
+
+  return true;
+}