@zudojs/database 1.1.0 → 1.2.1

package/README.md

@@ -6,6 +6,12 @@ that translates to Prisma `where` clauses, managed transactions, keyset
 pagination with signed cursors, migration and seed runners guarded by advisory
 locks, health checks with reconnect, and a bounded in-memory cache.
 
+<!-- zudo-docs:start -->
+
+**Documentation:** [zudojs.oyinlola.site/docs/packages-database](https://zudojs.oyinlola.site/docs/packages-database) · **For AI agents:** [Markdown version](https://zudojs.oyinlola.site/docs/packages-database.md), [llms.txt](https://zudojs.oyinlola.site/llms.txt)
+
+<!-- zudo-docs:end -->
+
 ## Installation
 
 ```bash
@@ -223,6 +229,8 @@ await assertDatabaseHealth(client); // throws DatabaseUnhealthyError with the re
 - `BaseRepository` with CRUD, `createMany` / `deleteMany`, soft delete (`softDelete`, `restore`, `findDeleted`, `withDeleted`), transaction rebinding (`withTransaction`), and `findByQuery`
 - Query builder and 40 filter helpers that translate to Prisma `where` / `orderBy` / `select` / `include`
 - Managed transactions with context, error enrichment, and `withTransactionRetry` (serialization failures retried by default)
+  with exponential backoff capped by `maxRetryDelayMs` (30 s by default, never above the
+  2^31-1 ms timer limit) and optional `jitter: "full"`
 - Offset pagination and keyset pagination with HMAC-signed, shape-validated cursors
 - Migration and seed runners using PostgreSQL advisory locks, per-item transactions, and BIGINT versioning
 - Advisory and row locks with `lock_timeout`, `SKIP LOCKED` / `NOWAIT`, and namespaced keys

package/dist/cache/cache.memory.js

@@ -303,19 +303,24 @@ export async function getOrSet(cache, key, loader, options) {
     const pending = inflight.get(key);
     if (pending)
         return pending;
+    // The cleanup lives outside the promise: the body runs synchronously up to
+    // its first `await`, so a loader that throws synchronously would otherwise
+    // run the cleanup before the entry is registered and leave the rejected
+    // promise cached for the lifetime of the cache.
     const promise = (async () => {
-        try {
-            const value = await loader();
-            if (value !== undefined)
-                cache.set(key, value, options);
-            return value;
-        }
-        finally {
-            inflight.delete(key);
-        }
+        const value = await loader();
+        if (value !== undefined)
+            cache.set(key, value, options);
+        return value;
     })();
     inflight.set(key, promise);
-    return promise;
+    try {
+        return await promise;
+    }
+    finally {
+        if (inflight.get(key) === promise)
+            inflight.delete(key);
+    }
 }
 /**
  * Invalidates all entries whose keys start with a prefix.

package/dist/databaseClient/databaseClient.logger.d.ts

@@ -1,9 +1,20 @@
 /**
  * @zudojs/database — Default Logger
  *
- * Minimal logger for environments where no application logger has been configured yet.
+ * Fallback logger for environments where no application logger has been
+ * configured yet. It writes through `@zudojs/logger` (console transport,
+ * secret-name redaction) instead of calling `console.*` directly.
  */
+import type { Logger } from "@zudojs/logger";
 import type { DatabaseLogger } from "../databaseType/databaseType.type.js";
-/** Creates a minimal logger for environments where no application logger has been configured yet. */
+/** Logger name used by the database fallback logger. */
+export declare const DEFAULT_DATABASE_LOGGER_NAME = "@zudojs/database";
+/**
+ * Adapts a `@zudojs/logger` {@link Logger} to the {@link DatabaseLogger}
+ * contract. `debug`/`info` are dropped when `NODE_ENV` is `"production"`,
+ * checked per call as before; `warn`/`error` are always written.
+ */
+export declare function createDatabaseLoggerAdapter(logger: Logger): DatabaseLogger;
+/** Creates the fallback database logger, backed by `@zudojs/logger`. */
 export declare function createDefaultLogger(): DatabaseLogger;
 //# sourceMappingURL=databaseClient.logger.d.ts.map

package/dist/databaseClient/databaseClient.logger.js

@@ -1,27 +1,55 @@
 /**
  * @zudojs/database — Default Logger
  *
- * Minimal logger for environments where no application logger has been configured yet.
+ * Fallback logger for environments where no application logger has been
+ * configured yet. It writes through `@zudojs/logger` (console transport,
+ * secret-name redaction) instead of calling `console.*` directly.
  */
-/** Creates a minimal logger for environments where no application logger has been configured yet. */
-export function createDefaultLogger() {
-    return {
+import { createLogger, LoggerLevel } from "@zudojs/logger";
+/** Logger name used by the database fallback logger. */
+export const DEFAULT_DATABASE_LOGGER_NAME = "@zudojs/database";
+function isVerboseEnabled() {
+    return process.env.NODE_ENV !== "production";
+}
+function toOptions(metadata, error) {
+    if (error === undefined) {
+        return metadata === undefined ? {} : { metadata };
+    }
+    if (error instanceof Error) {
+        return metadata === undefined ? { error } : { metadata, error };
+    }
+    return { metadata: { ...(metadata ?? {}), error } };
+}
+/**
+ * Adapts a `@zudojs/logger` {@link Logger} to the {@link DatabaseLogger}
+ * contract. `debug`/`info` are dropped when `NODE_ENV` is `"production"`,
+ * checked per call as before; `warn`/`error` are always written.
+ */
+export function createDatabaseLoggerAdapter(logger) {
+    return Object.freeze({
         debug: (message, metadata) => {
-            if (process.env.NODE_ENV !== "production") {
-                console.debug(message, metadata);
+            if (isVerboseEnabled()) {
+                logger.log(LoggerLevel.DEBUG, message, toOptions(metadata));
             }
         },
         info: (message, metadata) => {
-            if (process.env.NODE_ENV !== "production") {
-                console.info(message, metadata);
+            if (isVerboseEnabled()) {
+                logger.log(LoggerLevel.INFO, message, toOptions(metadata));
             }
         },
         warn: (message, metadata) => {
-            console.warn(message, metadata);
+            logger.log(LoggerLevel.WARN, message, toOptions(metadata));
         },
         error: (message, error, metadata) => {
-            console.error(message, error, metadata);
+            logger.log(LoggerLevel.ERROR, message, toOptions(metadata, error));
         },
-    };
+    });
+}
+/** Creates the fallback database logger, backed by `@zudojs/logger`. */
+export function createDefaultLogger() {
+    return createDatabaseLoggerAdapter(createLogger({
+        name: DEFAULT_DATABASE_LOGGER_NAME,
+        level: LoggerLevel.DEBUG,
+    }));
 }
 //# sourceMappingURL=databaseClient.logger.js.map

package/dist/queryBuilder/queryBuilder.prisma.js

@@ -1,3 +1,4 @@
+import { isPlainObject } from "@zudojs/types";
 import { normalizePagination } from "../pagination/pagination.core.js";
 import { toPrismaInclude, } from "../relations/relations.definition.js";
 const FIELD_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -224,10 +225,4 @@ function validateFieldName(field) {
         throw new TypeError(`Invalid query field name "${String(field)}".`);
     }
 }
-function isPlainObject(value) {
-    return (value !== null &&
-        typeof value === "object" &&
-        !Array.isArray(value) &&
-        !(value instanceof Date));
-}
 //# sourceMappingURL=queryBuilder.prisma.js.map

package/dist/relations/relations.definition.js

@@ -84,6 +84,23 @@ export function validateInclude(include) {
         validateInclude(nested);
     }
 }
+/**
+ * Validates a single include level: its shape, relation name and select
+ * fields, leaving nested includes to the caller.
+ *
+ * `buildInclude` uses this so the depth bound applies per level — a
+ * recursive validation would walk the whole caller-supplied subtree before
+ * the depth guard could refuse it.
+ */
+function validateIncludeLevel(include) {
+    if (!include || typeof include !== "object") {
+        throw new TypeError("A relation include is required.");
+    }
+    validateRelationName(include.relation);
+    for (const field of include.select ?? []) {
+        validateFieldName(field);
+    }
+}
 /**
  * Translates relation includes into a Prisma `include` object.
  *
@@ -105,10 +122,13 @@ function buildInclude(includes, options, parent, depth, maxDepth, path) {
     if (depth > maxDepth) {
         throw new RangeError(`Relation include depth exceeds the maximum of ${maxDepth}.`);
     }
-    const result = {};
+    // A null-prototype accumulator: relation names such as `toString` or
+    // `__proto__` must behave as ordinary keys. It is spread into a plain
+    // object before it is returned.
+    const result = Object.create(null);
     for (const include of includes) {
-        validateInclude(include);
-        if (include.relation in result) {
+        validateIncludeLevel(include);
+        if (Object.hasOwn(result, include.relation)) {
             throw new TypeError(`Relation "${include.relation}" is included more than once.`);
         }
         let definition;
@@ -123,11 +143,11 @@ function buildInclude(includes, options, parent, depth, maxDepth, path) {
         }
         const entry = {};
         if (include.select && include.select.length > 0) {
-            const select = {};
+            const select = Object.create(null);
             for (const field of include.select) {
                 select[field] = true;
             }
-            entry["select"] = select;
+            entry["select"] = { ...select };
         }
         if (include.include && include.include.length > 0) {
             const nested = buildInclude(include.include, options, definition ? definition.child : undefined, depth + 1, maxDepth, definition ? [...path, definition] : path);
@@ -147,7 +167,7 @@ function buildInclude(includes, options, parent, depth, maxDepth, path) {
         }
         result[include.relation] = Object.keys(entry).length === 0 ? true : entry;
     }
-    return result;
+    return { ...result };
 }
 /**
  * Creates a nested relation include.

package/dist/transaction/transaction.backoff.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @zudojs/database — Transaction retry backoff.
+ *
+ * `retryDelayMs * 2^(attempt-1)` passes 2^31-1 ms by attempt 26 at the
+ * default 100 ms base. `setTimeout` then warns and fires after 1 ms, so a
+ * large retry budget turned exponential backoff into a tight retry storm
+ * against a database that was already contended. The delay is clamped to a
+ * configurable ceiling and, below that, to the timer maximum.
+ */
+/** Largest delay `setTimeout` honours (2^31-1 ms, about 24.8 days). */
+export declare const MAX_TIMER_DELAY_MS = 2147483647;
+/** Default ceiling for a single retry delay: 30 seconds. */
+export declare const DEFAULT_MAX_RETRY_DELAY_MS = 30000;
+/** Inputs to {@link computeRetryDelay}. */
+export interface RetryDelayOptions {
+    /** Base delay, doubled each retry. */
+    readonly retryDelayMs: number;
+    /** Ceiling for any single delay. */
+    readonly maxRetryDelayMs?: number;
+    /** `"full"` picks uniformly in `[0, delay]` to spread contending retries. */
+    readonly jitter?: "none" | "full";
+    /** Random source in `[0, 1)`, injectable for tests. */
+    readonly random?: () => number;
+}
+/**
+ * Delay before retry number `attempt` (1-based).
+ *
+ * @param attempt - The retry about to be made, starting at 1.
+ * @param options - Base delay, ceiling and jitter.
+ * @returns A finite delay in `[0, min(maxRetryDelayMs, 2^31-1)]`.
+ */
+export declare function computeRetryDelay(attempt: number, options: RetryDelayOptions): number;
+//# sourceMappingURL=transaction.backoff.d.ts.map

package/dist/transaction/transaction.backoff.js

@@ -0,0 +1,32 @@
+/**
+ * @zudojs/database — Transaction retry backoff.
+ *
+ * `retryDelayMs * 2^(attempt-1)` passes 2^31-1 ms by attempt 26 at the
+ * default 100 ms base. `setTimeout` then warns and fires after 1 ms, so a
+ * large retry budget turned exponential backoff into a tight retry storm
+ * against a database that was already contended. The delay is clamped to a
+ * configurable ceiling and, below that, to the timer maximum.
+ */
+/** Largest delay `setTimeout` honours (2^31-1 ms, about 24.8 days). */
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/** Default ceiling for a single retry delay: 30 seconds. */
+export const DEFAULT_MAX_RETRY_DELAY_MS = 30_000;
+/**
+ * Delay before retry number `attempt` (1-based).
+ *
+ * @param attempt - The retry about to be made, starting at 1.
+ * @param options - Base delay, ceiling and jitter.
+ * @returns A finite delay in `[0, min(maxRetryDelayMs, 2^31-1)]`.
+ */
+export function computeRetryDelay(attempt, options) {
+    const ceiling = Math.min(Math.max(0, options.maxRetryDelayMs ?? DEFAULT_MAX_RETRY_DELAY_MS), MAX_TIMER_DELAY_MS);
+    const exponential = options.retryDelayMs * 2 ** Math.max(0, attempt - 1);
+    const capped = Number.isFinite(exponential)
+        ? Math.min(exponential, ceiling)
+        : ceiling;
+    if (options.jitter !== "full")
+        return capped;
+    const random = options.random ?? Math.random;
+    return Math.floor(random() * (capped + 1));
+}
+//# sourceMappingURL=transaction.backoff.js.map

package/dist/transaction/transaction.core.d.ts

@@ -41,6 +41,16 @@ export interface TransactionRetryOptions extends ManagedTransactionOptions {
      * Base delay between attempts (doubles each retry). Defaults to 100 ms.
      */
     readonly retryDelayMs?: number;
+    /**
+     * Ceiling for a single retry delay. Defaults to 30000 ms, and never
+     * exceeds the timer maximum (2^31-1 ms).
+     */
+    readonly maxRetryDelayMs?: number;
+    /**
+     * `"full"` spreads each delay uniformly over `[0, delay]` so contending
+     * callers do not retry in lockstep. Defaults to `"none"`.
+     */
+    readonly jitter?: "none" | "full";
     /**
      * Predicate deciding whether an error is retryable. Defaults to
      * {@link isRetryableTransactionError} (Prisma P2034/P2028/P1017 and

package/dist/transaction/transaction.core.js

@@ -1,5 +1,6 @@
 import { DatabaseOperation } from "@zudojs/errors";
 import { isDatabaseErrorLike, isRetryableTransactionError, normalizeDatabaseError, withDatabaseErrorMetadata, } from "../databaseClient/databaseClient.errors.js";
+import { computeRetryDelay } from "./transaction.backoff.js";
 /**
  * Generates a transaction identifier.
  */
@@ -94,7 +95,13 @@ export async function withTransactionRetry(client, callback, options = {}) {
                 throw error;
             }
             attempt += 1;
-            const delay = retryDelayMs * Math.pow(2, attempt - 1);
+            const delay = computeRetryDelay(attempt, {
+                retryDelayMs,
+                ...(options.maxRetryDelayMs !== undefined
+                    ? { maxRetryDelayMs: options.maxRetryDelayMs }
+                    : {}),
+                ...(options.jitter !== undefined ? { jitter: options.jitter } : {}),
+            });
             if (delay > 0)
                 await sleep(delay);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/database",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Database abstraction layer with clients, repositories, transactions, and query building for Zudojs applications.",
   "license": "MIT",
   "author": {
@@ -41,7 +41,9 @@
     "!dist/.tsbuildinfo"
   ],
   "dependencies": {
-    "@zudojs/errors": "1.0.1"
+    "@zudojs/errors": "1.2.0",
+    "@zudojs/logger": "1.3.0",
+    "@zudojs/types": "1.1.1"
   },
   "peerDependencies": {
     "@prisma/client": ">=7.0.0 <8"