s3db.js 8.0.1 → 8.0.3

package/PLUGINS.md

@@ -81,41 +81,83 @@ await users.list();  // Cached result
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `driver` | string | `'s3'` | Cache driver: `'memory'` or `'s3'` |
-| `ttl` | number | `300000` | Time-to-live in milliseconds (5 minutes) |
-| `maxSize` | number | `1000` | Maximum number of items in cache (memory driver) |
+| `driver` | string | `'s3'` | Cache driver: `'memory'`, `'s3'`, or `'filesystem'` |
+| `ttl` | number | `300000` | Time-to-live in milliseconds (5 minutes) - global setting |
+| `maxSize` | number | `1000` | Maximum number of items in cache - global setting |
+| `config` | object | `{}` | Driver-specific configuration options (can override global settings) |
 | `includePartitions` | boolean | `true` | Include partition values in cache keys |
 | `driver` | object | `null` | Custom cache driver instance |
-| `memoryOptions` | object | `{}` | Options for memory cache driver |
-| `s3Options` | object | `{}` | Options for S3 cache driver |
 
-### Memory Driver Options (`memoryOptions`)
+**Configuration Priority:** Driver-specific `config` options override global plugin settings. For example, if you set `ttl: 600000` at the plugin level and `ttl: 1800000` in the driver config, the driver will use 1800000 (30 minutes) while the global setting serves as the default for any drivers that don't specify their own TTL.
+
+### Driver Configuration Options
+
+The `config` object contains driver-specific options. Note that `ttl` and `maxSize` can be configured at the plugin level (applies to all operations) or in the driver config (driver-specific override).
+
+#### Memory Driver (`driver: 'memory'`)
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `maxSize` | number | `1000` | Maximum items in memory |
-| `ttl` | number | `300000` | Default TTL in milliseconds |
-| `checkPeriod` | number | `600000` | Cleanup interval in milliseconds |
+| `ttl` | number | inherited | TTL override for memory cache (inherits from plugin level) |
+| `maxSize` | number | inherited | Max items override for memory cache (inherits from plugin level) |
 
-### S3 Driver Options (`s3Options`)
+#### S3 Driver (`driver: 's3'`)
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
-| `bucket` | string | Same as database | S3 bucket for cache storage |
-| `prefix` | string | `'cache/'` | S3 key prefix for cache objects |
+| `ttl` | number | inherited | TTL override for S3 cache (inherits from plugin level) |
+| `keyPrefix` | string | `'cache'` | S3 key prefix for cache objects |
 | `client` | object | Database client | Custom S3 client instance |
 
+**Note:** S3 cache automatically uses gzip compression for all cached values.
+
+#### Filesystem Driver (`driver: 'filesystem'`)
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `directory` | string | required | Directory path to store cache files |
+| `ttl` | number | inherited | TTL override for filesystem cache (inherits from plugin level) |
+| `prefix` | string | `'cache'` | Prefix for cache filenames |
+| `enableCompression` | boolean | `true` | Whether to compress cache values using gzip |
+| `compressionThreshold` | number | `1024` | Minimum size in bytes to trigger compression |
+| `createDirectory` | boolean | `true` | Whether to create the directory if it doesn't exist |
+| `fileExtension` | string | `'.cache'` | File extension for cache files |
+| `enableMetadata` | boolean | `true` | Whether to store metadata alongside cache data |
+| `maxFileSize` | number | `10485760` | Maximum file size in bytes (10MB) |
+| `enableStats` | boolean | `false` | Whether to track cache statistics |
+| `enableCleanup` | boolean | `true` | Whether to automatically clean up expired files |
+| `cleanupInterval` | number | `300000` | Interval in milliseconds to run cleanup (5 minutes) |
+| `encoding` | string | `'utf8'` | File encoding to use |
+| `fileMode` | number | `0o644` | File permissions in octal notation |
+
 ### 🔧 Easy Example
 
 ```javascript
 import { S3db, CachePlugin } from 's3db.js';
 
+// Memory cache example with global settings
 const s3db = new S3db({
   connectionString: "s3://ACCESS_KEY:SECRET_KEY@BUCKET_NAME/databases/myapp",
   plugins: [new CachePlugin({
     driver: 'memory',
-    ttl: 600000, // 10 minutes
-    maxSize: 500
+    ttl: 600000, // 10 minutes - applies to all cache operations
+    maxSize: 500 // 500 items max - applies to all cache operations
+  })]
+});
+
+// Filesystem cache example with driver-specific override
+const s3dbWithFileCache = new S3db({
+  connectionString: "s3://ACCESS_KEY:SECRET_KEY@BUCKET_NAME/databases/myapp",
+  plugins: [new CachePlugin({
+    driver: 'filesystem',
+    ttl: 900000, // 15 minutes - global default
+    maxSize: 2000, // 2000 items max - global default
+    config: {
+      directory: './cache',
+      ttl: 1800000, // 30 minutes - overrides global for filesystem only
+      enableCompression: true,
+      enableCleanup: true
+    }
   })]
 });
 
@@ -143,46 +185,78 @@ const result3 = await products.count(); // Fresh data
 ### 🚀 Advanced Configuration Example
 
 ```javascript
-import { S3db, CachePlugin, MemoryCache, S3Cache } from 's3db.js';
+import { S3db, CachePlugin, MemoryCache, S3Cache, FilesystemCache } from 's3db.js';
 
 // Custom cache driver with advanced configuration
 const customCache = new MemoryCache({
   maxSize: 2000,
-  ttl: 900000, // 15 minutes
-  checkPeriod: 300000, // 5 minutes cleanup
-  algorithm: 'lru' // Least Recently Used
+  ttl: 900000 // 15 minutes
 });
 
-const s3db = new S3db({
+// Advanced cache configuration with global settings
+const s3dbWithAdvancedCache = new S3db({
   connectionString: "s3://ACCESS_KEY:SECRET_KEY@BUCKET_NAME/databases/myapp",
   plugins: [new CachePlugin({
-    driver: customCache,
-    includePartitions: true,
+    driver: 'filesystem',
     
-    // S3 cache fallback for persistence
-    s3Options: {
-      bucket: 'my-cache-bucket',
-      prefix: 'app-cache/',
-      ttl: 3600000, // 1 hour S3 cache
-      compression: true,
-      encryption: true
-    },
+    // Global cache settings (apply to all operations)
+    ttl: 3600000, // 1 hour default
+    maxSize: 5000, // 5000 items max
+    includePartitions: true,
     
-    // Memory cache for speed
-    memoryOptions: {
-      maxSize: 5000,
-      ttl: 600000, // 10 minutes memory cache
-      checkPeriod: 120000, // 2 minutes cleanup
-      evictionPolicy: 'lru',
-      stats: true // Enable cache statistics
+    // Driver-specific configuration
+    config: {
+      directory: './data/cache',
+      prefix: 'app-cache',
+      ttl: 7200000, // 2 hours - overrides global TTL for filesystem
+      enableCompression: true,
+      compressionThreshold: 512, // Compress files > 512 bytes
+      enableCleanup: true,
+      cleanupInterval: 600000, // 10 minutes
+      enableMetadata: true,
+      maxFileSize: 5242880, // 5MB per file
+      enableStats: true,
+      fileMode: 0o644,
+      encoding: 'utf8'
     }
   })]
 });
 
-await s3db.connect();
+// Multiple cache configuration examples
+const s3dbWithS3Cache = new S3db({
+  connectionString: "s3://ACCESS_KEY:SECRET_KEY@BUCKET_NAME/databases/myapp",
+  plugins: [new CachePlugin({
+    driver: 's3',
+    ttl: 3600000, // 1 hour - global TTL
+    includePartitions: true,
+    config: {
+      keyPrefix: 'app-cache'
+    }
+  })]
+});
+
+const s3dbWithMemoryCache = new S3db({
+  connectionString: "s3://ACCESS_KEY:SECRET_KEY@BUCKET_NAME/databases/myapp",
+  plugins: [new CachePlugin({
+    driver: 'memory',
+    ttl: 600000, // 10 minutes - global TTL
+    maxSize: 5000, // 5000 items max - global limit
+    includePartitions: true
+  })]
+});
+
+const s3dbWithCustomCache = new S3db({
+  connectionString: "s3://ACCESS_KEY:SECRET_KEY@BUCKET_NAME/databases/myapp",
+  plugins: [new CachePlugin({
+    driver: customCache, // Custom driver instance
+    includePartitions: true
+  })]
+});
+
+await s3dbWithAdvancedCache.connect();
 
 // Access cache methods on resources
-const users = s3db.resource('users');
+const users = s3dbWithAdvancedCache.resource('users');
 
 // Generate custom cache keys
 const cacheKey = await users.cacheKeyFor({
@@ -3888,7 +3962,8 @@ const s3db = new S3db({
     // Performance optimization
     new CachePlugin({ 
       driver: 'memory',
-      ttl: 600000 
+      ttl: 600000, // 10 minutes
+      maxSize: 1000
     }),
     
     // Cost tracking

package/README.md

@@ -357,13 +357,7 @@ A logical container for your resources, stored in a specific S3 prefix.
 
 ```javascript
 const s3db = new S3db({
-  connectionString: "s3://ACCESS_KEY:SECRET_KEY@BUCKET_NAME/databases/myapp",
-  // Optional: Customize HTTP client for performance
-  httpClientOptions: {
-    keepAlive: true,
-    maxSockets: 50,
-    timeout: 60000
-  }
+  connectionString: "s3://ACCESS_KEY:SECRET_KEY@BUCKET_NAME/databases/myapp"
 });
 ```
 
@@ -404,24 +398,6 @@ Built-in validation using [@icebob/fastest-validator](https://github.com/icebob/
 
 s3db.js is designed for high performance with optimized defaults and configurable settings:
 
-#### HTTP Client Optimization
-
-The default HTTP client configuration is optimized for most applications:
-
-```javascript
-// Default optimized settings
-const s3db = new S3db({
-  connectionString: "s3://ACCESS_KEY:SECRET_KEY@BUCKET_NAME/databases/myapp",
-  httpClientOptions: {
-    keepAlive: true,         // Connection reuse for better performance
-    keepAliveMsecs: 1000,    // 1 second keep-alive duration
-    maxSockets: 50,          // Balanced concurrency
-    maxFreeSockets: 10,      // Good connection pool utilization
-    timeout: 60000           // 60 second timeout
-  }
-});
-```
-
 #### Bulk Operations Performance
 
 Use bulk operations for better performance with large datasets:

package/dist/s3db.cjs.js

@@ -6627,8 +6627,8 @@ class MemoryCache extends Cache {
     super(config);
     this.cache = {};
     this.meta = {};
-    this.maxSize = config.maxSize || 0;
-    this.ttl = config.ttl || 0;
+    this.maxSize = config.maxSize !== void 0 ? config.maxSize : 1e3;
+    this.ttl = config.ttl !== void 0 ? config.ttl : 3e5;
   }
   async _set(key, data) {
     if (this.maxSize > 0 && Object.keys(this.cache).length >= this.maxSize) {
@@ -7486,37 +7486,81 @@ class PartitionAwareFilesystemCache extends FilesystemCache {
 class CachePlugin extends plugin_class_default {
   constructor(options = {}) {
     super(options);
-    this.driver = options.driver;
-    this.config = {
-      includePartitions: options.includePartitions !== false,
-      partitionStrategy: options.partitionStrategy || "hierarchical",
-      partitionAware: options.partitionAware !== false,
-      trackUsage: options.trackUsage !== false,
-      preloadRelated: options.preloadRelated !== false,
-      ...options
+    this.driverName = options.driver || "s3";
+    this.ttl = options.ttl;
+    this.maxSize = options.maxSize;
+    this.config = options.config || {};
+    this.includePartitions = options.includePartitions !== false;
+    this.partitionStrategy = options.partitionStrategy || "hierarchical";
+    this.partitionAware = options.partitionAware !== false;
+    this.trackUsage = options.trackUsage !== false;
+    this.preloadRelated = options.preloadRelated !== false;
+    this.legacyConfig = {
+      memoryOptions: options.memoryOptions,
+      filesystemOptions: options.filesystemOptions,
+      s3Options: options.s3Options,
+      driver: options.driver
     };
   }
   async setup(database) {
     await super.setup(database);
   }
   async onSetup() {
-    if (this.config.driver && typeof this.config.driver === "object") {
-      this.driver = this.config.driver;
-    } else if (this.config.driver === "memory") {
-      this.driver = new memory_cache_class_default(this.config.memoryOptions || {});
-    } else if (this.config.driver === "filesystem") {
-      if (this.config.partitionAware) {
+    if (this.driverName && typeof this.driverName === "object") {
+      this.driver = this.driverName;
+    } else if (this.driverName === "memory") {
+      const driverConfig = {
+        ...this.legacyConfig.memoryOptions,
+        // Legacy support (lowest priority)
+        ...this.config
+        // New config format (medium priority)
+      };
+      if (this.ttl !== void 0) {
+        driverConfig.ttl = this.ttl;
+      }
+      if (this.maxSize !== void 0) {
+        driverConfig.maxSize = this.maxSize;
+      }
+      this.driver = new memory_cache_class_default(driverConfig);
+    } else if (this.driverName === "filesystem") {
+      const driverConfig = {
+        ...this.legacyConfig.filesystemOptions,
+        // Legacy support (lowest priority)
+        ...this.config
+        // New config format (medium priority)
+      };
+      if (this.ttl !== void 0) {
+        driverConfig.ttl = this.ttl;
+      }
+      if (this.maxSize !== void 0) {
+        driverConfig.maxSize = this.maxSize;
+      }
+      if (this.partitionAware) {
         this.driver = new PartitionAwareFilesystemCache({
-          partitionStrategy: this.config.partitionStrategy,
-          trackUsage: this.config.trackUsage,
-          preloadRelated: this.config.preloadRelated,
-          ...this.config.filesystemOptions
+          partitionStrategy: this.partitionStrategy,
+          trackUsage: this.trackUsage,
+          preloadRelated: this.preloadRelated,
+          ...driverConfig
         });
       } else {
-        this.driver = new FilesystemCache(this.config.filesystemOptions || {});
+        this.driver = new FilesystemCache(driverConfig);
       }
     } else {
-      this.driver = new s3_cache_class_default({ client: this.database.client, ...this.config.s3Options || {} });
+      const driverConfig = {
+        client: this.database.client,
+        // Required for S3Cache
+        ...this.legacyConfig.s3Options,
+        // Legacy support (lowest priority)
+        ...this.config
+        // New config format (medium priority)
+      };
+      if (this.ttl !== void 0) {
+        driverConfig.ttl = this.ttl;
+      }
+      if (this.maxSize !== void 0) {
+        driverConfig.maxSize = this.maxSize;
+      }
+      this.driver = new s3_cache_class_default(driverConfig);
     }
     this.installDatabaseHooks();
     this.installResourceHooks();
@@ -9621,7 +9665,7 @@ class Client extends EventEmitter {
   }) {
     super();
     this.verbose = verbose;
-    this.id = id ?? idGenerator();
+    this.id = id ?? idGenerator(77);
     this.parallelism = parallelism;
     this.config = new ConnectionString(connectionString);
     this.httpClientOptions = {
@@ -11208,10 +11252,18 @@ class Resource extends EventEmitter {
    */
   constructor(config = {}) {
     super();
-    this._instanceId = Math.random().toString(36).slice(2, 8);
+    this._instanceId = idGenerator(7);
     const validation = validateResourceConfig(config);
     if (!validation.isValid) {
-      throw new ResourceError(`Invalid Resource ${config.name} configuration`, { resourceName: config.name, validation: validation.errors, operation: "constructor", suggestion: "Check resource config and attributes." });
+      const errorDetails = validation.errors.map((err) => `  \u2022 ${err}`).join("\n");
+      throw new ResourceError(
+        `Invalid Resource ${config.name || "[unnamed]"} configuration:
+${errorDetails}`,
+        {
+          resourceName: config.name,
+          validation: validation.errors
+        }
+      );
     }
     const {
       name,
@@ -13382,9 +13434,10 @@ var resource_class_default = Resource;
 class Database extends EventEmitter {
   constructor(options) {
     super();
+    this.id = idGenerator(7);
     this.version = "1";
     this.s3dbVersion = (() => {
-      const [ok, err, version] = try_fn_default(() => true ? "8.0.0" : "latest");
+      const [ok, err, version] = try_fn_default(() => true ? "8.0.2" : "latest");
       return ok ? version : "latest";
     })();
     this.resources = {};