express-memorize 1.4.0 → 2.0.0

package/dist/adapters/nestjs.js

@@ -0,0 +1,194 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemorizeModule = exports.MemorizeInterceptor = exports.MEMORIZE_MODULE_OPTIONS = exports.MEMORIZE_CACHE = void 0;
+exports.MemorizeCacheKey = MemorizeCacheKey;
+exports.MemorizeTtl = MemorizeTtl;
+exports.MemorizeNoCache = MemorizeNoCache;
+const memorize_1 = require("../memorize");
+exports.MEMORIZE_CACHE = Symbol('MEMORIZE_CACHE');
+exports.MEMORIZE_MODULE_OPTIONS = Symbol('MEMORIZE_MODULE_OPTIONS');
+const CACHE_KEY_METADATA = 'express-memorize:nestjs:cache-key';
+const TTL_METADATA = 'express-memorize:nestjs:ttl';
+const NO_CACHE_METADATA = 'express-memorize:nestjs:no-cache';
+const metadataFallback = new WeakMap();
+function setMetadata(key, value, target) {
+    var _a;
+    const reflect = Reflect;
+    if (reflect.defineMetadata) {
+        reflect.defineMetadata(key, value, target);
+        return;
+    }
+    const existing = (_a = metadataFallback.get(target)) !== null && _a !== void 0 ? _a : new Map();
+    existing.set(key, value);
+    metadataFallback.set(target, existing);
+}
+function getOwnMetadata(key, target) {
+    var _a;
+    const reflect = Reflect;
+    const value = reflect.getMetadata ? reflect.getMetadata(key, target) : (_a = metadataFallback.get(target)) === null || _a === void 0 ? void 0 : _a.get(key);
+    return value;
+}
+function getMetadata(key, context) {
+    var _a;
+    return (_a = getOwnMetadata(key, context.getHandler())) !== null && _a !== void 0 ? _a : getOwnMetadata(key, context.getClass());
+}
+function createMetadataDecorator(key, value) {
+    return (target, propertyKey, descriptor) => {
+        var _a;
+        setMetadata(key, value, (_a = descriptor === null || descriptor === void 0 ? void 0 : descriptor.value) !== null && _a !== void 0 ? _a : target);
+    };
+}
+function setCacheHeader(response, value) {
+    if (!response || response.headersSent)
+        return;
+    if (response.setHeader)
+        response.setHeader('X-Cache', value);
+    else if (response.header)
+        response.header('X-Cache', value);
+}
+function defaultKey(request) {
+    var _a, _b;
+    return (_b = (_a = request.originalUrl) !== null && _a !== void 0 ? _a : request.url) !== null && _b !== void 0 ? _b : '';
+}
+function parseCachedBody(body) {
+    if (typeof body !== 'string')
+        return body;
+    try {
+        return JSON.parse(body);
+    }
+    catch (_a) {
+        return body;
+    }
+}
+function toObservable(value) {
+    return {
+        subscribe(observerOrNext, _error, complete) {
+            var _a, _b;
+            if (typeof observerOrNext === 'function') {
+                observerOrNext(value);
+                complete === null || complete === void 0 ? void 0 : complete();
+                return { unsubscribe() { } };
+            }
+            (_a = observerOrNext === null || observerOrNext === void 0 ? void 0 : observerOrNext.next) === null || _a === void 0 ? void 0 : _a.call(observerOrNext, value);
+            (_b = observerOrNext === null || observerOrNext === void 0 ? void 0 : observerOrNext.complete) === null || _b === void 0 ? void 0 : _b.call(observerOrNext);
+            return { unsubscribe() { } };
+        },
+    };
+}
+function normalizeObserver(observerOrNext, error, complete) {
+    if (typeof observerOrNext === 'function') {
+        return { next: observerOrNext, error, complete };
+    }
+    return observerOrNext !== null && observerOrNext !== void 0 ? observerOrNext : {};
+}
+function cacheObservable(source, onCompleteValue) {
+    return {
+        subscribe(observerOrNext, error, complete) {
+            const observer = normalizeObserver(observerOrNext, error, complete);
+            let hasValue = false;
+            let latestValue;
+            return source.subscribe({
+                next(value) {
+                    var _a;
+                    hasValue = true;
+                    latestValue = value;
+                    (_a = observer.next) === null || _a === void 0 ? void 0 : _a.call(observer, value);
+                },
+                error(err) {
+                    var _a;
+                    (_a = observer.error) === null || _a === void 0 ? void 0 : _a.call(observer, err);
+                },
+                complete() {
+                    var _a;
+                    if (hasValue)
+                        onCompleteValue(latestValue);
+                    (_a = observer.complete) === null || _a === void 0 ? void 0 : _a.call(observer);
+                },
+            });
+        },
+    };
+}
+/**
+ * Decorates a controller or handler with a fixed cache key.
+ */
+function MemorizeCacheKey(key) {
+    return createMetadataDecorator(CACHE_KEY_METADATA, key);
+}
+/**
+ * Decorates a controller or handler with a TTL override in milliseconds.
+ */
+function MemorizeTtl(ttl) {
+    return createMetadataDecorator(TTL_METADATA, ttl);
+}
+/**
+ * Decorates a controller or handler so the interceptor bypasses cache reads and writes.
+ */
+function MemorizeNoCache() {
+    return createMetadataDecorator(NO_CACHE_METADATA, true);
+}
+/**
+ * NestJS interceptor backed by a shared {@link Memorize} cache instance.
+ *
+ * Register through {@link MemorizeModule.forRoot} for dependency injection, or
+ * instantiate directly in tests and small applications.
+ */
+class MemorizeInterceptor {
+    constructor(cache = (0, memorize_1.memorize)(), options = {}) {
+        this.cache = cache;
+        this.options = options;
+    }
+    intercept(context, next) {
+        var _a, _b, _c, _d;
+        const http = context.switchToHttp();
+        const request = http.getRequest();
+        const response = http.getResponse();
+        if (request.method !== 'GET') {
+            return next.handle();
+        }
+        const noCache = getMetadata(NO_CACHE_METADATA, context);
+        if (noCache) {
+            setCacheHeader(response, 'BYPASS');
+            return next.handle();
+        }
+        const metadataKey = getMetadata(CACHE_KEY_METADATA, context);
+        const key = (_c = metadataKey !== null && metadataKey !== void 0 ? metadataKey : (_b = (_a = this.options).key) === null || _b === void 0 ? void 0 : _b.call(_a, { context, request })) !== null && _c !== void 0 ? _c : defaultKey(request);
+        const ttl = (_d = getMetadata(TTL_METADATA, context)) !== null && _d !== void 0 ? _d : this.options.ttl;
+        const cached = this.cache._store.getRaw(key);
+        if (cached) {
+            setCacheHeader(response, 'HIT');
+            return toObservable(parseCachedBody(cached.body));
+        }
+        setCacheHeader(response, 'MISS');
+        return cacheObservable(next.handle(), (value) => {
+            if (value === undefined || response.headersSent)
+                return;
+            this.cache.set(key, value, ttl);
+        });
+    }
+}
+exports.MemorizeInterceptor = MemorizeInterceptor;
+/**
+ * Dynamic Nest module that provides a shared cache and interceptor.
+ */
+class MemorizeModule {
+    static forRoot(options = {}) {
+        return {
+            module: MemorizeModule,
+            providers: [
+                { provide: exports.MEMORIZE_MODULE_OPTIONS, useValue: options },
+                {
+                    provide: exports.MEMORIZE_CACHE,
+                    useFactory: () => (0, memorize_1.memorize)(options),
+                },
+                {
+                    provide: MemorizeInterceptor,
+                    useFactory: (cache, moduleOptions) => new MemorizeInterceptor(cache, moduleOptions),
+                    inject: [exports.MEMORIZE_CACHE, exports.MEMORIZE_MODULE_OPTIONS],
+                },
+            ],
+            exports: [exports.MEMORIZE_CACHE, MemorizeInterceptor],
+        };
+    }
+}
+exports.MemorizeModule = MemorizeModule;
+//# sourceMappingURL=nestjs.js.map

package/dist/adapters/nestjs.js.map

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

package/dist/domain/CacheEntry.d.ts

@@ -12,5 +12,7 @@ export interface CacheEntry {
     expiresAt: number | null;
     /** Number of times this entry has been requested (including the initial cache miss). */
     hits: number;
+    /** Approximate size of the cached body in bytes. */
+    size: number;
 }
 //# sourceMappingURL=CacheEntry.d.ts.map

package/dist/domain/CacheEntry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CacheEntry.d.ts","sourceRoot":"","sources":["../../src/domain/CacheEntry.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,IAAI,EAAE,OAAO,CAAC;IACd,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,WAAW,EAAE,MAAM,CAAC;IACpB,qFAAqF;IACrF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;CACd"}
+{"version":3,"file":"CacheEntry.d.ts","sourceRoot":"","sources":["../../src/domain/CacheEntry.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,IAAI,EAAE,OAAO,CAAC;IACd,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,4FAA4F;IAC5F,WAAW,EAAE,MAAM,CAAC;IACpB,qFAAqF;IACrF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,wFAAwF;IACxF,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;CACd"}

package/dist/domain/Memorize.d.ts

@@ -6,6 +6,9 @@ import { MemorizeSetEvent } from './MemorizeSetEvent';
 import { MemorizeDeleteEvent } from './MemorizeDeleteEvent';
 import { MemorizeExpireEvent } from './MemorizeExpireEvent';
 import { MemorizeEmptyEvent } from './MemorizeEmptyEvent';
+import { MemorizeEvictEvent } from './MemorizeEvictEvent';
+import { MemorizeStats } from './MemorizeStats';
+import { MemorizeStore } from '../MemorizeStore';
 /**
  * The cache instance returned by {@link memorize}.
  *
@@ -23,12 +26,22 @@ import { MemorizeEmptyEvent } from './MemorizeEmptyEvent';
  * // Global middleware — caches every GET route automatically
  * app.use(cache());
  *
+ * // Direct service-level usage
+ * const users = await cache.remember('users:list', () => userService.findAll());
+ *
  * // Cache management
  * cache.delete('/users');
  * cache.clear();
  * ```
  */
 export interface Memorize {
+    /**
+     * Returns an Express `RequestHandler` that caches `GET` responses with a `2xx`
+     * status code. Alias of {@link Memorize.express} kept for backwards compatibility.
+     *
+     * @param options - Optional per-route options (e.g. TTL override).
+     */
+    (options?: MemorizeCallOptions): RequestHandler;
     /**
      * Returns an Express `RequestHandler` that caches `GET` responses with a `2xx`
      * status code.
@@ -43,12 +56,58 @@ export interface Memorize {
      *
      * @example
      * ```ts
-     * app.get('/users',    cache(),               handler); // global TTL
-     * app.get('/products', cache({ ttl: 5_000 }), handler); // 5-second override
-     * app.use(cache());                                      // global middleware
+     * app.get('/users',    cache.express(),               handler); // global TTL
+     * app.get('/products', cache.express({ ttl: 5_000 }), handler); // 5-second override
+     * app.use(cache.express());                                      // global middleware
      * ```
      */
-    (options?: MemorizeCallOptions): RequestHandler;
+    express(options?: MemorizeCallOptions): RequestHandler;
+    /**
+     * Stores an arbitrary value in the cache under the given key.
+     *
+     * The value is serialized with `JSON.stringify`. Retrieve it with {@link getValue}.
+     *
+     * @param key - Cache key.
+     * @param value - Value to cache.
+     * @param ttl - Time-to-live in milliseconds. Defaults to the global TTL.
+     *
+     * @example
+     * ```ts
+     * cache.set('config', { theme: 'dark' });
+     * cache.set('config', { theme: 'dark' }, 60_000);
+     * ```
+     */
+    set<T>(key: string, value: T, ttl?: number): void;
+    /**
+     * Returns the cached value for the given key, or `undefined` if the key does
+     * not exist or has expired.
+     *
+     * Values stored via {@link set} or {@link remember} are deserialized with
+     * `JSON.parse`.
+     *
+     * @param key - Cache key.
+     *
+     * @example
+     * ```ts
+     * const config = cache.getValue<Config>('config');
+     * ```
+     */
+    getValue<T>(key: string): T | undefined;
+    /**
+     * Returns the cached value for the given key if it exists, otherwise calls
+     * `factory`, caches the result, and returns it.
+     *
+     * @param key - Cache key.
+     * @param factory - Async or sync function that produces the value on a cache miss.
+     * @param ttl - Time-to-live in milliseconds. Defaults to the global TTL.
+     *
+     * @example
+     * ```ts
+     * const users = await cache.remember('users:list', () => userService.findAll());
+     * const users = await cache.remember('users:list', () => userService.findAll(), 30_000);
+     * ```
+     */
+    remember<T>(key: string, factory: () => T | Promise<T>, ttl?: number): Promise<T>;
     /**
      * Returns the {@link CacheInfo} for a specific cache key, or `null` if the key
      * does not exist or has expired.
@@ -144,5 +203,41 @@ export interface Memorize {
     on(event: MemorizeEventType.Delete, handler: (e: MemorizeDeleteEvent) => void): void;
     on(event: MemorizeEventType.Expire, handler: (e: MemorizeExpireEvent) => void): void;
     on(event: MemorizeEventType.Empty, handler: (e: MemorizeEmptyEvent) => void): void;
+    on(event: MemorizeEventType.Evict, handler: (e: MemorizeEvictEvent) => void): void;
+    /**
+     * Returns the number of active (non-expired) cache entries.
+     *
+     * @example
+     * ```ts
+     * console.log(`${cache.size()} entries in cache`);
+     * ```
+     */
+    size(): number;
+    /**
+     * Returns the approximate total byte size of all cached bodies.
+     *
+     * The value is an estimate based on UTF-8 encoding for strings and
+     * `byteLength` for buffers. It may not reflect actual memory usage.
+     *
+     * @example
+     * ```ts
+     * console.log(`~${cache.byteSize()} bytes cached`);
+     * ```
+     */
+    byteSize(): number;
+    /**
+     * Returns aggregate cache statistics.
+     *
+     * @example
+     * ```ts
+     * const { entries, maxEntries, byteSize } = cache.getStats();
+     * ```
+     */
+    getStats(): MemorizeStats;
+    /**
+     * The underlying store. Intended for use by framework adapters only.
+     * @internal
+     */
+    _store: MemorizeStore;
 }
 //# sourceMappingURL=Memorize.d.ts.map

package/dist/domain/Memorize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Memorize.d.ts","sourceRoot":"","sources":["../../src/domain/Memorize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,QAAQ;IACvB;;;;;;;;;;;;;;;;;;OAkBG;IACH,CAAC,OAAO,CAAC,EAAE,mBAAmB,GAAG,cAAc,CAAC;IAEhD;;;;;;;;;;;OAWG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAAC;IAEnC;;;;;;;OAOG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAEpC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAE7B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAExC;;;;;;;;OAQG;IACH,KAAK,IAAI,IAAI,CAAC;IAEd;;;;;;;;;;;;;;;;;OAiBG;IACH,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,GAAG,EAAK,OAAO,EAAE,CAAC,CAAC,EAAE,gBAAgB,KAAK,IAAI,GAAG,IAAI,CAAC;IAClF,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,mBAAmB,KAAK,IAAI,GAAG,IAAI,CAAC;IACrF,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,mBAAmB,KAAK,IAAI,GAAG,IAAI,CAAC;IACrF,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,KAAK,EAAG,OAAO,EAAE,CAAC,CAAC,EAAE,kBAAkB,KAAK,IAAI,GAAG,IAAI,CAAC;CACrF"}
+{"version":3,"file":"Memorize.d.ts","sourceRoot":"","sources":["../../src/domain/Memorize.ts"],"names":[],"mappings":"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"}

package/dist/domain/MemorizeEvent.d.ts

@@ -2,6 +2,7 @@ import { MemorizeSetEvent } from './MemorizeSetEvent';
 import { MemorizeDeleteEvent } from './MemorizeDeleteEvent';
 import { MemorizeExpireEvent } from './MemorizeExpireEvent';
 import { MemorizeEmptyEvent } from './MemorizeEmptyEvent';
+import { MemorizeEvictEvent } from './MemorizeEvictEvent';
 /** Union of all possible cache events. */
-export type MemorizeEvent = MemorizeSetEvent | MemorizeDeleteEvent | MemorizeExpireEvent | MemorizeEmptyEvent;
+export type MemorizeEvent = MemorizeSetEvent | MemorizeDeleteEvent | MemorizeExpireEvent | MemorizeEmptyEvent | MemorizeEvictEvent;
 //# sourceMappingURL=MemorizeEvent.d.ts.map

package/dist/domain/MemorizeEvent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MemorizeEvent.d.ts","sourceRoot":"","sources":["../../src/domain/MemorizeEvent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,0CAA0C;AAC1C,MAAM,MAAM,aAAa,GACrB,gBAAgB,GAChB,mBAAmB,GACnB,mBAAmB,GACnB,kBAAkB,CAAC"}
+{"version":3,"file":"MemorizeEvent.d.ts","sourceRoot":"","sources":["../../src/domain/MemorizeEvent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D,0CAA0C;AAC1C,MAAM,MAAM,aAAa,GACrB,gBAAgB,GAChB,mBAAmB,GACnB,mBAAmB,GACnB,kBAAkB,GAClB,kBAAkB,CAAC"}

package/dist/domain/MemorizeEventType.d.ts

@@ -17,6 +17,8 @@ export declare enum MemorizeEventType {
     /** Fired when an entry is automatically removed after its TTL elapses. */
     Expire = "expire",
     /** Fired when the last entry is removed, leaving the cache empty. */
-    Empty = "empty"
+    Empty = "empty",
+    /** Fired when an entry is automatically removed because `maxEntries` was reached. */
+    Evict = "evict"
 }
 //# sourceMappingURL=MemorizeEventType.d.ts.map

package/dist/domain/MemorizeEventType.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MemorizeEventType.d.ts","sourceRoot":"","sources":["../../src/domain/MemorizeEventType.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,oBAAY,iBAAiB;IAC3B,oDAAoD;IACpD,GAAG,QAAQ;IACX,2EAA2E;IAC3E,MAAM,WAAW;IACjB,0EAA0E;IAC1E,MAAM,WAAW;IACjB,qEAAqE;IACrE,KAAK,UAAU;CAChB"}
+{"version":3,"file":"MemorizeEventType.d.ts","sourceRoot":"","sources":["../../src/domain/MemorizeEventType.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,oBAAY,iBAAiB;IAC3B,oDAAoD;IACpD,GAAG,QAAQ;IACX,2EAA2E;IAC3E,MAAM,WAAW;IACjB,0EAA0E;IAC1E,MAAM,WAAW;IACjB,qEAAqE;IACrE,KAAK,UAAU;IACf,qFAAqF;IACrF,KAAK,UAAU;CAChB"}

package/dist/domain/MemorizeEventType.js

@@ -22,5 +22,7 @@ var MemorizeEventType;
     MemorizeEventType["Expire"] = "expire";
     /** Fired when the last entry is removed, leaving the cache empty. */
     MemorizeEventType["Empty"] = "empty";
+    /** Fired when an entry is automatically removed because `maxEntries` was reached. */
+    MemorizeEventType["Evict"] = "evict";
 })(MemorizeEventType || (exports.MemorizeEventType = MemorizeEventType = {}));
 //# sourceMappingURL=MemorizeEventType.js.map

package/dist/domain/MemorizeEventType.js.map

@@ -1 +1 @@
-{"version":3,"file":"MemorizeEventType.js","sourceRoot":"","sources":["../../src/domain/MemorizeEventType.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;GAUG;AACH,IAAY,iBASX;AATD,WAAY,iBAAiB;IAC3B,oDAAoD;IACpD,gCAAW,CAAA;IACX,2EAA2E;IAC3E,sCAAiB,CAAA;IACjB,0EAA0E;IAC1E,sCAAiB,CAAA;IACjB,qEAAqE;IACrE,oCAAe,CAAA;AACjB,CAAC,EATW,iBAAiB,iCAAjB,iBAAiB,QAS5B"}
+{"version":3,"file":"MemorizeEventType.js","sourceRoot":"","sources":["../../src/domain/MemorizeEventType.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;GAUG;AACH,IAAY,iBAWX;AAXD,WAAY,iBAAiB;IAC3B,oDAAoD;IACpD,gCAAW,CAAA;IACX,2EAA2E;IAC3E,sCAAiB,CAAA;IACjB,0EAA0E;IAC1E,sCAAiB,CAAA;IACjB,qEAAqE;IACrE,oCAAe,CAAA;IACf,qFAAqF;IACrF,oCAAe,CAAA;AACjB,CAAC,EAXW,iBAAiB,iCAAjB,iBAAiB,QAW5B"}

package/dist/domain/MemorizeEvictEvent.d.ts

@@ -0,0 +1,18 @@
+import { MemorizeEventType } from './MemorizeEventType';
+/**
+ * Emitted when an entry is automatically removed because the cache reached
+ * its `maxEntries` limit.
+ *
+ * @example
+ * ```ts
+ * cache.on(MemorizeEventType.Evict, (e) => {
+ *   console.log(`evicted ${e.key} to make room`);
+ * });
+ * ```
+ */
+export interface MemorizeEvictEvent {
+    type: MemorizeEventType.Evict;
+    /** The cache key that was evicted. */
+    key: string;
+}
+//# sourceMappingURL=MemorizeEvictEvent.d.ts.map

package/dist/domain/MemorizeEvictEvent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemorizeEvictEvent.d.ts","sourceRoot":"","sources":["../../src/domain/MemorizeEvictEvent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,iBAAiB,CAAC,KAAK,CAAC;IAC9B,sCAAsC;IACtC,GAAG,EAAE,MAAM,CAAC;CACb"}

package/dist/domain/MemorizeEvictEvent.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=MemorizeEvictEvent.js.map

package/dist/domain/MemorizeEvictEvent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemorizeEvictEvent.js","sourceRoot":"","sources":["../../src/domain/MemorizeEvictEvent.ts"],"names":[],"mappings":""}

package/dist/domain/MemorizeOptions.d.ts

@@ -12,5 +12,17 @@ export interface MemorizeOptions {
      * Omit to cache indefinitely. Can be overridden per-route via {@link MemorizeCallOptions}.
      */
     ttl?: number;
+    /**
+     * Maximum number of entries the cache may hold at any time.
+     *
+     * When the limit is reached, the least-recently-used (LRU) entry is evicted
+     * before the new one is stored. Omit for an unlimited cache.
+     *
+     * @example
+     * ```ts
+     * const cache = memorize({ maxEntries: 1_000 });
+     * ```
+     */
+    maxEntries?: number;
 }
 //# sourceMappingURL=MemorizeOptions.d.ts.map

package/dist/domain/MemorizeOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MemorizeOptions.d.ts","sourceRoot":"","sources":["../../src/domain/MemorizeOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd"}
+{"version":3,"file":"MemorizeOptions.d.ts","sourceRoot":"","sources":["../../src/domain/MemorizeOptions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IAEb;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB"}

package/dist/domain/MemorizeSetEvent.d.ts

@@ -21,5 +21,7 @@ export interface MemorizeSetEvent {
     contentType: string;
     /** Expiry timestamp in ms, or `null` if no TTL was set. */
     expiresAt: number | null;
+    /** Approximate byte size of the cached body. */
+    size: number;
 }
 //# sourceMappingURL=MemorizeSetEvent.d.ts.map

package/dist/domain/MemorizeSetEvent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MemorizeSetEvent.d.ts","sourceRoot":"","sources":["../../src/domain/MemorizeSetEvent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,iBAAiB,CAAC,GAAG,CAAC;IAC5B,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,gCAAgC;IAChC,IAAI,EAAE,OAAO,CAAC;IACd,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B"}
+{"version":3,"file":"MemorizeSetEvent.d.ts","sourceRoot":"","sources":["../../src/domain/MemorizeSetEvent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,iBAAiB,CAAC,GAAG,CAAC;IAC5B,wCAAwC;IACxC,GAAG,EAAE,MAAM,CAAC;IACZ,gCAAgC;IAChC,IAAI,EAAE,OAAO,CAAC;IACd,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,WAAW,EAAE,MAAM,CAAC;IACpB,2DAA2D;IAC3D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gDAAgD;IAChD,IAAI,EAAE,MAAM,CAAC;CACd"}

package/dist/domain/MemorizeStats.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Aggregate cache statistics returned by {@link Memorize.getStats}.
+ */
+export interface MemorizeStats {
+    /** Number of active (non-expired) cache entries. */
+    entries: number;
+    /** Configured maximum number of entries, or `null` if unlimited. */
+    maxEntries: number | null;
+    /** Approximate total byte size of all cached bodies. */
+    byteSize: number;
+}
+//# sourceMappingURL=MemorizeStats.d.ts.map

package/dist/domain/MemorizeStats.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemorizeStats.d.ts","sourceRoot":"","sources":["../../src/domain/MemorizeStats.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;CAClB"}

package/dist/domain/MemorizeStats.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=MemorizeStats.js.map

package/dist/domain/MemorizeStats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MemorizeStats.js","sourceRoot":"","sources":["../../src/domain/MemorizeStats.ts"],"names":[],"mappings":""}

package/dist/domain/index.d.ts

@@ -6,6 +6,8 @@ export type { MemorizeSetEvent } from './MemorizeSetEvent';
 export type { MemorizeDeleteEvent } from './MemorizeDeleteEvent';
 export type { MemorizeExpireEvent } from './MemorizeExpireEvent';
 export type { MemorizeEmptyEvent } from './MemorizeEmptyEvent';
+export type { MemorizeEvictEvent } from './MemorizeEvictEvent';
+export type { MemorizeStats } from './MemorizeStats';
 export type { MemorizeOptions } from './MemorizeOptions';
 export type { MemorizeCallOptions } from './MemorizeCallOptions';
 export type { Memorize } from './Memorize';

package/dist/domain/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/domain/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/domain/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,YAAY,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,YAAY,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACzD,YAAY,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjE,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC"}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { memorize } from './memorize';
 export type { Memorize, MemorizeOptions, MemorizeCallOptions } from './memorize';
 export { MemorizeEventType } from './domain/MemorizeEventType';
-export type { CacheEntry, CacheInfo, MemorizeEvent, MemorizeSetEvent, MemorizeDeleteEvent, MemorizeExpireEvent, MemorizeEmptyEvent, } from './domain/index';
+export type { CacheEntry, CacheInfo, MemorizeEvent, MemorizeSetEvent, MemorizeDeleteEvent, MemorizeExpireEvent, MemorizeEmptyEvent, MemorizeEvictEvent, MemorizeStats, } from './domain/index';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,YAAY,EACV,UAAU,EACV,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,GACnB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,YAAY,EACV,UAAU,EACV,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,aAAa,GACd,MAAM,gBAAgB,CAAC"}

package/dist/memorize.d.ts

@@ -3,37 +3,40 @@ import { MemorizeOptions } from './domain/MemorizeOptions';
 import { MemorizeCallOptions } from './domain/MemorizeCallOptions';
 export type { Memorize, MemorizeOptions, MemorizeCallOptions };
 /**
- * Creates an in-memory cache for an Express application.
+ * Creates an in-memory cache instance.
  *
- * Returns a {@link Memorize} instance that can be used as per-route middleware,
- * a global `app.use()` middleware, or a cache management API — all sharing the
- * same underlying store.
+ * Returns a {@link Memorize} instance that can be used as Express middleware,
+ * as a direct service-level cache, or as a cache management API — all sharing
+ * the same underlying store.
  *
- * **Only `GET` requests are cached.** Responses are cached only when the HTTP
- * status code is in the `2xx` range. The cache key is `req.originalUrl`, which
- * includes the query string.
+ * **HTTP middleware:** Only `GET` requests with a `2xx` status code are cached.
+ * The cache key is `req.originalUrl`, which includes the query string.
+ *
+ * **Direct cache:** Use {@link Memorize.set}, {@link Memorize.getValue}, and
+ * {@link Memorize.remember} to cache arbitrary values from services, workers,
+ * or any non-HTTP code.
  *
  * @param options - Global configuration for the cache instance.
  *
- * @example Per-route middleware
+ * @example Express middleware
  * ```ts
  * const cache = memorize({ ttl: 30_000 });
  *
- * app.get('/users', cache(), (req, res) => {
- *   res.json({ data: users });
- * });
+ * app.get('/users', cache.express(), handler);
+ * app.get('/users', cache(), handler);           // backwards-compatible alias
  * ```
  *
- * @example Global middleware
+ * @example Service-level caching
  * ```ts
- * const cache = memorize({ ttl: 60_000 });
- * app.use(cache()); // caches all GET routes
+ * const cache = memorize({ ttl: 30_000 });
+ *
+ * const users = await cache.remember('users:list', () => userService.findAll());
+ * cache.set('config', appConfig);
+ * const config = cache.getValue<AppConfig>('config');
  * ```
  *
  * @example Cache invalidation
  * ```ts
- * const cache = memorize({ ttl: 30_000 });
- *
  * app.post('/users', (req, res) => {
  *   users.push(req.body);
  *   cache.delete('/users');

package/dist/memorize.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memorize.d.ts","sourceRoot":"","sources":["../src/memorize.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAEnE,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,mBAAmB,EAAE,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,QAAQ,CAoDhE"}
+{"version":3,"file":"memorize.d.ts","sourceRoot":"","sources":["../src/memorize.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAGnE,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,mBAAmB,EAAE,CAAC;AAE/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,QAAQ,CAAC,OAAO,GAAE,eAAoB,GAAG,QAAQ,CA6ChE"}