exisjs 0.9.0 → 0.9.1

package/dist/database/lifecycle.d.ts

@@ -12,7 +12,14 @@ export interface DatabaseRegistration {
     disconnect: () => Promise<void> | void;
     isHealthy?: () => Promise<boolean | DatabaseHealthInfo> | boolean | DatabaseHealthInfo;
     healthCheck?: () => Promise<boolean | DatabaseHealthInfo> | boolean | DatabaseHealthInfo;
+    /**
+     * How long a health check may take before it counts as failed, so one
+     * unresponsive database cannot hang `/_ready`. Default: 5000 ms.
+     */
+    healthTimeoutMs?: number;
 }
+/** Rejects when `promise` has not settled after `ms`. */
+export declare function withTimeout<T>(promise: Promise<T> | T, ms: number, message: string): Promise<T>;
 /**
  * Universal Database Manager for ExisJS.
  * Manages connections, graceful shutdown, and health checks for any database
@@ -22,6 +29,7 @@ export declare class DatabaseManager {
     private static databases;
     private static isShutdownHookRegistered;
     private static appManagedShutdown;
+    private static healthInFlight?;
     /**
      * Called by the server when it starts listening. From then on the app's
      * graceful shutdown disconnects databases, after in-flight requests have
@@ -33,7 +41,10 @@ export declare class DatabaseManager {
      */
     static register(db: DatabaseRegistration): void;
     /**
-     * Connects all registered databases that are not already connected.
+     * Connects all registered databases that are not already connected, in
+     * parallel: boot waits for the slowest database, not for the sum of all.
+     * If any fail, the error names every database that failed; the ones that
+     * connected stay connected, and a later call retries only the failed ones.
      */
     static connectAll(): Promise<void>;
     /**
@@ -41,12 +52,18 @@ export declare class DatabaseManager {
      */
     static disconnectAll(): Promise<void>;
     /**
-     * Checks the health of all registered databases.
+     * Checks the health of all registered databases, in parallel. Each check
+     * has a timeout (`healthTimeoutMs`, default 5 s) so an unresponsive
+     * database is reported as an error instead of hanging the probe, and
+     * calls made while a check is running share its result, so a burst of
+     * probes costs one round of pings.
      */
     static checkHealth(): Promise<{
         healthy: boolean;
         databases: Record<string, DatabaseHealthInfo>;
     }>;
+    private static runHealthChecks;
+    private static checkOne;
     /**
      * Returns the number of registered databases.
      */

package/dist/database/lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/database/lifecycle.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,oBAAoB,GAC9B,WAAW,GAAG,YAAY,GAAG,cAAc,GAAG,OAAO,CAAA;AAEvD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,oBAAoB,CAAA;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAC9B;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACnC,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACtC,SAAS,CAAC,EAAE,MACV,OAAO,CAAC,OAAO,GAAG,kBAAkB,CAAC,GAAG,OAAO,GAAG,kBAAkB,CAAA;IACtE,WAAW,CAAC,EAAE,MACZ,OAAO,CAAC,OAAO,GAAG,kBAAkB,CAAC,GAAG,OAAO,GAAG,kBAAkB,CAAA;CACvE;AAED;;;;GAIG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAC,SAAS,CAMrB;IACH,OAAO,CAAC,MAAM,CAAC,wBAAwB,CAAQ;IAC/C,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAQ;IAEzC;;;;OAIG;IACH,MAAM,CAAC,kBAAkB,IAAI,IAAI;IAIjC;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,oBAAoB,GAAG,IAAI;IAK/C;;OAEG;WACU,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAiBxC;;OAEG;WACU,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAuB3C;;OAEG;WACU,WAAW,IAAI,OAAO,CAAC;QAClC,OAAO,EAAE,OAAO,CAAA;QAChB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAA;KAC9C,CAAC;IAgDF;;OAEG;IACH,MAAM,KAAK,IAAI,IAAI,MAAM,CAExB;IAED;;OAEG;IACH,MAAM,CAAC,KAAK,IAAI,IAAI;IAKpB,OAAO,CAAC,MAAM,CAAC,mBAAmB;CAgBnC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,GAAG,EACZ,OAAO,CAAC,EAAE,oBAAoB,GAC7B,IAAI,CAGN"}
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../src/database/lifecycle.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,oBAAoB,GAC9B,WAAW,GAAG,YAAY,GAAG,cAAc,GAAG,OAAO,CAAA;AAEvD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,oBAAoB,CAAA;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;CAC9B;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACnC,UAAU,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAA;IACtC,SAAS,CAAC,EAAE,MACV,OAAO,CAAC,OAAO,GAAG,kBAAkB,CAAC,GAAG,OAAO,GAAG,kBAAkB,CAAA;IACtE,WAAW,CAAC,EAAE,MACZ,OAAO,CAAC,OAAO,GAAG,kBAAkB,CAAC,GAAG,OAAO,GAAG,kBAAkB,CAAA;IACtE;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAID,yDAAyD;AACzD,wBAAgB,WAAW,CAAC,CAAC,EAC3B,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EACvB,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,CAAC,CAAC,CASZ;AAED;;;;GAIG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAAC,SAAS,CAMrB;IACH,OAAO,CAAC,MAAM,CAAC,wBAAwB,CAAQ;IAC/C,OAAO,CAAC,MAAM,CAAC,kBAAkB,CAAQ;IAEzC,OAAO,CAAC,MAAM,CAAC,cAAc,CAAC,CAG5B;IAEF;;;;OAIG;IACH,MAAM,CAAC,kBAAkB,IAAI,IAAI;IAIjC;;OAEG;IACH,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,oBAAoB,GAAG,IAAI;IAK/C;;;;;OAKG;WACU,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAiCxC;;OAEG;WACU,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAuB3C;;;;;;OAMG;IACH,MAAM,CAAC,WAAW,IAAI,OAAO,CAAC;QAC5B,OAAO,EAAE,OAAO,CAAA;QAChB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAA;KAC9C,CAAC;mBASmB,eAAe;mBAgBf,QAAQ;IA4C7B;;OAEG;IACH,MAAM,KAAK,IAAI,IAAI,MAAM,CAExB;IAED;;OAEG;IACH,MAAM,CAAC,KAAK,IAAI,IAAI;IAMpB,OAAO,CAAC,MAAM,CAAC,mBAAmB;CAgBnC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,GAAG,EACZ,OAAO,CAAC,EAAE,oBAAoB,GAC7B,IAAI,CAGN"}

package/dist/database/lifecycle.js

@@ -1,7 +1,18 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DatabaseManager = void 0;
+exports.withTimeout = withTimeout;
 exports.registerDatabase = registerDatabase;
+const DEFAULT_HEALTH_TIMEOUT_MS = 5000;
+/** Rejects when `promise` has not settled after `ms`. */
+function withTimeout(promise, ms, message) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(message)), ms);
+        timer.unref?.();
+    });
+    return Promise.race([Promise.resolve(promise), timeout]).finally(() => clearTimeout(timer));
+}
 /**
  * Universal Database Manager for ExisJS.
  * Manages connections, graceful shutdown, and health checks for any database
@@ -24,23 +35,36 @@ class DatabaseManager {
         this.ensureShutdownHooks();
     }
     /**
-     * Connects all registered databases that are not already connected.
+     * Connects all registered databases that are not already connected, in
+     * parallel: boot waits for the slowest database, not for the sum of all.
+     * If any fail, the error names every database that failed; the ones that
+     * connected stay connected, and a later call retries only the failed ones.
      */
     static async connectAll() {
-        for (const [name, db] of this.databases) {
-            if (db._connected)
-                continue;
-            try {
-                await db.connect();
-                db._connected = true;
-                db._disconnecting = undefined;
-            }
-            catch (err) {
-                const error = new Error(`[ExisJS Database] Failed to connect database "${name}": ${err.message}`);
-                error.cause = err;
-                throw error;
+        const pending = [...this.databases.entries()].filter(([, db]) => !db._connected);
+        const results = await Promise.allSettled(pending.map(async ([, db]) => {
+            await db.connect();
+            db._connected = true;
+            db._disconnecting = undefined;
+        }));
+        const failures = [];
+        results.forEach((result, i) => {
+            if (result.status === 'rejected') {
+                failures.push([pending[i][0], result.reason]);
             }
-        }
+        });
+        if (failures.length === 0)
+            return;
+        const summary = failures
+            .map(([name, err]) => `"${name}": ${err?.message ?? String(err)}`)
+            .join('; ');
+        const error = new Error(`[ExisJS Database] Failed to connect database ${summary}`);
+        error.cause = failures[0][1];
+        error.failures = failures.map(([name, err]) => ({
+            name,
+            error: err,
+        }));
+        throw error;
     }
     /**
      * Disconnects all registered databases gracefully.
@@ -66,54 +90,68 @@ class DatabaseManager {
         await Promise.allSettled(disconnectPromises);
     }
     /**
-     * Checks the health of all registered databases.
+     * Checks the health of all registered databases, in parallel. Each check
+     * has a timeout (`healthTimeoutMs`, default 5 s) so an unresponsive
+     * database is reported as an error instead of hanging the probe, and
+     * calls made while a check is running share its result, so a burst of
+     * probes costs one round of pings.
      */
-    static async checkHealth() {
-        const results = {};
-        let allHealthy = true;
-        for (const [name, db] of this.databases) {
-            const start = Date.now();
-            try {
-                const healthFn = db.isHealthy || db.healthCheck;
-                if (!healthFn) {
-                    results[name] = { name, status: 'connected', latencyMs: 0 };
-                    continue;
-                }
-                const healthRes = await healthFn();
-                const latencyMs = Date.now() - start;
-                if (typeof healthRes === 'boolean') {
-                    results[name] = {
+    static checkHealth() {
+        if (this.healthInFlight)
+            return this.healthInFlight;
+        const run = this.runHealthChecks().finally(() => {
+            this.healthInFlight = undefined;
+        });
+        this.healthInFlight = run;
+        return run;
+    }
+    static async runHealthChecks() {
+        const entries = await Promise.all([...this.databases].map(([name, db]) => this.checkOne(name, db)));
+        const databases = {};
+        let healthy = true;
+        for (const info of entries) {
+            databases[info.key] = info.result;
+            if (info.result.status !== 'connected')
+                healthy = false;
+        }
+        return { healthy, databases };
+    }
+    static async checkOne(name, db) {
+        const healthFn = db.isHealthy || db.healthCheck;
+        if (!healthFn) {
+            return { key: name, result: { name, status: 'connected', latencyMs: 0 } };
+        }
+        const start = Date.now();
+        const timeoutMs = db.healthTimeoutMs ?? DEFAULT_HEALTH_TIMEOUT_MS;
+        try {
+            const healthRes = await withTimeout(healthFn(), timeoutMs, `Health check timed out after ${timeoutMs}ms`);
+            const latencyMs = Date.now() - start;
+            if (typeof healthRes === 'boolean') {
+                return {
+                    key: name,
+                    result: {
                         name,
                         status: healthRes ? 'connected' : 'disconnected',
                         latencyMs,
-                    };
-                    if (!healthRes)
-                        allHealthy = false;
-                }
-                else {
-                    results[name] = {
-                        latencyMs,
-                        ...healthRes,
-                        name: healthRes.name || name,
-                    };
-                    if (healthRes.status !== 'connected')
-                        allHealthy = false;
-                }
+                    },
+                };
             }
-            catch (err) {
-                allHealthy = false;
-                results[name] = {
+            return {
+                key: name,
+                result: { latencyMs, ...healthRes, name: healthRes.name || name },
+            };
+        }
+        catch (err) {
+            return {
+                key: name,
+                result: {
                     name,
                     status: 'error',
                     latencyMs: Date.now() - start,
-                    error: err.message,
-                };
-            }
+                    error: err?.message ?? String(err),
+                },
+            };
         }
-        return {
-            healthy: allHealthy,
-            databases: results,
-        };
     }
     /**
      * Returns the number of registered databases.
@@ -127,6 +165,7 @@ class DatabaseManager {
     static clear() {
         this.databases.clear();
         this.appManagedShutdown = false;
+        this.healthInFlight = undefined;
     }
     static ensureShutdownHooks() {
         if (this.isShutdownHookRegistered)

package/dist/database/lifecycle.js.map

@@ -1 +1 @@
-{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../src/database/lifecycle.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"lifecycle.js","sourceRoot":"","sources":["../../src/database/lifecycle.ts"],"names":[],"mappings":"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"}

package/dist/decorators/transaction.d.ts

@@ -4,26 +4,5 @@ export interface TransactionalOptions {
     /** Whether the transaction is read-only */
     readOnly?: boolean;
 }
-/**
- * Automatically wraps a service method inside a database transaction.
- * Commits automatically on success, and rolls back if an unhandled exception is thrown.
- *
- * Compatible with ExisJS built-in Database client, Prisma, Drizzle, TypeORM, Knex, and raw SQL pools.
- *
- * @example
- * ```ts
- * @Injectable()
- * export class OrderService {
- *   constructor(private db: DatabaseService) {}
- *
- *   @Transactional()
- *   async placeOrder(userId: string, items: CartItem[]) {
- *     const order = await this.db.orders.create({ userId })
- *     await this.db.inventory.decrement(items)
- *     return order
- *   }
- * }
- * ```
- */
 export declare function Transactional(_options?: TransactionalOptions): MethodDecorator;
 //# sourceMappingURL=transaction.d.ts.map

package/dist/decorators/transaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../src/decorators/transaction.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,oBAAoB;IACnC,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,GAAE,oBAAyB,GAClC,eAAe,CAmEjB"}
+{"version":3,"file":"transaction.d.ts","sourceRoot":"","sources":["../../src/decorators/transaction.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,oBAAoB;IACnC,yCAAyC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AA4ED,wBAAgB,aAAa,CAC3B,QAAQ,GAAE,oBAAyB,GAClC,eAAe,CAiDjB"}

package/dist/decorators/transaction.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Transactional = Transactional;
+const node_async_hooks_1 = require("node:async_hooks");
 /**
  * Automatically wraps a service method inside a database transaction.
  * Commits automatically on success, and rolls back if an unhandled exception is thrown.
@@ -22,49 +23,68 @@ exports.Transactional = Transactional;
  * }
  * ```
  */
+// Instance properties that may hold the database client, in lookup order
+const DB_KEYS = ['db', 'database', 'prisma', 'dataSource', 'connection'];
+// Services are usually shared singletons, so the transaction must not be
+// written onto the instance: a concurrent request using the same service
+// would run its queries inside this request's transaction. Instead the
+// database property becomes a getter that returns the transaction only
+// within the async context of the @Transactional call (and anything it
+// awaits or calls, which therefore joins the transaction).
+const activeTransactions = new node_async_hooks_1.AsyncLocalStorage();
+const BOUND = Symbol('exis.transactionalProperty');
+function bindDbProperty(self, key) {
+    const own = Object.getOwnPropertyDescriptor(self, key);
+    if (own?.get && own.get[BOUND])
+        return true;
+    // An inherited or hand-written accessor cannot be wrapped safely
+    if (own === undefined ? key in self : own.get || own.set)
+        return false;
+    if (own !== undefined && !own.configurable)
+        return false;
+    let value = own?.value;
+    const get = function () {
+        const tx = activeTransactions.getStore()?.get(self);
+        return tx !== undefined ? tx : value;
+    };
+    get[BOUND] = true;
+    Object.defineProperty(self, key, {
+        configurable: true,
+        enumerable: own?.enumerable ?? true,
+        get,
+        set(next) {
+            value = next;
+        },
+    });
+    return true;
+}
+function runWithTransaction(self, key, tx, fn) {
+    if (bindDbProperty(self, key)) {
+        const store = new Map(activeTransactions.getStore());
+        store.set(self, tx);
+        return activeTransactions.run(store, () => fn(self));
+    }
+    // Fallback for accessor-defined clients: a per-call view of the instance
+    const scoped = Object.create(self);
+    scoped[key] = tx;
+    return fn(scoped);
+}
 function Transactional(_options = {}) {
     return function (_target, _propertyKey, descriptor) {
         const originalMethod = descriptor.value;
         descriptor.value = async function (...args) {
             const self = this;
-            const db = self.db ||
-                self.database ||
-                self.prisma ||
-                self.dataSource ||
-                self.connection ||
-                globalThis.__EXIS_DB__;
+            const key = DB_KEYS.find((k) => self[k]);
+            const db = key ? self[key] : globalThis.__EXIS_DB__;
             if (db) {
+                const runInTransaction = (tx) => runWithTransaction(self, key ?? 'db', tx, (target) => originalMethod.apply(target, args));
                 // 1. Functional transaction wrapper: db.transaction((tx) => ...)
                 if (typeof db.transaction === 'function') {
-                    return db.transaction(async (tx) => {
-                        const originalDb = self.db;
-                        try {
-                            self.db = tx;
-                            return await originalMethod.apply(self, args);
-                        }
-                        finally {
-                            self.db = originalDb;
-                        }
-                    });
+                    return db.transaction(runInTransaction);
                 }
                 // 2. Prisma-style $transaction: db.$transaction(async (tx) => ...)
                 if (typeof db.$transaction === 'function') {
-                    return db.$transaction(async (tx) => {
-                        const originalPrisma = self.prisma || self.db;
-                        try {
-                            if (self.prisma)
-                                self.prisma = tx;
-                            if (self.db)
-                                self.db = tx;
-                            return await originalMethod.apply(self, args);
-                        }
-                        finally {
-                            if (self.prisma)
-                                self.prisma = originalPrisma;
-                            if (self.db)
-                                self.db = originalPrisma;
-                        }
-                    });
+                    return db.$transaction(runInTransaction);
                 }
                 // 3. Imperative beginTransaction / commit / rollback
                 if (typeof db.beginTransaction === 'function') {

package/dist/decorators/transaction.js.map

@@ -1 +1 @@
-{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../../src/decorators/transaction.ts"],"names":[],"mappings":";;AA4BA,sCAqEC;AA1FD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,aAAa,CAC3B,WAAiC,EAAE;IAEnC,OAAO,UACL,OAAY,EACZ,YAA6B,EAC7B,UAA8B;QAE9B,MAAM,cAAc,GAAG,UAAU,CAAC,KAAK,CAAA;QAEvC,UAAU,CAAC,KAAK,GAAG,KAAK,WAAW,GAAG,IAAW;YAC/C,MAAM,IAAI,GAAG,IAAW,CAAA;YACxB,MAAM,EAAE,GACN,IAAI,CAAC,EAAE;gBACP,IAAI,CAAC,QAAQ;gBACb,IAAI,CAAC,MAAM;gBACX,IAAI,CAAC,UAAU;gBACf,IAAI,CAAC,UAAU;gBACd,UAAkB,CAAC,WAAW,CAAA;YAEjC,IAAI,EAAE,EAAE,CAAC;gBACP,iEAAiE;gBACjE,IAAI,OAAO,EAAE,CAAC,WAAW,KAAK,UAAU,EAAE,CAAC;oBACzC,OAAO,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,EAAO,EAAE,EAAE;wBACtC,MAAM,UAAU,GAAG,IAAI,CAAC,EAAE,CAAA;wBAC1B,IAAI,CAAC;4BACH,IAAI,CAAC,EAAE,GAAG,EAAE,CAAA;4BACZ,OAAO,MAAM,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;wBAC/C,CAAC;gCAAS,CAAC;4BACT,IAAI,CAAC,EAAE,GAAG,UAAU,CAAA;wBACtB,CAAC;oBACH,CAAC,CAAC,CAAA;gBACJ,CAAC;gBAED,mEAAmE;gBACnE,IAAI,OAAO,EAAE,CAAC,YAAY,KAAK,UAAU,EAAE,CAAC;oBAC1C,OAAO,EAAE,CAAC,YAAY,CAAC,KAAK,EAAE,EAAO,EAAE,EAAE;wBACvC,MAAM,cAAc,GAAG,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,EAAE,CAAA;wBAC7C,IAAI,CAAC;4BACH,IAAI,IAAI,CAAC,MAAM;gCAAE,IAAI,CAAC,MAAM,GAAG,EAAE,CAAA;4BACjC,IAAI,IAAI,CAAC,EAAE;gCAAE,IAAI,CAAC,EAAE,GAAG,EAAE,CAAA;4BACzB,OAAO,MAAM,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;wBAC/C,CAAC;gCAAS,CAAC;4BACT,IAAI,IAAI,CAAC,MAAM;gCAAE,IAAI,CAAC,MAAM,GAAG,cAAc,CAAA;4BAC7C,IAAI,IAAI,CAAC,EAAE;gCAAE,IAAI,CAAC,EAAE,GAAG,cAAc,CAAA;wBACvC,CAAC;oBACH,CAAC,CAAC,CAAA;gBACJ,CAAC;gBAED,qDAAqD;gBACrD,IAAI,OAAO,EAAE,CAAC,gBAAgB,KAAK,UAAU,EAAE,CAAC;oBAC9C,MAAM,EAAE,CAAC,gBAAgB,EAAE,CAAA;oBAC3B,IAAI,CAAC;wBACH,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;wBACrD,IAAI,OAAO,EAAE,CAAC,MAAM,KAAK,UAAU;4BAAE,MAAM,EAAE,CAAC,MAAM,EAAE,CAAA;wBACtD,OAAO,MAAM,CAAA;oBACf,CAAC;oBAAC,OAAO,KAAK,EAAE,CAAC;wBACf,IAAI,OAAO,EAAE,CAAC,QAAQ,KAAK,UAAU;4BAAE,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAA;wBAC1D,MAAM,KAAK,CAAA;oBACb,CAAC;gBACH,CAAC;YACH,CAAC;YAED,8DAA8D;YAC9D,OAAO,cAAc,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAAA;QACzC,CAAC,CAAA;QAED,OAAO,UAAU,CAAA;IACnB,CAAC,CAAA;AACH,CAAC"}
+{"version":3,"file":"transaction.js","sourceRoot":"","sources":["../../src/decorators/transaction.ts"],"names":[],"mappings":"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"}

package/dist/docs/content/boundaries.mdx

@@ -148,6 +148,8 @@ export default class AdminBoundary {
 }
 ```
 
+`next()` resolves with what the route sent. Returning that value (or returning nothing) sends the route's response exactly as the route sent it, with the same type and `Content-Type`; a `Buffer` stays binary. Returning a different value replaces the response, and that value is sent like a handler's return value.
+
 ---
 
 ## Boundary Cascading & Execution Order

package/dist/docs/content/config.mdx

@@ -153,7 +153,7 @@ export default defineConfig({
 | `compression` | `boolean` | `false` | Gzip/Brotli HTTP response compression. |
 | `bodyLimit` | `number` | `10485760` (10MB) | Maximum request payload body size in bytes. |
 | `blockSuspiciousProbes` | `boolean \| BlockProbesOptions` | `false` | Blocks known vulnerability scanners and malicious probes (`.php`, `wp-admin`). |
-| `etag` | `boolean` | `false` | Generates weak ETags for cache validation on responses. |
+| `etag` | `boolean` | `false` | Weak ETags on successful GET/HEAD responses, with `304 Not Modified` for a matching `If-None-Match`. See [Caching & Conditional Requests](/docs/responses#caching--conditional-requests-etag-304-412). |
 | `transformResponse` | `boolean \| Function` | `false` | Standardizes handler response payload envelopes. |
 
 ### Logging & Diagnostics

package/dist/docs/content/decorators.mdx

@@ -475,7 +475,7 @@ export class OrderService implements OnInit, OnDestroy {
 | :--- | :--- | :--- |
 | `@Cacheable(options?)` | Method | Caches return value. Options: `{ ttl?: number, key?: string \| ((...args) => string) }`. |
 | `@CacheEvict(options)` | Method | Evicts cache keys on method completion. Options: `{ key: string \| ((...args) => string) }`. |
-| `@Transactional(options?)` | Method | Wraps execution in a database transaction (Prisma, Mongoose, Drizzle, SQL). |
+| `@Transactional(options?)` | Method | Wraps execution in a database transaction (Prisma, Drizzle, Knex, SQL). Inside the call, the service's client property (`db`, `database`, `prisma`, `dataSource` or `connection`) is the transaction, including in methods it calls; concurrent requests using the same service keep the normal client. |
 | `@Profile(options?)` | Method | Measures execution time using `performance.now()`. |
 | `OnInit` (`onInit()`) | Class Interface | Invoked once after service instantiation. |
 | `OnDestroy` (`onDestroy()`) | Class Interface | Invoked once during graceful shutdown. |

package/dist/docs/content/middleware.mdx

@@ -28,7 +28,7 @@ All standard middlewares can be imported directly from `exisjs/middleware`. Cust
 | `idempotent` | `idempotent(options?)` | Duplicate mutation caching keyed by `Idempotency-Key` headers. |
 | `dedupe` | `dedupe(options)` | Merges simultaneous identical in-flight `GET` requests into a single operation. |
 | `backpressure` | `backpressure(options?)` | Queues requests during high load and sheds excess traffic with `503 Service Unavailable`. |
-| `serveStatic` | `serveStatic(root, options?)` | Serves static assets from disk with strong ETags and Brotli/Gzip pre-compression. |
+| `serveStatic` | `serveStatic(root, options?)` | Serves static assets from disk with ETag / Last-Modified revalidation and Brotli/Gzip pre-compression. |
 | `timeout` | `timeout(ms \| options)` | Terminates requests exceeding the duration limit with `503 Service Unavailable`. |
 | `fileUpload` | `fileUpload(options?)` | Streaming multipart/form-data parser supporting disk/memory storage and MIME checks. |
 | `fromExpress` | `fromExpress(middleware)` | Connect/Express bridge adapter running third-party middleware (e.g. Multer) directly. |
@@ -151,6 +151,8 @@ export const requireAuth = defineMiddleware<AuthContext>(async (req, res, next)
 })
 ```
 
+Middleware may be `async`. ExisJS awaits the returned promise. If it throws, or rejects with an `HttpError` (such as `UnauthorizedException` above), that error becomes the response through the error handler, with the standard error envelope. You don't need to catch it and call `next(err)` yourself.
+
 ### 2. Using Typed Middleware in Functional Routes
 
 ```typescript filename="src/http/profile/route.ts"
@@ -287,4 +289,4 @@ export default exis({
 })
 ```
 
-`serveStatic` automatically handles MIME detection, conditional `If-None-Match` 304 caching, and serves pre-compressed `.br` or `.gz` files if present on disk.
+`serveStatic` handles MIME detection and serves a pre-compressed `.br` or `.gz` file when one exists and the client accepts that encoding (`br;q=0` counts as a refusal). Every file gets an `ETag` (from its size and modification time; each encoded file has its own) and `Last-Modified`, and conditional requests are answered with `304` or `412` as described in [Caching & Conditional Requests](/docs/responses#caching--conditional-requests-etag-304-412). `Vary: Accept-Encoding` is always sent so shared caches keep the variants apart.

package/dist/docs/content/requests.mdx

@@ -106,6 +106,8 @@ const data = await req.json<{ username: string }>()
 const { fields, files } = await req.formData()
 ```
 
+The body is read from the network once; these methods share the result. `req.buffer()` returns the bytes exactly as the client sent them, so binary payloads (images, protobuf, compressed or signed data) are safe. A body over `bodyLimit` makes these calls fail with `413 Payload Too Large`.
+
 ### Webhooks with `@RawBody()` (Class Controllers)
 
 In class-based controllers, use the `@RawBody()` parameter decorator to inject the raw `Buffer` or decoded string directly:

package/dist/docs/content/responses.mdx

@@ -451,6 +451,60 @@ export default controller({
 })
 ```
 
+## Caching & Conditional Requests (ETag, 304, 412)
+
+ExisJS follows the conditional request rules of RFC 9110 §13 everywhere: for automatic ETags, in `res.checkPreconditions()`, for `serveStatic` and for `res.download(path)`.
+
+| Request header | Checked against | Result when it does not hold |
+| :--- | :--- | :--- |
+| `If-Match` | `ETag`, strong comparison | `412 Precondition Failed` |
+| `If-Unmodified-Since` (only without `If-Match`) | `Last-Modified` | `412 Precondition Failed` |
+| `If-None-Match` | `ETag`, weak comparison; lists and `*` supported | Matches: `304` for GET/HEAD, `412` for writes |
+| `If-Modified-Since` (only without `If-None-Match`, GET/HEAD) | `Last-Modified` | Unchanged: `304 Not Modified` |
+
+A `304` carries the `ETag`, `Last-Modified`, `Cache-Control` and `Vary` of the `200` it replaces, and no body or `Content-Type`. Errors use the standard envelope (`PRECONDITION_FAILED`, `PRECONDITION_REQUIRED`).
+
+### Automatic ETags
+
+With `etag: true` in `exis.config.ts` (or `conditionalGet()` on some routes), every successful `GET`/`HEAD` response sent with `res.json()`, `res.send()` or a returned value gets a weak ETag hashed from its body, and a matching `If-None-Match` is answered with `304`. The handler still runs, so this saves bandwidth, not work. Writes and error responses get no ETag.
+
+### Validators from your data: `res.checkPreconditions()`
+
+When the resource has a version or update time, check it **before** doing the work. On reads this skips the query for the body and serialization; on writes it prevents lost updates: a client that edited an old copy gets `412` instead of overwriting someone else's change.
+
+```typescript filename="src/http/documents/[id]/route.ts"
+import { controller, route } from 'exisjs/router'
+
+export default controller({
+  read: route.get('/', {
+    async handle({ params, res }) {
+      const meta = await documents.meta(params.id) // cheap: version + updatedAt
+      // Sets ETag / Last-Modified; answers 304 and returns true when current
+      if (res.checkPreconditions({ etag: `v${meta.version}`, lastModified: meta.updatedAt })) return
+      return documents.find(params.id)
+    },
+  }),
+
+  update: route.put('/', {
+    async handle({ params, body, res }) {
+      const current = await documents.meta(params.id)
+      // 412 if the client's If-Match is stale; 428 if it sent no precondition
+      res.checkPreconditions({ etag: `v${current.version}` }, { required: true })
+      const updated = await documents.update(params.id, body)
+      res.setHeader('ETag', `"v${updated.version}"`) // the new state
+      return updated
+    },
+  }),
+})
+```
+
+- `etag` may be bare (`v3` is sent as `"v3"`) or a full tag (`W/"v3"`). Use a value that changes whenever the representation changes: a version column, a hash, `updatedAt`.
+- `lastModified` takes a `Date`, a timestamp or an HTTP date. It is rounded to whole seconds, and a time in the future is capped at the current time.
+- For "create only if absent" (`PUT` with `If-None-Match: *`), pass `exists: false` when the resource does not exist yet; an existing one answers `412`.
+- On writes, the old validators are not sent back. Set the new `ETag` after the change, as above.
+
+`req.fresh` (and `req.stale`) apply the same rules to the response headers set so far.
+
 ---
 
 ## Next Steps

package/dist/docs/content/validation.mdx

@@ -92,6 +92,19 @@ const Schema = tex.object({
 })
 ```
 
+Nested object schemas take the same modifiers as methods: `.optional()`, `.nullable()` and `.nullish()`. A plain object literal is also a nested object:
+
+```typescript filename="src/http/leads/schema.ts"
+const Address = tex.object({ city: tex.string(), pin: tex.string({ optional: true }) })
+
+export const UpdateLead = tex.object({
+  status: tex.enum(['new', 'won', 'lost']),
+  address: Address.optional(), // may be left out
+  billing: Address.nullish(), // may be left out or sent as null to clear it
+  meta: { source: tex.string() }, // same as tex.object({ source: tex.string() })
+})
+```
+
 ### Input and Output Types
 
 A field with a `default` may be left out of a request but is always present after parsing, so the two sides have different types: