@voyant-travel/runtime 0.3.0

package/README.md

@@ -0,0 +1,54 @@
+# @voyant-travel/runtime
+
+The runtime glue a Voyant app entry uses — request dispatch **and** the Node
+server it runs on — as one versioned package instead of copied template files.
+Merges the former `@voyant-travel/worker-runtime` (dispatch) and
+`@voyant-travel/dedicated-runtime` (Node server + providers): with Node the
+first-class runtime (voyant#2966), "worker"/"dedicated" were both stale names for
+what is simply the runtime.
+
+## Request dispatch (runtime-neutral)
+
+The `fetch`/API/SSR routing an app entry composes. Reused verbatim on Node and
+Cloudflare Workers.
+
+- `createWorkerFetch({ api, ssr })` — the `(request, env, ctx)` entry that routes
+  `/api/*` to the API dispatch and everything else to SSR.
+- `lazySsr(() => import("./ssr-handler"))` — memoize the dynamic import of the
+  TanStack Start server graph (React + `react-dom/server`) so it stays out of the
+  module's startup cost.
+- `createApiDispatch` / `lazyApp` — prefix-routed `/api/*` app dispatch with a
+  memoized loader.
+- `restrictSsrManifestToActiveRoutes` / `withActiveRouteSsrManifest` — trim the
+  TanStack SSR preload manifest to matched routes.
+
+## Node runtime
+
+The resident-process server plus the real providers it wires. See
+[docs/architecture/deployment-targets.md](../../docs/architecture/deployment-targets.md).
+
+- `createNodeServer({ fetch, scheduled, env, originTrustSecret })` — boots a Node
+  HTTP server (`@hono/node-server`) running the app's `fetch` unchanged, adding a
+  real per-request `waitUntil` (background work tracked + drained on shutdown), an
+  origin-trust gate, an HTTP `scheduled()` hook at `POST /__voyant/scheduled`, and
+  graceful SIGTERM/SIGINT drain.
+- `composeNodeEnv(process.env, { kv, r2 })` — assemble the env bag app code reads
+  (`env.CACHE`, `env.MEDIA_BUCKET`, …) from string vars + real provider objects.
+- `createMemoryKvNamespace()` — in-process KV (`Map` + TTL + LRU) for
+  `CACHE`/`RATE_LIMIT` in a single resident process.
+- `createR2BucketShim({ endpoint, bucket, … })` — S3-compatible object store for
+  production; `createMemoryR2Bucket()` — in-process store for dev/offline.
+- `originTrustMiddleware` / `verifyOriginTrust` / `constantTimeEqual` — the
+  `x-voyant-origin-trust` gate the platform dispatcher stamps.
+- `createWaitUntilRegistry()` — the in-process `waitUntil` registry + drain.
+
+## Out of scope
+
+- **Cache API (`caches.default`)** — not shimmed; the public-cache middleware
+  reads `env.CACHE` KV directly on Node.
+- **Distributed KV / object store** — the in-process providers are single-process;
+  a multi-instance deployment swaps them for a shared KV/S3 provider behind the
+  same interface (platform#940). The S3-backed `createR2BucketShim` covers durable
+  object storage.
+- **Durable Objects, Analytics Engine, `request.cf`** — no in-process equivalent;
+  app code tolerates their absence on Node.

package/dist/api-dispatch.d.ts

@@ -0,0 +1,44 @@
+import type { AppLoader, FetchApp, WaitUntilContext } from "./types.js";
+/**
+ * Memoize an app loader so the underlying dynamic `import()` runs once per
+ * isolate, no matter how many requests race on it.
+ */
+export declare function lazyApp<Env, Ctx extends WaitUntilContext = WaitUntilContext>(load: () => Promise<FetchApp<Env, Ctx>>): AppLoader<Env, Ctx>;
+export interface CreateApiDispatchOptions<Env, Ctx extends WaitUntilContext = WaitUntilContext> {
+    /** Loads the full API app (the heavy module graph). Wrap with {@link lazyApp}. */
+    loadApiApp: AppLoader<Env, Ctx>;
+    /**
+     * Optional lean auth app. When set, requests under `authPrefix` dispatch to
+     * it WITHOUT loading the full API graph — the fix for the cold-start outage
+     * where the first `/api/auth/*` call instantiated the whole API and hung.
+     * Set `warmApiOnAuth` to opt into background API warm-up after auth traffic.
+     */
+    loadAuthApp?: AppLoader<Env, Ctx>;
+    /** Hosting prefix stripped before dispatch. Default `/api`. */
+    apiPrefix?: string;
+    /**
+     * Optional post-strip app-path rewrite. Runs after `/api` is removed and
+     * before the request is forwarded to the app.
+     */
+    rewriteAppPath?: (pathname: string) => string;
+    /** Auth sub-prefix served by the lean app. Default `${apiPrefix}/auth`. */
+    authPrefix?: string;
+    /** Background-warm the full app on auth traffic. Default false. */
+    warmApiOnAuth?: boolean;
+    /** Called when the background warm-up fails. Defaults to `console.error`. */
+    onWarmError?: (error: unknown) => void;
+}
+export interface ApiDispatch<Env, Ctx extends WaitUntilContext = WaitUntilContext> {
+    isApiRequest(pathname: string): boolean;
+    isAuthRequest(pathname: string): boolean;
+    /** Strip the hosting prefix (`/api/v1/x` → `/v1/x`), preserving search/body. */
+    toAppRequest(request: Request): Request;
+    dispatch(request: Request, env: Env, ctx: Ctx): Promise<Response>;
+}
+/**
+ * Prefix-routed dispatch from a hosting Worker URL space (`/api/*`) onto a
+ * Hono-style app surface (`/v1/*`, `/auth/*`, `/health`). Framework-owned:
+ * apps supply only the loaders for their own modules.
+ */
+export declare function createApiDispatch<Env, Ctx extends WaitUntilContext = WaitUntilContext>(options: CreateApiDispatchOptions<Env, Ctx>): ApiDispatch<Env, Ctx>;
+//# sourceMappingURL=api-dispatch.d.ts.map

package/dist/api-dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-dispatch.d.ts","sourceRoot":"","sources":["../src/api-dispatch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAIvE;;;GAGG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,GAAG,SAAS,gBAAgB,GAAG,gBAAgB,EAC1E,IAAI,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,GACtC,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAMrB;AAED,MAAM,WAAW,wBAAwB,CAAC,GAAG,EAAE,GAAG,SAAS,gBAAgB,GAAG,gBAAgB;IAC5F,kFAAkF;IAClF,UAAU,EAAE,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IAC/B;;;;;OAKG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;IACjC,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAA;IAC7C,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,mEAAmE;IACnE,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAA;CACvC;AAED,MAAM,WAAW,WAAW,CAAC,GAAG,EAAE,GAAG,SAAS,gBAAgB,GAAG,gBAAgB;IAC/E,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAA;IACvC,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAA;IACxC,gFAAgF;IAChF,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAA;IACvC,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;CAClE;AAMD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,GAAG,SAAS,gBAAgB,GAAG,gBAAgB,EACpF,OAAO,EAAE,wBAAwB,CAAC,GAAG,EAAE,GAAG,CAAC,GAC1C,WAAW,CAAC,GAAG,EAAE,GAAG,CAAC,CAiDvB"}

package/dist/api-dispatch.js

@@ -0,0 +1,64 @@
+const DEFAULT_API_PREFIX = "/api";
+/**
+ * Memoize an app loader so the underlying dynamic `import()` runs once per
+ * isolate, no matter how many requests race on it.
+ */
+export function lazyApp(load) {
+    let promise;
+    return () => {
+        promise ??= load();
+        return promise;
+    };
+}
+function matchesPrefix(pathname, prefix) {
+    return pathname === prefix || pathname.startsWith(`${prefix}/`);
+}
+/**
+ * Prefix-routed dispatch from a hosting Worker URL space (`/api/*`) onto a
+ * Hono-style app surface (`/v1/*`, `/auth/*`, `/health`). Framework-owned:
+ * apps supply only the loaders for their own modules.
+ */
+export function createApiDispatch(options) {
+    const apiPrefix = options.apiPrefix ?? DEFAULT_API_PREFIX;
+    const authPrefix = options.authPrefix ?? `${apiPrefix}/auth`;
+    const warmApiOnAuth = options.warmApiOnAuth ?? false;
+    const onWarmError = options.onWarmError ??
+        ((error) => {
+            console.error("[worker-runtime] background API warm failed:", error);
+        });
+    function toAppRequest(request) {
+        const url = new URL(request.url);
+        const stripped = url.pathname.slice(apiPrefix.length) || "/";
+        const appPath = options.rewriteAppPath?.(stripped) ?? stripped;
+        const appUrl = new URL(appPath, url.origin);
+        appUrl.search = url.search;
+        const bodyless = request.method === "GET" || request.method === "HEAD";
+        return new Request(appUrl.toString(), {
+            method: request.method,
+            headers: request.headers,
+            body: bodyless ? null : request.body,
+            redirect: request.redirect,
+            signal: request.signal,
+            ...(bodyless ? {} : { duplex: "half" }),
+        });
+    }
+    async function dispatch(request, env, ctx) {
+        const { loadApiApp, loadAuthApp } = options;
+        if (loadAuthApp && matchesPrefix(new URL(request.url).pathname, authPrefix)) {
+            const authApp = await loadAuthApp();
+            const response = await authApp.fetch(toAppRequest(request), env, ctx);
+            if (warmApiOnAuth && request.method !== "OPTIONS") {
+                ctx.waitUntil(loadApiApp().then(() => undefined, onWarmError));
+            }
+            return response;
+        }
+        const apiApp = await loadApiApp();
+        return apiApp.fetch(toAppRequest(request), env, ctx);
+    }
+    return {
+        isApiRequest: (pathname) => matchesPrefix(pathname, apiPrefix),
+        isAuthRequest: (pathname) => matchesPrefix(pathname, authPrefix),
+        toAppRequest,
+        dispatch,
+    };
+}

package/dist/env.d.ts

@@ -0,0 +1,33 @@
+import type { KvNamespaceShim } from "./memory-kv.js";
+import type { R2BucketShim } from "./r2.js";
+export interface NodeEnvBindings {
+    /** KV namespace bindings, keyed by the binding name app code reads (e.g. `CACHE`). */
+    kv?: Record<string, KvNamespaceShim>;
+    /** R2 bucket bindings, keyed by the binding name (e.g. `DOCUMENTS_BUCKET`). */
+    r2?: Record<string, R2BucketShim>;
+}
+/**
+ * The env bag handed to `app.fetch(request, env, ctx)`. On Workers this is the
+ * bindings object the runtime injects; on Node we compose it from string
+ * process-env vars plus the real provider objects so app code sees the same
+ * shape (`env.CACHE`, `env.MEDIA_BUCKET`, …) without any Workers emulation.
+ */
+export type NodeEnv = Record<string, string | KvNamespaceShim | R2BucketShim>;
+/**
+ * Compose the env bag for a Node deployment. All string vars from `processEnv`
+ * (undefined values dropped) are spread first, then the KV and R2 providers are
+ * attached under their binding names — the same shape the Workers runtime used
+ * to inject, so the same `fetch(req, env, ctx)` runs unchanged. Unlike the old
+ * bindings emulation, the attached providers are real in-process / S3-backed
+ * stores, not shims over a Cloudflare binding.
+ *
+ * Binding names must not collide with a string var of the same name; the
+ * provider wins (a KV/R2 binding is never legitimately also a string).
+ *
+ * The `Env` type parameter lets a deployment present the bag as its own bindings
+ * interface (e.g. the operator's `CloudflareBindings`) at the boundary without a
+ * cast at the call site — the runtime bag genuinely carries those string vars +
+ * providers.
+ */
+export declare function composeNodeEnv<Env = NodeEnv>(processEnv: Record<string, string | undefined>, bindings?: NodeEnvBindings): Env;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAE3C,MAAM,WAAW,eAAe;IAC9B,sFAAsF;IACtF,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;IACpC,+EAA+E;IAC/E,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;CAClC;AAED;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,GAAG,YAAY,CAAC,CAAA;AAE7E;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,CAAC,GAAG,GAAG,OAAO,EAC1C,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EAC9C,QAAQ,GAAE,eAAoB,GAC7B,GAAG,CAYL"}

package/dist/env.js

@@ -0,0 +1,30 @@
+/**
+ * Compose the env bag for a Node deployment. All string vars from `processEnv`
+ * (undefined values dropped) are spread first, then the KV and R2 providers are
+ * attached under their binding names — the same shape the Workers runtime used
+ * to inject, so the same `fetch(req, env, ctx)` runs unchanged. Unlike the old
+ * bindings emulation, the attached providers are real in-process / S3-backed
+ * stores, not shims over a Cloudflare binding.
+ *
+ * Binding names must not collide with a string var of the same name; the
+ * provider wins (a KV/R2 binding is never legitimately also a string).
+ *
+ * The `Env` type parameter lets a deployment present the bag as its own bindings
+ * interface (e.g. the operator's `CloudflareBindings`) at the boundary without a
+ * cast at the call site — the runtime bag genuinely carries those string vars +
+ * providers.
+ */
+export function composeNodeEnv(processEnv, bindings = {}) {
+    const env = {};
+    for (const [key, value] of Object.entries(processEnv)) {
+        if (value !== undefined)
+            env[key] = value;
+    }
+    for (const [name, provider] of Object.entries(bindings.kv ?? {})) {
+        env[name] = provider;
+    }
+    for (const [name, provider] of Object.entries(bindings.r2 ?? {})) {
+        env[name] = provider;
+    }
+    return env;
+}

package/dist/env.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=env.test.d.ts.map

package/dist/env.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.test.d.ts","sourceRoot":"","sources":["../src/env.test.ts"],"names":[],"mappings":""}

package/dist/env.test.js

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+import { composeNodeEnv } from "./env.js";
+const fakeKv = {};
+const fakeR2 = {};
+describe("composeNodeEnv", () => {
+    it("spreads defined string vars and drops undefined", () => {
+        const env = composeNodeEnv({ DATABASE_URL: "postgres://x", MISSING: undefined });
+        expect(env.DATABASE_URL).toBe("postgres://x");
+        expect("MISSING" in env).toBe(false);
+    });
+    it("attaches KV and R2 providers under their binding names", () => {
+        const env = composeNodeEnv({ FOO: "bar" }, { kv: { CACHE: fakeKv }, r2: { DOCUMENTS_BUCKET: fakeR2 } });
+        expect(env.FOO).toBe("bar");
+        expect(env.CACHE).toBe(fakeKv);
+        expect(env.DOCUMENTS_BUCKET).toBe(fakeR2);
+    });
+    it("lets a binding provider win over a same-named string var", () => {
+        const env = composeNodeEnv({ CACHE: "should-be-overwritten" }, { kv: { CACHE: fakeKv } });
+        expect(env.CACHE).toBe(fakeKv);
+    });
+});

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+export type { ApiDispatch, CreateApiDispatchOptions } from "./api-dispatch.js";
+export { createApiDispatch, lazyApp } from "./api-dispatch.js";
+export type { NodeEnv, NodeEnvBindings } from "./env.js";
+export { composeNodeEnv } from "./env.js";
+export type { KvGetOptions, KvNamespaceShim, KvPutOptions, KvValueType, MemoryKvOptions, } from "./memory-kv.js";
+export { createMemoryKvNamespace } from "./memory-kv.js";
+export { createMemoryR2Bucket } from "./memory-r2.js";
+export type { CreateNodeServerOptions, NodeServerHandle, ScheduledHandlerArgs, } from "./node-server.js";
+export { createNodeServer, HEALTHZ_PATH, SCHEDULED_PATH, scheduledHandler, } from "./node-server.js";
+export type { R2BucketShim, R2BucketShimOptions, R2Fetch, R2ShimObject, } from "./r2.js";
+export { createR2BucketShim } from "./r2.js";
+export type { SsrManifest, SsrManifestRouter } from "./ssr-manifest.js";
+export { restrictSsrManifestToActiveRoutes, withActiveRouteSsrManifest } from "./ssr-manifest.js";
+export type { OriginTrustOptions } from "./trust.js";
+export { constantTimeEqual, ORIGIN_TRUST_HEADER, originTrustMiddleware, verifyOriginTrust, } from "./trust.js";
+export type { AppLoader, ExecutionContextLike, FetchApp, FetchHandler, ScheduledEventLike, ScheduledHandler, WaitUntilContext, } from "./types.js";
+export type { WaitUntilRegistry } from "./wait-until.js";
+export { createWaitUntilRegistry } from "./wait-until.js";
+export type { CreateWorkerFetchOptions, SsrHandler, SsrLoader } from "./worker-fetch.js";
+export { createWorkerFetch, lazySsr } from "./worker-fetch.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,WAAW,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAA;AAC9E,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAE9D,YAAY,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAA;AACzC,YAAY,EACV,YAAY,EACZ,eAAe,EACf,YAAY,EACZ,WAAW,EACX,eAAe,GAChB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAA;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAA;AACrD,YAAY,EACV,uBAAuB,EACvB,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,gBAAgB,EAChB,YAAY,EACZ,cAAc,EACd,gBAAgB,GACjB,MAAM,kBAAkB,CAAA;AACzB,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,OAAO,EACP,YAAY,GACb,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAA;AAC5C,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACvE,OAAO,EAAE,iCAAiC,EAAE,0BAA0B,EAAE,MAAM,mBAAmB,CAAA;AACjG,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AACpD,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,YAAY,CAAA;AAEnB,YAAY,EACV,SAAS,EACT,oBAAoB,EACpB,QAAQ,EACR,YAAY,EACZ,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AACxD,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAA;AACzD,YAAY,EAAE,wBAAwB,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAA;AACxF,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/index.js

@@ -0,0 +1,10 @@
+export { createApiDispatch, lazyApp } from "./api-dispatch.js";
+export { composeNodeEnv } from "./env.js";
+export { createMemoryKvNamespace } from "./memory-kv.js";
+export { createMemoryR2Bucket } from "./memory-r2.js";
+export { createNodeServer, HEALTHZ_PATH, SCHEDULED_PATH, scheduledHandler, } from "./node-server.js";
+export { createR2BucketShim } from "./r2.js";
+export { restrictSsrManifestToActiveRoutes, withActiveRouteSsrManifest } from "./ssr-manifest.js";
+export { constantTimeEqual, ORIGIN_TRUST_HEADER, originTrustMiddleware, verifyOriginTrust, } from "./trust.js";
+export { createWaitUntilRegistry } from "./wait-until.js";
+export { createWorkerFetch, lazySsr } from "./worker-fetch.js";

package/dist/memory-kv.d.ts

@@ -0,0 +1,49 @@
+/**
+ * An in-process `KVNamespace`-shaped store for a resident Node deployment.
+ *
+ * On Cloudflare Workers the `KV` binding is injected by the runtime; on a
+ * Node-only operator there is no binding and — with no Workers lane — nothing
+ * to emulate. A resident process instead holds its own map, so hot reads never
+ * leave the process. The surface is kept identical to the binding the operator
+ * packages already use (`env.CACHE` / `env.RATE_LIMIT`): `get(key)`,
+ * `get(key, "json")`, `put(key, value, { expirationTtl })`, `delete(key)` — so
+ * the same middleware (`publicResponseCache`, `rateLimit`, auth caches) runs
+ * unchanged against `KVStore` (`@voyant-travel/utils`).
+ *
+ * This is a single-process store: entries live only in the process that wrote
+ * them. That is the correct model for the dedicated per-app runtime (one
+ * resident process per deployment). A future multi-instance deployment swaps
+ * this for a shared KV/Redis provider behind the same interface (platform#940).
+ */
+export type KvValueType = "text" | "json";
+export interface KvGetOptions {
+    type?: KvValueType;
+}
+export interface KvPutOptions {
+    /** TTL in seconds — the entry is treated as absent once it elapses. */
+    expirationTtl?: number;
+}
+/** Minimal `KVNamespace` surface consumed across the operator packages. */
+export interface KvNamespaceShim {
+    get(key: string): Promise<string | null>;
+    get<T = unknown>(key: string, type: "json"): Promise<T | null>;
+    get<T = unknown>(key: string, options: KvGetOptions): Promise<T | string | null>;
+    put(key: string, value: string, options?: KvPutOptions): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+export interface MemoryKvOptions {
+    /**
+     * Cap on resident entries before least-recently-used eviction. A resident
+     * process is long-lived, so an unbounded map would grow without limit;
+     * defaults to 10,000. Set `0` to disable eviction (unbounded).
+     */
+    maxEntries?: number;
+    /** Injectable clock (ms) for deterministic TTL tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Build an in-process {@link KvNamespaceShim}. Backed by a `Map` with per-entry
+ * TTL and LRU eviction — the real Node KV, not a shim over a remote binding.
+ */
+export declare function createMemoryKvNamespace(options?: MemoryKvOptions): KvNamespaceShim;
+//# sourceMappingURL=memory-kv.d.ts.map

package/dist/memory-kv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-kv.d.ts","sourceRoot":"","sources":["../src/memory-kv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,CAAA;AAEzC,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,WAAW,CAAA;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB;AAED,2EAA2E;AAC3E,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACxC,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IAC9D,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,CAAC,GAAG,MAAM,GAAG,IAAI,CAAC,CAAA;IAChF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACtE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACnC;AAED,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,iFAAiF;IACjF,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CACnB;AAUD;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,GAAE,eAAoB,GAAG,eAAe,CAiDtF"}

package/dist/memory-kv.js

@@ -0,0 +1,69 @@
+/**
+ * An in-process `KVNamespace`-shaped store for a resident Node deployment.
+ *
+ * On Cloudflare Workers the `KV` binding is injected by the runtime; on a
+ * Node-only operator there is no binding and — with no Workers lane — nothing
+ * to emulate. A resident process instead holds its own map, so hot reads never
+ * leave the process. The surface is kept identical to the binding the operator
+ * packages already use (`env.CACHE` / `env.RATE_LIMIT`): `get(key)`,
+ * `get(key, "json")`, `put(key, value, { expirationTtl })`, `delete(key)` — so
+ * the same middleware (`publicResponseCache`, `rateLimit`, auth caches) runs
+ * unchanged against `KVStore` (`@voyant-travel/utils`).
+ *
+ * This is a single-process store: entries live only in the process that wrote
+ * them. That is the correct model for the dedicated per-app runtime (one
+ * resident process per deployment). A future multi-instance deployment swaps
+ * this for a shared KV/Redis provider behind the same interface (platform#940).
+ */
+const DEFAULT_MAX_ENTRIES = 10_000;
+/**
+ * Build an in-process {@link KvNamespaceShim}. Backed by a `Map` with per-entry
+ * TTL and LRU eviction — the real Node KV, not a shim over a remote binding.
+ */
+export function createMemoryKvNamespace(options = {}) {
+    const maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    const now = options.now ?? Date.now;
+    const map = new Map();
+    function readFresh(key) {
+        const entry = map.get(key);
+        if (!entry)
+            return null;
+        if (entry.expiresAt <= now()) {
+            map.delete(key);
+            return null;
+        }
+        // Refresh recency for LRU.
+        map.delete(key);
+        map.set(key, entry);
+        return entry.value;
+    }
+    async function get(key, typeOrOptions) {
+        const type = typeof typeOrOptions === "string" ? typeOrOptions : (typeOrOptions?.type ?? "text");
+        const raw = readFresh(key);
+        if (raw === null)
+            return null;
+        return type === "json" ? JSON.parse(raw) : raw;
+    }
+    return {
+        get: get,
+        async put(key, value, putOptions) {
+            if (map.has(key))
+                map.delete(key);
+            const expiresAt = putOptions?.expirationTtl === undefined
+                ? Number.POSITIVE_INFINITY
+                : now() + putOptions.expirationTtl * 1000;
+            map.set(key, { value, expiresAt });
+            if (maxEntries > 0) {
+                while (map.size > maxEntries) {
+                    const oldest = map.keys().next().value;
+                    if (oldest === undefined)
+                        break;
+                    map.delete(oldest);
+                }
+            }
+        },
+        async delete(key) {
+            map.delete(key);
+        },
+    };
+}

package/dist/memory-kv.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=memory-kv.test.d.ts.map

package/dist/memory-kv.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-kv.test.d.ts","sourceRoot":"","sources":["../src/memory-kv.test.ts"],"names":[],"mappings":""}

package/dist/memory-kv.test.js

@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import { createMemoryKvNamespace } from "./memory-kv.js";
+describe("createMemoryKvNamespace", () => {
+    it("puts and gets text values", async () => {
+        const kv = createMemoryKvNamespace();
+        await kv.put("k", "v");
+        expect(await kv.get("k")).toBe("v");
+    });
+    it("returns null for missing keys", async () => {
+        const kv = createMemoryKvNamespace();
+        expect(await kv.get("nope")).toBeNull();
+    });
+    it("parses JSON with the json type", async () => {
+        const kv = createMemoryKvNamespace();
+        await kv.put("obj", JSON.stringify({ a: 1 }));
+        expect(await kv.get("obj", "json")).toEqual({ a: 1 });
+        expect(await kv.get("obj", { type: "json" })).toEqual({ a: 1 });
+    });
+    it("deletes keys", async () => {
+        const kv = createMemoryKvNamespace();
+        await kv.put("k", "v");
+        await kv.delete("k");
+        expect(await kv.get("k")).toBeNull();
+    });
+    it("expires entries after expirationTtl seconds", async () => {
+        let clock = 1_000;
+        const kv = createMemoryKvNamespace({ now: () => clock });
+        await kv.put("k", "v", { expirationTtl: 30 });
+        expect(await kv.get("k")).toBe("v");
+        clock += 30_001;
+        expect(await kv.get("k")).toBeNull();
+    });
+    it("evicts least-recently-used entries past maxEntries", async () => {
+        const kv = createMemoryKvNamespace({ maxEntries: 2 });
+        await kv.put("a", "1");
+        await kv.put("b", "2");
+        // Touch "a" so "b" becomes the LRU victim.
+        await kv.get("a");
+        await kv.put("c", "3");
+        expect(await kv.get("a")).toBe("1");
+        expect(await kv.get("b")).toBeNull();
+        expect(await kv.get("c")).toBe("3");
+    });
+});

package/dist/memory-r2.d.ts

@@ -0,0 +1,4 @@
+import type { R2BucketShim } from "./r2.js";
+/** Build an in-memory {@link R2BucketShim} for local/dev runs. */
+export declare function createMemoryR2Bucket(): R2BucketShim;
+//# sourceMappingURL=memory-r2.d.ts.map

package/dist/memory-r2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-r2.d.ts","sourceRoot":"","sources":["../src/memory-r2.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,SAAS,CAAA;AAwDzD,kEAAkE;AAClE,wBAAgB,oBAAoB,IAAI,YAAY,CA8BnD"}

package/dist/memory-r2.js

@@ -0,0 +1,76 @@
+function bytesToStream(bytes) {
+    return new ReadableStream({
+        start(controller) {
+            controller.enqueue(bytes);
+            controller.close();
+        },
+    });
+}
+async function toBytes(value) {
+    if (value === null)
+        return new Uint8Array();
+    if (typeof value === "string")
+        return new TextEncoder().encode(value);
+    if (value instanceof Uint8Array)
+        return value;
+    if (value instanceof ArrayBuffer)
+        return new Uint8Array(value);
+    if (ArrayBuffer.isView(value)) {
+        return new Uint8Array(value.buffer, value.byteOffset, value.byteLength);
+    }
+    if (value instanceof Blob)
+        return new Uint8Array(await value.arrayBuffer());
+    return new Uint8Array(await new Response(value).arrayBuffer());
+}
+function toObject(stored) {
+    const { bytes } = stored;
+    const object = {
+        // Copy only this view's bytes — `bytes` may be a subarray of a larger
+        // backing buffer (e.g. a Node Buffer passed through `StorageProvider.upload`),
+        // so returning the whole `.buffer` would leak unrelated bytes.
+        arrayBuffer: async () => bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength),
+        body: bytesToStream(bytes),
+        size: bytes.byteLength,
+    };
+    if (stored.contentType)
+        object.httpMetadata = { contentType: stored.contentType };
+    if (stored.customMetadata)
+        object.customMetadata = stored.customMetadata;
+    return object;
+}
+/** Build an in-memory {@link R2BucketShim} for local/dev runs. */
+export function createMemoryR2Bucket() {
+    const map = new Map();
+    return {
+        async put(key, value, putOptions) {
+            const stored = { bytes: await toBytes(value) };
+            if (putOptions?.httpMetadata?.contentType) {
+                stored.contentType = putOptions.httpMetadata.contentType;
+            }
+            if (putOptions?.customMetadata)
+                stored.customMetadata = putOptions.customMetadata;
+            map.set(key, stored);
+            return { key };
+        },
+        async delete(key) {
+            const keys = Array.isArray(key) ? key : [key];
+            for (const k of keys)
+                map.delete(k);
+        },
+        async get(key) {
+            const stored = map.get(key);
+            return stored ? toObject(stored) : null;
+        },
+        async head(key) {
+            const stored = map.get(key);
+            if (!stored)
+                return null;
+            const meta = { size: stored.bytes.byteLength };
+            if (stored.contentType)
+                meta.httpMetadata = { contentType: stored.contentType };
+            if (stored.customMetadata)
+                meta.customMetadata = stored.customMetadata;
+            return meta;
+        },
+    };
+}

package/dist/memory-r2.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=memory-r2.test.d.ts.map

package/dist/memory-r2.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-r2.test.d.ts","sourceRoot":"","sources":["../src/memory-r2.test.ts"],"names":[],"mappings":""}

package/dist/memory-r2.test.js

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+import { createMemoryR2Bucket } from "./memory-r2.js";
+describe("createMemoryR2Bucket", () => {
+    it("puts and gets an object with metadata", async () => {
+        const bucket = createMemoryR2Bucket();
+        await bucket.put("docs/a.txt", "hello", {
+            httpMetadata: { contentType: "text/plain" },
+            customMetadata: { owner: "u1" },
+        });
+        const object = await bucket.get("docs/a.txt");
+        expect(object).not.toBeNull();
+        expect(new TextDecoder().decode(await object.arrayBuffer())).toBe("hello");
+        expect(object.httpMetadata?.contentType).toBe("text/plain");
+        expect(object.customMetadata?.owner).toBe("u1");
+        expect(object.size).toBe(5);
+    });
+    it("returns only the stored view's bytes when put a subarray of a larger buffer", async () => {
+        const bucket = createMemoryR2Bucket();
+        const backing = new Uint8Array([1, 2, 3, 4, 5, 6]);
+        await bucket.put("k", backing.subarray(2, 4)); // [3, 4], offset into a 6-byte buffer
+        const object = await bucket.get("k");
+        expect(new Uint8Array(await object.arrayBuffer())).toEqual(new Uint8Array([3, 4]));
+        expect(object.size).toBe(2);
+    });
+    it("returns null for a missing object", async () => {
+        const bucket = createMemoryR2Bucket();
+        expect(await bucket.get("missing")).toBeNull();
+        expect(await bucket.head("missing")).toBeNull();
+    });
+    it("heads without the body", async () => {
+        const bucket = createMemoryR2Bucket();
+        await bucket.put("k", "abc");
+        const head = await bucket.head("k");
+        expect(head?.size).toBe(3);
+    });
+    it("deletes one and many keys", async () => {
+        const bucket = createMemoryR2Bucket();
+        await bucket.put("a", "1");
+        await bucket.put("b", "2");
+        await bucket.delete("a");
+        await bucket.delete(["b"]);
+        expect(await bucket.get("a")).toBeNull();
+        expect(await bucket.get("b")).toBeNull();
+    });
+});