@opinionated-machine/sse-fallback 0.1.1

package/dist/reconciler.d.ts

@@ -0,0 +1,245 @@
+import type { EventPayloadMap, FallbackBindingConfig, FallbackEvent, Version } from './bindingTypes.ts';
+/**
+ * The reconciler is the pure correctness core of the fallback pattern: a
+ * version-gated event pipeline with a high-watermark, hydration buffering,
+ * and gap detection. It owns NO timers and NO transport — the subscription
+ * wires those around it — which keeps every race testable synchronously.
+ *
+ * The single delivery rule: an item (event or snapshot) with version `v` is
+ * delivered iff `v` is greater than the high-watermark; delivery advances
+ * the watermark. That one rule simultaneously handles duplicate delivery
+ * (SSE event + poll snapshot of the same update), the stale-poll race (a
+ * slow poll response arriving AFTER a newer pushed event is dropped at
+ * arrival time), and replay overlap after reconnection.
+ */
+/**
+ * A break in the version sequence that only a snapshot can repair.
+ *
+ * `'sequence'` means the dense counter skipped ahead inside one epoch, so a
+ * known number of events was lost. `'epoch-change'` means the id epoch itself
+ * changed (a writer restarted, or the ordering scope was reset): counters on
+ * either side are not comparable, so the number of missed events is unknowable
+ * and delta state has to be rebuilt from a snapshot rather than carried across.
+ */
+export type VersionGap = {
+    from: Version;
+    to: Version;
+    reason: 'sequence' | 'epoch-change';
+};
+/**
+ * A version extractor returned a value that cannot be ordered — `undefined`
+ * from `version.ofSnapshot` (a snapshot body missing its version field is the
+ * usual cause), `NaN`, `Infinity`, an empty string, or a non-scalar.
+ *
+ * The item is still delivered, just without advancing the watermark, so the
+ * subscription degrades to at-least-once rather than wedging. This exists so
+ * that degradation is visible instead of silent.
+ */
+export type InvalidVersionInfo = {
+    source: 'snapshot' | 'event';
+    value: unknown;
+};
+export type IncomingEvent = {
+    event: string;
+    data: unknown;
+    id?: string;
+};
+export type EventOutcome<Events extends EventPayloadMap> = {
+    deliveries: Array<FallbackEvent<Events>>;
+    /** Event was at/below the watermark and dropped. */
+    duplicate: boolean;
+    /** Event was buffered (hydration in progress). */
+    buffered: boolean;
+    /** Hydration buffer overflowed — caller must refetch the snapshot. */
+    bufferOverflow: boolean;
+    /** A gap or an epoch change was detected — caller should poll now. */
+    gap?: VersionGap;
+    /** A terminal event was delivered — the subscription is complete. */
+    terminated: boolean;
+    /** New state value when the state layer applied the event. */
+    state?: {
+        value: unknown;
+    };
+    /**
+     * Whether the state layer is gap-suspended after this event. While
+     * suspended `apply` is skipped, so `getState()` keeps returning the
+     * pre-gap value even though events are still delivered — the caller must
+     * poll for a repair snapshot and can surface the staleness meanwhile.
+     */
+    stateSuspended: boolean;
+};
+export type SnapshotOutcome<Events extends EventPayloadMap> = {
+    deliveries: Array<FallbackEvent<Events>>;
+    /** Snapshot was at/below the watermark and dropped entirely. */
+    stale: boolean;
+    /** The watermark (or versionless equivalent) advanced — the poll carried news. */
+    advanced: boolean;
+    /** Hydration completed with this snapshot (buffered events were flushed). */
+    hydrationCompleted: boolean;
+    /**
+     * A gap was detected while flushing the hydration buffer — caller should
+     * poll now. Buffered events pass through the same version gate as live
+     * ones, so the hole they expose needs the same repair poll; without this
+     * the gap would be found and then silently dropped with the flush outcome.
+     */
+    gap?: VersionGap;
+    terminated: boolean;
+    state?: {
+        value: unknown;
+    };
+    /** Whether the state layer is still gap-suspended after this snapshot. */
+    stateSuspended: boolean;
+    /** This snapshot lifted a gap suspension and re-initialized state. */
+    stateRepaired: boolean;
+};
+export declare class Reconciler<Snapshot, Events extends EventPayloadMap, State> {
+    private readonly config;
+    private readonly snapshotToEvents;
+    private readonly terminalSet;
+    private highWatermark;
+    private hydrationBuffer;
+    private readonly hydrationBufferLimit;
+    private stateValue;
+    private stateInitialized;
+    private stateSuspended;
+    /**
+     * Events delivered while the state layer is gap-suspended, in arrival
+     * order, so the repair snapshot can re-apply the ones it does not cover.
+     */
+    private stateReplayBuffer;
+    /**
+     * The replay buffer overflowed and was dropped. A below-watermark snapshot
+     * can no longer repair state without losing the events it does not cover,
+     * so the suspension holds until a snapshot reaches the watermark.
+     */
+    private stateReplayTruncated;
+    private terminated;
+    private readonly onInvalidVersion;
+    constructor(config: FallbackBindingConfig<Snapshot, Events, State>, options: {
+        hydrationBufferLimit: number;
+        /**
+         * Reported when a version extractor hands back something that cannot be
+         * ordered. Purely observational — the reconciler degrades on its own.
+         */
+        onInvalidVersion?: (info: InvalidVersionInfo) => void;
+    });
+    get isTerminated(): boolean;
+    get isHydrating(): boolean;
+    /**
+     * Whether the state layer is suspended after a detected gap. `apply` stays
+     * disabled until a snapshot repairs state, so `getState()` is known-stale
+     * while this is true.
+     */
+    get isStateSuspended(): boolean;
+    getState(): State | undefined;
+    /** Start buffering live events until the next snapshot arrives. */
+    beginHydration(): void;
+    /**
+     * Give up on subscribe-first hydration and resume direct delivery.
+     *
+     * The buffered events are FLUSHED, not discarded: hydration never completed,
+     * so no snapshot subsumes them and dropping them would lose exactly the
+     * events the buffer existed to protect. They pass through the version gate
+     * in arrival order, so a later snapshot still wins on version.
+     */
+    abandonHydration(): SnapshotOutcome<Events>;
+    handleEvent(incoming: IncomingEvent): EventOutcome<Events>;
+    handleSnapshot(snapshot: Snapshot): SnapshotOutcome<Events>;
+    /**
+     * The stale-poll race: everything this snapshot describes has already been
+     * delivered (or superseded) through the stream.
+     *
+     * One exception: a gap-suspended state layer is repaired by ANY snapshot,
+     * not only one whose version matches the watermark exactly. Live events keep
+     * advancing the watermark after a gap, so the repair snapshot this branch
+     * was polled for usually arrives strictly below it; requiring equality left
+     * `apply` disabled forever and froze `getState()` at its pre-gap value while
+     * events kept flowing. The events the snapshot does not cover are replayed
+     * onto it, so nothing delivered during the suspension is dropped from state.
+     * The watermark is NOT rewound, so nothing is re-delivered.
+     *
+     * With a dropped replay buffer that is impossible, so the suspension holds
+     * until a snapshot reaches the watermark, which covers everything delivered
+     * during it and needs no replay.
+     */
+    private handleStaleSnapshot;
+    /**
+     * Re-initialize a gap-suspended state layer from a snapshot below the
+     * watermark, then re-apply the buffered events the snapshot does not cover.
+     *
+     * The repair snapshot is usually older than the watermark, because live
+     * events keep arriving while the repair poll is in flight. Without the
+     * replay those events would be missing from state permanently: delivered to
+     * listeners, skipped by `apply` while suspended, then overwritten by an
+     * `init` that predates them. The next event would apply to a state that
+     * never saw them.
+     *
+     * The cut is by arrival order, anchored on the last buffered event the
+     * snapshot demonstrably covers. Events after it are replayed even when they
+     * carry no orderable version, because arrival order is the only ordering
+     * they have.
+     */
+    private repairState;
+    /**
+     * Keep a delivered event for the repair snapshot to replay. Overflow drops
+     * the whole buffer rather than half of it: replaying a partial buffer would
+     * apply deltas across a hole, which is exactly what the suspension exists
+     * to prevent.
+     */
+    private recordSuspendedEvent;
+    private finishHydration;
+    /**
+     * Record a detected gap on the outcome and suspend the state layer, so the
+     * caller polls for a repair snapshot instead of applying deltas across a
+     * hole.
+     */
+    private registerGap;
+    private gateAndDeliver;
+    private extractEventVersion;
+    /**
+     * A version the gate can actually order, or `undefined`.
+     *
+     * Nothing in the type system stops an extractor from handing back
+     * `undefined` (a snapshot body whose version field is absent), `NaN`, an
+     * empty string or an object, and storing one as the watermark is the worst
+     * outcome the gate has: `defaultCompareVersions` falls through to a
+     * lexicographic comparison against `'undefined'`/`'NaN'`, every later item
+     * ranks at or below it, and the subscription drops everything as a
+     * duplicate — silently, forever. Dropping the version instead costs
+     * deduplication (at-least-once delivery) and keeps the stream flowing.
+     */
+    private normalizeVersion;
+    /**
+     * Whether the epoch bypass below applies. A binding that declares
+     * `version.compare` owns ordering end to end, including across epochs, so
+     * its verdict is never overridden here — the bypass exists to correct the
+     * DEFAULT comparator, which ranks by epoch and therefore reads a lowered
+     * epoch as an older version.
+     */
+    private get ordersEpochs();
+    /**
+     * Whether two versions belong to different ordering scopes under the
+     * default comparator — see {@link ordersEpochs}.
+     */
+    private isEpochChange;
+    private compare;
+    private detectGap;
+}
+/**
+ * The version a bare SSE `id:` carries under the default extractor: a bare
+ * integer becomes a number, a `createEventIdSequence()` id stays a string
+ * (ordered by {@link defaultCompareVersions}), anything else carries no
+ * version at all.
+ */
+export declare function parseDefaultVersion(id: string): Version | undefined;
+/**
+ * Numeric when both sides are numeric, epoch-then-counter when both are
+ * `createEventIdSequence()` ids, lexicographic otherwise.
+ *
+ * Comparing sequence ids by their parsed parts rather than lexicographically
+ * keeps ordering correct when the counter outgrows its zero padding, and
+ * makes a new epoch (a process restart) sort above the old one, so the
+ * restarted counter does not read as a flood of duplicates.
+ */
+export declare function defaultCompareVersions(a: Version, b: Version): number;
+//# sourceMappingURL=reconciler.d.ts.map

package/dist/reconciler.d.ts.map

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