webspresso 0.0.90 → 0.0.93

package/core/orm/repository.js

@@ -16,6 +16,7 @@ const {
 const { ensureArray } = require('./utils');
 const { ModelEvents, createEventContext, Hooks, HookCancellationError } = require('./events');
 const { getJsonColumns, serializeJsonFields, deserializeJsonFields } = require('./json-fields');
+const { getAmbientTransaction } = require('./transaction');
 
 /**
  * Create a repository for a model
@@ -30,12 +31,37 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
   const jsonColumns = getJsonColumns(model);
   const hasJson = jsonColumns.size > 0;
 
+  /**
+   * Resolve active Knex instance (explicit or ambient transaction)
+   * @returns {import('knex').Knex|import('knex').Knex.Transaction}
+   */
+  function getActiveKnex() {
+    if (knex && (knex.isTransaction || typeof knex.commit === 'function')) {
+      return knex;
+    }
+    const ambientTrx = getAmbientTransaction();
+    if (ambientTrx) {
+      return ambientTrx;
+    }
+    return knex;
+  }
+
+  /**
+   * Get transaction handle for lifecycle hooks
+   * @returns {import('knex').Knex.Transaction|null}
+   */
+  function getHookTrx() {
+    const active = getActiveKnex();
+    return (active && (active.isTransaction || typeof active.commit === 'function')) ? active : null;
+  }
+
   /**
    * Get base query builder
    * @returns {import('knex').Knex.QueryBuilder}
    */
   function baseQuery() {
-    let qb = knex(model.table);
+    const activeKnex = getActiveKnex();
+    let qb = activeKnex(model.table);
     return applyScopes(qb, scopeContext, model);
   }
 
@@ -79,7 +105,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
       }
 
       if (withs.length > 0) {
-        await loadRelations([record], ensureArray(withs), model, knex, scopeContext);
+        await loadRelations([record], ensureArray(withs), model, getActiveKnex(), scopeContext);
       }
 
       if (shouldEmit) {
@@ -105,7 +131,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
         kind,
         kind === 'pk' ? id : null
       );
-      return cacheLayer.wrapRead(model, knex, scopeContext, fingerprint, tags, loadFromDb, (r) => r != null);
+      return cacheLayer.wrapRead(model, getActiveKnex(), scopeContext, fingerprint, tags, loadFromDb, (r) => r != null);
     }
 
     return loadFromDb();
@@ -160,7 +186,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
       }
 
       if (withs.length > 0) {
-        await loadRelations([record], ensureArray(withs), model, knex, scopeContext);
+        await loadRelations([record], ensureArray(withs), model, getActiveKnex(), scopeContext);
       }
 
       if (shouldEmit) {
@@ -172,7 +198,18 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
 
     if (cacheLayer && cacheLayer.strategyFor(model)) {
       const strat = cacheLayer.strategyFor(model);
-      const kind = isPkOnly ? 'pk' : 'collection';
+      if (isPkOnly) {
+        const pkVal = conditions[model.primaryKey];
+        const fingerprint = cacheLayer.findByIdFingerprint(
+          model,
+          scopeContext,
+          pkVal,
+          select || [],
+          withs
+        );
+        const tags = cacheLayer.buildReadTags(model, strat, 'pk', pkVal);
+        return cacheLayer.wrapRead(model, getActiveKnex(), scopeContext, fingerprint, tags, loadFromDb, (r) => r != null);
+      }
       const fingerprint = cacheLayer.findOneFingerprint(
         model,
         scopeContext,
@@ -180,20 +217,15 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
         select || [],
         withs
       );
-      const tags = cacheLayer.buildReadTags(
-        model,
-        strat,
-        kind,
-        kind === 'pk' ? conditions[model.primaryKey] : null
-      );
-      return cacheLayer.wrapRead(model, knex, scopeContext, fingerprint, tags, loadFromDb, (r) => r != null);
+      const tags = cacheLayer.buildReadTags(model, strat, 'collection', null);
+      return cacheLayer.wrapRead(model, getActiveKnex(), scopeContext, fingerprint, tags, loadFromDb, (r) => r != null);
     }
 
     return loadFromDb();
   }
 
   /**
-   * Find all records
+   * Find all records matching scope
    * @param {import('./types').FindOptions} [options={}] - Find options
    * @returns {Promise<Object[]>}
    */
@@ -229,7 +261,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
       }
 
       if (withs.length > 0 && records.length > 0) {
-        await loadRelations(records, ensureArray(withs), model, knex, scopeContext);
+        await loadRelations(records, ensureArray(withs), model, getActiveKnex(), scopeContext);
       }
 
       if (shouldEmit) {
@@ -246,7 +278,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
       const strat = cacheLayer.strategyFor(model);
       const fingerprint = cacheLayer.findAllFingerprint(model, scopeContext, select || []);
       const tags = cacheLayer.buildReadTags(model, strat, 'collection', null);
-      return cacheLayer.wrapRead(model, knex, scopeContext, fingerprint, tags, loadFromDb, () => true);
+      return cacheLayer.wrapRead(model, getActiveKnex(), scopeContext, fingerprint, tags, loadFromDb, () => true);
     }
 
     return loadFromDb();
@@ -258,7 +290,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
    * @returns {Promise<Object>}
    */
   async function create(data) {
-    const ctx = createEventContext(model.name, 'create', knex.isTransaction ? knex : null);
+    const ctx = createEventContext(model.name, 'create', getHookTrx());
     let workingData = { ...data };
 
     // Emit beforeValidation
@@ -294,7 +326,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
     }
 
     // Insert and return the record
-    const [id] = await knex(model.table).insert(insertData).returning(model.primaryKey);
+    const [id] = await getActiveKnex()(model.table).insert(insertData).returning(model.primaryKey);
 
     // For databases that don't support returning (SQLite), id might be the row itself
     const insertedId = typeof id === 'object' ? id[model.primaryKey] : id;
@@ -334,7 +366,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
    * @returns {Promise<Object|null>}
    */
   async function update(id, data) {
-    const ctx = createEventContext(model.name, 'update', knex.isTransaction ? knex : null);
+    const ctx = createEventContext(model.name, 'update', getHookTrx());
     // Don't include primary key in working data for validation
     // to avoid type mismatch issues (URL params come as strings)
     let workingData = { ...data };
@@ -431,7 +463,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
    * @returns {Promise<boolean>}
    */
   async function del(id) {
-    const ctx = createEventContext(model.name, 'delete', knex.isTransaction ? knex : null);
+    const ctx = createEventContext(model.name, 'delete', getHookTrx());
     
     // Get the record before deletion for hooks
     const record = await findById(id);
@@ -476,7 +508,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
    */
   async function forceDelete(id) {
     // Use raw query to bypass soft delete scope
-    const deleted = await knex(model.table)
+    const deleted = await getActiveKnex()(model.table)
       .where(model.primaryKey, id)
       .delete();
     if (cacheLayer && deleted > 0) {
@@ -495,10 +527,10 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
       throw new Error(`Model "${model.name}" does not have soft delete enabled`);
     }
 
-    const ctx = createEventContext(model.name, 'restore', knex.isTransaction ? knex : null);
+    const ctx = createEventContext(model.name, 'restore', getHookTrx());
 
     // Get the trashed record for hooks (bypass soft delete scope)
-    const trashedRecord = await knex(model.table)
+    const trashedRecord = await getActiveKnex()(model.table)
       .where(model.primaryKey, id)
       .whereNotNull('deleted_at')
       .first();
@@ -514,7 +546,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
     }
 
     // Update directly without scopes (to find trashed record)
-    const updated = await knex(model.table)
+    const updated = await getActiveKnex()(model.table)
       .where(model.primaryKey, id)
       .whereNotNull('deleted_at')
       .update({ deleted_at: null });
@@ -536,7 +568,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
    * @returns {import('./query-builder').QueryBuilder}
    */
   function query() {
-    return createQueryBuilder(model, knex, scopeContext, cacheLayer);
+    return createQueryBuilder(model, getActiveKnex(), scopeContext, cacheLayer);
   }
 
   /**
@@ -546,7 +578,7 @@ function createRepository(model, knex, initialContext, cacheLayer = null) {
    * @returns {Promise<Object[]>}
    */
   async function raw(sql, bindings = []) {
-    const result = await knex.raw(sql, bindings);
+    const result = await getActiveKnex().raw(sql, bindings);
     // Normalize result across database drivers
     return result.rows || result;
   }

package/core/orm/transaction.js

@@ -1,12 +1,42 @@
 /**
  * Webspresso ORM - Transaction
- * Transaction wrapper with scoped repositories
+ * Transaction wrapper with scoped repositories and AsyncLocalStorage ambient transaction support
  * @module core/orm/transaction
  */
 
-const { createRepository } = require('./repository');
+const { AsyncLocalStorage } = require('async_hooks');
 const { createScopeContext } = require('./scopes');
 
+// AsyncLocalStorage instance holding the current active ambient transaction
+const ambientTransactionStorage = new AsyncLocalStorage();
+
+/**
+ * Execute a callback within an ambient transaction context
+ * @param {import('knex').Knex.Transaction} trx - Knex transaction
+ * @param {Function} callback - Function to execute
+ * @returns {Promise<*>} Result of callback
+ */
+function runWithAmbientTransaction(trx, callback) {
+  return ambientTransactionStorage.run({ trx }, callback);
+}
+
+/**
+ * Get the currently active ambient Knex transaction, or null if none
+ * @returns {import('knex').Knex.Transaction|null}
+ */
+function getAmbientTransaction() {
+  const store = ambientTransactionStorage.getStore();
+  return store && store.trx ? store.trx : null;
+}
+
+/**
+ * Check if there is an active ambient Knex transaction in current execution context
+ * @returns {boolean}
+ */
+function hasAmbientTransaction() {
+  return Boolean(getAmbientTransaction());
+}
+
 /**
  * Create a transaction context
  * @param {import('knex').Knex.Transaction} trx - Knex transaction
@@ -14,6 +44,7 @@ const { createScopeContext } = require('./scopes');
  * @returns {import('./types').TransactionContext}
  */
 function createTransactionContext(trx, scopeContext) {
+  const { createRepository } = require('./repository');
   const context = scopeContext || createScopeContext();
 
   return {
@@ -49,7 +80,7 @@ function createTransactionContext(trx, scopeContext) {
 }
 
 /**
- * Run a callback within a transaction
+ * Run a callback within a transaction and bind ambient transaction storage
  * @param {import('knex').Knex} knex - Knex instance
  * @param {function(import('./types').TransactionContext): Promise<*>} callback - Transaction callback
  * @param {import('./types').ScopeContext} [scopeContext] - Scope context
@@ -58,12 +89,15 @@ function createTransactionContext(trx, scopeContext) {
 async function runTransaction(knex, callback, scopeContext) {
   return knex.transaction(async (trx) => {
     const ctx = createTransactionContext(trx, scopeContext);
-    return callback(ctx);
+    return runWithAmbientTransaction(trx, () => callback(ctx));
   });
 }
 
 module.exports = {
+  ambientTransactionStorage,
+  runWithAmbientTransaction,
+  getAmbientTransaction,
+  hasAmbientTransaction,
   createTransactionContext,
   runTransaction,
 };
-

package/core/orm/utils.js

@@ -107,11 +107,14 @@ function deepClone(obj) {
   if (Array.isArray(obj)) {
     return obj.map(deepClone);
   }
-  const cloned = {};
-  for (const key in obj) {
+  const cloned = Object.create(null);
+  for (const key of Object.keys(obj)) {
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+      continue;
+    }
     cloned[key] = deepClone(obj[key]);
   }
-  return cloned;
+  return { ...cloned };
 }
 
 /**

package/core/queue/adapters/database.js

@@ -0,0 +1,317 @@
+/**
+ * Knex Database-Backed Queue Adapter
+ * @module core/queue/adapters/database
+ */
+
+'use strict';
+
+const { Job } = require('../job');
+
+class DatabaseQueueAdapter {
+  /**
+   * @param {Object} options
+   * @param {import('knex').Knex} options.knex - Knex instance
+   * @param {string} [options.tableName='webspresso_jobs'] - Queue table name
+   */
+  constructor(options = {}) {
+    if (!options.knex) {
+      throw new Error('DatabaseQueueAdapter requires a Knex instance in options.knex');
+    }
+    this.knex = options.knex;
+    this.tableName = options.tableName || 'webspresso_jobs';
+    this._tableChecked = false;
+  }
+
+  /**
+   * Ensure the jobs table exists in the database
+   */
+  async ensureTable() {
+    if (this._tableChecked) return;
+
+    const exists = await this.knex.schema.hasTable(this.tableName);
+    if (!exists) {
+      await this.knex.schema.createTable(this.tableName, (table) => {
+        table.string('id').primary();
+        table.string('name').notNullable().index();
+        table.text('data').nullable();
+        table.string('status').notNullable().defaultTo('pending').index();
+        table.integer('attempts').notNullable().defaultTo(0);
+        table.integer('max_attempts').notNullable().defaultTo(3);
+        table.text('backoff').nullable();
+        table.integer('priority').notNullable().defaultTo(10);
+        table.integer('timeout').notNullable().defaultTo(30000);
+        table.integer('progress').notNullable().defaultTo(0);
+        table.text('result').nullable();
+        table.text('error').nullable();
+        table.dateTime('run_at').notNullable().index();
+        table.dateTime('created_at').notNullable();
+        table.dateTime('updated_at').notNullable();
+        table.index(['status', 'run_at', 'priority']);
+      });
+    }
+
+    this._tableChecked = true;
+  }
+
+  /**
+   * Enqueue a job into the database
+   * @param {Job} job
+   * @returns {Promise<Job>}
+   */
+  async enqueue(job) {
+    await this.ensureTable();
+    const jobInstance = job instanceof Job ? job : new Job(job);
+
+    await this.knex(this.tableName).insert({
+      id: String(jobInstance.id),
+      name: jobInstance.name,
+      data: JSON.stringify(jobInstance.data),
+      status: jobInstance.status,
+      attempts: jobInstance.attempts,
+      max_attempts: jobInstance.maxAttempts,
+      backoff: JSON.stringify(jobInstance.backoff),
+      priority: jobInstance.priority,
+      timeout: jobInstance.timeout,
+      progress: jobInstance.progressValue,
+      result: jobInstance.result ? JSON.stringify(jobInstance.result) : null,
+      error: jobInstance.error ? (jobInstance.error.message || String(jobInstance.error)) : null,
+      run_at: jobInstance.runAt,
+      created_at: jobInstance.createdAt,
+      updated_at: jobInstance.updatedAt,
+    });
+
+    return jobInstance;
+  }
+
+  /**
+   * Dequeue next pending job
+   * @param {string[]} [jobNames]
+   * @returns {Promise<Job|null>}
+   */
+  async dequeue(jobNames = []) {
+    const jobs = await this.dequeueMany(jobNames, 1);
+    return jobs.length > 0 ? jobs[0] : null;
+  }
+
+  /**
+   * Dequeue multiple pending jobs up to limit in a single transaction
+   * @param {string[]} [jobNames]
+   * @param {number} [limit=1]
+   * @returns {Promise<Job[]>}
+   */
+  async dequeueMany(jobNames = [], limit = 1) {
+    await this.ensureTable();
+    const now = new Date();
+    const take = Math.max(1, limit || 1);
+
+    return this.knex.transaction(async (trx) => {
+      let query = trx(this.tableName)
+        .where('status', 'pending')
+        .where('run_at', '<=', now)
+        .orderBy('priority', 'desc')
+        .orderBy('run_at', 'asc')
+        .limit(take);
+
+      if (jobNames && jobNames.length > 0) {
+        query = query.whereIn('name', jobNames);
+      }
+
+      // If Postgres or MySQL support forUpdate / skipLocked
+      const client = this.knex.client?.config?.client;
+      if (client === 'pg' || client === 'postgres' || client === 'mysql' || client === 'mysql2') {
+        try {
+          query = query.forUpdate().skipLocked();
+        } catch {}
+      }
+
+      const rows = await query;
+      if (!rows || rows.length === 0) return [];
+
+      const ids = rows.map((r) => r.id);
+      const updatedAt = new Date();
+
+      if (take === 1) {
+        const row = rows[0];
+        const nextAttempts = Number(row.attempts) + 1;
+        await trx(this.tableName)
+          .where('id', row.id)
+          .update({
+            status: 'running',
+            attempts: nextAttempts,
+            updated_at: updatedAt,
+          });
+
+        return [this._rowToJob({
+          ...row,
+          status: 'running',
+          attempts: nextAttempts,
+          updated_at: updatedAt,
+        })];
+      }
+
+      await trx(this.tableName)
+        .whereIn('id', ids)
+        .update({
+          status: 'running',
+          attempts: trx.raw('attempts + 1'),
+          updated_at: updatedAt,
+        });
+
+      return rows.map((row) =>
+        this._rowToJob({
+          ...row,
+          status: 'running',
+          attempts: Number(row.attempts) + 1,
+          updated_at: updatedAt,
+        })
+      );
+    });
+  }
+
+  /**
+   * Mark job as completed
+   * @param {string|number} jobId
+   * @param {any} [result]
+   * @returns {Promise<Job|null>}
+   */
+  async complete(jobId, result = null) {
+    await this.ensureTable();
+    const updatedAt = new Date();
+    await this.knex(this.tableName)
+      .where('id', String(jobId))
+      .update({
+        status: 'completed',
+        result: result !== undefined ? JSON.stringify(result) : null,
+        progress: 100,
+        updated_at: updatedAt,
+      });
+
+    return this.getJob(jobId);
+  }
+
+  /**
+   * Mark job as failed
+   * @param {string|number} jobId
+   * @param {any} [error]
+   * @returns {Promise<Job|null>}
+   */
+  async fail(jobId, error = null) {
+    await this.ensureTable();
+    const updatedAt = new Date();
+    const errorStr = error ? (error.message || String(error)) : null;
+
+    await this.knex(this.tableName)
+      .where('id', String(jobId))
+      .update({
+        status: 'failed',
+        error: errorStr,
+        updated_at: updatedAt,
+      });
+
+    return this.getJob(jobId);
+  }
+
+  /**
+   * Reschedule job for retry
+   * @param {string|number} jobId
+   * @param {number} delayMs
+   * @param {any} [error]
+   * @returns {Promise<Job|null>}
+   */
+  async retry(jobId, delayMs, error = null) {
+    await this.ensureTable();
+    const updatedAt = new Date();
+    const runAt = new Date(Date.now() + Math.max(0, delayMs));
+    const errorStr = error ? (error.message || String(error)) : null;
+
+    await this.knex(this.tableName)
+      .where('id', String(jobId))
+      .update({
+        status: 'pending',
+        run_at: runAt,
+        error: errorStr,
+        updated_at: updatedAt,
+      });
+
+    return this.getJob(jobId);
+  }
+
+  /**
+   * Get job by ID
+   * @param {string|number} jobId
+   * @returns {Promise<Job|null>}
+   */
+  async getJob(jobId) {
+    await this.ensureTable();
+    const row = await this.knex(this.tableName).where('id', String(jobId)).first();
+    if (!row) return null;
+    return this._rowToJob(row);
+  }
+
+  /**
+   * Get stats summary
+   * @returns {Promise<{ pending: number, running: number, completed: number, failed: number, total: number }>}
+   */
+  async getStats() {
+    await this.ensureTable();
+    const rows = await this.knex(this.tableName)
+      .select('status')
+      .count('* as count')
+      .groupBy('status');
+
+    const stats = { pending: 0, running: 0, completed: 0, failed: 0, total: 0 };
+    for (const r of rows) {
+      const count = Number(r.count || r.COUNT || 0);
+      if (r.status in stats) {
+        stats[r.status] = count;
+      }
+      stats.total += count;
+    }
+
+    return stats;
+  }
+
+  /**
+   * Clear all jobs from table
+   * @returns {Promise<void>}
+   */
+  async clear() {
+    await this.ensureTable();
+    await this.knex(this.tableName).del();
+  }
+
+  /**
+   * Convert DB row to Job instance
+   * @private
+   */
+  _rowToJob(row) {
+    let data = {};
+    try { data = JSON.parse(row.data); } catch {}
+
+    let backoff = { type: 'exponential', delay: 1000 };
+    try { if (row.backoff) backoff = JSON.parse(row.backoff); } catch {}
+
+    let result = null;
+    try { if (row.result) result = JSON.parse(row.result); } catch {}
+
+    return new Job({
+      id: row.id,
+      name: row.name,
+      data,
+      status: row.status,
+      attempts: Number(row.attempts),
+      maxAttempts: Number(row.max_attempts),
+      backoff,
+      priority: Number(row.priority),
+      timeout: Number(row.timeout),
+      progress: Number(row.progress),
+      result,
+      error: row.error,
+      runAt: row.run_at,
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+    });
+  }
+}
+
+module.exports = { DatabaseQueueAdapter };