s3db.js 12.3.0 → 13.0.0

package/src/plugins/api/index.js

@@ -437,15 +437,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
     };
   }
 

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

@@ -8,6 +8,44 @@ 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
@@ -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) => {

package/src/plugins/index.js

@@ -13,6 +13,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/ml/base-model.class.js

@@ -0,0 +1,459 @@
+/**
+ * Base Model Class
+ *
+ * Abstract base class for all ML models
+ * Provides common functionality for training, prediction, and persistence
+ */
+
+import {
+  TrainingError,
+  PredictionError,
+  ModelNotTrainedError,
+  DataValidationError,
+  InsufficientDataError,
+  TensorFlowDependencyError
+} from '../ml.errors.js';
+
+export class BaseModel {
+  constructor(config = {}) {
+    if (this.constructor === BaseModel) {
+      throw new Error('BaseModel is an abstract class and cannot be instantiated directly');
+    }
+
+    this.config = {
+      name: config.name || 'unnamed',
+      resource: config.resource,
+      features: config.features || [],
+      target: config.target,
+      modelConfig: {
+        epochs: 50,
+        batchSize: 32,
+        learningRate: 0.01,
+        validationSplit: 0.2,
+        ...config.modelConfig
+      },
+      verbose: config.verbose || false
+    };
+
+    // Model state
+    this.model = null;
+    this.isTrained = false;
+    this.normalizer = {
+      features: {},
+      target: {}
+    };
+    this.stats = {
+      trainedAt: null,
+      samples: 0,
+      loss: null,
+      accuracy: null,
+      predictions: 0,
+      errors: 0
+    };
+
+    // Validate TensorFlow.js
+    this._validateTensorFlow();
+  }
+
+  /**
+   * Validate TensorFlow.js is installed
+   * @private
+   */
+  _validateTensorFlow() {
+    try {
+      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 }
+      );
+    }
+  }
+
+  /**
+   * Abstract method: Build the model architecture
+   * Must be implemented by subclasses
+   * @abstract
+   */
+  buildModel() {
+    throw new Error('buildModel() must be implemented by subclass');
+  }
+
+  /**
+   * Train the model with provided data
+   * @param {Array} data - Training data records
+   * @returns {Object} Training results
+   */
+  async train(data) {
+    try {
+      if (!data || data.length === 0) {
+        throw new InsufficientDataError('No training data provided', {
+          model: this.config.name
+        });
+      }
+
+      // Validate minimum samples
+      const minSamples = this.config.modelConfig.batchSize || 10;
+      if (data.length < minSamples) {
+        throw new InsufficientDataError(
+          `Insufficient training data: ${data.length} samples (minimum: ${minSamples})`,
+          { model: this.config.name, samples: data.length, minimum: minSamples }
+        );
+      }
+
+      // Prepare data (extract features and target)
+      const { xs, ys } = this._prepareData(data);
+
+      // Build model if not already built
+      if (!this.model) {
+        this.buildModel();
+      }
+
+      // Train the model
+      const history = await this.model.fit(xs, ys, {
+        epochs: this.config.modelConfig.epochs,
+        batchSize: this.config.modelConfig.batchSize,
+        validationSplit: this.config.modelConfig.validationSplit,
+        verbose: this.config.verbose ? 1 : 0,
+        callbacks: {
+          onEpochEnd: (epoch, logs) => {
+            if (this.config.verbose && epoch % 10 === 0) {
+              console.log(`[MLPlugin] ${this.config.name} - Epoch ${epoch}: loss=${logs.loss.toFixed(4)}`);
+            }
+          }
+        }
+      });
+
+      // Update stats
+      this.isTrained = true;
+      this.stats.trainedAt = new Date().toISOString();
+      this.stats.samples = data.length;
+      this.stats.loss = history.history.loss[history.history.loss.length - 1];
+
+      // Get accuracy if available (classification models)
+      if (history.history.acc) {
+        this.stats.accuracy = history.history.acc[history.history.acc.length - 1];
+      }
+
+      // Cleanup tensors
+      xs.dispose();
+      ys.dispose();
+
+      if (this.config.verbose) {
+        console.log(`[MLPlugin] ${this.config.name} - Training completed:`, {
+          samples: this.stats.samples,
+          loss: this.stats.loss,
+          accuracy: this.stats.accuracy
+        });
+      }
+
+      return {
+        loss: this.stats.loss,
+        accuracy: this.stats.accuracy,
+        epochs: this.config.modelConfig.epochs,
+        samples: this.stats.samples
+      };
+    } catch (error) {
+      this.stats.errors++;
+      if (error instanceof InsufficientDataError || error instanceof DataValidationError) {
+        throw error;
+      }
+      throw new TrainingError(`Training failed: ${error.message}`, {
+        model: this.config.name,
+        originalError: error.message
+      });
+    }
+  }
+
+  /**
+   * Make a prediction with the trained model
+   * @param {Object} input - Input features
+   * @returns {Object} Prediction result
+   */
+  async predict(input) {
+    if (!this.isTrained) {
+      throw new ModelNotTrainedError(`Model "${this.config.name}" is not trained yet`, {
+        model: this.config.name
+      });
+    }
+
+    try {
+      // Validate input
+      this._validateInput(input);
+
+      // Extract and normalize features
+      const features = this._extractFeatures(input);
+      const normalizedFeatures = this._normalizeFeatures(features);
+
+      // Convert to tensor
+      const inputTensor = this.tf.tensor2d([normalizedFeatures]);
+
+      // Predict
+      const predictionTensor = this.model.predict(inputTensor);
+      const predictionArray = await predictionTensor.data();
+
+      // Cleanup
+      inputTensor.dispose();
+      predictionTensor.dispose();
+
+      // Denormalize prediction
+      const prediction = this._denormalizePrediction(predictionArray[0]);
+
+      this.stats.predictions++;
+
+      return {
+        prediction,
+        confidence: this._calculateConfidence(predictionArray[0])
+      };
+    } catch (error) {
+      this.stats.errors++;
+      if (error instanceof ModelNotTrainedError || error instanceof DataValidationError) {
+        throw error;
+      }
+      throw new PredictionError(`Prediction failed: ${error.message}`, {
+        model: this.config.name,
+        input,
+        originalError: error.message
+      });
+    }
+  }
+
+  /**
+   * Make predictions for multiple inputs
+   * @param {Array} inputs - Array of input objects
+   * @returns {Array} Array of prediction results
+   */
+  async predictBatch(inputs) {
+    if (!this.isTrained) {
+      throw new ModelNotTrainedError(`Model "${this.config.name}" is not trained yet`, {
+        model: this.config.name
+      });
+    }
+
+    const predictions = [];
+    for (const input of inputs) {
+      predictions.push(await this.predict(input));
+    }
+    return predictions;
+  }
+
+  /**
+   * Prepare training data (extract features and target)
+   * @private
+   * @param {Array} data - Raw training data
+   * @returns {Object} Prepared tensors {xs, ys}
+   */
+  _prepareData(data) {
+    const features = [];
+    const targets = [];
+
+    for (const record of data) {
+      // Validate record has required fields
+      const missingFeatures = this.config.features.filter(f => !(f in record));
+      if (missingFeatures.length > 0) {
+        throw new DataValidationError(
+          `Missing features in training data: ${missingFeatures.join(', ')}`,
+          { model: this.config.name, missingFeatures, record }
+        );
+      }
+
+      if (!(this.config.target in record)) {
+        throw new DataValidationError(
+          `Missing target "${this.config.target}" in training data`,
+          { model: this.config.name, target: this.config.target, record }
+        );
+      }
+
+      // Extract features
+      const featureValues = this._extractFeatures(record);
+      features.push(featureValues);
+
+      // Extract target
+      targets.push(record[this.config.target]);
+    }
+
+    // Calculate normalization parameters
+    this._calculateNormalizer(features, targets);
+
+    // Normalize data
+    const normalizedFeatures = features.map(f => this._normalizeFeatures(f));
+    const normalizedTargets = targets.map(t => this._normalizeTarget(t));
+
+    // Convert to tensors
+    return {
+      xs: this.tf.tensor2d(normalizedFeatures),
+      ys: this._prepareTargetTensor(normalizedTargets)
+    };
+  }
+
+  /**
+   * Prepare target tensor (can be overridden by subclasses)
+   * @protected
+   * @param {Array} targets - Normalized target values
+   * @returns {Tensor} Target tensor
+   */
+  _prepareTargetTensor(targets) {
+    return this.tf.tensor2d(targets.map(t => [t]));
+  }
+
+  /**
+   * Extract feature values from a record
+   * @private
+   * @param {Object} record - Data record
+   * @returns {Array} Feature values
+   */
+  _extractFeatures(record) {
+    return this.config.features.map(feature => {
+      const value = record[feature];
+      if (typeof value !== 'number') {
+        throw new DataValidationError(
+          `Feature "${feature}" must be a number, got ${typeof value}`,
+          { model: this.config.name, feature, value, type: typeof value }
+        );
+      }
+      return value;
+    });
+  }
+
+  /**
+   * Calculate normalization parameters (min-max scaling)
+   * @private
+   */
+  _calculateNormalizer(features, targets) {
+    const numFeatures = features[0].length;
+
+    // Initialize normalizer
+    for (let i = 0; i < numFeatures; i++) {
+      const featureName = this.config.features[i];
+      const values = features.map(f => f[i]);
+      this.normalizer.features[featureName] = {
+        min: Math.min(...values),
+        max: Math.max(...values)
+      };
+    }
+
+    // Normalize target
+    this.normalizer.target = {
+      min: Math.min(...targets),
+      max: Math.max(...targets)
+    };
+  }
+
+  /**
+   * Normalize features using min-max scaling
+   * @private
+   */
+  _normalizeFeatures(features) {
+    return features.map((value, i) => {
+      const featureName = this.config.features[i];
+      const { min, max } = this.normalizer.features[featureName];
+      if (max === min) return 0.5; // Handle constant features
+      return (value - min) / (max - min);
+    });
+  }
+
+  /**
+   * Normalize target value
+   * @private
+   */
+  _normalizeTarget(target) {
+    const { min, max } = this.normalizer.target;
+    if (max === min) return 0.5;
+    return (target - min) / (max - min);
+  }
+
+  /**
+   * Denormalize prediction
+   * @private
+   */
+  _denormalizePrediction(normalizedValue) {
+    const { min, max } = this.normalizer.target;
+    return normalizedValue * (max - min) + min;
+  }
+
+  /**
+   * Calculate confidence score (can be overridden)
+   * @protected
+   */
+  _calculateConfidence(value) {
+    // Default: simple confidence based on normalized value
+    // Closer to 0 or 1 = higher confidence, closer to 0.5 = lower confidence
+    const distanceFrom05 = Math.abs(value - 0.5);
+    return Math.min(0.5 + distanceFrom05, 1.0);
+  }
+
+  /**
+   * Validate input data
+   * @private
+   */
+  _validateInput(input) {
+    const missingFeatures = this.config.features.filter(f => !(f in input));
+    if (missingFeatures.length > 0) {
+      throw new DataValidationError(
+        `Missing features: ${missingFeatures.join(', ')}`,
+        { model: this.config.name, missingFeatures, input }
+      );
+    }
+  }
+
+  /**
+   * Export model to JSON (for persistence)
+   * @returns {Object} Serialized model
+   */
+  async export() {
+    if (!this.model) {
+      return null;
+    }
+
+    const modelJSON = await this.model.toJSON();
+
+    return {
+      config: this.config,
+      normalizer: this.normalizer,
+      stats: this.stats,
+      isTrained: this.isTrained,
+      model: modelJSON
+    };
+  }
+
+  /**
+   * Import model from JSON
+   * @param {Object} data - Serialized model data
+   */
+  async import(data) {
+    this.config = data.config;
+    this.normalizer = data.normalizer;
+    this.stats = data.stats;
+    this.isTrained = data.isTrained;
+
+    if (data.model) {
+      // Note: Actual model reconstruction depends on the model type
+      // This is a placeholder and should be overridden by subclasses
+      this.buildModel();
+    }
+  }
+
+  /**
+   * Dispose model and free memory
+   */
+  dispose() {
+    if (this.model) {
+      this.model.dispose();
+      this.model = null;
+    }
+    this.isTrained = false;
+  }
+
+  /**
+   * Get model statistics
+   */
+  getStats() {
+    return {
+      ...this.stats,
+      isTrained: this.isTrained,
+      config: this.config
+    };
+  }
+}
+
+export default BaseModel;