express-memorize 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This file is automatically updated by [release-please](https://github.com/googleapis/release-please) based on [Conventional Commits](https://www.conventionalcommits.org/).
+
+## [1.2.0](https://github.com/ElJijuna/express-memorize/compare/v1.1.0...v1.2.0) (2026-03-24)
+
+
+### Features
+
+* refactor to separate in domain files (one file per scope) and update memorize and Memorize store with implementation ([4f41f8c](https://github.com/ElJijuna/express-memorize/commit/4f41f8c0c350df36dcf111315857b6fd34c1a031))
+
+## [1.1.0](https://github.com/ElJijuna/express-memorize/compare/v1.0.0...v1.1.0) (2026-03-24)
+
+
+### Features
+
+* add evento to notify when cache is empty. ([8484f29](https://github.com/ElJijuna/express-memorize/commit/8484f29f1d1f2bd275970a0c02fa9b64a46576b9))
+
+## 1.0.0 (2026-03-24)
+
+
+### Features
+
+* add events to log activity in memory store. ([5b3905b](https://github.com/ElJijuna/express-memorize/commit/5b3905b898a5d91c4c61510dd5d8c92eabf096e9))
+* add github action to publish in NPM ([7f79eca](https://github.com/ElJijuna/express-memorize/commit/7f79eca766356280f677411b166c8e2608140d16))
+* add middleware to use memorize. ([73a02a0](https://github.com/ElJijuna/express-memorize/commit/73a02a096750ec66bb8d9c183b0f07c2aeb3cd83))
+* add tests and express client to execute local implementation. ([75d3cf8](https://github.com/ElJijuna/express-memorize/commit/75d3cf81f979a04ef9f0964a444e2966a2ba8164))
+* add validation to only add to store GET methods in middleware. ([04e2918](https://github.com/ElJijuna/express-memorize/commit/04e291884ab083321838cca40755e2c02e98ec6c))
+
+## [1.0.0] - 2026-03-24
+
+### Features
+
+- In-memory cache middleware for Express.js
+- Key-value store using full request path (`originalUrl`) as key
+- TTL support with automatic expiry via `setTimeout`
+- Per-route TTL override
+- Caches only `GET` requests with `2xx` status codes
+- `Content-Type` preservation on cache hits
+- `X-Cache: HIT | MISS` response header
+- Cache management API: `get`, `getAll`, `delete`, `clear`
+- Event system: `set`, `delete`, `expire` hooks
+- Full TypeScript support with declaration files

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ElJijuna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,201 @@
+# express-memorize
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/express-memorize"><img src="https://img.shields.io/npm/v/express-memorize?color=blue&label=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/express-memorize"><img src="https://img.shields.io/npm/dm/express-memorize?color=blue" alt="npm downloads" /></a>
+  <a href="https://github.com/ElJijuna/express-memorize/actions"><img src="https://github.com/ElJijuna/express-memorize/actions/workflows/publish.yml/badge.svg" alt="CI" /></a>
+  <a href="https://github.com/ElJijuna/express-memorize/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="license" /></a>
+  <img src="https://img.shields.io/badge/TypeScript-5-blue?logo=typescript&logoColor=white" alt="TypeScript" />
+</p>
+
+<p align="center">
+  In-memory cache middleware for <strong>Express.js</strong>.<br/>
+  Caches <code>GET</code> responses with optional TTL — zero dependencies, fully typed.
+</p>
+
+---
+
+## Features
+
+- Caches `GET` responses automatically when status code is `2xx`
+- Per-route TTL override
+- Event hooks: `set`, `delete`, `expire`
+- Cache inspection and invalidation API
+- `X-Cache: HIT | MISS` response header
+- Zero runtime dependencies
+- Full TypeScript support
+
+## Installation
+
+```bash
+npm install express-memorize
+```
+
+## Quick Start
+
+```typescript
+import express from 'express';
+import { memorize } from 'express-memorize';
+
+const app = express();
+const cache = memorize({ ttl: 30_000 }); // 30 seconds global TTL
+
+app.get('/users', cache(), async (req, res) => {
+  const users = await db.getUsers();
+  res.json({ data: users });
+});
+
+app.listen(3000);
+```
+
+The first request computes the response normally. Every subsequent `GET /users` is served from memory until the TTL expires.
+
+## Usage
+
+### Global middleware
+
+Apply the cache to the entire application with `app.use()`. Every `GET` route is cached automatically — non-`GET` requests are bypassed without any extra configuration.
+
+```typescript
+const cache = memorize({ ttl: 60_000 });
+
+app.use(cache()); // applies to all GET routes
+
+app.get('/users',   (req, res) => { res.json({ data: users }) });
+app.get('/products', (req, res) => { res.json({ data: products }) });
+// POST, PUT, PATCH, DELETE routes are unaffected
+```
+
+### Per-route cache
+
+```typescript
+const cache = memorize({ ttl: 60_000 });
+
+app.get('/products', cache(), (req, res) => {
+  res.json({ data: products });
+});
+```
+
+### Per-route TTL override
+
+```typescript
+const cache = memorize({ ttl: 60_000 }); // global: 60s
+
+app.get('/users',    cache(),               handler); // 60s
+app.get('/products', cache({ ttl: 10_000 }), handler); // override: 10s
+app.get('/config',   cache({ ttl: 0 }),      handler); // no expiry
+```
+
+### Cache invalidation
+
+```typescript
+const cache = memorize({ ttl: 30_000 });
+
+app.get('/users', cache(), (req, res) => {
+  res.json({ data: users });
+});
+
+app.post('/users', (req, res) => {
+  users.push(req.body);
+  cache.delete('/users'); // invalidate after mutation
+  res.status(201).json({ data: req.body });
+});
+```
+
+### Event hooks
+
+```typescript
+const cache = memorize({ ttl: 30_000 });
+
+cache.on('set', (e) => {
+  console.log(`[cache] stored ${e.key} — expires in ${e.expiresAt ? e.expiresAt - Date.now() : '∞'}ms`);
+});
+
+cache.on('delete', (e) => {
+  console.log(`[cache] deleted ${e.key}`);
+});
+
+cache.on('expire', (e) => {
+  console.log(`[cache] expired ${e.key}`);
+});
+```
+
+### Inspect the cache
+
+```typescript
+cache.get('/users');   // CacheInfo | null — single entry
+cache.getAll();        // Record<string, CacheInfo> — all active entries
+```
+
+`CacheInfo` shape:
+
+```typescript
+{
+  key: string;
+  body: unknown;
+  statusCode: number;
+  contentType: string;
+  expiresAt: number | null;
+  remainingTtl: number | null; // ms until expiry, null if no TTL
+}
+```
+
+### Clear the cache
+
+```typescript
+cache.delete('/users');  // remove one entry
+cache.clear();           // remove all entries
+```
+
+## API Reference
+
+### `memorize(options?)`
+
+Creates a cache instance. Returns a `Memorize` object.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `ttl` | `number` | `undefined` | Time-to-live in milliseconds. Omit for no expiry. |
+
+### `cache(options?)`
+
+Returns an Express `RequestHandler` middleware. Can override the global TTL.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `ttl` | `number` | global `ttl` | TTL override for this specific route. |
+
+### Cache management
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `get` | `(key: string) => CacheInfo \| null` | Returns info for a cached key. |
+| `getAll` | `() => Record<string, CacheInfo>` | Returns all active cache entries. |
+| `delete` | `(key: string) => boolean` | Removes a single entry. Returns `false` if not found. |
+| `clear` | `() => void` | Removes all entries. |
+
+### Events
+
+| Event | Payload | When |
+|-------|---------|------|
+| `set` | `{ type, key, body, statusCode, contentType, expiresAt }` | A response is stored |
+| `delete` | `{ type, key }` | `cache.delete()` or `cache.clear()` is called |
+| `expire` | `{ type, key }` | TTL timer fires or lazy expiry is detected |
+
+## Response Headers
+
+| Header | Value | Description |
+|--------|-------|-------------|
+| `X-Cache` | `HIT` | Response served from cache |
+| `X-Cache` | `MISS` | Response computed and stored |
+
+## Behavior
+
+- Only `GET` requests are cached. All other methods bypass the middleware entirely.
+- Only responses with a `2xx` status code are stored.
+- Each call to `cache()` returns an independent middleware handler, but all handlers created from the same `memorize()` instance **share the same store**.
+- Two separate `memorize()` calls produce **independent stores**.
+
+## License
+
+[MIT](LICENSE)

package/dist/MemorizeStore.d.ts

@@ -1,43 +1,82 @@
-export interface CacheEntry {
-    body: unknown;
-    statusCode: number;
-    contentType: string;
-    expiresAt: number | null;
-}
-export interface CacheInfo extends CacheEntry {
-    key: string;
-    remainingTtl: number | null;
-}
-export interface MemorizeSetEvent {
-    type: 'set';
-    key: string;
-    body: unknown;
-    statusCode: number;
-    contentType: string;
-    expiresAt: number | null;
-}
-export interface MemorizeDeleteEvent {
-    type: 'delete';
-    key: string;
-}
-export interface MemorizeExpireEvent {
-    type: 'expire';
-    key: string;
-}
-export type MemorizeEvent = MemorizeSetEvent | MemorizeDeleteEvent | MemorizeExpireEvent;
-export type MemorizeEventType = MemorizeEvent['type'];
+import { CacheEntry } from './domain/CacheEntry';
+import { CacheInfo } from './domain/CacheInfo';
+import { MemorizeEventType } from './domain/MemorizeEventType';
+import { MemorizeEvent } from './domain/MemorizeEvent';
+import { MemorizeSetEvent } from './domain/MemorizeSetEvent';
+import { MemorizeDeleteEvent } from './domain/MemorizeDeleteEvent';
+import { MemorizeExpireEvent } from './domain/MemorizeExpireEvent';
+import { MemorizeEmptyEvent } from './domain/MemorizeEmptyEvent';
+export type { CacheEntry, CacheInfo, MemorizeEvent, MemorizeSetEvent, MemorizeDeleteEvent, MemorizeExpireEvent, MemorizeEmptyEvent, };
+export { MemorizeEventType };
+/**
+ * Low-level in-memory key-value store with optional TTL and event emission.
+ *
+ * You do not usually interact with this class directly — use the {@link memorize} factory
+ * instead, which wraps this store in an Express middleware.
+ */
 export declare class MemorizeStore {
     private _store;
     private _timers;
     private _listeners;
-    on(event: 'set', handler: (e: MemorizeSetEvent) => void): void;
-    on(event: 'delete', handler: (e: MemorizeDeleteEvent) => void): void;
-    on(event: 'expire', handler: (e: MemorizeExpireEvent) => void): void;
+    /**
+     * Registers an event listener.
+     *
+     * @param event - The event to listen for.
+     * @param handler - Callback invoked with the event payload.
+     *
+     * @example
+     * ```ts
+     * store.on(MemorizeEventType.Set,    (e) => console.log('cached',  e.key));
+     * store.on(MemorizeEventType.Expire, (e) => console.log('expired', e.key));
+     * ```
+     */
+    on(event: MemorizeEventType.Set, handler: (e: MemorizeSetEvent) => void): void;
+    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;
+    /**
+     * Stores an entry in the cache.
+     *
+     * If an entry already exists for the given key its TTL timer is reset and the
+     * value is overwritten. Emits a {@link MemorizeEventType.Set} event.
+     *
+     * @param key - The cache key (typically `req.originalUrl`).
+     * @param entry - The response data to store.
+     * @param ttl - Time-to-live in milliseconds. Omit or pass `null` for no expiry.
+     */
     set(key: string, entry: Omit<CacheEntry, 'expiresAt'>, ttl?: number | null): void;
+    /**
+     * Returns the formatted {@link CacheInfo} for the given key, or `null` if the
+     * key does not exist or its TTL has elapsed.
+     *
+     * @param key - The cache key to look up.
+     */
     get(key: string): CacheInfo | null;
+    /**
+     * Returns all active (non-expired) cache entries as a key→{@link CacheInfo} map.
+     * Expired entries are lazily evicted during this call.
+     */
     getAll(): Record<string, CacheInfo>;
+    /**
+     * Removes a single entry from the cache. Emits a {@link MemorizeEventType.Delete} event.
+     *
+     * @param key - The cache key to remove.
+     * @returns `true` if the entry existed and was removed, `false` otherwise.
+     */
     delete(key: string): boolean;
+    /**
+     * Removes all entries from the cache. Emits a {@link MemorizeEventType.Delete} event
+     * for each entry.
+     */
     clear(): void;
+    /**
+     * Returns the raw {@link CacheEntry} for the given key without formatting metadata,
+     * or `null` if the entry is missing or expired. Used internally by the middleware
+     * to serve cached responses.
+     *
+     * @param key - The cache key to look up.
+     * @internal
+     */
     getRaw(key: string): CacheEntry | null;
     private _evict;
     private _emit;

package/dist/MemorizeStore.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MemorizeStore.d.ts","sourceRoot":"","sources":["../src/MemorizeStore.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,SAAU,SAAQ,UAAU;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAID,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,KAAK,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,OAAO,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,QAAQ,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,QAAQ,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,aAAa,GAAG,gBAAgB,GAAG,mBAAmB,GAAG,mBAAmB,CAAC;AACzF,MAAM,MAAM,iBAAiB,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;AAStD,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,OAAO,CAAoD;IACnE,OAAO,CAAC,UAAU,CAAoD;IAEtE,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,gBAAgB,KAAK,IAAI,GAAG,IAAI;IAC9D,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,mBAAmB,KAAK,IAAI,GAAG,IAAI;IACpE,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,mBAAmB,KAAK,IAAI,GAAG,IAAI;IAMpE,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAsBjF,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAYlC,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC;IAcnC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAM5B,KAAK,IAAI,IAAI;IAMb,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAYtC,OAAO,CAAC,MAAM;IASd,OAAO,CAAC,KAAK;IAMb,OAAO,CAAC,OAAO;CAUhB"}
+{"version":3,"file":"MemorizeStore.d.ts","sourceRoot":"","sources":["../src/MemorizeStore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAC;AAEjE,YAAY,EACV,UAAU,EACV,SAAS,EACT,aAAa,EACb,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,GACnB,CAAC;AACF,OAAO,EAAE,iBAAiB,EAAE,CAAC;AAS7B;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,MAAM,CAAiC;IAC/C,OAAO,CAAC,OAAO,CAAoD;IACnE,OAAO,CAAC,UAAU,CAKhB;IAEF;;;;;;;;;;;OAWG;IACH,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,GAAG,EAAK,OAAO,EAAE,CAAC,CAAC,EAAE,gBAAgB,KAAK,IAAI,GAAG,IAAI;IACjF,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,mBAAmB,KAAK,IAAI,GAAG,IAAI;IACpF,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,mBAAmB,KAAK,IAAI,GAAG,IAAI;IACpF,EAAE,CAAC,KAAK,EAAE,iBAAiB,CAAC,KAAK,EAAG,OAAO,EAAE,CAAC,CAAC,EAAE,kBAAkB,KAAK,IAAI,GAAG,IAAI;IAMnF;;;;;;;;;OASG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAsBjF;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAYlC;;;OAGG;IACH,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC;IAcnC;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAM5B;;;OAGG;IACH,KAAK,IAAI,IAAI;IAMb;;;;;;;OAOG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAYtC,OAAO,CAAC,MAAM;IAYd,OAAO,CAAC,KAAK;IAMb,OAAO,CAAC,OAAO;CAUhB"}

package/dist/MemorizeStore.js

@@ -1,17 +1,39 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MemorizeStore = void 0;
-// --- Store ---
+exports.MemorizeStore = exports.MemorizeEventType = void 0;
+const MemorizeEventType_1 = require("./domain/MemorizeEventType");
+Object.defineProperty(exports, "MemorizeEventType", { enumerable: true, get: function () { return MemorizeEventType_1.MemorizeEventType; } });
+/**
+ * Low-level in-memory key-value store with optional TTL and event emission.
+ *
+ * You do not usually interact with this class directly — use the {@link memorize} factory
+ * instead, which wraps this store in an Express middleware.
+ */
 class MemorizeStore {
     constructor() {
         this._store = new Map();
         this._timers = new Map();
-        this._listeners = { set: [], delete: [], expire: [] };
+        this._listeners = {
+            [MemorizeEventType_1.MemorizeEventType.Set]: [],
+            [MemorizeEventType_1.MemorizeEventType.Delete]: [],
+            [MemorizeEventType_1.MemorizeEventType.Expire]: [],
+            [MemorizeEventType_1.MemorizeEventType.Empty]: [],
+        };
     }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     on(event, handler) {
         this._listeners[event].push(handler);
     }
+    /**
+     * Stores an entry in the cache.
+     *
+     * If an entry already exists for the given key its TTL timer is reset and the
+     * value is overwritten. Emits a {@link MemorizeEventType.Set} event.
+     *
+     * @param key - The cache key (typically `req.originalUrl`).
+     * @param entry - The response data to store.
+     * @param ttl - Time-to-live in milliseconds. Omit or pass `null` for no expiry.
+     */
     set(key, entry, ttl) {
         if (this._timers.has(key)) {
             clearTimeout(this._timers.get(key));
@@ -20,54 +42,82 @@ class MemorizeStore {
         const expiresAt = ttl ? Date.now() + ttl : null;
         const stored = { ...entry, expiresAt };
         this._store.set(key, stored);
-        this._emit('set', { type: 'set', key, ...entry, expiresAt });
+        this._emit(MemorizeEventType_1.MemorizeEventType.Set, { type: MemorizeEventType_1.MemorizeEventType.Set, key, ...entry, expiresAt });
         if (ttl) {
             const timer = setTimeout(() => {
-                this._evict(key, 'expire');
+                this._evict(key, MemorizeEventType_1.MemorizeEventType.Expire);
             }, ttl);
             if (typeof timer === 'object' && 'unref' in timer)
                 timer.unref();
             this._timers.set(key, timer);
         }
     }
+    /**
+     * Returns the formatted {@link CacheInfo} for the given key, or `null` if the
+     * key does not exist or its TTL has elapsed.
+     *
+     * @param key - The cache key to look up.
+     */
     get(key) {
         const entry = this._store.get(key);
         if (!entry)
             return null;
         if (entry.expiresAt && Date.now() > entry.expiresAt) {
-            this._evict(key, 'expire');
+            this._evict(key, MemorizeEventType_1.MemorizeEventType.Expire);
             return null;
         }
         return this._format(key, entry);
     }
+    /**
+     * Returns all active (non-expired) cache entries as a key→{@link CacheInfo} map.
+     * Expired entries are lazily evicted during this call.
+     */
     getAll() {
         const result = {};
         for (const [key, entry] of this._store) {
             if (entry.expiresAt && Date.now() > entry.expiresAt) {
-                this._evict(key, 'expire');
+                this._evict(key, MemorizeEventType_1.MemorizeEventType.Expire);
                 continue;
             }
             result[key] = this._format(key, entry);
         }
         return result;
     }
+    /**
+     * Removes a single entry from the cache. Emits a {@link MemorizeEventType.Delete} event.
+     *
+     * @param key - The cache key to remove.
+     * @returns `true` if the entry existed and was removed, `false` otherwise.
+     */
     delete(key) {
         if (!this._store.has(key))
             return false;
-        this._evict(key, 'delete');
+        this._evict(key, MemorizeEventType_1.MemorizeEventType.Delete);
         return true;
     }
+    /**
+     * Removes all entries from the cache. Emits a {@link MemorizeEventType.Delete} event
+     * for each entry.
+     */
     clear() {
         for (const key of this._store.keys()) {
-            this._evict(key, 'delete');
+            this._evict(key, MemorizeEventType_1.MemorizeEventType.Delete);
         }
     }
+    /**
+     * Returns the raw {@link CacheEntry} for the given key without formatting metadata,
+     * or `null` if the entry is missing or expired. Used internally by the middleware
+     * to serve cached responses.
+     *
+     * @param key - The cache key to look up.
+     * @internal
+     */
     getRaw(key) {
         const entry = this._store.get(key);
         if (!entry)
             return null;
         if (entry.expiresAt && Date.now() > entry.expiresAt) {
-            this._evict(key, 'expire');
+            this._evict(key, MemorizeEventType_1.MemorizeEventType.Expire);
             return null;
         }
         return entry;
@@ -79,6 +129,9 @@ class MemorizeStore {
         }
         this._store.delete(key);
         this._emit(reason, { type: reason, key });
+        if (this._store.size === 0) {
+            this._emit(MemorizeEventType_1.MemorizeEventType.Empty, { type: MemorizeEventType_1.MemorizeEventType.Empty });
+        }
     }
     _emit(event, payload) {
         for (const handler of this._listeners[event]) {

package/dist/MemorizeStore.js.map

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

package/dist/domain/CacheEntry.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The raw data stored for a cached response.
+ */
+export interface CacheEntry {
+    /** The serialized response body, as passed to `res.send()`. */
+    body: unknown;
+    /** HTTP status code of the cached response (e.g. `200`, `201`). */
+    statusCode: number;
+    /** Value of the `Content-Type` response header (e.g. `application/json; charset=utf-8`). */
+    contentType: string;
+    /** Unix timestamp (ms) at which the entry expires, or `null` if it never expires. */
+    expiresAt: number | null;
+}
+//# sourceMappingURL=CacheEntry.d.ts.map

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

@@ -0,0 +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;CAC1B"}

package/dist/domain/CacheEntry.js

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

package/dist/domain/CacheEntry.js.map

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

package/dist/domain/CacheInfo.d.ts

@@ -0,0 +1,12 @@
+import { CacheEntry } from './CacheEntry';
+/**
+ * A cache entry enriched with lookup metadata, returned by {@link Memorize.get} and
+ * {@link Memorize.getAll}.
+ */
+export interface CacheInfo extends CacheEntry {
+    /** The cache key — the full request path including query string (e.g. `/users?page=1`). */
+    key: string;
+    /** Milliseconds remaining until the entry expires. `null` if the entry has no TTL. */
+    remainingTtl: number | null;
+}
+//# sourceMappingURL=CacheInfo.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CacheInfo.d.ts","sourceRoot":"","sources":["../../src/domain/CacheInfo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE1C;;;GAGG;AACH,MAAM,WAAW,SAAU,SAAQ,UAAU;IAC3C,2FAA2F;IAC3F,GAAG,EAAE,MAAM,CAAC;IACZ,sFAAsF;IACtF,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B"}

package/dist/domain/CacheInfo.js

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

package/dist/domain/CacheInfo.js.map

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