iterate 0.3.0 → 0.4.0

package/dist/processors/testing.d.ts

@@ -1,302 +0,0 @@
-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

@@ -1,10 +0,0 @@
-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

@@ -1 +0,0 @@
-{"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

@@ -1,3 +0,0 @@
-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 };