@kiwa-test/edge 1.0.2 → 1.1.0

package/dist/index.d.ts

@@ -63,4 +63,522 @@ interface InvokeEdgeHandlerResult {
  */
 declare function invokeEdgeHandler<TEnv extends EdgeEnvBindings = EdgeEnvBindings>(opts: InvokeEdgeHandlerOptions<TEnv>): Promise<InvokeEdgeHandlerResult>;
 
-export { type EdgeEnvBindings, type EdgeFetchHandler, type InvokeEdgeHandlerOptions, type InvokeEdgeHandlerResult, type KVMockEntry, type KVNamespace, type KVNamespaceListOptions, type KVNamespaceListResult, type KVNamespacePutOptions, type SimulatedExecutionContext, createKvNamespace, invokeEdgeHandler };
+/**
+ * Advanced edge semantics — platform-neutral axis SSOT.
+ *
+ * v0.1 edge mocks only carried fetch invocation + lightweight KV helpers.
+ * v0.2 adds 8 production semantics that edge runtimes expose differently —
+ * Durable Objects, websocket upgrades, edge KV, geo replication, cron triggers,
+ * subrequest limits, CPU time limits, and streaming responses. Each axis is
+ * expressed as a small pure state-machine helper that returns a neutral
+ * envelope, so downstream tests can drive the axis without knowing the
+ * platform's payload dialect.
+ */
+type EdgePlatform = 'cloudflare' | 'vercel' | 'deno';
+type EdgeAxis = 'durable-object' | 'websocket-edge' | 'edge-kv' | 'geo-replicated' | 'cron-trigger' | 'subrequest-limit' | 'cpu-time-limit' | 'streaming-response';
+/**
+ * Platform-neutral event names used inside the axis helpers. Real edge
+ * platforms expose different string ids (Cloudflare `durable_object.fetch`,
+ * Vercel `edge_function.session_affinity`, Deno Deploy `deploy.stateful_fetch`)
+ * — the {@link platformEventName} map handles the translation. Tests can
+ * assert on the neutral name via `step.neutralEvent` or on the
+ * platform-specific one via `step.platformEvent`.
+ */
+type NeutralEventName = 'durable-object.created' | 'durable-object.requested' | 'durable-object.alarm-fired' | 'durable-object.storage-written' | 'websocket.upgrade-requested' | 'websocket.accepted' | 'websocket.message' | 'websocket.closed' | 'kv.read' | 'kv.write' | 'kv.cache-hit' | 'kv.cache-miss' | 'geo.primary-write' | 'geo.replica-lagged' | 'geo.replica-synced' | 'geo.conflict-resolved' | 'cron.scheduled' | 'cron.started' | 'cron.completed' | 'cron.failed' | 'subrequest.started' | 'subrequest.counted' | 'subrequest.limited' | 'subrequest.completed' | 'cpu.started' | 'cpu.budget-warning' | 'cpu.limited' | 'cpu.completed' | 'stream.opened' | 'stream.chunk-sent' | 'stream.backpressure' | 'stream.closed';
+/**
+ * Translate a neutral event name to the platform dialect. Falls back to the
+ * neutral name if the platform has no specific dialect entry — this makes
+ * the map partial-safe without silent typos.
+ */
+declare function platformEventName(platform: EdgePlatform, neutral: NeutralEventName): string;
+/**
+ * Axis result envelope returned by every state-machine step. Edge semantics
+ * are pure helpers (no adapters); the envelope surfaces the next state
+ * transition metadata so tests can drive the next call without re-reading
+ * runtime-specific telemetry.
+ */
+interface AxisStep<TState> {
+    neutralEvent: NeutralEventName;
+    platformEvent: string;
+    state: TState;
+    platform: EdgePlatform;
+    metadata: Record<string, string | number | boolean>;
+}
+
+/**
+ * Fidelity harness — collects the platform × axis coverage grid that
+ * downstream release-gate reports on. Not a runner (no side effect emit);
+ * pure inspection so tests / release-gate can assert "3 platform × 8 axis"
+ * without walking every neutral event by hand.
+ */
+interface FidelityRow {
+    platform: EdgePlatform;
+    axis: EdgeAxis;
+    neutralEvents: NeutralEventName[];
+    platformEvents: string[];
+}
+interface FidelityCoverage {
+    platforms: EdgePlatform[];
+    axes: EdgeAxis[];
+    rows: FidelityRow[];
+}
+declare const AXIS_TO_EVENTS: Record<EdgeAxis, NeutralEventName[]>;
+/**
+ * Collect the platform × axis coverage grid. `platforms` is the list of
+ * platforms to inspect — usually all 3 (`cloudflare`, `vercel`, `deno`).
+ *
+ * The output is a flat row list `platforms.length * 8 = 24` for the default
+ * setup, plus `platforms` + `axes` roll-up lists so callers can assert on
+ * the grid dimensions.
+ */
+declare function collectFidelityCoverage(platforms: EdgePlatform[]): FidelityCoverage;
+
+/**
+ * Durable Object — stateful, single-instance actor pinned to one edge
+ * location. Cloudflare Durable Objects are the canonical example; Vercel's
+ * closest analogue is a session-affine edge function, Deno Deploy exposes
+ * stateful objects backed by Deno KV. The mock reproduces the user-observable
+ * lifecycle: an instance is created once, receives fetch requests (which pin
+ * it "active"), can wake on a scheduled alarm, and persists to transactional
+ * storage. Hibernation / eviction is intentionally out of scope for v0.2 — the
+ * axis only exposes the 4 neutral events the fidelity grid tracks.
+ *
+ * State transitions:
+ *   created            → 'initialized'
+ *   requestDurableObject → 'active'   (from initialized or active)
+ *   fireAlarm          → 'active'     (an alarm wakes the object)
+ *   writeStorage       → 'active'     (a storage write implies an active handler)
+ */
+type DoState = 'initialized' | 'active' | 'hibernated' | 'terminated';
+interface DurableObjectSession {
+    id: string;
+    platform: EdgePlatform;
+    state: DoState;
+    requestCount: number;
+    storageKeys: Map<string, string>;
+    scheduledAlarmAt: number | null;
+    history: AxisStep<DoState>[];
+}
+/**
+ * Create a durable object instance. State starts at 'initialized' and no
+ * request has been served yet. Emits `durable-object.created`.
+ */
+declare function createDurableObject(input: {
+    id: string;
+    platform: EdgePlatform;
+}): DurableObjectSession;
+/**
+ * Route a fetch request to the object. Pins the instance 'active' and bumps
+ * the request counter. Emits `durable-object.requested`.
+ */
+declare function requestDurableObject(session: DurableObjectSession, input: {
+    url: string;
+}): AxisStep<DoState>;
+/**
+ * Fire the scheduled alarm. Wakes the object into 'active' regardless of the
+ * prior state and clears the pending alarm. Emits `durable-object.alarm-fired`.
+ */
+declare function fireAlarm(session: DurableObjectSession): AxisStep<DoState>;
+/**
+ * Write a key to transactional storage. Implies an active handler, so the
+ * object stays 'active'. Emits `durable-object.storage-written`.
+ */
+declare function writeStorage(session: DurableObjectSession, input: {
+    key: string;
+    value: string;
+}): AxisStep<DoState>;
+
+/**
+ * WebSocket at the edge — the HTTP-upgrade handshake plus the message /
+ * close lifecycle. All three runtimes accept a `101 Switching Protocols`
+ * upgrade (Cloudflare `WebSocketPair`, Vercel edge websockets, Deno
+ * `Deno.upgradeWebSocket`) but expose different telemetry strings. The mock
+ * drives the neutral lifecycle so a test can assert the handshake ordering
+ * without a live socket.
+ *
+ * State transitions:
+ *   requestWebSocketUpgrade → 'pending'
+ *   acceptWebSocket         → 'open'    (only from 'pending')
+ *   sendMessage             → 'open'    (only while 'open')
+ *   closeWebSocket          → 'closed'
+ */
+type WsState = 'pending' | 'open' | 'closing' | 'closed';
+interface WebSocketSession {
+    id: string;
+    platform: EdgePlatform;
+    state: WsState;
+    messages: string[];
+    history: AxisStep<WsState>[];
+}
+/**
+ * Begin the upgrade handshake. State starts 'pending' until the server
+ * accepts. Emits `websocket.upgrade-requested`.
+ */
+declare function requestWebSocketUpgrade(input: {
+    id: string;
+    platform: EdgePlatform;
+}): WebSocketSession;
+/**
+ * Accept the pending upgrade, moving the socket 'open'. Rejects if the socket
+ * is not awaiting acceptance. Emits `websocket.accepted`.
+ */
+declare function acceptWebSocket(session: WebSocketSession): AxisStep<WsState>;
+/**
+ * Send a frame over the open socket. Rejects unless the socket is 'open'.
+ * Emits `websocket.message`.
+ */
+declare function sendMessage(session: WebSocketSession, input: {
+    data: string;
+}): AxisStep<WsState>;
+/**
+ * Close the socket with a status code. Rejects if already closed. Emits
+ * `websocket.closed`.
+ */
+declare function closeWebSocket(session: WebSocketSession, input: {
+    code: number;
+}): AxisStep<WsState>;
+
+/**
+ * Edge KV — a globally replicated key/value store with a read-through cache.
+ * Cloudflare KV, Vercel Edge Config, and Deno KV all trade strong consistency
+ * for low-latency edge reads: a write may take time to propagate, and reads
+ * are served from a per-POP cache when warm. The mock models the observable
+ * surface: a backing `store`, a `cache` layer that a read populates and a
+ * write invalidates, and a range query over a key prefix.
+ *
+ * There is no state machine per se — the store is always usable. `state`
+ * records the consistency model the caller declared so downstream tests can
+ * assert on it. The 4 neutral events distinguish a cold read, a write, a warm
+ * cache hit, and a miss on an absent key.
+ */
+type KvState = 'consistent' | 'eventually-consistent';
+interface EdgeKvSession {
+    platform: EdgePlatform;
+    store: Map<string, string>;
+    cache: Map<string, string>;
+    state: KvState;
+    history: AxisStep<KvState>[];
+}
+/**
+ * Construct a KV session. No event is emitted — the store is simply opened.
+ * Defaults to eventual consistency, the common edge-KV replication model.
+ */
+declare function createEdgeKvSession(input: {
+    platform: EdgePlatform;
+    state?: KvState;
+}): EdgeKvSession;
+/**
+ * Read a key. Three outcomes:
+ *   - cache warm  → `kv.cache-hit`
+ *   - store only  → `kv.read` and the cache is populated (read-through)
+ *   - absent      → `kv.cache-miss`
+ */
+declare function kvRead(session: EdgeKvSession, input: {
+    key: string;
+}): AxisStep<KvState>;
+/**
+ * Write a key. Updates the backing store and invalidates the cache entry so
+ * the next read goes through to the store. Emits `kv.write`.
+ */
+declare function kvWrite(session: EdgeKvSession, input: {
+    key: string;
+    value: string;
+}): AxisStep<KvState>;
+/**
+ * Range query over a key prefix. Returns the matching keys (sorted, up to
+ * `limit`) alongside the emitted step. Emits `kv.read` since a range scan is a
+ * store read. `limit` defaults to no cap.
+ */
+declare function kvRangeQuery(session: EdgeKvSession, input: {
+    prefix: string;
+    limit?: number;
+}): {
+    matches: string[];
+    step: AxisStep<KvState>;
+};
+
+/**
+ * Geo-replicated store — a primary region that accepts writes and N replica
+ * regions that catch up asynchronously. This is the multi-region consistency
+ * model behind Cloudflare Smart Placement + KV replication, Vercel Edge Config
+ * replication, and Deno KV's primary/replica topology. The mock exposes the
+ * observable lifecycle a test cares about: a primary write bumps a version and
+ * leaves replicas lagging, each replica is marked lagged then synced, and a
+ * write conflict can be explicitly resolved.
+ *
+ * State transitions:
+ *   createGeoReplicatedSession → 'in-sync'   (version 0, no lag)
+ *   geoPrimaryWrite            → 'lagging'    (replicas fall behind)
+ *   markReplicaLagged          → 'lagging'
+ *   syncReplica                → 'in-sync'    (only once every replica lag = 0)
+ *   resolveConflict            → 'in-sync'
+ */
+type GeoRegion = string;
+type GeoState = 'in-sync' | 'lagging' | 'conflict-detected';
+interface GeoReplicatedSession {
+    platform: EdgePlatform;
+    primaryRegion: GeoRegion;
+    replicaRegions: GeoRegion[];
+    state: GeoState;
+    version: number;
+    lagMs: Record<GeoRegion, number>;
+    history: AxisStep<GeoState>[];
+}
+/**
+ * Construct a geo-replicated session. Starts 'in-sync' at version 0 with every
+ * replica at zero lag. No event is emitted.
+ */
+declare function createGeoReplicatedSession(input: {
+    platform: EdgePlatform;
+    primaryRegion: GeoRegion;
+    replicaRegions: GeoRegion[];
+}): GeoReplicatedSession;
+/**
+ * Write to the primary region. Bumps the version and marks every replica as
+ * lagging (they have not yet received the new version). Emits
+ * `geo.primary-write`.
+ */
+declare function geoPrimaryWrite(session: GeoReplicatedSession, input: {
+    data: string;
+}): AxisStep<GeoState>;
+/**
+ * Report replication lag for a specific replica. Rejects an unknown region.
+ * Emits `geo.replica-lagged`.
+ */
+declare function markReplicaLagged(session: GeoReplicatedSession, input: {
+    region: GeoRegion;
+    lagMs: number;
+}): AxisStep<GeoState>;
+/**
+ * Mark a replica caught up (lag → 0). When every replica has zero lag the
+ * session returns 'in-sync'. Rejects an unknown region. Emits
+ * `geo.replica-synced`.
+ */
+declare function syncReplica(session: GeoReplicatedSession, input: {
+    region: GeoRegion;
+}): AxisStep<GeoState>;
+/**
+ * Resolve a write conflict for a region by picking a winning version. Rejects
+ * an unknown region. Adopts the chosen version, clears every replica's lag and
+ * forces the session back to 'in-sync'. Emits `geo.conflict-resolved`.
+ */
+declare function resolveConflict(session: GeoReplicatedSession, input: {
+    region: GeoRegion;
+    chosenVersion: number;
+}): AxisStep<GeoState>;
+
+/**
+ * Cron trigger — scheduled invocation lifecycle. Edge platforms fire scheduled
+ * handlers from distinct sources (Cloudflare Cron Triggers + Queue consumers +
+ * Email routing, Vercel Cron jobs, Deno Deploy cron) yet share the same
+ * observable lifecycle: an event is scheduled, starts running, then either
+ * completes or fails. A failed run re-enters the schedule until `maxRetries`
+ * is exhausted, at which point it terminates in `failed`.
+ */
+type CronState = 'scheduled' | 'running' | 'completed' | 'failed';
+/** Which trigger source fired the scheduled handler. */
+type CronTriggerType = 'scheduled' | 'queue' | 'email';
+interface CronSession {
+    id: string;
+    platform: EdgePlatform;
+    triggerType: CronTriggerType;
+    cronSpec: string;
+    state: CronState;
+    startedAt: number | null;
+    retryCount: number;
+    maxRetries: number;
+    history: AxisStep<CronState>[];
+}
+/**
+ * Schedule a cron invocation. Emits `cron.scheduled` and seeds the session in
+ * the `scheduled` state. `triggerType` defaults to `scheduled` (a plain time
+ * trigger) and `maxRetries` defaults to 3.
+ */
+declare function scheduleCron(input: {
+    id: string;
+    platform: EdgePlatform;
+    triggerType?: CronTriggerType;
+    cronSpec: string;
+    maxRetries?: number;
+}): CronSession;
+/**
+ * Begin executing a scheduled invocation. Transitions `scheduled` → `running`,
+ * stamps `startedAt`, and emits `cron.started`. Rejects if the session is not
+ * currently `scheduled` (already running / terminal).
+ */
+declare function startCron(session: CronSession): AxisStep<CronState>;
+/**
+ * Finish a running invocation successfully. Transitions `running` →
+ * `completed` and emits `cron.completed`. Rejects if not `running`.
+ */
+declare function completeCron(session: CronSession, input: {
+    durationMs: number;
+}): AxisStep<CronState>;
+/**
+ * Fail a running invocation. Increments `retryCount`; if retries remain the
+ * session re-enters the `scheduled` state (to be picked up again), otherwise it
+ * terminates in `failed`. Emits `cron.failed` with `willRetry` reflecting the
+ * decision. Rejects if the session already `completed`.
+ */
+declare function failCron(session: CronSession, input: {
+    reason: string;
+}): AxisStep<CronState>;
+
+/**
+ * Subrequest limit — outbound fetch budget per invocation. Edge runtimes cap
+ * how many subrequests a single handler may issue (Cloudflare Workers default
+ * 50 on the free plan, Vercel + Deno enforce comparable ceilings). The axis
+ * tracks a running count against the limit: below a warning threshold the
+ * session is `ok`, at the threshold it is `approaching-limit`, and once the
+ * count reaches the hard limit it is `limited` and further fetches are refused.
+ */
+type SubrequestState = 'ok' | 'approaching-limit' | 'limited';
+interface SubrequestSession {
+    platform: EdgePlatform;
+    count: number;
+    limit: number;
+    warningThreshold: number;
+    state: SubrequestState;
+    history: AxisStep<SubrequestState>[];
+}
+/**
+ * Open a subrequest budget. `limit` defaults to 50 (Workers free-plan default)
+ * and `warningThreshold` to 40 (80% of the default limit). Emits nothing — the
+ * budget is inert until the first {@link startSubrequest}.
+ */
+declare function startSubrequestBudget(input: {
+    platform: EdgePlatform;
+    limit?: number;
+    warningThreshold?: number;
+}): SubrequestSession;
+/**
+ * Announce an outbound subrequest. Emits `subrequest.started` but does not
+ * advance the count (starting is distinct from counting — a started request
+ * only counts once it is admitted via {@link countSubrequest}). Rejects when
+ * the budget is already `limited`.
+ */
+declare function startSubrequest(session: SubrequestSession, input: {
+    url: string;
+}): AxisStep<SubrequestState>;
+/**
+ * Count an admitted subrequest against the budget. Increments the count and
+ * emits `subrequest.limited` when the count reaches the hard limit (state →
+ * `limited`), otherwise `subrequest.counted` — flipping to `approaching-limit`
+ * once the warning threshold is crossed.
+ */
+declare function countSubrequest(session: SubrequestSession): AxisStep<SubrequestState>;
+/**
+ * Mark an outbound subrequest as finished. Emits `subrequest.completed` with
+ * the final count. Does not mutate state — a completed request that already
+ * tripped the limit stays `limited`.
+ */
+declare function completeSubrequest(session: SubrequestSession, input: {
+    url: string;
+    durationMs: number;
+}): AxisStep<SubrequestState>;
+/** Remaining subrequest budget (never negative). */
+declare function remainingBudget(session: SubrequestSession): number;
+
+/**
+ * CPU time limit — per-invocation compute budget. Edge runtimes bill wall-clock
+ * loosely but enforce a hard CPU budget (Cloudflare Workers 50ms on the free
+ * plan, Vercel + Deno enforce comparable ceilings). The axis accumulates
+ * elapsed CPU time across ticks: below a warning threshold it is `running`, at
+ * the threshold it flips to `warning`, and once the budget is exhausted the
+ * invocation is `throttled` and no further work is admitted.
+ */
+type CpuState = 'idle' | 'running' | 'warning' | 'throttled' | 'completed';
+interface CpuSession {
+    platform: EdgePlatform;
+    budgetMs: number;
+    warningAtMs: number;
+    elapsedMs: number;
+    state: CpuState;
+    history: AxisStep<CpuState>[];
+}
+/**
+ * Open a CPU budget. `budgetMs` defaults to 50 (Workers free-plan default) and
+ * `warningAtMs` to 40 (80% of the default budget). Emits nothing — the budget
+ * is `idle` until {@link startCpu}.
+ */
+declare function startCpuBudget(input: {
+    platform: EdgePlatform;
+    budgetMs?: number;
+    warningAtMs?: number;
+}): CpuSession;
+/**
+ * Begin consuming the CPU budget. Transitions `idle` → `running` and emits
+ * `cpu.started`. Rejects if the session is not `idle`.
+ */
+declare function startCpu(session: CpuSession): AxisStep<CpuState>;
+/**
+ * Advance the CPU clock by `deltaMs`. Emits `cpu.limited` when the accumulated
+ * time reaches the budget (state → `throttled`), `cpu.budget-warning` when it
+ * crosses the warning threshold (state → `warning`), otherwise a `cpu.started`
+ * heartbeat carrying the remaining budget. Rejects once the session is
+ * `throttled` or `completed`.
+ */
+declare function tickCpu(session: CpuSession, input: {
+    deltaMs: number;
+}): AxisStep<CpuState>;
+/**
+ * Finish the invocation. Transitions to `completed` and emits `cpu.completed`
+ * with the used ratio. Rejects if the session never started (`idle`).
+ */
+declare function completeCpu(session: CpuSession): AxisStep<CpuState>;
+
+/**
+ * Streaming response — chunked / SSE / websocket body delivery with
+ * backpressure. Edge runtimes stream responses through a bounded buffer: while
+ * buffered bytes stay under the high-water mark the stream is `open` and chunks
+ * flow freely; once the mark is exceeded the stream enters `backpressure` and
+ * the producer must wait for the consumer to drain before resuming.
+ */
+type StreamState = 'open' | 'backpressure' | 'closed';
+/** Delivery mechanism for the streamed body. */
+type StreamKind = 'chunked' | 'sse' | 'websocket';
+interface StreamSession {
+    id: string;
+    platform: EdgePlatform;
+    kind: StreamKind;
+    state: StreamState;
+    chunksSent: number;
+    bytesSent: number;
+    highWaterMark: number;
+    history: AxisStep<StreamState>[];
+}
+/**
+ * Open a response stream. `kind` defaults to `chunked` and `highWaterMark` to
+ * 65536 bytes (64 KiB). Emits `stream.opened` and seeds counters at zero.
+ */
+declare function openStream(input: {
+    id: string;
+    platform: EdgePlatform;
+    kind?: StreamKind;
+    highWaterMark?: number;
+}): StreamSession;
+/**
+ * Write a chunk to the stream. Advances `chunksSent` + `bytesSent`; when the
+ * buffered byte total exceeds the high-water mark the stream flips to
+ * `backpressure` and emits `stream.backpressure`, otherwise `stream.chunk-sent`.
+ * Rejects if the stream is already `closed`.
+ */
+declare function sendChunk(session: StreamSession, input: {
+    data: string;
+}): AxisStep<StreamState>;
+/**
+ * Resume a back-pressured stream after the consumer drained. Transitions
+ * `backpressure` → `open`, drains one high-water mark worth of buffered bytes,
+ * and re-emits `stream.chunk-sent` tagged `resumed: true` (there is no distinct
+ * neutral resume event). Rejects unless the stream is `backpressure`.
+ */
+declare function resumeStream(session: StreamSession): AxisStep<StreamState>;
+/**
+ * Close the stream. Transitions to `closed` and emits `stream.closed` with the
+ * final chunk + byte totals. Rejects if the stream is already `closed`.
+ */
+declare function closeStream(session: StreamSession, input: {
+    reason: string;
+}): AxisStep<StreamState>;
+
+export { AXIS_TO_EVENTS, type AxisStep, type CpuSession, type CpuState, type CronSession, type CronState, type CronTriggerType, type DoState, type DurableObjectSession, type EdgeAxis, type EdgeEnvBindings, type EdgeFetchHandler, type EdgeKvSession, type EdgePlatform, type FidelityCoverage, type FidelityRow, type GeoRegion, type GeoReplicatedSession, type GeoState, type InvokeEdgeHandlerOptions, type InvokeEdgeHandlerResult, type KVMockEntry, type KVNamespace, type KVNamespaceListOptions, type KVNamespaceListResult, type KVNamespacePutOptions, type KvState, type NeutralEventName, type SimulatedExecutionContext, type StreamKind, type StreamSession, type StreamState, type SubrequestSession, type SubrequestState, type WebSocketSession, type WsState, acceptWebSocket, closeStream, closeWebSocket, collectFidelityCoverage, completeCpu, completeCron, completeSubrequest, countSubrequest, createDurableObject, createEdgeKvSession, createGeoReplicatedSession, createKvNamespace, failCron, fireAlarm, geoPrimaryWrite, invokeEdgeHandler, kvRangeQuery, kvRead, kvWrite, markReplicaLagged, openStream, platformEventName, remainingBudget, requestDurableObject, requestWebSocketUpgrade, resolveConflict, resumeStream, scheduleCron, sendChunk, sendMessage, startCpu, startCpuBudget, startCron, startSubrequest, startSubrequestBudget, syncReplica, tickCpu, writeStorage };