webspresso 0.0.90 → 0.0.93

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/eager-loader.js

@@ -49,6 +49,35 @@ async function loadRelations(records, relationNames, model, knex, scopeContext)
   return records;
 }
 
+/**
+ * Execute whereIn query in chunks to prevent parameter limits and query planner degradation
+ * @param {import('knex').Knex} knex
+ * @param {string} table
+ * @param {string} column
+ * @param {Array<string|number>} values
+ * @param {import('./types').ScopeContext} scopeContext
+ * @param {import('./types').ModelDefinition} model
+ * @param {number} [chunkSize=500]
+ * @returns {Promise<Object[]>}
+ */
+async function queryInChunks(knex, table, column, values, scopeContext, model, chunkSize = 500) {
+  if (values.length <= chunkSize) {
+    let qb = knex(table).whereIn(column, values);
+    qb = applyScopes(qb, scopeContext, model);
+    return await qb;
+  }
+
+  const results = [];
+  for (let i = 0; i < values.length; i += chunkSize) {
+    const slice = values.slice(i, i + chunkSize);
+    let qb = knex(table).whereIn(column, slice);
+    qb = applyScopes(qb, scopeContext, model);
+    const chunkResults = await qb;
+    results.push(...chunkResults);
+  }
+  return results;
+}
+
 /**
  * Load belongsTo relation
  * Parent record has foreign key pointing to related record's primary key
@@ -78,9 +107,14 @@ async function loadBelongsTo(records, relationName, localKey, foreignKey, relate
   }
 
   const foreignKeyValues = Array.from(fkSet);
-  let qb = knex(relatedModel.table).whereIn(relatedModel.primaryKey, foreignKeyValues);
-  qb = applyScopes(qb, scopeContext, relatedModel);
-  const relatedRecords = await qb;
+  const relatedRecords = await queryInChunks(
+    knex,
+    relatedModel.table,
+    relatedModel.primaryKey,
+    foreignKeyValues,
+    scopeContext,
+    relatedModel
+  );
 
   const relatedMap = new Map();
   const rLen = relatedRecords.length;
@@ -128,9 +162,14 @@ async function loadHasMany(records, relationName, localKey, foreignKey, relatedM
   }
 
   const primaryKeyValues = Array.from(pkSet);
-  let qb = knex(relatedModel.table).whereIn(foreignKey, primaryKeyValues);
-  qb = applyScopes(qb, scopeContext, relatedModel);
-  const relatedRecords = await qb;
+  const relatedRecords = await queryInChunks(
+    knex,
+    relatedModel.table,
+    foreignKey,
+    primaryKeyValues,
+    scopeContext,
+    relatedModel
+  );
 
   const relatedGroups = new Map();
   const rLen = relatedRecords.length;
@@ -181,9 +220,14 @@ async function loadHasOne(records, relationName, localKey, foreignKey, relatedMo
   }
 
   const primaryKeyValues = Array.from(pkSet);
-  let qb = knex(relatedModel.table).whereIn(foreignKey, primaryKeyValues);
-  qb = applyScopes(qb, scopeContext, relatedModel);
-  const relatedRecords = await qb;
+  const relatedRecords = await queryInChunks(
+    knex,
+    relatedModel.table,
+    foreignKey,
+    primaryKeyValues,
+    scopeContext,
+    relatedModel
+  );
 
   const relatedMap = new Map();
   const rLen = relatedRecords.length;
@@ -222,5 +266,6 @@ module.exports = {
   loadBelongsTo,
   loadHasMany,
   loadHasOne,
+  queryInChunks,
 };
 

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
@@ -66,10 +74,46 @@ function createDatabase(config) {
     }
   }
 
-  // Create Knex instance
+  // Create Knex instance (default useNullAsDefault: true for SQLite to prevent unneeded warnings)
+  const isSqlite = client === 'better-sqlite3' || client === 'sqlite3';
+  const knexConfig = {
+    ...(isSqlite && config.useNullAsDefault === undefined ? { useNullAsDefault: true } : {}),
+    ...config,
+  };
+
+  if (isSqlite) {
+    const userAfterCreate = knexConfig.pool?.afterCreate;
+    knexConfig.pool = {
+      ...(knexConfig.pool || {}),
+      afterCreate: (conn, cb) => {
+        try {
+          if (typeof conn.pragma === 'function') {
+            const isMemory =
+              knexConfig.connection === ':memory:' ||
+              knexConfig.connection?.filename === ':memory:' ||
+              knexConfig.connection?.database === ':memory:';
+
+            if (!isMemory) {
+              try { conn.pragma('journal_mode = WAL'); } catch (e) {}
+            }
+            try { conn.pragma('synchronous = NORMAL'); } catch (e) {}
+            try { conn.pragma('busy_timeout = 5000'); } catch (e) {}
+            try { conn.pragma('foreign_keys = ON'); } catch (e) {}
+          }
+        } catch (e) {}
+
+        if (typeof userAfterCreate === 'function') {
+          userAfterCreate(conn, cb);
+        } else {
+          cb(null, conn);
+        }
+      },
+    };
+  }
+
   let knexInstance;
   try {
-    knexInstance = knex(config);
+    knexInstance = knex(knexConfig);
   } catch (e) {
     // Provide helpful error message
     if (e.message && (e.message.includes('Cannot find module') || e.message.includes('npm install'))) {
@@ -128,10 +172,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 +269,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 +311,9 @@ function createDatabase(config) {
     createRepository: createRepositoryFromModel,
     query,
     transaction,
+    runInTransaction: transaction,
+    getAmbientTransaction,
+    hasActiveTransaction: hasAmbientTransaction,
     createSeeder: createSeederInstance,
     cache: ormCachePublicApi,
     destroy: () => {
@@ -275,6 +334,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 +364,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;
 
@@ -45,13 +46,22 @@ function defineModel(options) {
     throw new Error('Model schema is required and must be a Zod schema');
   }
 
+  let normalizedSchema = schema;
+  if (schema && schema.shape) {
+    for (const [key, val] of Object.entries(schema.shape)) {
+      if (val && typeof val._finalize === 'function') {
+        schema.shape[key] = val._finalize();
+      }
+    }
+  }
+
   // Check for duplicate registration
   if (modelRegistry.has(name)) {
     throw new Error(`Model "${name}" is already defined`);
   }
 
   // Extract column metadata from schema
-  const columns = extractColumnsFromSchema(schema);
+  const columns = extractColumnsFromSchema(normalizedSchema);
 
   // Validate relations
   const normalizedRelations = {};
@@ -79,7 +89,7 @@ function defineModel(options) {
   const model = {
     name,
     table,
-    schema,
+    schema: normalizedSchema,
     primaryKey,
     relations: normalizedRelations,
     scopes: {
@@ -105,6 +115,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;