webspresso 0.0.106 → 0.0.108

package/core/context/app-context.js

@@ -0,0 +1,201 @@
+/**
+ * Process-wide app context set by createApp() — use from API handlers, jobs, etc.
+ * @module src/app-context
+ */
+
+const { circuitBreakerRegistry, retry } = require('../resilience');
+
+/** @type {{ db: object|null, shutdownManager: object|null, serviceRegistry: object|null, events: object|null, mailer: object|null, cache: object|null, breakers: object|null }} */
+let context = {
+  db: null,
+  shutdownManager: null,
+  serviceRegistry: null,
+  events: null,
+  mailer: null,
+  cache: null,
+  breakers: circuitBreakerRegistry,
+};
+
+/**
+ * Merge into the current context (typically called once from createApp).
+ * @param {{ db?: object|null, shutdownManager?: object|null, serviceRegistry?: object|null, events?: object|null, mailer?: object|null, cache?: object|null }} partial
+ */
+function setAppContext(partial) {
+  context = { ...context, ...partial };
+}
+
+/**
+ * @returns {{ db: object|null, shutdownManager: object|null, serviceRegistry: object|null, events: object|null, mailer: object|null }}
+ */
+function getAppContext() {
+  return context;
+}
+
+/**
+ * Database instance passed to createApp({ db }) (Knex + ORM helpers).
+ * @returns {object}
+ * @throws {Error} If createApp was not given a db instance
+ */
+function getDb() {
+  if (!context.db) {
+    throw new Error(
+      'No database registered. Create a DB with createDatabase(), then pass it to createApp({ db }). ' +
+        'Or use hasDb() before calling getDb().'
+    );
+  }
+  return context.db;
+}
+
+/**
+ * @returns {boolean}
+ */
+function hasDb() {
+  return context.db != null;
+}
+
+/**
+ * @returns {object|null}
+ */
+function getShutdownManager() {
+  return context.shutdownManager;
+}
+
+/**
+ * @returns {boolean}
+ */
+function hasShutdownManager() {
+  return context.shutdownManager != null;
+}
+
+/**
+ * Get the registered ServiceRegistry instance
+ * @returns {object|null}
+ */
+function getServiceRegistry() {
+  return context.serviceRegistry;
+}
+
+/**
+ * Check if a ServiceRegistry is registered
+ * @returns {boolean}
+ */
+function hasServiceRegistry() {
+  return context.serviceRegistry != null;
+}
+
+/**
+ * Get the registered EventDispatcher instance
+ * @returns {object|null}
+ */
+function getEvents() {
+  return context.events;
+}
+
+/**
+ * Check if an EventDispatcher is registered
+ * @returns {boolean}
+ */
+function hasEvents() {
+  return context.events != null;
+}
+
+/**
+ * Clear context (e.g. between tests).
+ */
+function resetAppContext() {
+  context = {
+    db: null,
+    shutdownManager: null,
+    serviceRegistry: null,
+    events: null,
+    mailer: null,
+    cache: null,
+    breakers: circuitBreakerRegistry,
+  };
+}
+
+/**
+ * @returns {object|null}
+ */
+function getMailer() {
+  return context.mailer;
+}
+
+/**
+ * @returns {boolean}
+ */
+function hasMailer() {
+  return context.mailer != null;
+}
+
+/**
+ * @returns {object|null}
+ */
+function getCache() {
+  return context.cache;
+}
+
+/**
+ * @returns {boolean}
+ */
+function hasCache() {
+  return context.cache != null;
+}
+
+/**
+ * Express middleware: sets `req.db`, `req.service`, `req.events`, `req.mailer`, and `req.cache` from registered app context.
+ * File-based `pages/api/*` routes attach this automatically; use in `setupRoutes`
+ * for manually registered handlers that need `req.db` and `req.service`.
+ * @type {import('express').RequestHandler}
+ */
+function attachDbMiddleware(req, res, next) {
+  if (context.db != null) {
+    req.db = context.db;
+  }
+  if (context.events != null) {
+    req.events = context.events;
+  }
+  if (context.mailer != null) {
+    req.mailer = context.mailer;
+  }
+  if (context.cache != null) {
+    req.cache = context.cache;
+  }
+  req.breakers = context.breakers || circuitBreakerRegistry;
+  req.breaker = (name, opts) => (context.breakers || circuitBreakerRegistry).getBreaker(name, opts);
+  req.retry = retry;
+  if (context.serviceRegistry != null) {
+    req.service = (name, input, opts) =>
+      context.serviceRegistry.call(name, input, req.context || {
+        req,
+        res,
+        db: context.db,
+        events: context.events,
+        mailer: context.mailer,
+        cache: context.cache,
+        breakers: req.breakers,
+        breaker: req.breaker,
+        retry,
+      }, opts);
+  }
+  next();
+}
+
+module.exports = {
+  setAppContext,
+  getAppContext,
+  getDb,
+  hasDb,
+  getShutdownManager,
+  hasShutdownManager,
+  getServiceRegistry,
+  hasServiceRegistry,
+  getEvents,
+  hasEvents,
+  getMailer,
+  hasMailer,
+  getCache,
+  hasCache,
+  resetAppContext,
+  attachDbMiddleware,
+};

package/core/context/index.js

@@ -0,0 +1,55 @@
+'use strict';
+
+/**
+ * Webspresso Context Management Layer
+ * Process-wide application context and request-scoped AsyncLocalStorage ambient context.
+ *
+ * @module core/context
+ */
+
+const appContext = require('./app-context');
+const requestContext = require('./request');
+
+module.exports = {
+  // App context (process-wide)
+  setAppContext: appContext.setAppContext,
+  getAppContext: appContext.getAppContext,
+  getDb: appContext.getDb,
+  hasDb: appContext.hasDb,
+  getShutdownManager: appContext.getShutdownManager,
+  hasShutdownManager: appContext.hasShutdownManager,
+  getServiceRegistry: appContext.getServiceRegistry,
+  hasServiceRegistry: appContext.hasServiceRegistry,
+  getEvents: appContext.getEvents,
+  hasEvents: appContext.hasEvents,
+  getMailer: appContext.getMailer,
+  hasMailer: appContext.hasMailer,
+  getCache: appContext.getCache,
+  hasCache: appContext.hasCache,
+  resetAppContext: appContext.resetAppContext,
+  attachDbMiddleware: appContext.attachDbMiddleware,
+
+  // Request & ambient execution context (AsyncLocalStorage)
+  requestContextStorage: requestContext.requestContextStorage,
+  runWithContext: requestContext.runWithContext,
+  withContext: requestContext.withContext,
+  getContext: requestContext.getContext,
+  useContext: requestContext.useContext,
+  useDb: requestContext.useDb,
+  useAuth: requestContext.useAuth,
+  useUser: requestContext.useUser,
+  useLogger: requestContext.useLogger,
+  useReq: requestContext.useReq,
+  useRes: requestContext.useRes,
+  useParams: requestContext.useParams,
+  useQuery: requestContext.useQuery,
+  useService: requestContext.useService,
+  useQueue: requestContext.useQueue,
+  useCache: requestContext.useCache,
+  useBreaker: requestContext.useBreaker,
+  useTransaction: requestContext.useTransaction,
+
+  // Namespace accessors
+  appContext,
+  requestContext,
+};

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/errors/domain.js

@@ -17,20 +17,38 @@ class ValidationError extends HttpError {
    * @param {string} [message='Validation failed']
    * @param {Object} [options]
    * @param {Record<string, string[]|string>} [options.fields={}] - Field-specific validation error messages
+   * @param {Record<string, string[]>} [options.fieldErrors={}] - Detailed array of errors per field
    * @param {number} [options.status=422]
+   * @param {number} [options.statusCode]
    * @param {string} [options.code='VALIDATION_ERROR']
+   * @param {string} [options.service] - Service identifier if originating from services layer
    * @param {unknown} [options.details]
+   * @param {unknown} [options.issues]
    * @param {unknown} [options.cause]
    */
   constructor(message = 'Validation failed', options = {}) {
-    super(options.status || 422, message, {
+    const status = typeof options.status === 'number'
+      ? options.status
+      : (typeof options.statusCode === 'number' ? options.statusCode : 422);
+
+    super(status, message, {
       code: options.code || 'VALIDATION_ERROR',
       expose: true,
       ...options,
     });
 
+    this.statusCode = this.status;
     this.fields = options.fields || {};
-    this.issues = options.issues || options.details || [];
+    if (options.fieldErrors) {
+      this.fieldErrors = options.fieldErrors;
+    }
+    if (options.issues !== undefined || options.details !== undefined) {
+      this.issues = options.issues !== undefined ? options.issues : (options.details || []);
+      this.details = options.details !== undefined ? options.details : this.issues;
+    }
+    if (options.service) {
+      this.service = options.service;
+    }
   }
 }
 

package/core/errors/http.js

@@ -23,6 +23,7 @@ class HttpError extends WebspressoError {
     super(message, options);
 
     this.status = typeof status === 'number' ? status : 500;
+    this.statusCode = this.status;
     this.headers = options.headers || {};
     this.expose = options.expose !== undefined ? Boolean(options.expose) : this.status < 500;
   }