@x12i/api-hub-cache 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# @x12i/api-hub-cache
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Response cache with 6 hour and 24 hour TTLs for the x12i API hub
+
+ESM package for Node.js 24 or newer. Import the public name:
+
+```js
+import * as cache from '@x12i/api-hub-cache';
+```
+
+The whole set is also available from [`@x12i/api-hub`](https://www.npmjs.com/package/@x12i/api-hub).

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import type { Cache, CacheTtl } from '@x12i/api-hub-core';
+export declare const TTL_SECONDS: {
+    readonly '6h': number;
+    readonly '24h': number;
+};
+export declare function ttlSeconds(ttl: CacheTtl): number;
+/** Storage behind the cache, so Redis or another shared store can replace memory later. */
+export interface CacheStore {
+    get(key: string): Promise<{
+        value: unknown;
+        expiresAt: number;
+    } | undefined>;
+    set(key: string, value: unknown, expiresAt: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export declare function memoryStore(maxEntries?: number): CacheStore;
+/** Deterministic key for a capability call: same slug and same input (any key order) give the same key. */
+export declare function cacheKey(namespace: string, input: unknown): string;
+export interface CacheOptions {
+    store?: CacheStore;
+    now?: () => number;
+}
+export declare function createCache(options?: CacheOptions): Cache;

package/dist/index.js

@@ -0,0 +1,80 @@
+import { createHash } from 'node:crypto';
+export const TTL_SECONDS = { '6h': 6 * 3600, '24h': 24 * 3600 };
+export function ttlSeconds(ttl) {
+    return typeof ttl === 'number' ? ttl : TTL_SECONDS[ttl];
+}
+export function memoryStore(maxEntries = 10_000) {
+    const map = new Map();
+    return {
+        async get(key) {
+            const hit = map.get(key);
+            if (!hit)
+                return undefined;
+            map.delete(key);
+            map.set(key, hit);
+            return hit;
+        },
+        async set(key, value, expiresAt) {
+            map.delete(key);
+            map.set(key, { value, expiresAt });
+            while (map.size > maxEntries)
+                map.delete(map.keys().next().value);
+        },
+        async delete(key) {
+            map.delete(key);
+        },
+    };
+}
+function stable(value) {
+    if (Array.isArray(value))
+        return value.map(stable);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.keys(value)
+            .sort()
+            .map((k) => [k, stable(value[k])]));
+    }
+    return value;
+}
+/** Deterministic key for a capability call: same slug and same input (any key order) give the same key. */
+export function cacheKey(namespace, input) {
+    const digest = createHash('sha256').update(JSON.stringify(stable(input))).digest('base64url');
+    return `${namespace}:${digest}`;
+}
+export function createCache(options = {}) {
+    const store = options.store ?? memoryStore();
+    const now = options.now ?? Date.now;
+    const inflight = new Map();
+    const cache = {
+        async get(key) {
+            const hit = await store.get(key);
+            if (!hit)
+                return undefined;
+            if (hit.expiresAt <= now()) {
+                await store.delete(key);
+                return undefined;
+            }
+            return hit.value;
+        },
+        async set(key, value, ttl) {
+            await store.set(key, value, now() + ttlSeconds(ttl) * 1000);
+        },
+        async wrap(key, ttl, fn) {
+            const cached = await cache.get(key);
+            if (cached !== undefined)
+                return cached;
+            const pending = inflight.get(key);
+            if (pending)
+                return pending;
+            const run = fn()
+                .then(async (value) => {
+                await cache.set(key, value, ttl);
+                return value;
+            })
+                .finally(() => inflight.delete(key));
+            inflight.set(key, run);
+            return run;
+        },
+    };
+    return cache;
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../packages/cache/src/index.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from 'node:crypto';\nimport type { Cache, CacheTtl } from '@x12i/api-hub-core';\n\nexport const TTL_SECONDS = { '6h': 6 * 3600, '24h': 24 * 3600 } as const;\n\nexport function ttlSeconds(ttl: CacheTtl): number {\n  return typeof ttl === 'number' ? ttl : TTL_SECONDS[ttl];\n}\n\n/** Storage behind the cache, so Redis or another shared store can replace memory later. */\nexport interface CacheStore {\n  get(key: string): Promise<{ value: unknown; expiresAt: number } | undefined>;\n  set(key: string, value: unknown, expiresAt: number): Promise<void>;\n  delete(key: string): Promise<void>;\n}\n\nexport function memoryStore(maxEntries = 10_000): CacheStore {\n  const map = new Map<string, { value: unknown; expiresAt: number }>();\n  return {\n    async get(key) {\n      const hit = map.get(key);\n      if (!hit) return undefined;\n      map.delete(key);\n      map.set(key, hit);\n      return hit;\n    },\n    async set(key, value, expiresAt) {\n      map.delete(key);\n      map.set(key, { value, expiresAt });\n      while (map.size > maxEntries) map.delete(map.keys().next().value!);\n    },\n    async delete(key) {\n      map.delete(key);\n    },\n  };\n}\n\nfunction stable(value: unknown): unknown {\n  if (Array.isArray(value)) return value.map(stable);\n  if (value && typeof value === 'object') {\n    return Object.fromEntries(\n      Object.keys(value as Record<string, unknown>)\n        .sort()\n        .map((k) => [k, stable((value as Record<string, unknown>)[k])]),\n    );\n  }\n  return value;\n}\n\n/** Deterministic key for a capability call: same slug and same input (any key order) give the same key. */\nexport function cacheKey(namespace: string, input: unknown): string {\n  const digest = createHash('sha256').update(JSON.stringify(stable(input))).digest('base64url');\n  return `${namespace}:${digest}`;\n}\n\nexport interface CacheOptions {\n  store?: CacheStore;\n  now?: () => number;\n}\n\nexport function createCache(options: CacheOptions = {}): Cache {\n  const store = options.store ?? memoryStore();\n  const now = options.now ?? Date.now;\n  const inflight = new Map<string, Promise<unknown>>();\n\n  const cache: Cache = {\n    async get<T>(key: string) {\n      const hit = await store.get(key);\n      if (!hit) return undefined;\n      if (hit.expiresAt <= now()) {\n        await store.delete(key);\n        return undefined;\n      }\n      return hit.value as T;\n    },\n    async set<T>(key: string, value: T, ttl: CacheTtl) {\n      await store.set(key, value, now() + ttlSeconds(ttl) * 1000);\n    },\n    async wrap<T>(key: string, ttl: CacheTtl, fn: () => Promise<T>) {\n      const cached = await cache.get<T>(key);\n      if (cached !== undefined) return cached;\n      const pending = inflight.get(key) as Promise<T> | undefined;\n      if (pending) return pending;\n      const run = fn()\n        .then(async (value) => {\n          await cache.set(key, value, ttl);\n          return value;\n        })\n        .finally(() => inflight.delete(key));\n      inflight.set(key, run);\n      return run;\n    },\n  };\n  return cache;\n}\n"]}

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@x12i/api-hub-cache",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Response cache with 6 hour and 24 hour TTLs for the x12i API hub",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/x12i/apis-hub.git",
+    "directory": "packages/cache"
+  },
+  "bugs": {
+    "url": "https://github.com/x12i/apis-hub/issues"
+  },
+  "homepage": "https://github.com/x12i/apis-hub",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@x12i/api-hub-core": "0.1.1"
+  }
+}