@opinionated-machine/sse-fallback 0.1.1

package/dist/scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.js","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"AASA,uCAAuC;AACvC,MAAM,OAAO,eAAe;IAClB,MAAM,CAAyB;IACtB,MAAM,CAAY;IAEnC,YAAY,MAAkB;QAC5B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;IAED,kEAAkE;IAClE,GAAG,CAAC,OAAe;QACjB,IAAI,CAAC,KAAK,EAAE,CAAA;QACZ,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAE7C;QAAC,IAAI,CAAC,MAAiC,CAAC,KAAK,EAAE,EAAE,CAAA;IACpD,CAAC;IAED,KAAK;QACH,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;YAC9B,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,CAAA;YACzB,IAAI,CAAC,MAAM,GAAG,SAAS,CAAA;QACzB,CAAC;IACH,CAAC;IAED,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,MAAM,KAAK,SAAS,CAAA;IAClC,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,UAAU,YAAY,CAAC,MAAqB,EAAE,OAAe,EAAE,MAAoB;IACvF,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,IAAI,OAAO,CAAC,CAAA;IAChF,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,CAAA;AACpD,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,KAAK,CAAC,OAAe,EAAE,MAAmB;IACxD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,OAAO,CAAC,KAAK,CAAC,CAAA;YACd,OAAM;QACR,CAAC;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;YAC5C,OAAO,CAAC,IAAI,CAAC,CAAA;QACf,CAAC,EAAE,OAAO,CAAC,CACV;QAAC,KAAgC,CAAC,KAAK,EAAE,EAAE,CAAA;QAC5C,MAAM,OAAO,GAAG,GAAG,EAAE;YACnB,YAAY,CAAC,KAAK,CAAC,CAAA;YACnB,OAAO,CAAC,KAAK,CAAC,CAAA;QAChB,CAAC,CAAA;QACD,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;IAC3D,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/dist/subscription.d.ts

@@ -0,0 +1,164 @@
+import type { FallbackBinding, FallbackRequestParams } from './binding.ts';
+import type { EventPayloadMap, FallbackEvent, FallbackPolicy } from './bindingTypes.ts';
+import type { PollGate } from './pollGate.ts';
+import type { InvalidVersionInfo, VersionGap } from './reconciler.ts';
+import type { FallbackTransport } from './transport.ts';
+export type SubscriptionStatus = 'connecting' | 'live' | 'reconnecting' | 'polling' | 'stopped';
+/**
+ * Why a subscription reached `'stopped'`.
+ *
+ * `'stopped'` alone cannot be acted on: a completed job, an auth failure and a
+ * caller's own `stop()` all land there. The reason is what lets a UI tell
+ * success from give-up, and give-up from "the user navigated away".
+ *
+ * - `'terminal-event'` — a terminal event was delivered. Success.
+ * - `'unretryable-status'` — the stream or a poll was refused with a status in
+ *   `unretryableStatuses` (and `onAuthChallenge`, if any, did not recover).
+ *   `status` carries which one.
+ * - `'budget-exhausted'` — `subscriptionBudget` ran out. `limit` says which
+ *   half. Show an actionable error and offer a manual retry.
+ * - `'manual'` — the caller called `stop()`, or the `signal` passed at
+ *   creation aborted.
+ */
+export type StopReason = 'terminal-event' | 'unretryable-status' | 'budget-exhausted' | 'manual';
+/** The reason a subscription stopped, plus whatever detail that reason carries. */
+export type SubscriptionStopDetail = {
+    reason: StopReason;
+    /** The refusing HTTP status, for `'unretryable-status'`. */
+    status?: number;
+    /** Which half of the budget ran out, for `'budget-exhausted'`. */
+    limit?: 'maxDurationMs' | 'maxPolls';
+    /** Which channel hit the refusal, for `'unretryable-status'`. */
+    channel?: 'poll' | 'stream';
+};
+/**
+ * Rejection thrown by `waitFor` / `waitForTerminal` when the subscription
+ * stops before the awaited event arrives. Carries the stop reason so the
+ * caller can branch without inspecting the message.
+ */
+export declare class SubscriptionStoppedError extends Error {
+    readonly reason: StopReason;
+    readonly status: number | undefined;
+    readonly limit: 'maxDurationMs' | 'maxPolls' | undefined;
+    readonly channel: 'poll' | 'stream' | undefined;
+    constructor(detail: SubscriptionStopDetail);
+}
+/**
+ * Observability hooks — all optional, all no-ops by default. None of these
+ * affect delivery semantics; they exist so applications can meter the
+ * fallback machinery (gap rate, duplicate rate, poll errors).
+ */
+export type FallbackDiagnostics = {
+    onGap?: (gap: VersionGap) => void;
+    onDuplicate?: (event: string) => void;
+    onStaleSnapshot?: () => void;
+    onPollError?: (error: unknown) => void;
+    onStreamError?: (error: unknown) => void;
+    /**
+     * A gap suspended the state layer: `getState()` is frozen at its pre-gap
+     * value until a snapshot repairs it, even though events keep flowing.
+     */
+    onStateSuspended?: (gap: VersionGap) => void;
+    /** A snapshot lifted the suspension and re-initialized state. */
+    onStateRepaired?: () => void;
+    /** A listener passed to `onEvent` / `onStateChange` / `onStatusChange` threw. */
+    onListenerError?: (error: unknown) => void;
+    /**
+     * A version extractor returned something the gate cannot order, so the item
+     * was delivered without advancing the watermark. Delivery keeps working
+     * (at-least-once, no deduplication between the channels), but the binding
+     * is misconfigured or the payload is missing its version field — this hook
+     * is the only signal that says so.
+     */
+    onInvalidVersion?: (info: InvalidVersionInfo) => void;
+};
+export type CreateResilientSubscriptionOptions = {
+    transport: FallbackTransport;
+    params?: FallbackRequestParams;
+    policy?: Partial<FallbackPolicy>;
+    diagnostics?: FallbackDiagnostics;
+    signal?: AbortSignal;
+    /**
+     * Shared cap and stagger for reconciliation polls across subscriptions —
+     * see `createPollGate`. Without one, a fleet-wide reconnect fires every
+     * subscription's reconciliation poll on the same tick.
+     */
+    pollGate?: PollGate;
+    /**
+     * Called when a poll or stream connect is refused with a status in
+     * `policy.authChallengeStatuses` (default `[401]`). Refresh credentials
+     * here — the transport builds every request fresh, so a token stored on the
+     * transport is picked up by the retry.
+     *
+     * Resolve `true` to run the refused request once more; resolve `false`, or
+     * throw, to stop the subscription with `'unretryable-status'`. The retry is
+     * granted once per auth failure streak: a second refusal with no successful
+     * request in between stops the subscription.
+     */
+    onAuthChallenge?: (challenge: {
+        status: number;
+        channel: 'poll' | 'stream';
+    }) => boolean | Promise<boolean>;
+    /**
+     * Decode an SSE `data:` payload into the value handed to the reconciler.
+     * Defaults to `JSON.parse`, matching the framework's default serializer.
+     * Routes that configure a custom `serializer` (or send raw strings) declare
+     * the matching decoder here — otherwise their frames cannot be read, and a
+     * frame that cannot be read is a lost event, repaired by a poll.
+     */
+    parseEventData?: (raw: string) => unknown;
+    /** Injectable randomness for deterministic backoff in tests. */
+    random?: () => number;
+};
+export type ResilientSubscription<Events extends EventPayloadMap = EventPayloadMap, State = undefined> = {
+    /** Uniform event stream — SSE-pushed, replayed, and poll-synthesized alike. */
+    events(): AsyncIterable<FallbackEvent<Events>>;
+    /** Callback-style event consumption; returns an unsubscribe function. */
+    onEvent(listener: (event: FallbackEvent<Events>) => void): () => void;
+    /** Latest reduced state — only meaningful when the binding declares `state`. */
+    getState(): State | undefined;
+    onStateChange(listener: (state: State) => void): () => void;
+    readonly status: SubscriptionStatus;
+    /**
+     * Observe status transitions. `detail` is present exactly when `status` is
+     * `'stopped'`, and says why — see {@link StopReason}.
+     */
+    onStatusChange(listener: (status: SubscriptionStatus, detail?: SubscriptionStopDetail) => void): () => void;
+    /**
+     * Why the subscription stopped, or `undefined` while it is still running.
+     * Also delivered to `onStop` and `onStatusChange` at the moment it stops.
+     */
+    readonly result: SubscriptionStopDetail | undefined;
+    /**
+     * Run a listener when the subscription stops. Registering after it has
+     * already stopped calls the listener immediately, so there is no race
+     * between subscribing and a terminal event that arrived first.
+     */
+    onStop(listener: (detail: SubscriptionStopDetail) => void): () => void;
+    /** Force an immediate reconciliation poll + connection check. */
+    nudge(): void;
+    /** Stop the subscription: cancel timers, abort in-flight requests. */
+    stop(): void;
+    /**
+     * Await the first delivery of a specific event (use case: await async
+     * completion). Resolves identically whether the event traveled over SSE,
+     * replay, or a fallback poll.
+     *
+     * Rejects with {@link SubscriptionStoppedError} if the subscription stops
+     * first, so the caller can tell an auth failure from an exhausted budget.
+     */
+    waitFor<K extends keyof Events & string>(event: K, opts?: {
+        timeoutMs?: number;
+    }): Promise<Events[K]>;
+    /** Await the first terminal event (any of the binding's terminalEvents). */
+    waitForTerminal(opts?: {
+        timeoutMs?: number;
+    }): Promise<FallbackEvent<Events>>;
+};
+/**
+ * Create a resilient subscription: SSE as the low-latency channel, short
+ * polls as the correctness backbone. See the package README for the state
+ * machine and reconciliation semantics.
+ */
+export declare function createResilientSubscription<Snapshot, Events extends EventPayloadMap, State = undefined>(binding: FallbackBinding<Snapshot, Events, State>, options: CreateResilientSubscriptionOptions): ResilientSubscription<Events, State>;
+//# sourceMappingURL=subscription.d.ts.map

package/dist/subscription.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription.d.ts","sourceRoot":"","sources":["../src/subscription.ts"],"names":[],"mappings":"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"}