iterate 0.2.7 → 0.3.0

package/dist/processors/testing.d.ts

@@ -0,0 +1,302 @@
+import type { StreamEvent, StreamEventInput } from "./schemas.ts";
+import type { StreamEventReadInput } from "./rpc-types.ts";
+import type { ConsumedInput, ProcessorState, ResolvedEvent } from "./processor-contracts.ts";
+import type { RegisteredProcessorReads } from "./stream-processor-registry.ts";
+import type { ProcessorStream } from "./stream-handle.ts";
+import type { StreamProcessor, StreamProcessorContract } from "./stream-processor.ts";
+import type { ProcessorProgressStore } from "./stream-processor-runner.ts";
+import { StreamProcessorRunner } from "./stream-processor-runner.ts";
+export declare class MemoryStream implements ProcessorStream {
+    events: StreamEvent[];
+    streamId: `${string}-${string}-${string}-${string}-${string}`;
+    /** Injectable clock for createdAt stamps; harnesses point it at virtual time. */
+    now: () => number;
+    /** Simulate a transient Stream DO outage: appends of this type throw. */
+    failAppendsOfType: string | undefined;
+    /**
+     * OPT-IN ASYNCHRONOUS COMMIT. Undefined — the default — is today's behaviour
+     * and every existing suite's behaviour.
+     *
+     * `append` below validates and publishes in its own SYNCHRONOUS body: it is
+     * declared `async`, but nothing inside it awaits, so the events are in
+     * `this.events` and their offsets are taken before the returned promise is
+     * even handed back. Two call sites therefore commit in the order they
+     * CALLED, whoever awaited and whoever did not. That determinism is what
+     * makes scenario steps reproducible and it is why ~250 suites rest on it.
+     *
+     * It is also a lie about production. A real append is an RPC to the Stream
+     * Durable Object; two of them can be in flight at once, and the one issued
+     * first is not guaranteed to commit first. Every ordering bug of that shape
+     * — an un-awaited append racing an awaited one, and the un-awaited one
+     * losing — is structurally invisible here.
+     *
+     * Set this and an append waits for the returned promise before it validates
+     * anything or takes an offset, so offsets are assigned at COMMIT the way the
+     * Durable Object assigns them. Return `undefined` to let a batch commit at
+     * once, which is what keeps the cost of the mode to the batches a test
+     * actually cares about.
+     *
+     * A test is expected to DECIDE which of two in-flight appends wins rather
+     * than to wait and see: a race whose loser cannot be pinned is a flake, not
+     * a test. Whatever the hook waits on must be bounded, because the fix for
+     * such a bug is usually to make the overtake impossible — and then a hook
+     * that waits for it forever hangs the suite that proves it.
+     */
+    holdAppend: ((events: readonly StreamEventInput[]) => Promise<void> | undefined) | undefined;
+    /** Set by MemoryStreamNetwork.get(); a detached stream answers `at()` with itself. */
+    network: MemoryStreamNetwork | undefined;
+    readonly path: string;
+    constructor(path?: string);
+    __describe(): Promise<{
+        instructions: string;
+        types: string;
+        children: {};
+    }>;
+    kill(): Promise<void>;
+    append(...inputs: StreamEventInput[]): Promise<StreamEvent[]>;
+    appendIfStreamId(args: {
+        streamId: string;
+        events: StreamEventInput[];
+    }): Promise<StreamEvent[]>;
+    at(path?: string): MemoryStream;
+    getEvent(input: {
+        offset: number;
+    } | {
+        idempotencyKey: string;
+    }): Promise<StreamEvent | undefined>;
+    getEvents(input?: StreamEventReadInput): Promise<StreamEvent[]>;
+    getEventPage(input?: StreamEventReadInput): Promise<{
+        streamId: `${string}-${string}-${string}-${string}-${string}`;
+        streamMaxOffset: number;
+        events: {
+            type: string;
+            offset: number;
+            createdAt: string;
+            path: string;
+            payload?: Record<string, unknown> | undefined;
+            metadata?: Record<string, unknown> | undefined;
+            source?: {
+                processor?: {
+                    slug: string;
+                    version: string;
+                    stream: {
+                        path: string;
+                        projectId: string | null;
+                        streamId: string;
+                    };
+                    whileProcessing?: {
+                        offset: number;
+                        type: string;
+                    } | undefined;
+                } | undefined;
+                copiedFrom?: {
+                    name: string;
+                    streamId: string;
+                    streamCreatedAt: string;
+                    cursorChangedAtSourceOffset: number;
+                    createdAt: string;
+                    offset: number;
+                    path: string;
+                    projectId: string | null;
+                    type: string;
+                }[] | undefined;
+            } | undefined;
+            idempotencyKey?: string | undefined;
+            ephemeral?: true | undefined;
+        }[];
+    }>;
+    readEvents(input?: StreamEventReadInput): {
+        next: () => Promise<{
+            type: string;
+            offset: number;
+            createdAt: string;
+            path: string;
+            payload?: Record<string, unknown> | undefined;
+            metadata?: Record<string, unknown> | undefined;
+            source?: {
+                processor?: {
+                    slug: string;
+                    version: string;
+                    stream: {
+                        path: string;
+                        projectId: string | null;
+                        streamId: string;
+                    };
+                    whileProcessing?: {
+                        offset: number;
+                        type: string;
+                    } | undefined;
+                } | undefined;
+                copiedFrom?: {
+                    name: string;
+                    streamId: string;
+                    streamCreatedAt: string;
+                    cursorChangedAtSourceOffset: number;
+                    createdAt: string;
+                    offset: number;
+                    path: string;
+                    projectId: string | null;
+                    type: string;
+                }[] | undefined;
+            } | undefined;
+            idempotencyKey?: string | undefined;
+            ephemeral?: true | undefined;
+        }[]>;
+        [Symbol.dispose](): void;
+    };
+    waitForEvent(input: {
+        afterOffset?: number;
+        eventTypes?: readonly string[];
+        predicate?: (event: StreamEvent) => boolean | Promise<boolean>;
+        timeoutMs: number;
+    }): Promise<StreamEvent>;
+    getProcessorRuntimeState(): Promise<null>;
+    runtimeState(): Promise<{
+        coreProcessorState: null;
+        runtime: {
+            connections: {};
+            sending: {};
+            metrics: {
+                measuredSince: string;
+                reportedAt: string;
+                ingress: {
+                    perSecond5s: number;
+                    bytesPerSecond5s: number;
+                    lastMinute: {
+                        count: number;
+                        bytes: number;
+                        perSecond: number;
+                    };
+                    series: {
+                        counts: any[];
+                        bytes: any[];
+                    };
+                };
+                egress: {
+                    perSecond5s: number;
+                    bytesPerSecond5s: number;
+                    lastMinute: {
+                        count: number;
+                        bytes: number;
+                        perSecond: number;
+                    };
+                    series: {
+                        counts: any[];
+                        bytes: any[];
+                    };
+                };
+            };
+            storageSizeBytes: number;
+        };
+    }>;
+}
+/**
+ * In-memory network of streams keyed by path, so router tests can observe
+ * the cross-stream forwards (`stream.at(path).append(...)`) next to
+ * same-stream appends. `now` feeds every member stream's createdAt stamp, so
+ * freshness checks (such as webhook acknowledgement horizons) can be tested on both sides
+ * of the horizon. `eventsAt` never creates a stream — `network.streams.size`
+ * assertions ("nothing was forwarded anywhere") stay honest.
+ */
+export declare class MemoryStreamNetwork {
+    readonly streams: Map<string, MemoryStream>;
+    readonly now: () => number;
+    constructor(now?: () => number);
+    get(path: string): MemoryStream;
+    eventsAt(path: string): StreamEvent[];
+}
+/**
+ * One scenario step. Three built-in kinds plus a function escape hatch:
+ *
+ * - `["append", ...events]` — typed appends (the contract's `consumes`
+ *   vocabulary: what the outside world can put on this processor's stream);
+ * - `["advanceTime", ms]` — move the virtual clock, releasing any harness
+ *   `sleep(...)` calls that come due;
+ * - `["crash"]` — abandon the incarnation like an eviction (runtime state and
+ *   pending closures die; stream, progress, and clock survive);
+ * - `async () => ...` — anything processor-specific (resolve a fake transport,
+ *   assert mid-scenario).
+ *
+ * After every step the harness drives delivery to a fixpoint, so each step
+ * observes the stream consequences of the previous one.
+ */
+export type HarnessStep<Contract extends StreamProcessorContract> = readonly ["append", ...ConsumedInput<Contract>[]] | readonly ["advanceTime", number] | readonly ["crash"] | (() => unknown);
+/** The durable substrate shared across incarnations (and zombie twins). */
+export type HarnessSubstrate = {
+    clock: {
+        now: number;
+    };
+    stream: MemoryStream;
+    progress: ProcessorProgressStore<unknown>;
+};
+/** What {@link makeProcessorHarness}'s factory receives: base deps plus the
+ * harness's virtual clock/sleep, for processors that take injectable time. */
+export type HarnessProcessorDeps<Contract extends StreamProcessorContract> = {
+    stream: ProcessorStream;
+    path: string;
+    projectId: string | null;
+    now: () => number;
+    sleep: (ms: number) => Promise<void>;
+    reads: Pick<RegisteredProcessorReads<ProcessorState<Contract>>, "snapshot" | "waitUntilEvent">;
+};
+export type ProcessorHarness<Contract extends StreamProcessorContract, Processor extends StreamProcessor<Contract, object> = StreamProcessor<Contract, object>> = {
+    clock: {
+        now: number;
+    };
+    stream: MemoryStream;
+    substrate: HarnessSubstrate;
+    /** The current incarnation's runner, for tests that need its full surface.
+     * A method (not a property) so suites can spread the harness into a wider
+     * object without freezing a pre-crash incarnation. */
+    runner(): StreamProcessorRunner<Contract>;
+    /** The current incarnation's processor instance. */
+    processor(): Processor;
+    /** Run steps in order, driving delivery to a fixpoint after each. */
+    play(...steps: HarnessStep<Contract>[]): Promise<void>;
+    /** Typed append (the contract's `consumes` vocabulary) + drive to fixpoint. */
+    append(...events: ConsumedInput<Contract>[]): Promise<void>;
+    /** Advance the virtual clock, release due sleeps, drive to fixpoint. */
+    advanceTime(ms: number): Promise<void>;
+    /** Abandon this incarnation like an eviction; a fresh one takes over the
+     * same stream/progress/clock. Does NOT deliver — the successor first acts
+     * on the next step, exactly like a real revival. */
+    crash(): void;
+    /** Drive delivery to a fixpoint: repeated catch-up passes (with microtask
+     * drains between them, so settled background work can land its appends)
+     * until the stream head stops moving. */
+    settle(): Promise<void>;
+    /** The runner's committed reduced state. */
+    state(): ProcessorState<Contract>;
+    /** All committed stream rows. */
+    events(): StreamEvent[];
+    /** Committed rows of one event type, typed when the contract resolves it. */
+    events<Type extends string>(type: Type): ResolvedEvent<Contract, Type>[];
+};
+/** In-memory {@link ProcessorProgressStore} with the DO store's fencing check,
+ * so progress survives `crash()` into the successor incarnation. Exported so
+ * suites can hand a harness a FRESH store over an existing stream — a full
+ * replay from offset zero, which is both the re-reduce-from-scratch recipe and the harshest
+ * at-least-once redelivery test (every per-event append re-runs).
+ *
+ * The contract is required because progress and recovery share the same
+ * per-processor Durable Object keys. A generic placeholder slug would let the
+ * runner commit progress under one key while recovery looks under another.
+ */
+export declare function makeMemoryProgressStore(contract: Pick<StreamProcessorContract, "slug">): ProcessorProgressStore<unknown>;
+/**
+ * Build a {@link ProcessorHarness}: the real runner, ProcessorKeepalive, and
+ * Durable Object durability adapters over an in-memory stream/KV/alarm
+ * substrate. `crash()` is eviction: delivery stays detached until a new
+ * append wakes it or a due keepalive alarm appends the revival fact. Pass
+ * another harness's `substrate` to run a second incarnation over the same
+ * durable state (the zombie-race setup).
+ *
+ * Appends commit synchronously unless a suite opts out through
+ * `harness.stream.holdAppend` — the one seam for reproducing a processor that
+ * appends the same lane from two places and orders only one of them.
+ */
+export declare function makeProcessorHarness<Contract extends StreamProcessorContract, Processor extends StreamProcessor<Contract, object> = StreamProcessor<Contract, object>>(args: {
+    createProcessor: (deps: HarnessProcessorDeps<Contract>) => Processor;
+    path?: string;
+    substrate?: HarnessSubstrate;
+}): ProcessorHarness<Contract, Processor>;

package/dist/processors-BoNyeBfQ.mjs

@@ -0,0 +1,10 @@
+import "./usingCtx-mZx5nsAW.mjs";
+//#region src/processors/idempotency.ts
+const IDEMPOTENCY_CONFLICT_FRAGMENT = " already names a different event at offset ";
+function isIdempotencyConflict(error) {
+	return (error instanceof Error ? error.message : String(error)).includes(IDEMPOTENCY_CONFLICT_FRAGMENT);
+}
+//#endregion
+export { isIdempotencyConflict as t };
+
+//# sourceMappingURL=processors-BoNyeBfQ.mjs.map

package/dist/processors-BoNyeBfQ.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"processors-BoNyeBfQ.mjs","names":[],"sources":["../src/processors/idempotency.ts"],"sourcesContent":["// The Stream DO's idempotency semantics, importable: a same-key append is a\n// dedup ONLY when its body is structurally identical — otherwise it must be\n// rejected. Lives here so the production Stream Durable Object and the\n// MemoryStream test double share ONE predicate and cannot drift.\n\ntype EventBody = {\n  type: string;\n  payload?: unknown;\n  metadata?: unknown;\n  ephemeral?: boolean | undefined;\n};\n\n// The wording is a live wire contract: the rejection crosses Workers RPC,\n// which preserves the message but not class identity, so deployed processors\n// classify the conflict by this text. Mint with the builder, match with the\n// predicate — never spell the wording anywhere else.\nconst IDEMPOTENCY_CONFLICT_FRAGMENT = \" already names a different event at offset \";\n\nexport function idempotencyConflictMessage(idempotencyKey: string, existingOffset: number) {\n  return `idempotency key \"${idempotencyKey}\"${IDEMPOTENCY_CONFLICT_FRAGMENT}${existingOffset}`;\n}\n\nexport function isIdempotencyConflict(error: unknown) {\n  const message = error instanceof Error ? error.message : String(error);\n  return message.includes(IDEMPOTENCY_CONFLICT_FRAGMENT);\n}\n\n/** Whether a requested append names the SAME event an idempotency key already committed. */\nexport function sameIdempotentEvent(existing: EventBody, requested: EventBody): boolean {\n  return (\n    existing.type === requested.type &&\n    jsonValuesEqual(existing.payload, requested.payload) &&\n    jsonValuesEqual(existing.metadata, requested.metadata) &&\n    existing.ephemeral === requested.ephemeral\n  );\n}\n\n/** Structural JSON equality (key-order-insensitive). */\nexport function jsonValuesEqual(left: unknown, right: unknown): boolean {\n  if (Object.is(left, right)) return true;\n  if (Array.isArray(left) || Array.isArray(right)) {\n    return (\n      Array.isArray(left) &&\n      Array.isArray(right) &&\n      left.length === right.length &&\n      left.every((value, index) => jsonValuesEqual(value, right[index]))\n    );\n  }\n  if (typeof left === \"object\" && typeof right === \"object\" && left !== null && right !== null) {\n    const leftKeys = Object.keys(left).sort();\n    const rightKeys = Object.keys(right).sort();\n    if (leftKeys.length !== rightKeys.length) return false;\n    return leftKeys.every(\n      (key, index) =>\n        key === rightKeys[index] &&\n        jsonValuesEqual(\n          (left as Record<string, unknown>)[key],\n          (right as Record<string, unknown>)[key],\n        ),\n    );\n  }\n  return false;\n}\n"],"mappings":";;AAgBA,MAAM,gCAAgC;AAMtC,SAAgB,sBAAsB,OAAgB;CAEpD,QADgB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK,EAAA,CACtD,SAAS,6BAA6B;AACvD"}

package/dist/processors-cloudflare.mjs

@@ -0,0 +1,3 @@
+import { a as createStreamProcessorRegistry, i as plainAlarmInvocationInfo, n as ProcessorFacet, r as facetProcessorDurableObjectState, t as FACET_IDENTITY_KEY } from "./cloudflare-BTm90gQ4.mjs";
+import { i as processorProgressKey, n as durableObjectRecovery, r as processorKeepaliveKey, t as durableObjectProgressStore } from "./durable-object-processor-durability-CNsTjAJS.mjs";
+export { FACET_IDENTITY_KEY, ProcessorFacet, createStreamProcessorRegistry, durableObjectProgressStore, durableObjectRecovery, facetProcessorDurableObjectState, plainAlarmInvocationInfo, processorKeepaliveKey, processorProgressKey };