@zudojs/database 0.1.0 → 1.0.0

package/dist/cache/cache.memory.js

@@ -1,20 +1,26 @@
 import { DatabaseError } from "@zudojs/errors";
 /**
- * In-memory cache implementation for database read results.
+ * In-memory LRU cache for database read results.
  *
- * This cache is intentionally process-local. It should not be used
- * where multiple application instances require shared cache state.
+ * This cache is process-local and is not transaction-aware: never populate
+ * it from inside a transaction that may still roll back, because other
+ * callers would observe the uncommitted value.
  */
 export class MemoryDatabaseCache {
     entries = new Map();
     hits = 0;
     misses = 0;
+    evictions = 0;
     defaultTtlMs;
+    maxEntries;
+    pruneTimer;
     constructor(options = {}) {
         this.defaultTtlMs = normalizeTtl(options.ttlMs);
+        this.maxEntries = normalizeMaxEntries(options.maxEntries);
+        this.startPruning(options.pruneIntervalMs);
     }
     /**
-     * Gets a cached value.
+     * Gets a cached value and marks it as recently used.
      */
     get(key) {
         validateKey(key);
@@ -28,31 +34,36 @@ export class MemoryDatabaseCache {
             this.misses += 1;
             return undefined;
         }
+        // Re-insert to move the key to the most-recently-used position.
+        this.entries.delete(key);
+        this.entries.set(key, entry);
         this.hits += 1;
         return entry.value;
     }
     /**
-     * Sets a cached value.
+     * Sets a cached value, evicting the least recently used entry when the
+     * cache is full.
      */
     set(key, value, options = {}) {
         validateKey(key);
         const ttlMs = normalizeTtl(options.ttlMs ?? this.defaultTtlMs);
         const createdAt = Date.now();
+        this.entries.delete(key);
         this.entries.set(key, {
             value,
             createdAt,
             expiresAt: ttlMs === undefined ? undefined : createdAt + ttlMs,
         });
+        this.evictOverflow();
     }
     /**
-     * Checks whether a valid cached value exists.
+     * Checks whether a valid cached value exists (does not touch recency).
      */
     has(key) {
         validateKey(key);
         const entry = this.entries.get(key);
-        if (!entry) {
+        if (!entry)
             return false;
-        }
         if (isExpired(entry)) {
             this.entries.delete(key);
             return false;
@@ -85,6 +96,15 @@ export class MemoryDatabaseCache {
         }
         return removed;
     }
+    /**
+     * Stops the background prune timer.
+     */
+    dispose() {
+        if (this.pruneTimer) {
+            clearInterval(this.pruneTimer);
+            this.pruneTimer = undefined;
+        }
+    }
     /**
      * Returns the number of valid entries.
      */
@@ -103,22 +123,46 @@ export class MemoryDatabaseCache {
             hits: this.hits,
             misses: this.misses,
             hitRate: total === 0 ? 0 : this.hits / total,
+            evictions: this.evictions,
         };
     }
     /**
-     * Resets hit/miss counters.
+     * Resets hit/miss/eviction counters.
      */
     resetStats() {
         this.hits = 0;
         this.misses = 0;
+        this.evictions = 0;
     }
     /**
-     * Returns all currently valid cache keys.
+     * Returns all currently valid cache keys (least recently used first).
      */
     keys() {
         this.prune();
         return Object.freeze([...this.entries.keys()]);
     }
+    evictOverflow() {
+        if (this.maxEntries === undefined)
+            return;
+        while (this.entries.size > this.maxEntries) {
+            const oldest = this.entries.keys().next();
+            if (oldest.done)
+                break;
+            this.entries.delete(oldest.value);
+            this.evictions += 1;
+        }
+    }
+    startPruning(intervalMs) {
+        if (intervalMs === undefined)
+            return;
+        if (!Number.isFinite(intervalMs) || intervalMs <= 0) {
+            throw new TypeError("Cache prune interval must be a positive finite number.");
+        }
+        this.pruneTimer = setInterval(() => {
+            this.prune();
+        }, Math.floor(intervalMs));
+        this.pruneTimer.unref?.();
+    }
 }
 /**
  * Creates an in-memory database cache.
@@ -126,34 +170,51 @@ export class MemoryDatabaseCache {
 export function createDatabaseCache(options = {}) {
     return new MemoryDatabaseCache(options);
 }
+/**
+ * Separator used between cache key parts.
+ */
+export const CACHE_KEY_SEPARATOR = ":";
 /**
  * Builds a stable cache key from a namespace and parts.
+ *
+ * Each part is serialised deterministically (nested keys sorted at every
+ * level). Plain string parts are escaped so that a separator inside a part
+ * cannot collide with the part boundary: `("ns", "a:b", "c")` and
+ * `("ns", "a", "b:c")` produce different keys; serialised objects are
+ * self-delimiting and are left as-is. The namespace itself is used verbatim
+ * so it can be used as a prefix with {@link invalidateByPrefix}.
  */
 export function createCacheKey(namespace, ...parts) {
     validateKey(namespace);
-    return [namespace, ...parts.map(serializeCachePart)].join(":");
+    return [
+        namespace,
+        ...parts.map((part) => typeof part === "string"
+            ? escapeCachePart(part)
+            : serializeCachePart(part)),
+    ].join(CACHE_KEY_SEPARATOR);
+}
+/**
+ * Escapes separators and backslashes inside a key part.
+ */
+export function escapeCachePart(part) {
+    return part.replace(/\\/g, "\\\\").replace(/:/g, "\\:");
 }
 /**
  * Serializes a cache key component deterministically.
+ *
+ * Objects are serialised with keys sorted at every nesting level;
+ * `bigint`, `Date`, `undefined`, `Map` and `Set` are handled explicitly.
+ * Functions and symbols cannot be part of a cache key and throw.
  */
 export function serializeCachePart(value) {
-    if (value === null) {
-        return "null";
-    }
-    if (value === undefined) {
-        return "undefined";
-    }
     if (typeof value === "string" ||
         typeof value === "number" ||
         typeof value === "boolean" ||
         typeof value === "bigint") {
         return String(value);
     }
-    if (value instanceof Date) {
-        return value.toISOString();
-    }
     try {
-        return JSON.stringify(value, Object.keys(value).sort());
+        return stableSerialize(value, new Set());
     }
     catch (error) {
         throw new DatabaseError("Unable to serialize database cache key.", {
@@ -161,8 +222,70 @@ export function serializeCachePart(value) {
         });
     }
 }
+function stableSerialize(value, seen) {
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        return "undefined";
+    switch (typeof value) {
+        case "string":
+            return JSON.stringify(value);
+        case "number":
+            return Number.isFinite(value) ? String(value) : JSON.stringify(String(value));
+        case "boolean":
+            return String(value);
+        case "bigint":
+            return `${value.toString()}n`;
+        case "function":
+        case "symbol":
+            throw new TypeError(`Cannot serialize a ${typeof value} as a cache key part.`);
+        default:
+            break;
+    }
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime()) ? '"Invalid Date"' : JSON.stringify(value.toISOString());
+    }
+    if (typeof value === "object") {
+        if (seen.has(value)) {
+            throw new TypeError("Cannot serialize a circular structure as a cache key part.");
+        }
+        seen.add(value);
+        try {
+            if (Array.isArray(value)) {
+                return `[${value.map((item) => stableSerialize(item, seen)).join(",")}]`;
+            }
+            if (value instanceof Set) {
+                return `Set[${[...value].map((item) => stableSerialize(item, seen)).sort().join(",")}]`;
+            }
+            if (value instanceof Map) {
+                const entries = [...value.entries()]
+                    .map(([k, v]) => `${stableSerialize(k, seen)}=>${stableSerialize(v, seen)}`)
+                    .sort();
+                return `Map{${entries.join(",")}}`;
+            }
+            if (typeof value.toJSON === "function") {
+                return stableSerialize(value.toJSON(), seen);
+            }
+            const record = value;
+            const keys = Object.keys(record).sort();
+            const fields = keys
+                .filter((key) => record[key] !== undefined)
+                .map((key) => `${JSON.stringify(key)}:${stableSerialize(record[key], seen)}`);
+            return `{${fields.join(",")}}`;
+        }
+        finally {
+            seen.delete(value);
+        }
+    }
+    return JSON.stringify(String(value));
+}
+const inflightLoaders = new WeakMap();
 /**
  * Wraps a cache around an asynchronous loader.
+ *
+ * Concurrent misses for the same key on the same cache share one loader
+ * call (stampede protection). Values are stored only when the loader
+ * resolves; `undefined` results are never cached.
  */
 export async function getOrSet(cache, key, loader, options) {
     validateKey(key);
@@ -170,43 +293,61 @@ export async function getOrSet(cache, key, loader, options) {
         throw new TypeError("A cache loader function is required.");
     }
     const cached = cache.get(key);
-    if (cached !== undefined) {
+    if (cached !== undefined)
         return cached;
+    let inflight = inflightLoaders.get(cache);
+    if (!inflight) {
+        inflight = new Map();
+        inflightLoaders.set(cache, inflight);
     }
-    const value = await loader();
-    cache.set(key, value, options);
-    return value;
+    const pending = inflight.get(key);
+    if (pending)
+        return pending;
+    const promise = (async () => {
+        try {
+            const value = await loader();
+            if (value !== undefined)
+                cache.set(key, value, options);
+            return value;
+        }
+        finally {
+            inflight.delete(key);
+        }
+    })();
+    inflight.set(key, promise);
+    return promise;
 }
 /**
  * Invalidates all entries whose keys start with a prefix.
  *
- * This is useful when a write invalidates a group of related reads.
+ * Matching is separator-aware: `"user"` matches `"user"` and `"user:…"`
+ * but not `"users:…"`. Pass a prefix ending in the separator to match a
+ * namespace only.
  */
 export function invalidateByPrefix(cache, prefix) {
     validateKey(prefix);
+    if (typeof cache.keys !== "function") {
+        throw new TypeError("The cache does not expose keys(); cannot invalidate by prefix.");
+    }
+    const normalized = prefix.endsWith(CACHE_KEY_SEPARATOR)
+        ? prefix.slice(0, -CACHE_KEY_SEPARATOR.length)
+        : prefix;
+    const withSeparator = normalized + CACHE_KEY_SEPARATOR;
     let removed = 0;
     for (const key of cache.keys()) {
-        if (key.startsWith(prefix)) {
-            if (cache.delete(key)) {
+        if (key === normalized || key.startsWith(withSeparator)) {
+            if (cache.delete(key))
                 removed += 1;
-            }
         }
     }
     return removed;
 }
-/**
- * Checks whether a cache entry has expired.
- */
 function isExpired(entry) {
     return entry.expiresAt !== undefined && entry.expiresAt <= Date.now();
 }
-/**
- * Normalizes a TTL value.
- */
 function normalizeTtl(ttlMs) {
-    if (ttlMs === undefined) {
+    if (ttlMs === undefined)
         return undefined;
-    }
     if (!Number.isFinite(ttlMs)) {
         throw new TypeError("Cache TTL must be a finite number.");
     }
@@ -215,9 +356,14 @@ function normalizeTtl(ttlMs) {
     }
     return Math.floor(ttlMs);
 }
-/**
- * Validates a cache key.
- */
+function normalizeMaxEntries(maxEntries) {
+    if (maxEntries === undefined)
+        return undefined;
+    if (!Number.isInteger(maxEntries) || maxEntries <= 0) {
+        throw new TypeError("Cache maxEntries must be a positive integer.");
+    }
+    return maxEntries;
+}
 function validateKey(key) {
     if (typeof key !== "string" || key.trim().length === 0) {
         throw new TypeError("A non-empty cache key is required.");

package/dist/cache/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * @zudojs/database — Database Cache
  *
- * In-memory cache for database read results.
+ * In-memory LRU cache for database read results.
  */
-export { MemoryDatabaseCache, createDatabaseCache, createCacheKey, serializeCachePart, getOrSet, invalidateByPrefix, type CacheEntry, type CacheOptions, type CacheStats, type DatabaseCache, } from "./cache.memory.js";
+export { MemoryDatabaseCache, createDatabaseCache, createCacheKey, escapeCachePart, serializeCachePart, getOrSet, invalidateByPrefix, CACHE_KEY_SEPARATOR, type CacheEntry, type CacheOptions, type MemoryCacheOptions, type CacheStats, type DatabaseCache, } from "./cache.memory.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/cache/index.js

@@ -1,7 +1,7 @@
 /**
  * @zudojs/database — Database Cache
  *
- * In-memory cache for database read results.
+ * In-memory LRU cache for database read results.
  */
-export { MemoryDatabaseCache, createDatabaseCache, createCacheKey, serializeCachePart, getOrSet, invalidateByPrefix, } from "./cache.memory.js";
+export { MemoryDatabaseCache, createDatabaseCache, createCacheKey, escapeCachePart, serializeCachePart, getOrSet, invalidateByPrefix, CACHE_KEY_SEPARATOR, } from "./cache.memory.js";
 //# sourceMappingURL=index.js.map

package/dist/database/database.core.d.ts

@@ -0,0 +1,91 @@
+import { DatabaseClient, type DatabaseClientOptions, type DatabaseTransactionContext, type PrismaClientLike } from "../databaseClient/databaseClient.core.js";
+import type { DatabaseHealth, DatabaseStatus, TransactionCallback, TransactionOptions } from "../databaseType/databaseType.type.js";
+/**
+ * Database facade used by the application layer.
+ *
+ * This module provides a single database lifecycle entry point while
+ * keeping the underlying Prisma client implementation inside the
+ * database package.
+ */
+export declare class Database {
+    private readonly client;
+    /**
+     * @param options Client options, or an existing {@link DatabaseClient}
+     * to wrap so a single client is shared by the facade and other managers.
+     */
+    constructor(options?: DatabaseClientOptions | DatabaseClient);
+    /**
+     * Initializes the database connection.
+     */
+    connect(): Promise<void>;
+    /**
+     * Closes the database connection.
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Ensures the database is connected.
+     */
+    ensureConnected(): Promise<void>;
+    /**
+     * Checks database connectivity.
+     */
+    ping(): Promise<void>;
+    /**
+     * Returns the current database status.
+     */
+    getStatus(): DatabaseStatus;
+    /**
+     * Returns database health information.
+     */
+    healthCheck(): Promise<DatabaseHealth>;
+    /**
+     * Executes work inside a database transaction.
+     */
+    transaction<TResult>(callback: TransactionCallback<DatabaseTransactionContext, TResult>, options?: TransactionOptions): Promise<TResult>;
+    /**
+     * Returns the underlying database client.
+     *
+     * This should primarily be used by repository and infrastructure
+     * implementations that require direct Prisma access.
+     */
+    getClient(): DatabaseClient;
+    /**
+     * Returns the underlying Prisma client.
+     */
+    getPrisma(): PrismaClientLike;
+    /**
+     * Releases all database resources.
+     */
+    destroy(): Promise<void>;
+}
+/**
+ * Creates a database facade.
+ */
+export declare function createDatabase(options?: DatabaseClientOptions | DatabaseClient): Database;
+/**
+ * Returns the shared application database instance.
+ *
+ * The connection is not established automatically. Call
+ * `connect()` during application bootstrap.
+ *
+ * @throws {TypeError} when options are supplied after the shared instance
+ * has already been created; they would otherwise be silently ignored.
+ * Call {@link resetDatabase} first to reconfigure.
+ */
+export declare function getDatabase(options?: DatabaseClientOptions | DatabaseClient): Database;
+/**
+ * Connects the shared application database.
+ */
+export declare function connectDatabase(options?: DatabaseClientOptions | DatabaseClient): Promise<Database>;
+/**
+ * Disconnects the shared application database.
+ */
+export declare function disconnectDatabase(): Promise<void>;
+/**
+ * Resets the shared database instance.
+ *
+ * Primarily useful for application shutdown, tests, and isolated
+ * runtime environments.
+ */
+export declare function resetDatabase(): Promise<void>;
+//# sourceMappingURL=database.core.d.ts.map

package/dist/database/database.core.js

@@ -1,4 +1,4 @@
-import { createDatabaseClient, } from "../databaseClient/databaseClient.core.js";
+import { DatabaseClient, createDatabaseClient, } from "../databaseClient/databaseClient.core.js";
 /**
  * Database facade used by the application layer.
  *
@@ -8,8 +8,13 @@ import { createDatabaseClient, } from "../databaseClient/databaseClient.core.js"
  */
 export class Database {
     client;
+    /**
+     * @param options Client options, or an existing {@link DatabaseClient}
+     * to wrap so a single client is shared by the facade and other managers.
+     */
     constructor(options = {}) {
-        this.client = createDatabaseClient(options);
+        this.client =
+            options instanceof DatabaseClient ? options : createDatabaseClient(options);
     }
     /**
      * Initializes the database connection.
@@ -93,10 +98,19 @@ let defaultDatabase;
  *
  * The connection is not established automatically. Call
  * `connect()` during application bootstrap.
+ *
+ * @throws {TypeError} when options are supplied after the shared instance
+ * has already been created; they would otherwise be silently ignored.
+ * Call {@link resetDatabase} first to reconfigure.
  */
 export function getDatabase(options = {}) {
     if (!defaultDatabase) {
         defaultDatabase = createDatabase(options);
+        return defaultDatabase;
+    }
+    const hasOptions = options instanceof DatabaseClient || Object.keys(options).length > 0;
+    if (hasOptions && !(options instanceof DatabaseClient && defaultDatabase.getClient() === options)) {
+        throw new TypeError("The shared database instance already exists; options passed to getDatabase() would be ignored. Call resetDatabase() before reconfiguring.");
     }
     return defaultDatabase;
 }
@@ -124,10 +138,13 @@ export async function disconnectDatabase() {
  * runtime environments.
  */
 export async function resetDatabase() {
-    if (!defaultDatabase) {
+    const database = defaultDatabase;
+    if (!database) {
         return;
     }
-    await defaultDatabase.destroy();
+    // Clear the singleton first so a failing destroy() never leaves a stale
+    // instance behind.
     defaultDatabase = undefined;
+    await database.destroy();
 }
 //# sourceMappingURL=database.core.js.map