s3db.js 12.4.0 → 13.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s3db.js",
-  "version": "12.4.0",
+  "version": "13.1.0",
   "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",
@@ -88,6 +88,7 @@
     "@google-cloud/bigquery": "^7.0.0",
     "@hono/node-server": "^1.0.0",
     "@hono/swagger-ui": "^0.5.0",
+    "@tensorflow/tfjs-node": "^4.0.0",
     "amqplib": "^0.10.8",
     "hono": "^4.0.0",
     "node-cron": "^4.0.0",
@@ -106,6 +107,9 @@
     "@hono/swagger-ui": {
       "optional": true
     },
+    "@tensorflow/tfjs-node": {
+      "optional": true
+    },
     "pg": {
       "optional": true
     },

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

@@ -640,41 +640,58 @@ export class MemoryClient extends EventEmitter {
     for (const [resourceName, keys] of resourceMap.entries()) {
       const records = [];
 
-      for (const key of keys) {
-        const obj = await this.getObject(key);
+      // Get resource from database if available (for proper field decoding)
+      const resource = database && database.resources && database.resources[resourceName];
 
+      for (const key of keys) {
         // Extract id from key (e.g., resource=products/id=pr1 -> pr1)
         const idMatch = key.match(/\/id=([^/]+)/);
         const recordId = idMatch ? idMatch[1] : null;
 
-        // Reconstruct record from metadata and body
-        const record = { ...obj.Metadata };
+        let record;
 
-        // Include id in record if extracted from key
-        if (recordId && !record.id) {
-          record.id = recordId;
+        // If resource is available, use its get() method for proper field name decoding
+        if (resource && recordId) {
+          try {
+            record = await resource.get(recordId);
+          } catch (err) {
+            // Fallback to manual reconstruction if get() fails
+            console.warn(`Failed to get record ${recordId} from resource ${resourceName}, using fallback`);
+            record = null;
+          }
         }
 
-        // If body exists, parse it
-        if (obj.Body) {
-          const chunks = [];
-          for await (const chunk of obj.Body) {
-            chunks.push(chunk);
+        // Fallback: manually reconstruct from metadata and body
+        if (!record) {
+          const obj = await this.getObject(key);
+          record = { ...obj.Metadata };
+
+          // Include id in record if extracted from key
+          if (recordId && !record.id) {
+            record.id = recordId;
           }
-          const bodyBuffer = Buffer.concat(chunks);
-
-          // Try to parse as JSON if it looks like JSON
-          const bodyStr = bodyBuffer.toString('utf-8');
-          if (bodyStr.startsWith('{') || bodyStr.startsWith('[')) {
-            try {
-              const bodyData = JSON.parse(bodyStr);
-              Object.assign(record, bodyData);
-            } catch {
-              // If not JSON, store as _body field
+
+          // If body exists, parse it
+          if (obj.Body) {
+            const chunks = [];
+            for await (const chunk of obj.Body) {
+              chunks.push(chunk);
+            }
+            const bodyBuffer = Buffer.concat(chunks);
+
+            // Try to parse as JSON if it looks like JSON
+            const bodyStr = bodyBuffer.toString('utf-8');
+            if (bodyStr.startsWith('{') || bodyStr.startsWith('[')) {
+              try {
+                const bodyData = JSON.parse(bodyStr);
+                Object.assign(record, bodyData);
+              } catch {
+                // If not JSON, store as _body field
+                record._body = bodyStr;
+              }
+            } else if (bodyStr) {
               record._body = bodyStr;
             }
-          } else if (bodyStr) {
-            record._body = bodyStr;
           }
         }
 

package/src/database.class.js

@@ -14,7 +14,12 @@ export class Database extends EventEmitter {
   constructor(options) {
     super();
 
-    this.id = idGenerator(7)
+    // Generate database ID with fallback for reliability
+    this.id = (() => {
+      const [ok, err, id] = tryFn(() => idGenerator(7));
+      return ok && id ? id : `db-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`;
+    })();
+
     this.version = "1";
     // Version is injected during build, fallback to "latest" for development
     this.s3dbVersion = (() => {
@@ -64,6 +69,7 @@ export class Database extends EventEmitter {
     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
+    this.strictHooks = options.strictHooks || false; // Throw on first hook error instead of continuing
 
     // Initialize hooks system
     this._initHooks();
@@ -110,21 +116,32 @@ export class Database extends EventEmitter {
     this.bucket = this.client.bucket;
     this.keyPrefix = this.client.keyPrefix;
 
-    // Add process exit listener for cleanup
-    if (!this._exitListenerRegistered) {
+    // Register exit listener for cleanup
+    this._registerExitListener();
+  }
+
+  /**
+   * Register process exit listener for automatic cleanup
+   * @private
+   */
+  _registerExitListener() {
+    if (!this._exitListenerRegistered && typeof process !== 'undefined') {
       this._exitListenerRegistered = true;
-      if (typeof process !== 'undefined') {
-        process.on('exit', async () => {
-          if (this.isConnected()) {
-            // Silently ignore errors on exit
-            await tryFn(() => this.disconnect());
-          }
-        });
-      }
+      // Store listener reference for cleanup
+      this._exitListener = async () => {
+        if (this.isConnected()) {
+          // Silently ignore errors on exit
+          await tryFn(() => this.disconnect());
+        }
+      };
+      process.on('exit', this._exitListener);
     }
   }
-  
+
   async connect() {
+    // Re-register exit listener if it was cleaned up
+    this._registerExitListener();
+
     await this.startPlugins();
 
     let metadata = null;
@@ -1271,15 +1288,24 @@ export class Database extends EventEmitter {
         this.client.removeAllListeners();
       }
 
-      // 4. Remove all listeners from the database itself
+      // 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());
+
+      // 5. Remove all listeners from the database itself
       this.removeAllListeners();
 
-      // 5. Clear saved metadata and plugin lists
+      // 6. Cleanup process exit listener (memory leak fix)
+      if (this._exitListener && typeof process !== 'undefined') {
+        process.off('exit', this._exitListener);
+        this._exitListener = null;
+        this._exitListenerRegistered = false;
+      }
+
+      // 7. Clear saved metadata and plugin lists
       this.savedMetadata = null;
       this.plugins = {};
       this.pluginList = [];
-
-      this.emit('disconnected', new Date());
     });
   }
 
@@ -1400,8 +1426,17 @@ export class Database extends EventEmitter {
     for (const hook of hooks) {
       const [ok, error] = await tryFn(() => hook({ database: this, ...context }));
       if (!ok) {
-        // Emit error but don't stop hook execution
+        // Emit error event
         this.emit('hookError', { event, error, context });
+
+        // In strict mode, throw on first error instead of continuing
+        if (this.strictHooks) {
+          throw new DatabaseError(`Hook execution failed for event '${event}': ${error.message}`, {
+            event,
+            originalError: error,
+            context
+          });
+        }
       }
     }
   }

package/src/plugins/api/index.js

@@ -35,6 +35,7 @@
 import { Plugin } from '../plugin.class.js';
 import { requirePluginDependency } from '../concerns/plugin-dependencies.js';
 import tryFn from '../../concerns/try-fn.js';
+import { ApiServer } from './server.js';
 
 /**
  * API Plugin class
@@ -437,15 +438,18 @@ export class ApiPlugin extends Plugin {
     return async (c, next) => {
       await next();
 
-      // Note: Actual compression would require proper streaming support
-      // For now, this is a placeholder
-      const acceptEncoding = c.req.header('accept-encoding') || '';
-
-      if (acceptEncoding.includes('gzip')) {
-        c.header('Content-Encoding', 'gzip');
-      } else if (acceptEncoding.includes('deflate')) {
-        c.header('Content-Encoding', 'deflate');
-      }
+      // TODO: Implement actual compression using zlib
+      // For now, this is a no-op placeholder to avoid ERR_CONTENT_DECODING_FAILED errors
+      //
+      // WARNING: Do NOT set Content-Encoding headers without actually compressing!
+      // Setting these headers without compression causes browsers to fail with:
+      // net::ERR_CONTENT_DECODING_FAILED 200 (OK)
+      //
+      // Real implementation would require:
+      // 1. Check Accept-Encoding header
+      // 2. Compress response body with zlib.gzip() or zlib.deflate()
+      // 3. Set Content-Encoding header
+      // 4. Update Content-Length header
     };
   }
 
@@ -457,11 +461,6 @@ export class ApiPlugin extends Plugin {
       console.log('[API Plugin] Starting server...');
     }
 
-    // Dynamic import with path manipulation to prevent Rollup from inlining
-    // This ensures hono is only loaded when ApiPlugin is actually used
-    const serverPath = './server' + '.js';
-    const { ApiServer } = await import(/* @vite-ignore */ serverPath);
-
     // Create server instance
     this.server = new ApiServer({
       port: this.config.port,
@@ -543,5 +542,3 @@ export class ApiPlugin extends Plugin {
     return this.server ? this.server.getApp() : null;
   }
 }
-
-export default ApiPlugin;

package/src/plugins/api/routes/resource-routes.js

@@ -4,18 +4,56 @@
  * Automatically generates REST endpoints for each resource
  */
 
-import { Hono } from 'hono';
 import { asyncHandler } from '../utils/error-handler.js';
 import * as formatter from '../utils/response-formatter.js';
 
+/**
+ * Parse custom route definition (e.g., "GET /healthcheck" or "async POST /custom")
+ * @param {string} routeDef - Route definition string
+ * @returns {Object} Parsed route { method, path, isAsync }
+ */
+function parseCustomRoute(routeDef) {
+  // Remove "async" prefix if present
+  let def = routeDef.trim();
+  const isAsync = def.startsWith('async ');
+
+  if (isAsync) {
+    def = def.substring(6).trim(); // Remove "async "
+  }
+
+  // Split by space (e.g., "GET /path" -> ["GET", "/path"])
+  const parts = def.split(/\s+/);
+
+  if (parts.length < 2) {
+    throw new Error(`Invalid route definition: "${routeDef}". Expected format: "METHOD /path" or "async METHOD /path"`);
+  }
+
+  const method = parts[0].toUpperCase();
+  const path = parts.slice(1).join(' ').trim(); // Join remaining parts in case path has spaces (unlikely but possible)
+
+  // Validate HTTP method
+  const validMethods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+  if (!validMethods.includes(method)) {
+    throw new Error(`Invalid HTTP method: "${method}". Must be one of: ${validMethods.join(', ')}`);
+  }
+
+  // Validate path starts with /
+  if (!path.startsWith('/')) {
+    throw new Error(`Invalid route path: "${path}". Path must start with "/"`);
+  }
+
+  return { method, path, isAsync };
+}
+
 /**
  * Create routes for a resource
  * @param {Object} resource - s3db.js Resource instance
  * @param {string} version - Resource version (e.g., 'v1', 'v1')
  * @param {Object} config - Route configuration
+ * @param {Function} Hono - Hono constructor (passed from server.js)
  * @returns {Hono} Hono app with resource routes
  */
-export function createResourceRoutes(resource, version, config = {}) {
+export function createResourceRoutes(resource, version, config = {}, Hono) {
   const app = new Hono();
   const {
     methods = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'],
@@ -31,6 +69,46 @@ export function createResourceRoutes(resource, version, config = {}) {
     app.use('*', middleware);
   });
 
+  // Register custom routes from resource.config.api (if defined)
+  if (resource.config?.api && typeof resource.config.api === 'object') {
+    for (const [routeDef, handler] of Object.entries(resource.config.api)) {
+      try {
+        const { method, path } = parseCustomRoute(routeDef);
+
+        if (typeof handler !== 'function') {
+          throw new Error(`Handler for route "${routeDef}" must be a function`);
+        }
+
+        // Register the custom route
+        // The handler receives the full Hono context
+        app.on(method, path, asyncHandler(async (c) => {
+          // Call user's handler with Hono context
+          const result = await handler(c, { resource, database: resource.database });
+
+          // If handler already returned a response, use it
+          if (result && result.constructor && result.constructor.name === 'Response') {
+            return result;
+          }
+
+          // If handler returned data, wrap in success formatter
+          if (result !== undefined && result !== null) {
+            return c.json(formatter.success(result));
+          }
+
+          // If no return value, return 204 No Content
+          return c.json(formatter.noContent(), 204);
+        }));
+
+        if (config.verbose || resource.database?.verbose) {
+          console.log(`[API Plugin] Registered custom route for ${resourceName}: ${method} ${path}`);
+        }
+      } catch (error) {
+        console.error(`[API Plugin] Error registering custom route "${routeDef}" for ${resourceName}:`, error.message);
+        throw error;
+      }
+    }
+  }
+
   // LIST - GET /{version}/{resource}
   if (methods.includes('GET')) {
     app.get('/', asyncHandler(async (c) => {
@@ -307,7 +385,7 @@ export function createResourceRoutes(resource, version, config = {}) {
  * @param {string} version - Resource version (e.g., 'v1')
  * @returns {Hono} Hono app with relational routes
  */
-export function createRelationalRoutes(sourceResource, relationName, relationConfig, version) {
+export function createRelationalRoutes(sourceResource, relationName, relationConfig, version, Hono) {
   const app = new Hono();
   const resourceName = sourceResource.name;
   const relatedResourceName = relationConfig.resource;

package/src/plugins/api/server.js

@@ -4,9 +4,6 @@
  * Manages HTTP server lifecycle and routing
  */
 
-import { Hono } from 'hono';
-import { serve } from '@hono/node-server';
-import { swaggerUI } from '@hono/swagger-ui';
 import { createResourceRoutes, createRelationalRoutes } from './routes/resource-routes.js';
 import { errorHandler } from './utils/error-handler.js';
 import * as formatter from './utils/response-formatter.js';
@@ -46,17 +43,18 @@ export class ApiServer {
       }
     };
 
-    this.app = new Hono();
+    this.app = null; // Will be initialized in start() with dynamic import
     this.server = null;
     this.isRunning = false;
     this.openAPISpec = null;
+    this.initialized = false;
 
     // Detect if RelationPlugin is installed
     this.relationsPlugin = this.options.database?.plugins?.relation ||
                           this.options.database?.plugins?.RelationPlugin ||
                           null;
 
-    this._setupRoutes();
+    // Routes will be setup in start() after dynamic import
   }
 
   /**
@@ -170,7 +168,7 @@ export class ApiServer {
 
       // API Documentation UI endpoint
       if (this.options.docsUI === 'swagger') {
-        this.app.get('/docs', swaggerUI({
+        this.app.get('/docs', this.swaggerUI({
           url: '/openapi.json'
         }));
       } else {
@@ -254,7 +252,7 @@ export class ApiServer {
         methods: config.methods,
         customMiddleware: config.customMiddleware || [],
         enableValidation: config.validation !== false
-      });
+      }, this.Hono);
 
       // Mount resource routes
       this.app.route(`/${version}/${name}`, resourceApp);
@@ -317,7 +315,8 @@ export class ApiServer {
           resource,
           relationName,
           relationConfig,
-          version
+          version,
+          this.Hono
         );
 
         // Mount relational routes at /{version}/{resource}/:id/{relation}
@@ -343,11 +342,32 @@ export class ApiServer {
       return;
     }
 
+    // Dynamic import of Hono dependencies (peer dependencies)
+    // This ensures hono is only loaded when server actually starts
+    if (!this.initialized) {
+      const { Hono } = await import('hono');
+      const { serve } = await import('@hono/node-server');
+      const { swaggerUI } = await import('@hono/swagger-ui');
+
+      // Store for use in _setupRoutes
+      this.Hono = Hono;
+      this.serve = serve;
+      this.swaggerUI = swaggerUI;
+
+      // Initialize app
+      this.app = new Hono();
+
+      // Setup all routes
+      this._setupRoutes();
+
+      this.initialized = true;
+    }
+
     const { port, host } = this.options;
 
     return new Promise((resolve, reject) => {
       try {
-        this.server = serve({
+        this.server = this.serve({
           fetch: this.app.fetch,
           port,
           hostname: host

package/src/plugins/audit.plugin.js

@@ -1,4 +1,4 @@
-import Plugin from "./plugin.class.js";
+import { Plugin } from "./plugin.class.js";
 import tryFn from "../concerns/try-fn.js";
 
 export class AuditPlugin extends Plugin {
@@ -420,6 +420,4 @@ export class AuditPlugin extends Plugin {
 
     return deletedCount;
   }
-}
-
-export default AuditPlugin; 
+} 

package/src/plugins/backup.plugin.js

@@ -1,4 +1,4 @@
-import Plugin from "./plugin.class.js";
+import { Plugin } from "./plugin.class.js";
 import tryFn from "../concerns/try-fn.js";
 import { createBackupDriver, validateBackupConfig } from "./backup/index.js";
 import { StreamingExporter } from "./backup/streaming-exporter.js";
@@ -982,6 +982,4 @@ export class BackupPlugin extends Plugin {
       await this.driver.cleanup();
     }
   }
-}
-
-export default BackupPlugin;
+}

package/src/plugins/cache.plugin.js

@@ -2,7 +2,7 @@ import { join } from "path";
 import jsonStableStringify from "json-stable-stringify";
 import crypto from 'crypto';
 
-import Plugin from "./plugin.class.js";
+import { Plugin } from "./plugin.class.js";
 import S3Cache from "./cache/s3-cache.class.js";
 import MemoryCache from "./cache/memory-cache.class.js";
 import { FilesystemCache } from "./cache/filesystem-cache.class.js";
@@ -781,5 +781,3 @@ export class CachePlugin extends Plugin {
     return parts.join(' ');
   }
 }
-
-export default CachePlugin;

package/src/plugins/costs.plugin.js

@@ -299,5 +299,3 @@ export class CostsPlugin extends Plugin {
     }
   }
 }
-
-export default CostsPlugin;

package/src/plugins/eventual-consistency/index.js

@@ -4,7 +4,7 @@
  * @module eventual-consistency
  */
 
-import Plugin from "../plugin.class.js";
+import { Plugin } from "../plugin.class.js";
 import { createConfig, validateResourcesConfig, logConfigWarnings, logInitialization } from "./config.js";
 import { detectTimezone, getCohortInfo, createFieldHandler } from "./utils.js";
 import { createPartitionConfig } from "./partitions.js";
@@ -733,5 +733,3 @@ export class EventualConsistencyPlugin extends Plugin {
     return diagnostics;
   }
 }
-
-export default EventualConsistencyPlugin;

package/src/plugins/fulltext.plugin.js

@@ -1,4 +1,4 @@
-import Plugin from "./plugin.class.js";
+import { Plugin } from "./plugin.class.js";
 import tryFn from "../concerns/try-fn.js";
 import { FulltextError } from "./fulltext.errors.js";
 
@@ -554,6 +554,4 @@ export class FullTextPlugin extends Plugin {
     // Save changes
     await this.saveIndexes();
   }
-}
-
-export default FullTextPlugin; 
+} 

package/src/plugins/geo.plugin.js

@@ -1,4 +1,4 @@
-import Plugin from "./plugin.class.js";
+import { Plugin } from "./plugin.class.js";
 import tryFn from "../concerns/try-fn.js";
 
 /**
@@ -868,5 +868,3 @@ export class GeoPlugin extends Plugin {
     await super.uninstall();
   }
 }
-
-export default GeoPlugin;

package/src/plugins/importer/index.js

@@ -1016,5 +1016,3 @@ export const Transformers = {
     return String(value).trim();
   }
 };
-
-export default ImporterPlugin;

package/src/plugins/index.js

@@ -1,6 +1,5 @@
 export * from './plugin.class.js'
 export * from './plugin.obj.js'
-export { default as Plugin } from './plugin.class.js'
 
 // plugins:
 // ApiPlugin is exported separately to avoid bundling hono dependencies
@@ -13,6 +12,7 @@ export * from './eventual-consistency/index.js'
 export * from './fulltext.plugin.js'
 export * from './geo.plugin.js'
 export * from './metrics.plugin.js'
+export * from './ml.plugin.js'
 export * from './queue-consumer.plugin.js'
 export * from './relation.plugin.js'
 export * from './replicator.plugin.js'

package/src/plugins/metrics.plugin.js

@@ -1,4 +1,4 @@
-import Plugin from "./plugin.class.js";
+import { Plugin } from "./plugin.class.js";
 import tryFn from "../concerns/try-fn.js";
 
 export class MetricsPlugin extends Plugin {
@@ -831,6 +831,4 @@ export class MetricsPlugin extends Plugin {
       console.error('[Metrics Plugin] Standalone metrics server error:', err);
     });
   }
-}
-
-export default MetricsPlugin; 
+}