webspresso 0.0.107 → 0.0.108

package/core/context/request.js

@@ -0,0 +1,241 @@
+'use strict';
+
+/**
+ * Webspresso Ambient Request & Execution Context
+ * Zero-dependency execution context powered by Node.js AsyncLocalStorage.
+ * Provides composable hooks (useContext, useDb, useAuth, useUser, useLogger, useService,
+ * useReq, useRes, useParams, useQuery, useQueue, useCache, useBreaker, useTransaction, withContext)
+ * across loaders, services, models, and background workers without prop drilling.
+ *
+ * @module core/context/request
+ */
+
+const { AsyncLocalStorage } = require('async_hooks');
+
+const requestContextStorage = new AsyncLocalStorage();
+
+/**
+ * Runs a callback within an ambient request or execution context
+ * @param {Object} context - Execution context payload
+ * @param {Function} fn - Function to execute within context
+ * @returns {*} Return value of fn
+ */
+function runWithContext(context, fn) {
+  return requestContextStorage.run(context || {}, fn);
+}
+
+/**
+ * Run a callback with shallow-merged overrides on top of the current ambient context
+ * @param {Object} overrides - Object containing fields to override in current context
+ * @param {Function} fn - Function to execute
+ * @returns {*} Return value of fn
+ */
+function withContext(overrides, fn) {
+  const current = requestContextStorage.getStore() || {};
+  const merged = { ...current, ...(overrides || {}) };
+  return requestContextStorage.run(merged, fn);
+}
+
+/**
+ * Get the current active ambient context (returns null if outside context)
+ * @returns {Object|null}
+ */
+function getContext() {
+  return requestContextStorage.getStore() || null;
+}
+
+/**
+ * Hook to access the ambient execution context
+ * @returns {Object} Active context object
+ * @throws {Error} If called outside of an active execution context
+ */
+function useContext() {
+  const store = requestContextStorage.getStore();
+  if (!store) {
+    throw new Error('useContext() must be called within an active request, job, or execution context.');
+  }
+  return store;
+}
+
+/**
+ * Hook to access the ambient database instance
+ * @returns {Object|null} Database / ORM instance or null
+ */
+function useDb() {
+  const store = requestContextStorage.getStore();
+  return store?.db || store?.req?.db || null;
+}
+
+/**
+ * Hook to access the ambient authenticated user / principal
+ * @returns {Object|null} User / Auth object or null
+ */
+function useAuth() {
+  const store = requestContextStorage.getStore();
+  return (
+    store?.user ||
+    store?.auth?.user ||
+    store?.auth ||
+    store?.req?.user ||
+    store?.req?.auth?.user ||
+    store?.req?.auth ||
+    null
+  );
+}
+
+/**
+ * Hook to access the ambient authenticated user
+ * Alias / dedicated helper for useAuth()
+ * @returns {Object|null} User object or null
+ */
+function useUser() {
+  return useAuth();
+}
+
+/**
+ * Hook to access the ambient logger
+ * @returns {Object} Logger instance
+ */
+function useLogger() {
+  const store = requestContextStorage.getStore();
+  return store?.logger || store?.req?.logger || console;
+}
+
+/**
+ * Hook to access the ambient HTTP request object
+ * @returns {Object|null} Express/Hono request object or null if outside HTTP request
+ */
+function useReq() {
+  const store = requestContextStorage.getStore();
+  return store?.req || null;
+}
+
+/**
+ * Hook to access the ambient HTTP response object
+ * @returns {Object|null} Express/Hono response object or null if outside HTTP request
+ */
+function useRes() {
+  const store = requestContextStorage.getStore();
+  return store?.res || null;
+}
+
+/**
+ * Hook to access the ambient route parameters
+ * @returns {Object} Route parameters map (e.g. { id: '123' })
+ */
+function useParams() {
+  const store = requestContextStorage.getStore();
+  return store?.params || store?.req?.params || {};
+}
+
+/**
+ * Hook to access the ambient URL query parameters
+ * @returns {Object} URL query parameters map
+ */
+function useQuery() {
+  const store = requestContextStorage.getStore();
+  return store?.query || store?.req?.query || {};
+}
+
+/**
+ * Hook to invoke a registered service using the ambient context
+ * @param {string} name - Service name (e.g. 'user.get')
+ * @param {*} [input={}] - Input payload
+ * @param {Object} [opts] - Optional execution options
+ * @returns {Promise<*>}
+ */
+async function useService(name, input = {}, opts) {
+  const store = requestContextStorage.getStore();
+  if (store?.service && typeof store.service === 'function') {
+    return store.service(name, input, opts);
+  }
+  if (store?.req?.service && typeof store.req.service === 'function') {
+    return store.req.service(name, input, opts);
+  }
+  throw new Error(`useService() failed: no service registry available in active context.`);
+}
+
+/**
+ * Hook to access the ambient background queue
+ * @returns {Object|null}
+ */
+function useQueue() {
+  const store = requestContextStorage.getStore();
+  return store?.queue || store?.req?.queue || null;
+}
+
+/**
+ * Hook to access the ambient cache
+ * @returns {Object|null}
+ */
+function useCache() {
+  const store = requestContextStorage.getStore();
+  return store?.cache || store?.req?.cache || null;
+}
+
+/**
+ * Hook to access or create a circuit breaker by name
+ * @param {string} name - Circuit breaker name
+ * @param {Object} [options] - Circuit breaker options
+ * @returns {Object|null} CircuitBreaker instance or null
+ */
+function useBreaker(name, options) {
+  const store = requestContextStorage.getStore();
+  if (store?.breaker && typeof store.breaker === 'function') {
+    return store.breaker(name, options);
+  }
+  if (store?.req?.breaker && typeof store.req.breaker === 'function') {
+    return store.req.breaker(name, options);
+  }
+  try {
+    const { circuitBreakerRegistry } = require('../resilience');
+    return circuitBreakerRegistry.getBreaker(name, options);
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Hook to execute a callback within a managed transaction on the ambient database
+ * Automatically binds transactional context to ambient hooks inside the callback.
+ * @param {function(trx: any): Promise<*>} callback - Transaction callback
+ * @returns {Promise<*>} Result of callback
+ */
+async function useTransaction(callback) {
+  const db = useDb();
+  if (!db) {
+    throw new Error('useTransaction() failed: no database instance available in active context.');
+  }
+
+  if (typeof db.transaction === 'function') {
+    return db.transaction(async (trx) => {
+      const current = requestContextStorage.getStore() || {};
+      const txDb = trx.db || trx;
+      const txCtx = { ...current, db: txDb, trx: trx.trx || trx };
+      return requestContextStorage.run(txCtx, () => callback(trx));
+    });
+  }
+
+  throw new Error('useTransaction() failed: db does not support transaction().');
+}
+
+module.exports = {
+  requestContextStorage,
+  runWithContext,
+  withContext,
+  getContext,
+  useContext,
+  useDb,
+  useAuth,
+  useUser,
+  useLogger,
+  useReq,
+  useRes,
+  useParams,
+  useQuery,
+  useService,
+  useQueue,
+  useCache,
+  useBreaker,
+  useTransaction,
+};

package/core/events/dispatcher.js

@@ -324,7 +324,7 @@ class EventDispatcher extends EventEmitter {
       } catch (err) {
         // Emit error on dispatcher or log
         if (this.listenerCount('error') > 0) {
-          super.emit('error', err);
+          this.emit('error', err);
         } else if (this.logger && typeof this.logger.error === 'function') {
           this.logger.error(`[EventDispatcher] Error in listener for event "${event}":`, err);
         }
@@ -355,10 +355,19 @@ class EventDispatcher extends EventEmitter {
     const meta = { event, sender, timestamp: Date.now() };
 
     const promises = listeners.map(async (listener) => {
-      if (listener.isAny) {
-        return listener.handler(event, payload, meta);
+      try {
+        if (listener.isAny) {
+          return await listener.handler(event, payload, meta);
+        }
+        return await listener.handler(payload, meta);
+      } catch (err) {
+        if (this.listenerCount('error') > 0) {
+          this.emit('error', err);
+        } else if (this.logger && typeof this.logger.error === 'function') {
+          this.logger.error(`[EventDispatcher] Error in async listener for event "${event}":`, err);
+        }
+        throw err;
       }
-      return listener.handler(payload, meta);
     });
 
     return Promise.allSettled(promises);
@@ -399,10 +408,19 @@ class EventDispatcher extends EventEmitter {
     const results = [];
 
     for (const listener of listeners) {
-      const res = listener.isAny
-        ? await listener.handler(event, payload, meta)
-        : await listener.handler(payload, meta);
-      results.push(res);
+      try {
+        const res = listener.isAny
+          ? await listener.handler(event, payload, meta)
+          : await listener.handler(payload, meta);
+        results.push(res);
+      } catch (err) {
+        if (this.listenerCount('error') > 0) {
+          this.emit('error', err);
+        } else if (this.logger && typeof this.logger.error === 'function') {
+          this.logger.error(`[EventDispatcher] Error in serial listener for event "${event}":`, err);
+        }
+        throw err;
+      }
     }
 
     return results;
@@ -429,18 +447,113 @@ class EventDispatcher extends EventEmitter {
     let currentData = payload;
 
     for (const listener of listeners) {
-      const res = listener.isAny
-        ? await listener.handler(event, currentData, meta)
-        : await listener.handler(currentData, meta);
+      try {
+        const res = listener.isAny
+          ? await listener.handler(event, currentData, meta)
+          : await listener.handler(currentData, meta);
 
-      if (res !== undefined) {
-        currentData = res;
+        if (res !== undefined) {
+          currentData = res;
+        }
+      } catch (err) {
+        if (this.listenerCount('error') > 0) {
+          this.emit('error', err);
+        } else if (this.logger && typeof this.logger.error === 'function') {
+          this.logger.error(`[EventDispatcher] Error in waterfall listener for event "${event}":`, err);
+        }
+        throw err;
       }
     }
 
     return currentData;
   }
 
+  /**
+   * Asynchronously wait for a matching event to be emitted
+   * @param {string} event - Event name or pattern
+   * @param {Object|number|Function} [optionsOrTimeout=5000] - Timeout in ms, predicate, or options
+   * @param {number} [optionsOrTimeout.timeout=5000] - Timeout in ms (0 for indefinite)
+   * @param {Function} [optionsOrTimeout.filter] - Predicate (data, meta) => boolean
+   * @param {AbortSignal} [optionsOrTimeout.signal] - AbortSignal for cancellation
+   * @param {any} [optionsOrTimeout.sender] - Filter by sender
+   * @returns {Promise<{ data: any, meta: Object }>}
+   */
+  waitFor(event, optionsOrTimeout = {}) {
+    let timeoutMs = 5000;
+    let filter = null;
+    let signal = null;
+    let sender = undefined;
+
+    if (typeof optionsOrTimeout === 'number') {
+      timeoutMs = optionsOrTimeout;
+    } else if (typeof optionsOrTimeout === 'function') {
+      filter = optionsOrTimeout;
+    } else if (typeof optionsOrTimeout === 'object' && optionsOrTimeout !== null) {
+      if (optionsOrTimeout.timeout !== undefined) timeoutMs = optionsOrTimeout.timeout;
+      if (typeof optionsOrTimeout.filter === 'function') filter = optionsOrTimeout.filter;
+      if (optionsOrTimeout.signal) signal = optionsOrTimeout.signal;
+      if (optionsOrTimeout.sender !== undefined) sender = optionsOrTimeout.sender;
+    }
+
+    return new Promise((resolve, reject) => {
+      if (signal && signal.aborted) {
+        return reject(new Error(`waitFor('${event}') aborted before execution`));
+      }
+
+      let timeoutTimer = null;
+      let unsubscribe = null;
+      let abortHandler = null;
+
+      const cleanup = () => {
+        if (timeoutTimer) {
+          clearTimeout(timeoutTimer);
+          timeoutTimer = null;
+        }
+        if (typeof unsubscribe === 'function') {
+          unsubscribe();
+          unsubscribe = null;
+        }
+        if (signal && abortHandler) {
+          signal.removeEventListener('abort', abortHandler);
+          abortHandler = null;
+        }
+      };
+
+      if (timeoutMs > 0) {
+        timeoutTimer = setTimeout(() => {
+          cleanup();
+          reject(new Error(`Timeout of ${timeoutMs}ms exceeded while waiting for event '${event}'`));
+        }, timeoutMs);
+        if (timeoutTimer && typeof timeoutTimer.unref === 'function') {
+          timeoutTimer.unref();
+        }
+      }
+
+      if (signal) {
+        abortHandler = () => {
+          cleanup();
+          reject(new Error(`waitFor('${event}') was aborted`));
+        };
+        signal.addEventListener('abort', abortHandler, { once: true });
+      }
+
+      const handler = (data, meta) => {
+        try {
+          if (filter && !filter(data, meta)) {
+            return;
+          }
+          cleanup();
+          resolve({ data, meta });
+        } catch (err) {
+          cleanup();
+          reject(err);
+        }
+      };
+
+      unsubscribe = this.on(event, handler, { sender });
+    });
+  }
+
   /**
    * Set or update background queue manager for job dispatching
    * @param {any} queueManager
@@ -462,11 +575,27 @@ class EventDispatcher extends EventEmitter {
   listenAndQueue(event, jobName, queueOptions = {}) {
     return this.on(event, (data) => {
       if (!this.queue || typeof this.queue.dispatch !== 'function') {
-        throw new Error(
+        const err = new Error(
           `[EventDispatcher] Cannot queue job '${jobName}' for event '${event}'. No QueueManager is attached.`
         );
+        if (this.listenerCount('error') > 0) {
+          this.emit('error', err);
+        } else if (this.logger && typeof this.logger.error === 'function') {
+          this.logger.error(err.message);
+        }
+        return Promise.reject(err);
+      }
+      const dispatchPromise = this.queue.dispatch(jobName, data, queueOptions);
+      if (dispatchPromise && typeof dispatchPromise.catch === 'function') {
+        dispatchPromise.catch((dispatchErr) => {
+          if (this.listenerCount('error') > 0) {
+            this.emit('error', dispatchErr);
+          } else if (this.logger && typeof this.logger.error === 'function') {
+            this.logger.error(`[EventDispatcher] Failed to dispatch queued job '${jobName}':`, dispatchErr);
+          }
+        });
       }
-      return this.queue.dispatch(jobName, data, queueOptions);
+      return dispatchPromise;
     });
   }
 

package/core/events/signal.js

@@ -79,6 +79,15 @@ class Signal {
   async dispatch(data, options = {}) {
     return this.sendAsync(data, options);
   }
+
+  /**
+   * Asynchronously wait for this signal to be emitted
+   * @param {Object|number|Function} [optionsOrTimeout]
+   * @returns {Promise<{ data: any, meta: Object }>}
+   */
+  waitFor(optionsOrTimeout) {
+    return this.dispatcher.waitFor(this.name, optionsOrTimeout);
+  }
 }
 
 /**

package/core/health/probes.js

@@ -112,9 +112,15 @@ async function probeDatabase(db, timeoutMs = 3000) {
       timer = setTimeout(() => {
         reject(new Error(`Database ping timed out after ${timeoutMs}ms`));
       }, timeoutMs);
+      if (typeof timer?.unref === 'function') timer.unref();
     });
 
-    await Promise.race([knex.raw('SELECT 1'), timeoutPromise]);
+    const pingPromise = Promise.resolve(knex.raw('SELECT 1'));
+    if (typeof pingPromise.catch === 'function') {
+      pingPromise.catch(() => {});
+    }
+
+    await Promise.race([pingPromise, timeoutPromise]);
     const latencyMs = Date.now() - startTime;
     return { status: 'up', latencyMs };
   } catch (err) {
@@ -170,9 +176,13 @@ async function probeCustomChecks(checks = {}, context = {}, timeoutMs = 3000) {
     try {
       const timeoutPromise = new Promise((_, reject) => {
         timer = setTimeout(() => reject(new Error(`Health check "${name}" timed out after ${timeoutMs}ms`)), timeoutMs);
+        if (typeof timer?.unref === 'function') timer.unref();
       });
 
-      const res = await Promise.race([Promise.resolve(checkFn(context)), timeoutPromise]);
+      const checkPromise = Promise.resolve().then(() => checkFn(context));
+      checkPromise.catch(() => {});
+
+      const res = await Promise.race([checkPromise, timeoutPromise]);
       const latencyMs = Date.now() - startTime;
 
       if (res === false || (res && typeof res === 'object' && res.status === 'down')) {

package/core/http/index.js

@@ -7,7 +7,14 @@
 
 const { HttpAdapter } = require('./adapter');
 const { ExpressHttpAdapter, createExpressHttpAdapter } = require('./express-adapter');
-const { runMiddlewares, enrichRouteError, executeApiPipeline, executePagePipeline } = require('./pipeline');
+const {
+  createPipelineRunner,
+  runMiddlewares,
+  enrichRouteError,
+  validateRequestInput,
+  executeApiPipeline,
+  executePagePipeline,
+} = require('./pipeline');
 
 let _honoModule = null;
 function getHonoModule() {
@@ -21,8 +28,10 @@ module.exports = {
   HttpAdapter,
   ExpressHttpAdapter,
   createExpressHttpAdapter,
+  createPipelineRunner,
   runMiddlewares,
   enrichRouteError,
+  validateRequestInput,
   executeApiPipeline,
   executePagePipeline,
 };