@abloatai/transaction 0.37.0

package/dist/types/streams.d.ts

@@ -0,0 +1,545 @@
+/**
+ * The types for real-time multiplayer coordination.
+ *
+ * Ablo treats people and AI agents alike as participants working on live
+ * application entities. A participant announces what it is reading or editing,
+ * claims an entity before writing to it, and captures a context snapshot before
+ * starting long-running AI work. You keep your own schema, agent stack, tools,
+ * prompts, and product rules; this package provides the shared coordination
+ * layer underneath.
+ */
+import type { InferModel, Schema } from '../schema/schema.js';
+import type { ResolveClaimMeta } from './global.js';
+import type { OnStaleMode, WireClaim, ClaimRejection, ClaimLost, PresenceKind, ParticipantKind, PublicClaimStatus, PresenceUpdatePayload } from '../coordination/schema.js';
+export type { OnStaleMode, WireClaim, ClaimRejection, ClaimLost, PresenceKind, ParticipantKind, PresenceUpdatePayload, };
+/**
+ * Any JSON-serializable value. Used where the SDK accepts free-form metadata
+ * that is stored or transported as JSON — more precise than `unknown` while
+ * still allowing any JSON shape.
+ */
+export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export type { ParticipantRef } from './participant.js';
+import type { Delta } from '../wire/delta.js';
+export type { ConfirmationState, Delta } from '../wire/delta.js';
+/**
+ * @deprecated Renamed to {@link Delta} — the authoritative change feed serves
+ * every participant, not only agents, and the seam names it plainly.
+ * Removed in 0.36.0.
+ */
+export type AgentDelta = Delta;
+/**
+ * A flat, point-in-time view of application data returned by
+ * `participant.snapshot(...)`. Capture it before long-running AI work, then
+ * detect whether the data changed underneath while that work ran.
+ *
+ *   - Per-model buckets: `snap.<modelName>[id]` returns the entity, typed from
+ *     your schema (via `InferModel`) rather than as `unknown` — so, for
+ *     example, `snap.clauses[clauseId].text` is a `string`.
+ *   - `stamp` — an opaque version marker. Thread it into writes as
+ *     `{ readAt: snap.stamp }` so the server can reject a write made against
+ *     stale data.
+ *   - `signal` — an `AbortSignal` that fires if any captured entity receives a
+ *     change during the window. Pass it into your LLM call so a mid-generation
+ *     change aborts the token stream instead of completing against a snapshot
+ *     that is no longer current.
+ *   - `onChange(fn)` — a callback alternative to `signal` for cases that don't
+ *     abort, such as logging, UI flags, or partial regeneration. Returns an
+ *     unsubscribe function.
+ *
+ * The per-model buckets share the object with `stamp`, `signal`, and
+ * `onChange`, so naming a model `stamp`, `signal`, or `onChange` collides.
+ * Snapshot creation throws a clear error in that case.
+ */
+export type Snapshot<TSchema extends Schema = Schema, ModelName extends keyof TSchema['models'] = keyof TSchema['models']> = {
+    readonly stamp: number;
+    readonly signal: AbortSignal;
+    onChange(listener: (change: ContextChange) => void): () => void;
+} & {
+    readonly [M in ModelName]: Readonly<Record<string, InferModel<TSchema, M>>>;
+};
+export interface ContextChange {
+    readonly model: string;
+    readonly id: string;
+    readonly severity: 'semantic' | 'metadata';
+}
+/**
+ * The staleness mode for a write that follows a snapshot. When `readAt` is
+ * provided without an `onStale` mode, it defaults to `'reject'`.
+ */
+/**
+ * A pointer to one entity, optionally narrowed to a part of it. `type` and `id`
+ * come from your schema; `path`, `range`, `field`, and `meta` are
+ * general-purpose hints for finer-grained coordination in tools like code
+ * editors, document editors, and design tools.
+ */
+export interface ClaimTarget<M = ResolveClaimMeta> {
+    readonly type: string;
+    readonly id: string;
+    readonly field?: string;
+    /**
+     * Several named parts of the row at once — three sections of a document, two
+     * cells of a table. Claims conflict where their sets intersect, so two
+     * holders working on disjoint parts of one row do not wait for each other.
+     *
+     * Use this instead of packing names into `field`: a delimited string compares
+     * as one opaque value, so `'b_1,b_2'` and `'b_2,b_3'` read as unrelated
+     * targets and both holders are granted `b_2`.
+     */
+    readonly fields?: readonly string[];
+    /**
+     * Application metadata, carried verbatim and never interpreted.
+     *
+     * The protocol does not know what is in here — the caller does, so the
+     * caller says so once, where the schema is already registered:
+     *
+     * ```ts
+     * declare module '@abloatai/ablo' {
+     *   interface Register { ClaimMeta: { blocks: string[] } }
+     * }
+     * ```
+     *
+     * From then on every claim surface reads this field as that shape and no
+     * read of it needs a `typeof` guard. The `M` parameter remains for a program
+     * carrying more than one meta shape — `claim.state<OtherMeta>({ id })`
+     * overrides the registration for that one call.
+     */
+    readonly meta?: M;
+}
+/**
+ * A pointer to the entity a participant is acting on. Either a
+ * {@link ClaimTarget} object or a `[type, id]` tuple such as `['Clause', 'cl_3']`
+ * for concise inline use. The verb methods below accept either form.
+ */
+export type PresenceTarget = ClaimTarget | readonly [type: string, id: string];
+/**
+ * A reactive, always-on stream of what every participant is doing. Each
+ * participant has one, and it stays current for as long as the connection is
+ * open.
+ */
+export interface PresenceStream {
+    /**
+     * This participant's own broadcast state — the same thing every other
+     * participant sees for it. Read-only here; change it through `update(...)`.
+     */
+    readonly self: Peer;
+    /**
+     * Broadcast a new activity. Synchronous — the frame ships on the already-open
+     * connection, with no request-response round-trip to await. Call it as often
+     * as the activity meaningfully changes: on read, on generation start, on
+     * partial output, on write, on done.
+     *
+     * For the common actions, prefer the verb methods below (`editing`,
+     * `viewing`, and so on): they read as one line and save you from remembering
+     * the action strings.
+     */
+    update(activity: Activity): void;
+    /** Participant is actively modifying this entity. */
+    editing(target: PresenceTarget, detail?: string): void;
+    /** Participant is reading this entity; no modifications. */
+    reading(target: PresenceTarget, detail?: string): void;
+    /** Participant is reading this entity; no modifications. */
+    viewing(target: PresenceTarget, detail?: string): void;
+    /** Participant has stepped away from any specific entity. */
+    idle(): void;
+    /**
+     * A reactive view of every other participant's current activity on this
+     * participant's sync groups. Reading it returns the current snapshot; pair it
+     * with `onChange(listener)` below to be notified when it changes.
+     *
+     * You can drop `presence.others` into an LLM's system prompt so the model
+     * reasons about what other agents are doing right now — for example,
+     * "copy-bot is generating a new title for section 5; don't duplicate that work."
+     */
+    readonly others: readonly Peer[];
+    /** Subset of `others` filtered to a specific sync group. */
+    othersIn(syncGroup: string): readonly Peer[];
+    /**
+     * A framework-agnostic reactivity hook. Register a callback that fires
+     * whenever `others` or `othersIn(...)` changes — a peer joined, left, or
+     * updated its activity. Returns a function that unsubscribes.
+     *
+     * React binding:
+     * ```ts
+     * const others = useSyncExternalStore(
+     *   presence.subscribe,
+     *   () => presence.others,
+     * );
+     * ```
+     *
+     * MobX binding:
+     * ```ts
+     * autorun(() => {
+     *   // Triggered on every presence change because the observable
+     *   // version counter inside presence is read here.
+     *   const peers = presence.others;
+     *   // ...
+     * });
+     * ```
+     */
+    onChange(listener: () => void): () => void;
+    /**
+     * An async-iterable view of the peer roster. Each iteration yields the
+     * current `others` snapshot whenever it changes, so you can watch the world
+     * update without registering a callback.
+     *
+     * ```ts
+     * for await (const peers of participant.presence) {
+     *   renderAvatars(peers);
+     *   if (peers.length === 0) break; // iteration stops, subscription drops
+     * }
+     * ```
+     *
+     * Each `for await` gets an independent iterator — two loops on the same
+     * stream both see every update rather than stealing values from each other.
+     * Breaking out of the loop, or throwing, tears the subscription down cleanly.
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<readonly Peer[]>;
+}
+/**
+ * What a participant is currently doing. This type is both the SDK shape and
+ * the wire shape: a presence broadcast on the `presence_update` frame carries
+ * exactly these fields.
+ *
+ * Every activity is about one entity in focus. An agent working across several
+ * entities calls `presence.update(...)` each time its focus shifts, and other
+ * participants see the change in real time.
+ */
+export interface Activity {
+    /** Entity type the participant is focused on (e.g. "Section", "Document"). */
+    readonly entityType: string;
+    /** Specific entity id. */
+    readonly entityId: string;
+    /** Optional field/property for field-level coordination. */
+    readonly field?: string;
+    /**
+     * Several named parts of the row at once — the same member
+     * {@link ClaimTarget} carries, and the one the presence frame has always
+     * declared. It was missing here, so a set-scoped participant announced
+     * itself as holding the whole row and the overlap filter compared it as if
+     * it named no parts at all.
+     */
+    readonly fields?: readonly string[];
+    /** App-defined structured metadata. Display-only unless app policy uses it. */
+    readonly meta?: Record<string, unknown>;
+    /**
+     * What the participant is doing to that entity. Canonical values:
+     * `'editing'` / `'reviewing'` / `'generating'` / `'analyzing'` /
+     * `'executing'`. Free-form strings are accepted for app-specific
+     * phases.
+     */
+    readonly action: string;
+    /** Human-readable detail — "section 3", "cell A1:B5", etc. */
+    readonly detail?: string;
+    /**
+     * A backpressure signal in the range `[0.0, 1.0]`. When set, orchestrator
+     * agents reading peer activity can route work away from busy participants:
+     * `0.0` means idle, `1.0` means at capacity, and values in between mean "I
+     * have headroom but would rather not." Optional — agents that don't take part
+     * in load-aware routing leave it unset, and orchestrators ignore them when
+     * balancing load. The server passes it through without interpreting it.
+     */
+    readonly loadFactor?: number;
+    /**
+     * A backpressure gate for new work assignments. It defaults to `true` when
+     * unset, so everyone accepts work by default. Set it to `false` during
+     * graceful shutdown, at capacity, or while committed to a long step that
+     * can't be interrupted. Orchestrators should skip a peer showing `false`, and
+     * treat `true` with a high `loadFactor` as available but lower priority.
+     */
+    readonly acceptingNewWork?: boolean;
+}
+/**
+ * One participant's live state as seen by everyone else in scope — its
+ * identity, sync groups, current {@link Activity}, and any open claims.
+ */
+export interface Peer {
+    readonly participantKind: ParticipantKind;
+    readonly participantId: string;
+    readonly label?: string;
+    readonly syncGroups: readonly string[];
+    readonly activity: Activity;
+    /** Server timestamp of the most recent frame from this participant. */
+    readonly lastActive: string;
+    /** The claims this participant currently holds. */
+    readonly activeClaims?: readonly Claim[];
+}
+/**
+ * A claim is a broadcast that says "I'm about to work on this entity." Claims
+ * travel on the same connection as presence, so every participant sees them in
+ * real time. They are cooperative rather than enforced: a claim announces
+ * intent, and other agents observe it and yield. This is lighter and more
+ * flexible than a central lock table and composes with presence.
+ */
+/**
+ * The options shared by every verb-style claim announcement
+ * (`claims.analyzing`, `claims.drafting`, and so on). The only required piece
+ * is the target; everything else has a sensible default. Prefer the verb
+ * methods on {@link ClaimStream} — for example `analyzing(entity, { ttl: '3m' })`
+ * — over the raw `announce(...)` call.
+ */
+export interface ClaimLeaseOptions {
+    /**
+     * How long before the server auto-expires this claim if the participant
+     * hasn't finished. Accepts a number of seconds or a duration string such as
+     * `'500ms'`, `'30s'`, `'3m'`, or `'24h'`.
+     */
+    readonly ttl?: Duration;
+}
+/** The duration value type used by `ttl`, re-exported for convenience. */
+export type Duration = import('../utils/duration.js').Duration;
+export interface ClaimOptions extends ClaimLeaseOptions {
+    /**
+     * Peer-visible description of the work you're doing — the sentence another
+     * participant reads to decide whether to wait, work elsewhere, or move on
+     * (`'rewriting the risk section to match Q3'`). Surfaces in conflict
+     * messages and the activity overlay, and rides back in the rejection a
+     * blocked writer receives. Defaults to `'editing'`.
+     */
+    readonly description?: string;
+    /**
+     * @deprecated Renamed to {@link ClaimOptions.description}. Still accepted —
+     * `description` wins when both are given — and removed in 0.36.0.
+     *
+     * The rename shipped without this line, so the server went on accepting
+     * `reason` while the type stopped offering it. Code written against the older
+     * shape kept working at runtime and stopped type-checking, with nothing
+     * saying why.
+     */
+    readonly reason?: string;
+    /**
+     * On contention, join the server's fair first-in-first-out queue instead of
+     * being rejected. The grant then arrives asynchronously — immediately if the
+     * target was free, or once you reach the head of the line. To wait for the
+     * grant, use `ablo.<model>.claim`, which pairs this flag with the wait.
+     */
+    readonly queue?: boolean;
+}
+export interface ClaimStream {
+    /**
+     * A reactive view of every other participant's active claims. Reading it
+     * returns the current snapshot; pair it with `onChange(...)` to be notified
+     * when it changes.
+     */
+    readonly others: readonly Claim[];
+    /**
+     * A reactive view of the wait queue on one target — the ordered line of
+     * queued claims behind the current holder, each carrying its `description`,
+     * `heldBy`, and `position`. Empty when no one is waiting. Pair it with
+     * `onChange(...)` for change notifications.
+     */
+    queueFor(target: PresenceTarget): readonly Claim[];
+    /**
+     * Re-rank the wait queue on a target: move the listed waiters to the front in
+     * the given order, leaving the rest in their existing relative order behind
+     * them. Pass the claims from `queueFor(target)` in the order you want. This
+     * is privileged — the server rejects a participant that lacks the
+     * `claim.reorder` capability — and fire-and-forget: the new order arrives
+     * reactively through `queueFor`.
+     */
+    reorder(target: PresenceTarget, order: readonly Claim[]): void;
+    /**
+     * A framework-agnostic reactivity hook, with the same contract as
+     * {@link PresenceStream.onChange}: register a listener that fires on every
+     * change — a claim announced, revoked, or expired — and returns a function
+     * that unsubscribes. Use `useSyncExternalStore` in React or `autorun` in
+     * MobX.
+     */
+    onChange(listener: () => void): () => void;
+    /**
+     * Observe claims the server rejected. Fires when a claim you tried to take is
+     * refused because another participant already holds an open claim on the same
+     * target.
+     *
+     * Use it to surface conflicts to the user:
+     * ```ts
+     * participant.claims.onRejected((r) => {
+     *   toast.error(`${r.heldBy} is editing — try again in a moment`);
+     * });
+     * ```
+     *
+     * Returns a function that unsubscribes.
+     */
+    onRejected(listener: (rejection: ClaimRejection) => void): () => void;
+    /**
+     * Observe losing a claim you held — distinct from `onRejected`, which is a
+     * claim the server refused to grant. Fires when the server reports the loss,
+     * carrying why: `'preempted'` (a privileged participant evicted you) or
+     * `'expired'` (your lease lapsed). This lets a holder react — re-plan or
+     * re-claim — rather than discovering the lease gone through presence.
+     *
+     * ```ts
+     * participant.claims.onLost((lost) => {
+     *   if (lost.reason === 'preempted') replanAgainst(lost.target);
+     *   else reclaim(lost.target);
+     * });
+     * ```
+     *
+     * Returns a function that unsubscribes.
+     */
+    onLost(listener: (lost: ClaimLost) => void): () => void;
+    /**
+     * An async-iterable view of everyone else's open claims. Each iteration
+     * yields the current snapshot whenever it changes.
+     *
+     * ```ts
+     * for await (const openClaims of participant.claims) {
+     *   if (openClaims.some((i) => i.target.id === clauseId)) wait();
+     * }
+     * ```
+     */
+    [Symbol.asyncIterator](): AsyncIterableIterator<readonly Claim[]>;
+}
+/**
+ * Every lifecycle state of a claim. `active` is the current holder — the lock
+ * itself. `queued` is waiting in line behind the holder and carries a
+ * `position`. The remaining states are terminal and drop the claim from the
+ * synced set.
+ */
+export type ClaimStatus = PublicClaimStatus;
+/** Options for waiting on a target to become free. */
+export interface ClaimWaitOptions {
+    readonly timeout?: number;
+    readonly pollInterval?: number;
+    readonly signal?: AbortSignal;
+}
+export interface Claim<T = Record<string, unknown>, M = ResolveClaimMeta> {
+    readonly object: 'claim';
+    /** This claim's id. */
+    readonly id: string;
+    /**
+     * The claim's lifecycle state. `active` is the holder — the lock; `queued` is
+     * waiting in line and carries a `position`. It is optional on shapes derived
+     * from a presence frame, where a present entry is `active` by construction.
+     */
+    readonly status?: ClaimStatus;
+    /** What is being coordinated. */
+    readonly target: ClaimTarget<M>;
+    /**
+     * Peer-visible description of the work being done — the same field on every
+     * claim surface. Always present: the SDK resolves it as it decodes the frame,
+     * defaulting to `'editing'` when a claim carries no description.
+     */
+    readonly description: string;
+    /** Participant holding it. Absent on a handle you hold for yourself. */
+    readonly heldBy?: string;
+    /**
+     * Whether the holder is a user (session), agent, or system actor — so UIs
+     * style "agent editing X" vs "user editing X" without string-parsing
+     * `heldBy`. Present on observed claims; absent on your own fresh handle.
+     */
+    readonly participantKind?: ParticipantKind;
+    /** Epoch-ms the holder opened it. */
+    readonly createdAt?: number;
+    /** Epoch-ms the server auto-expires it if the holder doesn't finish. */
+    readonly expiresAt?: number;
+    /**
+     * The seconds remaining until auto-expiry — a countdown output as a plain
+     * number, distinct from the `ttl: Duration` (such as `'3m'`) you pass in when
+     * claiming.
+     */
+    readonly ttlSeconds?: number;
+    /**
+     * The claim's open metadata bag, as it stands on the wire.
+     *
+     * A heartbeat's `details` land here under `progress` — last beat wins — so
+     * an observer can read what a long hold is doing without waiting for the
+     * holder to release. Deliberately the open record rather than the declared
+     * `ClaimMeta`: a shape the program declared has no member for a key the
+     * coordinator wrote, and `target.meta` beside it is that declared shape.
+     */
+    readonly meta?: Record<string, unknown>;
+    /**
+     * 0-based place in the FIFO line — present only when `status: 'queued'`
+     * (`0` = next behind the holder). Absent for the active holder.
+     */
+    readonly position?: number;
+    /**
+     * True when the grant arrived only after waiting in the server's queue — the
+     * reliable signal that the row may have changed while you waited. Absent for
+     * an immediate, uncontended grant.
+     */
+    readonly waited?: boolean;
+    /**
+     * The sync watermark at which `data` was read. A write made under this claim
+     * uses it as the `readAt` staleness guard. Present on a claim you hold.
+     */
+    readonly readAt?: number;
+    /**
+     * The monotonic fencing token the server minted for this grant (Option B). A
+     * write made under this claim carries it, and the server rejects the write if
+     * a later holder already advanced this entity past the token — closing the
+     * "my claim lapsed and its successor came and went" lost-update window that
+     * `readAt` alone cannot (a blind write with no read basis has nothing to
+     * compare). Present on a claim you hold that was granted a token.
+     */
+    readonly fenceToken?: number;
+    /** Row snapshot under the lease — present on a claim you hold. */
+    readonly data?: T;
+    /**
+     * Release the lease. Present only on a claim you hold (returned by
+     * `ablo.<model>.claim`); absent on observed peer claims.
+     */
+    release?: () => Promise<void>;
+    /** Synchronously abandon the lease. Present only on a claim you hold. */
+    revoke?: () => void;
+    /**
+     * Extend the lease past the liveness window — the "still working" signal
+     * for long-running tasks. Resolving means the lease is still yours, now
+     * good until the returned `expiresAt`; a lease that lapsed (and may have
+     * been granted to the next in line) rejects with an
+     * {@link ../errors.js AbloClaimedError} carrying code `claim_lost`, so the
+     * failed beat doubles as the loss notification. Each beat's extension is
+     * clamped server-side — hold a long task by beating on a cadence (pass
+     * `heartbeat` when claiming to have the SDK do this for you), not by
+     * asking once for a huge window. Present only on a claim you hold.
+     */
+    heartbeat?: (options?: Duration | ClaimHeartbeatOptions) => Promise<ClaimHeartbeat>;
+    /** Auto-release on `await using` scope exit. Present only on a held claim. */
+    [Symbol.asyncDispose]?(): PromiseLike<void>;
+}
+/** Options for one beat — a bare {@link Duration} is shorthand for `{ ttl }`. */
+export interface ClaimHeartbeatOptions {
+    /** Requested extension from now; the server clamps it and never shortens. */
+    readonly ttl?: Duration;
+    /**
+     * Lightweight progress the beat carries along (`{ pages: 42, of: 100 }`) —
+     * becomes the claim's peer-visible `meta.progress` (last beat wins) and
+     * dies with the lease. Durable checkpoints belong in the data itself:
+     * write a row, and every subscriber already sees it.
+     */
+    readonly details?: Record<string, unknown>;
+}
+/** The resolved value of a successful {@link Claim.heartbeat} — the lease is
+ *  still yours, now good until `expiresAt` (epoch milliseconds). */
+export interface ClaimHeartbeat {
+    readonly expiresAt: number;
+    /**
+     * How many participants wait in line behind this lease — cooperative-yield
+     * pressure. A worker that can checkpoint may release early when others
+     * wait. Absent when the server predates the field.
+     */
+    readonly queueDepth?: number;
+}
+/**
+ * A claim you hold — the resolved value of `ablo.<model>.claim(...)`. It is a
+ * {@link Claim} with the lease-control members (`data`, `release`, `revoke`,
+ * and the async-dispose hook) made required; they are optional on the base
+ * because that shape also models observed peer claims, which lack them. Making
+ * them required is what lets `await using held = await ablo.x.claim(...)`
+ * typecheck, since `Claim`'s optional dispose hook is not assignable to
+ * `AsyncDisposable`.
+ */
+export type HeldClaim<T = Record<string, unknown>, M = ResolveClaimMeta> = Claim<T, M> & Required<Pick<Claim<T, M>, 'data' | 'release' | 'revoke' | 'heartbeat' | typeof Symbol.asyncDispose>>;
+/**
+ * A held advisory lease you took on a key whose row Ablo does not hold — the
+ * resolved value of the row-free `ablo.<model>.claim(id)` overload. It is a
+ * {@link HeldClaim} minus `.data`: the same lease controls (`release`, `revoke`,
+ * `heartbeat`, and the `await using` disposer are all required and behave
+ * identically), only without a snapshot, because the row lives solely in the
+ * customer's own database and was never replicated into the local pool. Use it
+ * to serialize work against a key you know by id alone.
+ */
+export type HeldLease = Omit<HeldClaim, 'data'>;
+//# sourceMappingURL=streams.d.ts.map

package/dist/types/streams.d.ts.map

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

package/dist/types/streams.js

@@ -0,0 +1,12 @@
+/**
+ * The types for real-time multiplayer coordination.
+ *
+ * Ablo treats people and AI agents alike as participants working on live
+ * application entities. A participant announces what it is reading or editing,
+ * claims an entity before writing to it, and captures a context snapshot before
+ * starting long-running AI work. You keep your own schema, agent stack, tools,
+ * prompts, and product rules; this package provides the shared coordination
+ * layer underneath.
+ */
+export {};
+//# sourceMappingURL=streams.js.map

package/dist/types/streams.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streams.js","sourceRoot":"","sources":["../../src/types/streams.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/utils/asyncIterator.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Turns a callback-based subscription into an async iterable that yields the
+ * latest snapshot each time the source changes. You supply two functions:
+ * `subscribe(listener)`, which registers your listener and returns a teardown
+ * function, and `getSnapshot()`, which reads the current value. On every change
+ * notification the iterator calls `getSnapshot()` and hands the result to the
+ * consumer's `for await` loop; when the loop ends, the iterator runs the
+ * teardown function.
+ *
+ * Because each notification yields the current snapshot rather than a specific
+ * event, bursts coalesce harmlessly — a consumer that falls behind still ends up
+ * with the freshest value. The queue is unbounded, so a consumer that never
+ * advances lets memory grow without limit. When individual events matter and
+ * must not be dropped, use {@link asyncIteratorFromEvents} instead.
+ *
+ * Each call to the factory creates an independent iterator with its own
+ * subscription. Two `for await` loops over the same source each observe every
+ * change; they do not take values from one another.
+ */
+/**
+ * Turns a callback-based subscription into an async iterable that yields each
+ * discrete event, in order, with none dropped. You supply a single
+ * `subscribe(push)` function: it registers your producer and returns a teardown
+ * function, and your producer calls `push(value)` once per event. The consumer's
+ * `for await` loop receives every pushed value.
+ *
+ * This is the counterpart to {@link asyncIteratorFrom}. Reach for that one when
+ * you only need the latest state and coalescing bursts is fine; reach for this
+ * one when every event is significant — for example a stream of change deltas
+ * where skipping one would lose data. The queue is unbounded, so a consumer that
+ * stops advancing lets memory grow without limit.
+ */
+export declare function asyncIteratorFromEvents<T>(subscribe: (push: (value: T) => void) => () => void): AsyncIterableIterator<T>;
+export declare function asyncIteratorFrom<T>(subscribe: (listener: () => void) => () => void, getSnapshot: () => T): AsyncIterableIterator<T>;
+//# sourceMappingURL=asyncIterator.d.ts.map

package/dist/utils/asyncIterator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"asyncIterator.d.ts","sourceRoot":"","sources":["../../src/utils/asyncIterator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,KAAK,MAAM,IAAI,GAClD,qBAAqB,CAAC,CAAC,CAAC,CA+C1B;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,SAAS,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,EAC/C,WAAW,EAAE,MAAM,CAAC,GACnB,qBAAqB,CAAC,CAAC,CAAC,CAsD1B"}