s3db.js 13.4.0 → 13.5.1

package/src/plugins/api/server.js

@@ -5,9 +5,13 @@
  */
 
 import { createResourceRoutes, createRelationalRoutes } from './routes/resource-routes.js';
+import { createAuthRoutes } from './routes/auth-routes.js';
+import { mountCustomRoutes } from './utils/custom-routes.js';
 import { errorHandler } from './utils/error-handler.js';
 import * as formatter from './utils/response-formatter.js';
 import { generateOpenAPISpec } from './utils/openapi-generator.js';
+import { jwtAuth } from './auth/jwt-auth.js';
+import { basicAuth } from './auth/basic-auth.js';
 
 /**
  * API Server class
@@ -29,6 +33,7 @@ export class ApiServer {
       host: options.host || '0.0.0.0',
       database: options.database,
       resources: options.resources || {},
+      routes: options.routes || {}, // Plugin-level custom routes
       middlewares: options.middlewares || [],
       verbose: options.verbose || false,
       auth: options.auth || {},
@@ -36,6 +41,7 @@ export class ApiServer {
       docsUI: options.docsUI || 'redoc', // 'swagger' or 'redoc'
       maxBodySize: options.maxBodySize || 10 * 1024 * 1024, // 10MB default
       rootHandler: options.rootHandler, // Custom handler for root path, if not provided redirects to /docs
+      versionPrefix: options.versionPrefix, // Global version prefix config
       apiInfo: {
         title: options.apiTitle || 's3db.js API',
         version: options.apiVersion || '1.0.0',
@@ -198,11 +204,19 @@ export class ApiServer {
     // Setup resource routes
     this._setupResourceRoutes();
 
+    // Setup authentication routes if driver is configured
+    if (this.options.auth.driver) {
+      this._setupAuthRoutes();
+    }
+
     // Setup relational routes if RelationPlugin is active
     if (this.relationsPlugin) {
       this._setupRelationalRoutes();
     }
 
+    // Setup plugin-level custom routes
+    this._setupPluginRoutes();
+
     // Global error handler
     this.app.onError((err, c) => {
       return errorHandler(err, c);
@@ -247,22 +261,154 @@ export class ApiServer {
       // Determine version
       const version = resource.config?.currentVersion || resource.version || 'v1';
 
+      // Determine version prefix (resource-level overrides global)
+      // Priority: resource.versionPrefix > global versionPrefix > false (default - no prefix)
+      let versionPrefixConfig = config.versionPrefix !== undefined
+        ? config.versionPrefix
+        : this.options.versionPrefix !== undefined
+          ? this.options.versionPrefix
+          : false;
+
+      // Calculate the actual prefix to use
+      let prefix = '';
+      if (versionPrefixConfig === true) {
+        // true: use resource version
+        prefix = version;
+      } else if (versionPrefixConfig === false) {
+        // false: no prefix
+        prefix = '';
+      } else if (typeof versionPrefixConfig === 'string') {
+        // string: custom prefix
+        prefix = versionPrefixConfig;
+      }
+
+      // Prepare custom middleware
+      const middlewares = [...(config.customMiddleware || [])];
+
+      // Add authentication middleware if required
+      if (config.auth && this.options.auth.driver) {
+        const authMiddleware = this._createAuthMiddleware();
+        if (authMiddleware) {
+          middlewares.unshift(authMiddleware); // Add at beginning
+        }
+      }
+
       // Create resource routes
       const resourceApp = createResourceRoutes(resource, version, {
         methods: config.methods,
-        customMiddleware: config.customMiddleware || [],
-        enableValidation: config.validation !== false
+        customMiddleware: middlewares,
+        enableValidation: config.validation !== false,
+        versionPrefix: prefix
       }, this.Hono);
 
-      // Mount resource routes
-      this.app.route(`/${version}/${name}`, resourceApp);
+      // Mount resource routes (with or without prefix)
+      const mountPath = prefix ? `/${prefix}/${name}` : `/${name}`;
+      this.app.route(mountPath, resourceApp);
 
       if (this.options.verbose) {
-        console.log(`[API Plugin] Mounted routes for resource '${name}' at /${version}/${name}`);
+        console.log(`[API Plugin] Mounted routes for resource '${name}' at ${mountPath}`);
       }
+
+      // Mount custom routes for this resource (if defined)
+      if (config.routes) {
+        const routeContext = {
+          resource,
+          database,
+          resourceName: name,
+          version
+        };
+
+        // Mount on the resourceApp (nested under resource path)
+        mountCustomRoutes(resourceApp, config.routes, routeContext, this.options.verbose);
+      }
+    }
+  }
+
+  /**
+   * Setup authentication routes (when auth driver is configured)
+   * @private
+   */
+  _setupAuthRoutes() {
+    const { database, auth } = this.options;
+    const { driver, resource: resourceName, usernameField, passwordField, config } = auth;
+
+    // Get auth resource from database
+    const authResource = database.resources[resourceName];
+    if (!authResource) {
+      console.error(`[API Plugin] Auth resource '${resourceName}' not found. Skipping auth routes.`);
+      return;
+    }
+
+    // Prepare auth config for routes
+    const authConfig = {
+      driver,
+      usernameField,
+      passwordField,
+      jwtSecret: config.jwtSecret || config.secret,
+      jwtExpiresIn: config.jwtExpiresIn || config.expiresIn || '7d',
+      passphrase: config.passphrase || 'secret',
+      allowRegistration: config.allowRegistration !== false
+    };
+
+    // Create auth routes
+    const authApp = createAuthRoutes(authResource, authConfig);
+
+    // Mount auth routes at /auth
+    this.app.route('/auth', authApp);
+
+    if (this.options.verbose) {
+      console.log(`[API Plugin] Mounted auth routes (driver: ${driver}) at /auth`);
     }
   }
 
+  /**
+   * Create authentication middleware based on driver
+   * @private
+   * @returns {Function|null} Auth middleware function
+   */
+  _createAuthMiddleware() {
+    const { database, auth } = this.options;
+    const { driver, resource: resourceName, usernameField, passwordField, config } = auth;
+
+    if (!driver) {
+      return null;
+    }
+
+    const authResource = database.resources[resourceName];
+    if (!authResource) {
+      console.error(`[API Plugin] Auth resource '${resourceName}' not found for middleware`);
+      return null;
+    }
+
+    if (driver === 'jwt') {
+      const jwtSecret = config.jwtSecret || config.secret;
+      if (!jwtSecret) {
+        console.error('[API Plugin] JWT driver requires jwtSecret in config');
+        return null;
+      }
+
+      return jwtAuth({
+        secret: jwtSecret,
+        authResource,
+        usernameField,
+        passwordField
+      });
+    }
+
+    if (driver === 'basic') {
+      return basicAuth({
+        realm: config.realm || 'API Access',
+        authResource,
+        usernameField,
+        passwordField,
+        passphrase: config.passphrase || 'secret'
+      });
+    }
+
+    console.error(`[API Plugin] Unknown auth driver: ${driver}`);
+    return null;
+  }
+
   /**
    * Setup relational routes (when RelationPlugin is active)
    * @private
@@ -332,6 +478,31 @@ export class ApiServer {
     }
   }
 
+  /**
+   * Setup plugin-level custom routes
+   * @private
+   */
+  _setupPluginRoutes() {
+    const { routes, database } = this.options;
+
+    if (!routes || Object.keys(routes).length === 0) {
+      return;
+    }
+
+    // Plugin-level routes context
+    const context = {
+      database,
+      plugins: database?.plugins || {}
+    };
+
+    // Mount plugin routes directly on main app (not nested)
+    mountCustomRoutes(this.app, routes, context, this.options.verbose);
+
+    if (this.options.verbose) {
+      console.log(`[API Plugin] Mounted ${Object.keys(routes).length} plugin-level custom routes`);
+    }
+  }
+
   /**
    * Start the server
    * @returns {Promise<void>}

package/src/plugins/api/utils/custom-routes.js

@@ -0,0 +1,102 @@
+/**
+ * Custom Routes Utilities
+ *
+ * Parse and mount custom routes defined in resources or plugins
+ * Inspired by moleculer-js route syntax
+ */
+
+import { asyncHandler } from './error-handler.js';
+
+/**
+ * Parse route definition from key
+ * @param {string} key - Route key (e.g., 'GET /users', 'POST /custom/:id/action')
+ * @returns {Object} { method, path }
+ */
+export function parseRouteKey(key) {
+  const match = key.match(/^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+(.+)$/i);
+
+  if (!match) {
+    throw new Error(`Invalid route key format: "${key}". Expected format: "METHOD /path"`);
+  }
+
+  return {
+    method: match[1].toUpperCase(),
+    path: match[2]
+  };
+}
+
+/**
+ * Mount custom routes on Hono app
+ * @param {Object} app - Hono app instance
+ * @param {Object} routes - Routes object { 'METHOD /path': handler }
+ * @param {Object} context - Context to pass to handlers (resource, database, etc.)
+ * @param {boolean} verbose - Enable verbose logging
+ */
+export function mountCustomRoutes(app, routes, context = {}, verbose = false) {
+  if (!routes || typeof routes !== 'object') {
+    return;
+  }
+
+  for (const [key, handler] of Object.entries(routes)) {
+    try {
+      const { method, path } = parseRouteKey(key);
+
+      // Wrap handler with async error handler and context
+      const wrappedHandler = asyncHandler(async (c) => {
+        // Inject context into Hono context
+        c.set('customRouteContext', context);
+
+        // Call user handler with Hono context
+        return await handler(c);
+      });
+
+      // Mount route
+      app.on(method, path, wrappedHandler);
+
+      if (verbose) {
+        console.log(`[Custom Routes] Mounted ${method} ${path}`);
+      }
+    } catch (err) {
+      console.error(`[Custom Routes] Error mounting route "${key}":`, err.message);
+    }
+  }
+}
+
+/**
+ * Validate custom routes object
+ * @param {Object} routes - Routes to validate
+ * @returns {Array} Array of validation errors
+ */
+export function validateCustomRoutes(routes) {
+  const errors = [];
+
+  if (!routes || typeof routes !== 'object') {
+    return errors;
+  }
+
+  for (const [key, handler] of Object.entries(routes)) {
+    // Validate key format
+    try {
+      parseRouteKey(key);
+    } catch (err) {
+      errors.push({ key, error: err.message });
+      continue;
+    }
+
+    // Validate handler is a function
+    if (typeof handler !== 'function') {
+      errors.push({
+        key,
+        error: `Handler must be a function, got ${typeof handler}`
+      });
+    }
+  }
+
+  return errors;
+}
+
+export default {
+  parseRouteKey,
+  mountCustomRoutes,
+  validateCustomRoutes
+};

package/src/plugins/api/utils/openapi-generator.js

@@ -185,7 +185,20 @@ function generateResourceSchema(resource) {
  */
 function generateResourcePaths(resource, version, config = {}) {
   const resourceName = resource.name;
-  const basePath = `/${version}/${resourceName}`;
+
+  // Determine version prefix (same logic as server.js)
+  let versionPrefixConfig = config.versionPrefix !== undefined ? config.versionPrefix : false;
+
+  let prefix = '';
+  if (versionPrefixConfig === true) {
+    prefix = version;
+  } else if (versionPrefixConfig === false) {
+    prefix = '';
+  } else if (typeof versionPrefixConfig === 'string') {
+    prefix = versionPrefixConfig;
+  }
+
+  const basePath = prefix ? `/${prefix}/${resourceName}` : `/${resourceName}`;
   const schema = generateResourceSchema(resource);
   const methods = config.methods || ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
   const authMethods = config.auth || [];
@@ -820,11 +833,14 @@ The response includes pagination metadata in the \`pagination\` object with tota
  * @param {Object} relationConfig - Relation configuration
  * @param {string} version - Resource version
  * @param {Object} relatedSchema - OpenAPI schema for related resource
+ * @param {string} versionPrefix - Version prefix to use (empty string for no prefix)
  * @returns {Object} OpenAPI paths for relation
  */
-function generateRelationalPaths(resource, relationName, relationConfig, version, relatedSchema) {
+function generateRelationalPaths(resource, relationName, relationConfig, version, relatedSchema, versionPrefix = '') {
   const resourceName = resource.name;
-  const basePath = `/${version}/${resourceName}/{id}/${relationName}`;
+  const basePath = versionPrefix
+    ? `/${versionPrefix}/${resourceName}/{id}/${relationName}`
+    : `/${resourceName}/{id}/${relationName}`;
   const relatedResourceName = relationConfig.resource;
   const isToMany = relationConfig.type === 'hasMany' || relationConfig.type === 'belongsToMany';
 
@@ -950,7 +966,24 @@ export function generateOpenAPISpec(database, config = {}) {
       ? resourceDescription.resource
       : resourceDescription || 'No description';
 
-    resourcesTableRows.push(`| ${name} | ${descText} | \`/${version}/${name}\` |`);
+    // Check version prefix for this resource (same logic as server.js)
+    const config = resourceConfigs[name] || {};
+    let versionPrefixConfig = config.versionPrefix !== undefined
+      ? config.versionPrefix
+      : false; // Default to false (no prefix)
+
+    let prefix = '';
+    if (versionPrefixConfig === true) {
+      prefix = version;
+    } else if (versionPrefixConfig === false) {
+      prefix = '';
+    } else if (typeof versionPrefixConfig === 'string') {
+      prefix = versionPrefixConfig;
+    }
+
+    const basePath = prefix ? `/${prefix}/${name}` : `/${name}`;
+
+    resourcesTableRows.push(`| ${name} | ${descText} | \`${basePath}\` |`);
   }
 
   // Build enhanced description with resources table
@@ -1084,6 +1117,18 @@ For detailed information about each endpoint, see the sections below.`;
     // Determine version
     const version = resource.config?.currentVersion || resource.version || 'v1';
 
+    // Determine version prefix (same logic as server.js)
+    let versionPrefixConfig = config.versionPrefix !== undefined ? config.versionPrefix : false;
+
+    let prefix = '';
+    if (versionPrefixConfig === true) {
+      prefix = version;
+    } else if (versionPrefixConfig === false) {
+      prefix = '';
+    } else if (typeof versionPrefixConfig === 'string') {
+      prefix = versionPrefixConfig;
+    }
+
     // Generate paths
     const paths = generateResourcePaths(resource, version, config);
 
@@ -1128,13 +1173,14 @@ For detailed information about each endpoint, see the sections below.`;
 
         const relatedSchema = generateResourceSchema(relatedResource);
 
-        // Generate relational paths
+        // Generate relational paths (using the same prefix calculated above)
         const relationalPaths = generateRelationalPaths(
           resource,
           relationName,
           relationConfig,
           version,
-          relatedSchema
+          relatedSchema,
+          prefix
         );
 
         // Merge relational paths

package/src/plugins/concerns/plugin-dependencies.js

@@ -170,7 +170,7 @@ async function tryLoadPackage(packageName) {
     let version = null;
     try {
       const pkgJson = await import(`${packageName}/package.json`, {
-        assert: { type: 'json' }
+        with: { type: 'json' }
       });
       version = pkgJson.default?.version || pkgJson.version || null;
     } catch (e) {

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

@@ -140,7 +140,7 @@ export async function runConsolidation(transactionResource, consolidateRecordFn,
     }
 
     if (emitFn) {
-      emitFn('eventual-consistency.consolidated', {
+      emitFn('plg:eventual-consistency:consolidated', {
         resource: config.resource,
         field: config.field,
         recordCount: uniqueIds.length,
@@ -157,7 +157,7 @@ export async function runConsolidation(transactionResource, consolidateRecordFn,
       error
     );
     if (emitFn) {
-      emitFn('eventual-consistency.consolidation-error', error);
+      emitFn('plg:eventual-consistency:consolidation-error', error);
     }
   }
 }

package/src/plugins/eventual-consistency/garbage-collection.js

@@ -103,7 +103,7 @@ export async function runGarbageCollection(transactionResource, storage, config,
     }
 
     if (emitFn) {
-      emitFn('eventual-consistency.gc-completed', {
+      emitFn('plg:eventual-consistency:gc-completed', {
         resource: config.resource,
         field: config.field,
         deletedCount: results.length,
@@ -115,7 +115,7 @@ export async function runGarbageCollection(transactionResource, storage, config,
       console.warn(`[EventualConsistency] GC error:`, error.message);
     }
     if (emitFn) {
-      emitFn('eventual-consistency.gc-error', error);
+      emitFn('plg:eventual-consistency:gc-error', error);
     }
   } finally {
     // Always release GC lock

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

@@ -255,7 +255,7 @@ export async function onStart(fieldHandlers, config, runConsolidationFn, runGCFn
         }
 
         if (emitFn) {
-          emitFn('eventual-consistency.started', {
+          emitFn('plg:eventual-consistency:started', {
             resource: resourceName,
             field: fieldName,
             cohort: config.cohort
@@ -295,7 +295,7 @@ export async function onStop(fieldHandlers, emitFn) {
       }
 
       if (emitFn) {
-        emitFn('eventual-consistency.stopped', {
+        emitFn('plg:eventual-consistency:stopped', {
           resource: resourceName,
           field: fieldName
         });

package/src/plugins/ml/base-model.class.js

@@ -51,22 +51,36 @@ export class BaseModel {
       errors: 0
     };
 
-    // Validate TensorFlow.js
-    this._validateTensorFlow();
+    // TensorFlow will be loaded lazily on first use
+    this.tf = null;
+    this._tfValidated = false;
   }
 
   /**
-   * Validate TensorFlow.js is installed
+   * Validate and load TensorFlow.js (lazy loading)
    * @private
    */
-  _validateTensorFlow() {
+  async _validateTensorFlow() {
+    if (this._tfValidated) {
+      return; // Already validated and loaded
+    }
+
     try {
+      // Try CommonJS require first (works in most environments)
       this.tf = require('@tensorflow/tfjs-node');
-    } catch (error) {
-      throw new TensorFlowDependencyError(
-        'TensorFlow.js is not installed. Run: pnpm add @tensorflow/tfjs-node',
-        { originalError: error.message }
-      );
+      this._tfValidated = true;
+    } catch (requireError) {
+      // If require fails (e.g., Jest VM modules), try dynamic import
+      try {
+        const tfModule = await import('@tensorflow/tfjs-node');
+        this.tf = tfModule.default || tfModule;
+        this._tfValidated = true;
+      } catch (importError) {
+        throw new TensorFlowDependencyError(
+          'TensorFlow.js is not installed. Run: pnpm add @tensorflow/tfjs-node',
+          { originalError: importError.message }
+        );
+      }
     }
   }
 
@@ -85,6 +99,11 @@ export class BaseModel {
    * @returns {Object} Training results
    */
   async train(data) {
+    // Validate TensorFlow on first use (lazy loading)
+    if (!this._tfValidated) {
+      await this._validateTensorFlow();
+    }
+
     try {
       if (!data || data.length === 0) {
         throw new InsufficientDataError('No training data provided', {
@@ -171,6 +190,11 @@ export class BaseModel {
    * @returns {Object} Prediction result
    */
   async predict(input) {
+    // Validate TensorFlow on first use (lazy loading)
+    if (!this._tfValidated) {
+      await this._validateTensorFlow();
+    }
+
     if (!this.isTrained) {
       throw new ModelNotTrainedError(`Model "${this.config.name}" is not trained yet`, {
         model: this.config.name