webspresso 0.0.90 → 0.0.91

package/core/errors/normalize.js

@@ -0,0 +1,171 @@
+/**
+ * Error Normalization & Formatting Utilities
+ * Standardizes errors across all layers and formats safe HTTP error payloads.
+ * @module core/errors/normalize
+ */
+
+const { WebspressoError } = require('./base');
+const { HttpError } = require('./http');
+
+const HTTP_TITLES = {
+  400: 'Bad Request',
+  401: 'Unauthorized',
+  403: 'Forbidden',
+  404: 'Not Found',
+  405: 'Method Not Allowed',
+  408: 'Request Timeout',
+  409: 'Conflict',
+  413: 'Payload Too Large',
+  415: 'Unsupported Media Type',
+  422: 'Unprocessable Entity',
+  429: 'Too Many Requests',
+  500: 'Internal Server Error',
+  502: 'Bad Gateway',
+  503: 'Service Unavailable',
+  504: 'Gateway Timeout',
+};
+
+/**
+ * Get human-readable title for an HTTP status code
+ * @param {number} status
+ * @returns {string}
+ */
+function getStatusTitle(status) {
+  return HTTP_TITLES[status] || (status >= 500 ? 'Internal Server Error' : 'Error');
+}
+
+/**
+ * Normalize any thrown value (Error, string, object, null) into a standardized HttpError or WebspressoError
+ * @param {unknown} err - The raw thrown error
+ * @param {boolean} [isDev=false] - Whether in development environment
+ * @returns {HttpError|WebspressoError}
+ */
+function normalizeError(err, isDev = false) {
+  // Handle nullish throws
+  if (err === null || err === undefined) {
+    return new HttpError(500, 'Internal Server Error', {
+      expose: false,
+    });
+  }
+
+  // If already a WebspressoError / HttpError
+  if (err instanceof WebspressoError) {
+    return err;
+  }
+
+  // If standard JavaScript Error (TypeError, RangeError, standard Error)
+  if (err instanceof Error) {
+    const status = typeof err.status === 'number'
+      ? err.status
+      : (typeof err.statusCode === 'number' ? err.statusCode : 500);
+
+    const isClientError = status < 500;
+    const expose = typeof err.expose === 'boolean' ? err.expose : isClientError;
+
+    const httpErr = new HttpError(
+      status,
+      (expose || isDev) ? (err.message || getStatusTitle(status)) : getStatusTitle(status),
+      {
+        code: err.code || (status === 500 ? 'INTERNAL_SERVER_ERROR' : undefined),
+        details: err.details,
+        cause: err,
+        headers: err.headers,
+        expose,
+      }
+    );
+
+    // Retain original stack
+    if (err.stack) {
+      httpErr.stack = err.stack;
+    }
+
+    return httpErr;
+  }
+
+  // If primitive string or number thrown
+  if (typeof err === 'string' || typeof err === 'number' || typeof err === 'boolean') {
+    const msg = String(err);
+    return new HttpError(500, isDev ? msg : 'Internal Server Error', {
+      details: { rawValue: err },
+      expose: false,
+    });
+  }
+
+  // If plain object thrown (e.g. { message: 'Failed', status: 400 })
+  if (typeof err === 'object') {
+    const status = typeof err.status === 'number'
+      ? err.status
+      : (typeof err.statusCode === 'number' ? err.statusCode : 500);
+
+    const msg = typeof err.message === 'string' ? err.message : getStatusTitle(status);
+
+    return new HttpError(status, (status < 500 || isDev) ? msg : getStatusTitle(status), {
+      code: err.code,
+      details: err.details,
+      headers: err.headers,
+      expose: typeof err.expose === 'boolean' ? err.expose : status < 500,
+    });
+  }
+
+  return new HttpError(500, 'Internal Server Error', { expose: false });
+}
+
+/**
+ * Format a normalized error into a clean JSON response object conforming to contract
+ * @param {HttpError|WebspressoError|Error} error - Normalized error
+ * @param {boolean} [isDev=false] - Whether running in development mode
+ * @returns {Record<string, unknown>}
+ */
+function toErrorResponseObject(error, isDev = false) {
+  const status = typeof error.status === 'number' ? error.status : 500;
+  const errorTitle = error.name === 'ValidationError'
+    ? 'Validation Error'
+    : getStatusTitle(status);
+
+  let shouldExpose;
+  if (typeof error.expose === 'boolean') {
+    shouldExpose = error.expose || isDev;
+  } else {
+    shouldExpose = isDev || status < 500;
+  }
+
+  const message = shouldExpose && error.message ? error.message : getStatusTitle(status);
+
+  const payload = {
+    status,
+    error: errorTitle,
+    message,
+  };
+
+  if (error.code) {
+    payload.code = error.code;
+  }
+
+  // Include validation fields if present
+  if (error.fields && Object.keys(error.fields).length > 0 && shouldExpose) {
+    payload.fields = error.fields;
+  }
+
+  // Include contextual details if expose is true or in dev
+  if (error.details !== undefined && shouldExpose) {
+    payload.details = error.details;
+  }
+
+  // Include stack and cause strictly in development mode
+  if (isDev) {
+    if (error.stack) {
+      payload.stack = error.stack;
+    }
+    if (error.cause) {
+      payload.cause = error.cause instanceof Error ? (error.cause.stack || error.cause.message) : error.cause;
+    }
+  }
+
+  return payload;
+}
+
+module.exports = {
+  getStatusTitle,
+  normalizeError,
+  toErrorResponseObject,
+};

package/core/orm/complexity.js

@@ -0,0 +1,120 @@
+/**
+ * ORM Query Complexity & DoS Protection
+ * @module core/orm/complexity
+ */
+
+'use strict';
+
+const { BadRequestError } = require('../errors/http');
+
+class QueryComplexityError extends BadRequestError {
+  /**
+   * @param {string} message
+   * @param {Object} [details]
+   */
+  constructor(message, details = {}) {
+    super(message || 'Query complexity limit exceeded', details);
+    this.name = 'QueryComplexityError';
+    this.code = 'QUERY_COMPLEXITY_EXCEEDED';
+  }
+}
+
+const DEFAULT_QUERY_LIMITS = Object.freeze({
+  maxLimit: 100,
+  defaultLimit: 15,
+  maxIncludes: 5,
+  maxFilterConditions: 25,
+});
+
+/**
+ * Resolve query limits for a given model
+ * @param {import('./types').ModelDefinition} [model]
+ * @returns {typeof DEFAULT_QUERY_LIMITS}
+ */
+function resolveQueryLimits(model) {
+  if (!model || !model.queryLimits) {
+    return DEFAULT_QUERY_LIMITS;
+  }
+  return {
+    maxLimit: Number(model.queryLimits.maxLimit) || DEFAULT_QUERY_LIMITS.maxLimit,
+    defaultLimit: Number(model.queryLimits.defaultLimit) || DEFAULT_QUERY_LIMITS.defaultLimit,
+    maxIncludes: Number(model.queryLimits.maxIncludes) || DEFAULT_QUERY_LIMITS.maxIncludes,
+    maxFilterConditions: Number(model.queryLimits.maxFilterConditions) || DEFAULT_QUERY_LIMITS.maxFilterConditions,
+  };
+}
+
+/**
+ * Validate and clamp query complexity parameters against model / default limits
+ * @param {import('./types').ModelDefinition} [model]
+ * @param {Object} params
+ * @param {number} [params.perPage]
+ * @param {number} [params.limit]
+ * @param {string[]} [params.includes]
+ * @param {number} [params.filterCount]
+ * @param {boolean} [params.strict=false] - If true, throws QueryComplexityError instead of clamping
+ * @returns {{ limit: number, perPage: number, includes: string[] }}
+ */
+function validateQueryComplexity(model, params = {}) {
+  const limits = resolveQueryLimits(model);
+  const strict = params.strict === true;
+
+  // 1. Validate includes
+  let includes = Array.isArray(params.includes) ? params.includes : [];
+  if (includes.length > limits.maxIncludes) {
+    if (strict) {
+      throw new QueryComplexityError(
+        `Too many eager-loaded relations (${includes.length}). Maximum allowed is ${limits.maxIncludes}.`,
+        { maxIncludes: limits.maxIncludes, requested: includes.length }
+      );
+    }
+    includes = includes.slice(0, limits.maxIncludes);
+  }
+
+  // 2. Validate perPage / limit
+  let requestedLimit = params.perPage !== undefined ? params.perPage : params.limit;
+  if (requestedLimit !== undefined) {
+    const numLimit = parseInt(requestedLimit, 10);
+    if (!isNaN(numLimit)) {
+      if (numLimit > limits.maxLimit) {
+        if (strict) {
+          throw new QueryComplexityError(
+            `Requested limit (${numLimit}) exceeds maximum allowed limit of ${limits.maxLimit}.`,
+            { maxLimit: limits.maxLimit, requested: numLimit }
+          );
+        }
+        requestedLimit = limits.maxLimit;
+      } else if (numLimit < 1) {
+        requestedLimit = limits.defaultLimit;
+      } else {
+        requestedLimit = numLimit;
+      }
+    } else {
+      requestedLimit = limits.defaultLimit;
+    }
+  } else {
+    requestedLimit = limits.defaultLimit;
+  }
+
+  // 3. Validate filter count
+  if (params.filterCount !== undefined && params.filterCount > limits.maxFilterConditions) {
+    if (strict) {
+      throw new QueryComplexityError(
+        `Too many filter conditions (${params.filterCount}). Maximum allowed is ${limits.maxFilterConditions}.`,
+        { maxFilterConditions: limits.maxFilterConditions, requested: params.filterCount }
+      );
+    }
+  }
+
+  return {
+    limit: requestedLimit,
+    perPage: requestedLimit,
+    includes,
+  };
+}
+
+module.exports = {
+  QueryComplexityError,
+  DEFAULT_QUERY_LIMITS,
+  resolveQueryLimits,
+  validateQueryComplexity,
+};

package/core/orm/events.js

@@ -1,6 +1,6 @@
 /**
  * Webspresso ORM - Events/Signals System
- * Django-style signal system for model lifecycle events
+ * Django-style signal system for model lifecycle events with leak detection and maxListeners bounds
  * @module core/orm/events
  */
 
@@ -16,6 +16,7 @@
  */
 
 const EMPTY_ARRAY = Object.freeze([]);
+const DEFAULT_MAX_LISTENERS = 50;
 
 function cancelContext(reason = 'Operation cancelled') {
   this.isCancelled = true;
@@ -42,12 +43,34 @@ function createEventContext(model, operation, trx = null) {
 
 /**
  * ModelEvents - Global event bus for ORM lifecycle events
- * Singleton class that manages event listeners and emission
+ * Singleton class that manages event listeners, emission, and memory leak warnings
  */
 class ModelEventsClass {
   constructor() {
     /** @type {Map<string, Set<Function>>} */
     this.listeners = new Map();
+    this.maxListeners = DEFAULT_MAX_LISTENERS;
+  }
+
+  /**
+   * Set maximum number of listeners allowed per event before warning
+   * @param {number} n
+   * @returns {this}
+   */
+  setMaxListeners(n) {
+    if (typeof n !== 'number' || n < 0 || Number.isNaN(n)) {
+      throw new TypeError('The value of "n" must be a non-negative number');
+    }
+    this.maxListeners = n;
+    return this;
+  }
+
+  /**
+   * Get current maximum listeners threshold
+   * @returns {number}
+   */
+  getMaxListeners() {
+    return this.maxListeners;
   }
 
   /**
@@ -64,7 +87,19 @@ class ModelEventsClass {
     if (!this.listeners.has(event)) {
       this.listeners.set(event, new Set());
     }
-    this.listeners.get(event).add(callback);
+
+    const set = this.listeners.get(event);
+    set.add(callback);
+
+    // Memory leak detection & warning
+    if (this.maxListeners > 0 && set.size > this.maxListeners) {
+      const warnMsg = `Possible ModelEvents memory leak detected. ${set.size} '${event}' listeners added. Use setMaxListeners() to increase limit.`;
+      if (typeof process !== 'undefined' && typeof process.emitWarning === 'function') {
+        process.emitWarning(warnMsg, 'MaxListenersExceededWarning');
+      } else {
+        console.warn(`[webspresso:warning] ${warnMsg}`);
+      }
+    }
 
     // Return unsubscribe function
     return () => this.off(event, callback);
@@ -84,6 +119,27 @@ class ModelEventsClass {
     return this.on(event, wrapper);
   }
 
+  /**
+   * Attach a listener scoped to an HTTP request or lifecycle target (auto-removes on finish/close)
+   * @param {string} event - Event name
+   * @param {Function} callback - Callback function
+   * @param {Object} [lifecycleTarget] - Optional target with on/once (e.g. Express `res` or `req`)
+   * @returns {Function} Unsubscribe function
+   */
+  listenScoped(event, callback, lifecycleTarget) {
+    const unsubscribe = this.on(event, callback);
+
+    if (lifecycleTarget && typeof lifecycleTarget.once === 'function') {
+      const cleanup = () => {
+        unsubscribe();
+      };
+      lifecycleTarget.once('finish', cleanup);
+      lifecycleTarget.once('close', cleanup);
+    }
+
+    return unsubscribe;
+  }
+
   /**
    * Remove an event listener
    * @param {string} event - Event name
@@ -93,7 +149,11 @@ class ModelEventsClass {
   off(event, callback) {
     const listeners = this.listeners.get(event);
     if (listeners) {
-      return listeners.delete(callback);
+      const removed = listeners.delete(callback);
+      if (listeners.size === 0) {
+        this.listeners.delete(event);
+      }
+      return removed;
     }
     return false;
   }
@@ -227,16 +287,6 @@ class ModelEventsClass {
     return ctx;
   }
 
-  /**
-   * Check if there are any listeners for an event
-   * @param {string} model - Model name
-   * @param {string} hook - Hook name
-   * @returns {boolean}
-   */
-  hasListeners(model, hook) {
-    return this.getMatchingListeners(model, hook).length > 0;
-  }
-
   /**
    * Get listener count for an event
    * @param {string} [event] - Specific event (optional)

package/core/orm/index.js

@@ -16,6 +16,14 @@ const { ModelEvents, Hooks, HookCancellationError, createEventContext } = requir
 const { omitHiddenColumns, sanitizeForOutput } = require('./utils');
 const { generateNanoid, zodNanoid, extendZ } = require('./utils/nanoid');
 const { createOrmCacheFromConfig, unregisterOrmCacheListeners } = require('./cache');
+const {
+  ambientTransactionStorage,
+  runWithAmbientTransaction,
+  getAmbientTransaction,
+  hasAmbientTransaction,
+  createTransactionContext,
+  runTransaction,
+} = require('./transaction');
 
 /**
  * Create a database instance
@@ -128,10 +136,14 @@ function createDatabase(config) {
 
   /**
    * Get a model by name
-   * @param {string} name - Model name
+   * @param {string|import('./types').ModelDefinition} nameOrModel - Model name or model definition
    * @returns {import('./types').ModelDefinition}
    */
-  function getModelInstance(name) {
+  function getModelInstance(nameOrModel) {
+    const name = typeof nameOrModel === 'object' && nameOrModel !== null && nameOrModel.name
+      ? nameOrModel.name
+      : nameOrModel;
+
     // First check local registry
     let model = models.get(name);
     
@@ -221,26 +233,34 @@ function createDatabase(config) {
   }
 
   /**
-   * Run operations in a transaction
+   * Run operations in an ambient transaction
    * @param {Function} callback - Callback receiving transaction context
+   * @param {import('./types').ScopeContext} [scopeContext] - Optional scope context
    * @returns {Promise<*>} Result of callback
    */
-  async function transaction(callback) {
+  async function transaction(callback, scopeContext) {
     return knexInstance.transaction(async (trx) => {
-      // Create transaction context with repository methods
       const trxContext = {
         trx,
-        getRepository(modelName, scopeContext) {
+        getRepository(modelName, sContext) {
           const model = getModelInstance(modelName);
-          const ctx = scopeContext || createScopeContext();
+          const ctx = sContext || scopeContext || createScopeContext();
           return createRepository(model, trx, ctx, ormCacheLayer);
         },
-        createRepository(model, scopeContext) {
-          const ctx = scopeContext || createScopeContext();
+        createRepository(model, sContext) {
+          const ctx = sContext || scopeContext || createScopeContext();
           return createRepository(model, trx, ctx, ormCacheLayer);
         },
+        forTenant(tenantId) {
+          if (!scopeContext) scopeContext = createScopeContext();
+          scopeContext.tenantId = tenantId;
+          return this;
+        },
+        getScopeContext() {
+          return { ...(scopeContext || createScopeContext()) };
+        },
       };
-      return callback(trxContext);
+      return runWithAmbientTransaction(trx, () => callback(trxContext));
     });
   }
 
@@ -255,6 +275,9 @@ function createDatabase(config) {
     createRepository: createRepositoryFromModel,
     query,
     transaction,
+    runInTransaction: transaction,
+    getAmbientTransaction,
+    hasActiveTransaction: hasAmbientTransaction,
     createSeeder: createSeederInstance,
     cache: ormCachePublicApi,
     destroy: () => {
@@ -275,6 +298,13 @@ module.exports = {
   createMemoryCacheProvider: require('./cache/memory-provider').createMemoryCacheProvider,
   OrmCacheLayer: require('./cache/layer').OrmCacheLayer,
   createOrmCacheFromConfig: require('./cache').createOrmCacheFromConfig,
+  // Ambient transaction management
+  ambientTransactionStorage,
+  runWithAmbientTransaction,
+  getAmbientTransaction,
+  hasAmbientTransaction,
+  createTransactionContext,
+  runTransaction,
   // Schema helpers
   zdb,
   createSchemaHelpers,
@@ -298,4 +328,9 @@ module.exports = {
   Hooks,
   HookCancellationError,
   createEventContext,
+  // Query Complexity & DoS Protection
+  QueryComplexityError: require('./complexity').QueryComplexityError,
+  validateQueryComplexity: require('./complexity').validateQueryComplexity,
+  resolveQueryLimits: require('./complexity').resolveQueryLimits,
+  DEFAULT_QUERY_LIMITS: require('./complexity').DEFAULT_QUERY_LIMITS,
 };

package/core/orm/model.js

@@ -31,6 +31,7 @@ function defineModel(options) {
     rest = {},
     hooks = {},
     hidden = [],
+    queryLimits = {},
     cache: cacheOption,
   } = options;
 
@@ -105,6 +106,7 @@ function defineModel(options) {
       allowInclude: Array.isArray(rest.allowInclude) ? rest.allowInclude.filter((x) => typeof x === 'string') : null,
     },
     hidden: Array.isArray(hidden) ? hidden : [],
+    queryLimits: typeof queryLimits === 'object' && queryLimits !== null ? queryLimits : {},
     hooks: {},
     cache: cacheOption,
   };

package/core/orm/query-builder.js

@@ -13,6 +13,8 @@ const {
   serializeJsonFields,
   deserializeJsonFields,
 } = require('./json-fields');
+const { getAmbientTransaction } = require('./transaction');
+const { validateQueryComplexity } = require('./complexity');
 
 /**
  * Create a new query builder
@@ -236,7 +238,8 @@ class QueryBuilder {
    * @returns {this}
    */
   limit(limit) {
-    this.state.limitValue = limit;
+    const validated = validateQueryComplexity(this.model, { limit });
+    this.state.limitValue = validated.limit;
     return this;
   }
 
@@ -256,7 +259,9 @@ class QueryBuilder {
    * @returns {this}
    */
   with(...relations) {
-    this.state.withs.push(...relations.flat());
+    const flat = relations.flat();
+    const validated = validateQueryComplexity(this.model, { includes: [...this.state.withs, ...flat] });
+    this.state.withs = validated.includes;
     return this;
   }
 
@@ -288,12 +293,28 @@ class QueryBuilder {
     return this;
   }
 
+  /**
+   * Resolve active Knex instance (explicit or ambient transaction)
+   * @returns {import('knex').Knex|import('knex').Knex.Transaction}
+   */
+  getActiveKnex() {
+    if (this.knex && (this.knex.isTransaction || typeof this.knex.commit === 'function')) {
+      return this.knex;
+    }
+    const ambientTrx = getAmbientTransaction();
+    if (ambientTrx) {
+      return ambientTrx;
+    }
+    return this.knex;
+  }
+
   /**
    * Transaction handle for lifecycle hooks (matches repository pattern)
    * @returns {import('knex').Knex.Transaction|null}
    */
   _hookTrx() {
-    return this.knex.isTransaction ? this.knex : null;
+    const active = this.getActiveKnex();
+    return (active && (active.isTransaction || typeof active.commit === 'function')) ? active : null;
   }
 
   /**
@@ -304,7 +325,8 @@ class QueryBuilder {
    */
   toKnex(options = {}) {
     const { includeLimitOffset = true } = options;
-    let qb = this.knex(this.model.table);
+    const activeKnex = this.getActiveKnex();
+    let qb = activeKnex(this.model.table);
 
     // Apply global scopes
     qb = applyScopes(qb, this.scopeContext, this.model);
@@ -564,6 +586,10 @@ class QueryBuilder {
    * @returns {Promise<import('./types').PaginatedResult>}
    */
   async paginate(page = 1, perPage = 15) {
+    const validated = validateQueryComplexity(this.model, { perPage });
+    perPage = validated.perPage;
+    page = Math.max(1, parseInt(page, 10) || 1);
+
     const ctx = createEventContext(this.model.name, 'find', this._hookTrx());
     const self = this;