@proj-airi/stream-kit 0.0.0-stage → 0.15.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-PRESENT Neko Ayaka
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,153 @@
-# Temporary Holding Version
+# @proj-airi/stream-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Lifetime, scheduling, and stream helpers for AIRI. The package has no UI, audio, or provider dependency.
+
+## Use it for
+
+- One unit of async work with one outcome, a timeout, and cleanups: `createTask` and `runTask`.
+- Work that only the newest input needs, like `switchMap`: `createLatest`.
+- A lifetime for resources with child lifetimes: `createScope`.
+- A readable stream that a push source writes to: `createPushStream`.
+- A queue that runs handlers for each item in order: `createQueue`.
+- Event stream state: batches, a bounded buffer, sequence and lateness checks, demand, leases, cooldowns, and a feed that catches up new subscribers. See [Event streams](#event-streams).
+
+## Do not use it for
+
+- Audio windows, captures, or playback. Use `@proj-airi/pipelines-audio`.
+- Cross-process events. Use `@moeru/eventa`.
+
+## Tasks
+
+A task settles once with an `Outcome`: `finished`, `cancelled`, or `failed`.
+
+```ts
+const task = runTask(async ({ signal }) => fetchText(url, signal), { signal: parent, timeoutMs: 5000 })
+task.defer(() => connection.close())
+const outcome = await task.done
+```
+
+- `signal` aborts on cancellation, failure, timeout, or parent abort. It does not abort on `finish`, so handed-off work, such as queued playback, continues.
+- Cleanups run once, in reverse order, after the outcome. `closed` resolves after they settle.
+- `worstOutcome(outcomes)` merges outcomes. A failure wins over a cancellation, and a cancellation wins over success.
+
+## Newest input only
+
+```ts
+const runner = createLatest<Document>(async (document, signal) => {
+  cache.set(document.text, await rewrite(document.text, signal))
+}, { key: document => document.text, debounceMs: 600 })
+
+runner.push(document)
+```
+
+- A new key aborts the active run and replaces a waiting input. An equal key keeps the active run.
+- `debounceMs` waits until the key stays the same for that long.
+- `cancelPending()` drops a waiting input and keeps the active run.
+- Errors of superseded or closed runs are not reported.
+
+## Event streams
+
+These primitives keep no hidden clock. Each method that needs the time takes `now`, and only `createBatcher` starts a timer.
+
+### Batches: `createBatcher`
+
+Groups items, like `groupedWithin`. A batch flushes at `maxItems` items or `maxWaitMs` after its first item, whichever comes first. Use it to send many small messages as fewer large ones.
+
+```ts
+const batcher = createBatcher<TraceRecord>({ maxWaitMs: 50, maxItems: 500, flush: records => send({ records }) })
+batcher.push(record)
+batcher.close() // flushes the rest
+```
+
+- `schedule` replaces the `setTimeout` timer, for example in tests.
+- With `now`, a push after the deadline flushes at once, also when a background tab delays the timer.
+
+### Bounded buffer: `RetentionBuffer`
+
+Keeps the newest items within `maxBytes` and `maxAgeMs`, in insertion order. Use it for a replay buffer or a flight recorder window.
+
+```ts
+const buffer = new RetentionBuffer<Entry>({ maxBytes: 8_000_000, maxAgeMs: 600_000, sizeOf: entry => entry.bytes, ageOf: entry => entry.observedAt, onEvict: reportGap })
+buffer.push(entry) // applies the byte limit
+buffer.evict(now) // applies both limits, from a periodic tick
+```
+
+- Only the oldest items drop. Eviction costs time for the dropped items only.
+- `onEvict` receives each group of dropped items, so the caller can report a gap.
+
+### Sequence numbers: `SequenceTracker`
+
+Accepts each sequence number once, in any arrival order. Use it to drop repeats after a reconnect or a retry.
+
+```ts
+const tracker = new SequenceTracker()
+if (tracker.accept(record.seq))
+  handle(record) // a repeat does not reach this line
+```
+
+`nextSeq - 1` is the end of the unbroken prefix.
+
+### Late events: `Watermark`
+
+Tracks the newest event time and marks an event that is more than `allowedLatenessMs` behind it.
+
+```ts
+const watermark = new Watermark({ allowedLatenessMs: 2000 })
+const { late } = watermark.observe(record.ts)
+```
+
+### Wanted keys: `DemandUnion`
+
+The union of what each member wants. A `'*'` member makes the union `'*'`. Use it so that a producer skips work that no viewer wants.
+
+```ts
+const demand = new DemandUnion<string>({ onChange: union => source.setWanted(union) })
+demand.set(viewerId, ['audio.level'])
+demand.delete(viewerId)
+```
+
+`onChange` runs only when the union changes.
+
+### Leases: `createLeaseTable`
+
+Keys that stay alive while their owner renews them. Use it for heartbeats and repeated announcements.
+
+```ts
+const leases = createLeaseTable<string>({ ttlMs: 12_000 })
+leases.touch(tabId, now)
+for (const tab of leases.expired(now))
+  forgetTab(tab)
+```
+
+### Cooldowns: `createCooldown`
+
+Allows an action at most once per window for each key.
+
+```ts
+const cooldown = createCooldown({ ms: 30_000 })
+if (cooldown.tryAcquire(source, now))
+  dump()
+```
+
+### Catch-up feed: `createCatchUpFeed`
+
+A live feed in which a new subscriber receives the backlog, then an optional `caughtUp` message, then live messages. Use it when a viewer opens after the stream started.
+
+```ts
+const feed = createCatchUpFeed<Message>({ backlog: () => buffer.values(), caughtUp: () => ({ kind: 'caughtUp' }) })
+const { unsubscribe } = feed.subscribe(render)
+buffer.push(record)
+feed.publish({ kind: 'record', record })
+```
+
+- No message is lost or repeated between the backlog and the live messages. The owner must update the backlog state before each `publish`.
+- A `publish` during the backlog delivery waits, and goes to the new subscriber after `caughtUp`.
+- The backlog and `caughtUp` arrive synchronously inside `subscribe`.
+- The `strategy` applies to live messages. `unbounded` calls the listener inside `publish`. `sliding` and `dropping` keep up to `capacity` messages and deliver them in a microtask. A full `sliding` queue drops its oldest message, and a full `dropping` queue drops the new one.
+
+## Checks
+
+```sh
+pnpm -F @proj-airi/stream-kit typecheck
+pnpm -F @proj-airi/stream-kit test:run
+```

package/dist/index.d.mts

@@ -0,0 +1,429 @@
+//#region src/batcher.d.ts
+/** Runs `callback` after `delayMs`. Returns a function that cancels the run. */
+type BatchScheduler = (callback: () => void, delayMs: number) => () => void;
+interface BatcherOptions<T> {
+  /** The longest time that the first pending item waits before a flush. */
+  readonly maxWaitMs: number;
+  /** Flushes at once when this many items wait. @default Infinity */
+  readonly maxItems?: number;
+  /** Receives each nonempty batch, in push order. A push inside `flush` starts a new batch. */
+  readonly flush: (items: T[]) => void;
+  /**
+   * The current time. When given, a push after the deadline of the batch flushes at once, also when the timer runs
+   * late, for example in a throttled background tab. Omission leaves the deadline to the timer only.
+   */
+  readonly now?: () => number;
+  /** Starts the wait timer. @default a `setTimeout` and `clearTimeout` pair */
+  readonly schedule?: BatchScheduler;
+}
+interface Batcher<T> {
+  push: (item: T) => void;
+  /** Flushes the pending items now. Does nothing when no item waits. */
+  flush: () => void;
+  /** Flushes the pending items and ignores later pushes. */
+  close: () => void;
+}
+/**
+ * Groups items into batches, like `groupedWithin`. A batch flushes when it has `maxItems` items, or `maxWaitMs`
+ * after its first item, whichever comes first.
+ *
+ * @example
+ * const batcher = createBatcher<TraceRecord>({ maxWaitMs: 50, maxItems: 500, flush: records => send({ records }) })
+ * batcher.push(record)
+ */
+declare function createBatcher<T>(options: BatcherOptions<T>): Batcher<T>;
+//#endregion
+//#region src/catch-up-feed.d.ts
+/**
+ * How a subscriber receives live messages.
+ *
+ * - `unbounded`: `publish` calls the listener at once. A slow listener slows the publisher.
+ * - `sliding`: a queue of `capacity` messages, delivered in a microtask. A full queue drops its oldest message.
+ * - `dropping`: a queue of `capacity` messages, delivered in a microtask. A full queue drops the new message.
+ */
+type DeliveryStrategy = 'unbounded' | 'sliding' | 'dropping';
+interface SubscribeOptions {
+  /** @default 'unbounded' */
+  readonly strategy?: DeliveryStrategy;
+  /** The queue size of `sliding` and `dropping`. @default 256 */
+  readonly capacity?: number;
+}
+interface CatchUpFeedOptions<M> {
+  /** The messages that a new subscriber receives first, for example the kept buffer. Read once per subscribe. */
+  readonly backlog: () => Iterable<M>;
+  /** A message after the backlog, for example a cursor. Created when the backlog is read. */
+  readonly caughtUp?: () => M;
+}
+interface CatchUpFeed<M> {
+  /** Sends a live message. Update the state behind `backlog` before this call. */
+  publish: (message: M) => void;
+  subscribe: (listener: (message: M) => void, options?: SubscribeOptions) => {
+    unsubscribe: () => void;
+  };
+  /** The number of active subscribers, including one that is still catching up. */
+  readonly subscribers: number;
+}
+/**
+ * A live feed in which a new subscriber first receives the backlog, then `caughtUp`, then the live messages.
+ *
+ * Guarantee: no message is lost or repeated between the backlog and the live messages, if the owner updates the
+ * state behind `backlog` before each `publish`. `subscribe` copies the backlog first. A `publish` during the backlog
+ * delivery, for example from a listener, waits and goes to the new subscriber after `caughtUp`. A subscriber added
+ * during a `publish` does not receive that message live, because its backlog already has it.
+ *
+ * The backlog and `caughtUp` always arrive synchronously inside `subscribe`. The strategy applies to live messages.
+ *
+ * @example
+ * const feed = createCatchUpFeed<Message>({ backlog: () => buffer.values(), caughtUp: () => ({ kind: 'caughtUp' }) })
+ * buffer.push(record)
+ * feed.publish({ kind: 'record', record })
+ */
+declare function createCatchUpFeed<M>(options: CatchUpFeedOptions<M>): CatchUpFeed<M>;
+//#endregion
+//#region src/cooldown.d.ts
+interface CooldownOptions {
+  /** The shortest time between two successful acquires of one key. */
+  readonly ms: number;
+}
+interface Cooldown {
+  /** Returns true and starts a new window when the window of `key` has passed. Returns false inside the window. */
+  tryAcquire: (key: string, now: number) => boolean;
+}
+/**
+ * Limits an action to once per window for each key, for example one flight recorder dump per source.
+ *
+ * The cooldown keeps one time for each key that it has seen.
+ *
+ * @example
+ * const cooldown = createCooldown({ ms: 30_000 })
+ * if (cooldown.tryAcquire(source, now))
+ *   dump()
+ */
+declare function createCooldown(options: CooldownOptions): Cooldown;
+//#endregion
+//#region src/demand-union.d.ts
+/** A set of wanted keys, or `'*'` for all keys. */
+type Demand<T> = ReadonlySet<T> | '*';
+interface DemandUnionOptions<T> {
+  /** Receives the new union after each change of it. A `set` that keeps the union the same does not call it. */
+  readonly onChange?: (union: Demand<T>) => void;
+}
+/**
+ * The union of what each member wants, for example the tracks of all viewers.
+ *
+ * A producer reads the union to skip work that no member wants. One `'*'` member makes the union `'*'`.
+ *
+ * @example
+ * const demand = new DemandUnion<string>({ onChange: union => source.setWanted(union) })
+ * demand.set('viewer-1', ['audio.level'])
+ * demand.set('viewer-2', '*') // onChange('*')
+ * demand.delete('viewer-2') // onChange(Set { 'audio.level' })
+ */
+declare class DemandUnion<T> {
+  private readonly options;
+  private readonly members;
+  private current;
+  constructor(options?: DemandUnionOptions<T>);
+  get union(): Demand<T>;
+  set(id: string, demand: Iterable<T> | '*'): void;
+  delete(id: string): void;
+  private update;
+  private compute;
+}
+//#endregion
+//#region src/latest.d.ts
+interface LatestOptions<T> {
+  /**
+   * Values with an equal key (`Object.is`) are the same input. A repeated key keeps the active run.
+   * Omission treats every pushed value as new.
+   */
+  readonly key?: (value: T) => unknown;
+  /** Waits until no new key arrives for this long, then runs. @default 0 */
+  readonly debounceMs?: number;
+  /** Closes the runner. */
+  readonly signal?: AbortSignal;
+  /** Receives errors from runs that were not superseded or closed. */
+  readonly onError?: (error: unknown) => void;
+}
+/**
+ * Runs work for the newest input only, like `switchMap`.
+ *
+ * Each new key aborts the active run and replaces any waiting input. A run sees one value and one signal. The signal
+ * aborts when a newer key arrives or the runner closes. Errors after that abort are expected and not reported.
+ */
+interface Latest<T> {
+  push: (value: T) => void;
+  /** Drops an input that waits for its debounce. The active run continues. */
+  cancelPending: () => void;
+  /** Resolves when no run is active or waiting. */
+  idle: () => Promise<void>;
+  close: (reason?: string) => void;
+}
+/**
+ * Creates a runner that keeps only the newest input.
+ *
+ * @example
+ * const runner = createLatest<string>(async (text, signal) => cache.set(text, await rephrase(text, signal)), { debounceMs: 600 })
+ * runner.push('hello')
+ * runner.push('hello world') // aborts the run for 'hello'
+ */
+declare function createLatest<T>(run: (value: T, signal: AbortSignal) => Promise<void> | void, options?: LatestOptions<T>): Latest<T>;
+//#endregion
+//#region src/lease-table.d.ts
+interface LeaseTableOptions {
+  /** A key expires when no `touch` renews it for longer than this. */
+  readonly ttlMs: number;
+}
+interface LeaseTable<K> {
+  /** Adds the key, or renews its lease. */
+  touch: (key: K, now: number) => void;
+  /** Removes and returns the keys whose last `touch` is more than `ttlMs` before `now`. */
+  expired: (now: number) => K[];
+  delete: (key: K) => void;
+  has: (key: K) => boolean;
+  keys: () => IterableIterator<K>;
+}
+/**
+ * Keys that stay alive while their owner renews them, for example a remote source with a heartbeat, or a tab that
+ * repeats its announcement. The caller decides when to call `expired`, usually from a periodic tick.
+ *
+ * @example
+ * const leases = createLeaseTable<string>({ ttlMs: 12_000 })
+ * leases.touch('tab-1', now)
+ * for (const tab of leases.expired(later))
+ *   forgetTab(tab)
+ */
+declare function createLeaseTable<K>(options: LeaseTableOptions): LeaseTable<K>;
+//#endregion
+//#region src/queue.d.ts
+interface HandlerContext<T> {
+  data: T;
+  emit: (eventName: string, ...params: unknown[]) => void;
+}
+interface Events<T> {
+  enqueue: Array<(payload: T, queueLength: number) => void>;
+  dequeue: Array<(payload: T, queueLength: number) => void>;
+  process: Array<(payload: T, handler: (param: HandlerContext<T>) => Promise<unknown>) => void>;
+  error: Array<(payload: T, error: unknown, handler: (param: HandlerContext<T>) => Promise<unknown>) => void>;
+  result: Array<(<R>(payload: T, result: R, handler: (param: HandlerContext<T>) => Promise<unknown>) => void)>;
+  drain: Array<() => void>;
+}
+declare function createQueue<T>(options: {
+  handlers: Array<(ctx: HandlerContext<T>) => Promise<void>>;
+}): {
+  enqueue: (payload: T) => void;
+  clear: () => void;
+  length: () => number;
+  on: <E extends keyof Events<T>>(eventName: E, listener: Events<T>[E][number]) => void;
+  onHandlerEvent: (eventName: string, listener: (...params: unknown[]) => void) => void;
+};
+type UseQueueReturn<T> = ReturnType<typeof createQueue<T>>;
+//#endregion
+//#region src/retention-buffer.d.ts
+interface RetentionBufferOptions<T> {
+  /** Drops the oldest items while the total size is over this limit. @default Infinity */
+  readonly maxBytes?: number;
+  /** `evict` drops items that are older than this. @default Infinity */
+  readonly maxAgeMs?: number;
+  /** The size of an item. The buffer reads it once, at `push`. */
+  readonly sizeOf: (item: T) => number;
+  /** The time of an item, in the clock of the `now` that `evict` receives. */
+  readonly ageOf: (item: T) => number;
+  /** Receives each group of dropped items, oldest first. A caller can report the gap here. */
+  readonly onEvict?: (items: T[]) => void;
+}
+/**
+ * Keeps the newest items within a byte limit and an age limit, in insertion order.
+ *
+ * Only the head can drop, so the age limit assumes that `ageOf` grows with insertion order. An older item behind a
+ * newer one stays until the newer one drops. A `push` applies only the byte limit, because the age limit needs `now`.
+ * One item that is larger than `maxBytes` drops at once. Eviction costs time for the dropped items only.
+ *
+ * @example
+ * const buffer = new RetentionBuffer<Entry>({ maxBytes: 8_000_000, maxAgeMs: 600_000, sizeOf: e => e.bytes, ageOf: e => e.observedAt })
+ * buffer.push(entry)
+ * buffer.evict(now) // call it from a periodic tick
+ */
+declare class RetentionBuffer<T> {
+  private readonly options;
+  private entries;
+  private head;
+  private totalBytes;
+  constructor(options: RetentionBufferOptions<T>);
+  get size(): number;
+  get bytes(): number;
+  push(item: T): void;
+  /** Drops the items older than the age limit, then the oldest items over the byte limit. Returns the dropped items. */
+  evict(now: number): T[];
+  /** The kept items, oldest first. Do not push or evict while you iterate. */
+  values(): IterableIterator<T>;
+  /** Drops every item without `onEvict`. */
+  clear(): void;
+  private evictWhile;
+}
+//#endregion
+//#region src/scope.d.ts
+/**
+ * One owned lifetime.
+ *
+ * `signal` aborts when the scope closes, either through `close` or through its parent signal.
+ * Deferred cleanups run once, in reverse registration order, after the signal aborts.
+ */
+interface Scope {
+  readonly signal: AbortSignal;
+  /** Resolves after every deferred cleanup has settled. Cleanup errors are reported, not thrown. */
+  readonly closed: Promise<void>;
+  /** Registers cleanup. A cleanup registered after closing runs immediately. */
+  defer: (cleanup: () => unknown) => void;
+  /**
+   * Creates a scope that closes with this one, and can also close earlier by itself.
+   * Children start closing before the parent's own cleanups. The parent does not await child cleanup.
+   */
+  child: () => Scope;
+  close: (reason?: unknown) => Promise<void>;
+}
+/**
+ * Creates a scope that closes when `parent` aborts.
+ *
+ * @example
+ * const scope = createScope(options.signal)
+ * scope.defer(() => track.stop())
+ * await scope.close('Recording finished')
+ */
+declare function createScope(parent?: AbortSignal, onCleanupError?: (error: unknown) => void): Scope;
+//#endregion
+//#region src/sequence-tracker.d.ts
+/**
+ * Accepts each sequence number once, in any arrival order.
+ *
+ * Numbers below `nextSeq` and repeats are not new. A number above `nextSeq` waits in a set until the numbers before
+ * it arrive. `nextSeq - 1` is the end of the unbroken prefix, so a reader can resume from it.
+ *
+ * @example
+ * const tracker = new SequenceTracker()
+ * tracker.accept(1) // => true, waits for 0
+ * tracker.accept(0) // => true, nextSeq is now 2
+ * tracker.accept(1) // => false
+ */
+declare class SequenceTracker {
+  private next;
+  private readonly ahead;
+  constructor(firstSeq?: number);
+  /** The lowest number that did not arrive yet. */
+  get nextSeq(): number;
+  /** Returns true when `seq` is new. */
+  accept(seq: number): boolean;
+}
+//#endregion
+//#region src/stream.d.ts
+interface StreamController<T> {
+  stream: ReadableStream<T>;
+  write: (value: T) => void;
+  close: () => void;
+  error: (err: unknown) => void;
+  isClosed: () => boolean;
+  /** Remaining queue capacity under `strategy`. Negative when the reader is behind. Null after an error. */
+  desiredSize: () => number | null;
+}
+/**
+ * The optional cancellation handler owns resources that feed this readable output.
+ * `strategy` measures unread values. Writers check `desiredSize` because a push source cannot wait.
+ */
+declare function createPushStream<T>(onCancel?: (reason: unknown) => void, strategy?: QueuingStrategy<T>): StreamController<T>;
+declare function readStream<T>(stream: ReadableStream<T>, handler: (value: T) => Promise<void> | void): Promise<void>;
+//#endregion
+//#region src/task.d.ts
+/** The result of one task. Cancellation and failure carry their cause. */
+type Outcome<T = void> = {
+  readonly status: 'finished';
+  readonly value: T;
+} | {
+  readonly status: 'cancelled';
+  readonly reason: string;
+} | {
+  readonly status: 'failed';
+  readonly error: Error;
+};
+interface TaskOptions {
+  /** The task cancels when this signal aborts. */
+  readonly signal?: AbortSignal;
+  /** The task fails with a timeout error after this many milliseconds. Omission adds no timeout. */
+  readonly timeoutMs?: number;
+  /** Receives cleanup errors. Cleanup errors never change the outcome. */
+  readonly onCleanupError?: (error: unknown) => void;
+}
+/**
+ * One unit of work with one outcome.
+ *
+ * `signal` aborts on cancellation, failure, or timeout. It does not abort on `finish`, so work that the task
+ * handed off, for example queued playback, continues. Deferred cleanups run once, in reverse order, after the
+ * outcome is set.
+ */
+interface Task<T = void> {
+  readonly signal: AbortSignal;
+  readonly done: Promise<Outcome<T>>;
+  /** Resolves after every deferred cleanup has settled. */
+  readonly closed: Promise<void>;
+  /** True after the first of `finish`, `cancel`, or `fail`. */
+  readonly settled: boolean;
+  /** Registers cleanup. A cleanup registered after settlement runs at once. */
+  defer: (cleanup: () => unknown) => void;
+  finish: (value: T) => void;
+  cancel: (reason: string) => void;
+  fail: (error: Error) => void;
+}
+/**
+ * Creates a task that settles by an explicit call.
+ *
+ * @example
+ * const task = createTask<string>({ signal: parent.signal, timeoutMs: 5000 })
+ * task.defer(() => socket.close())
+ * task.finish('ok')
+ * await task.done // => { status: 'finished', value: 'ok' }
+ */
+declare function createTask<T = void>(options?: TaskOptions): Task<T>;
+/**
+ * Runs `work` as one task. The returned value finishes the task, and a thrown error fails it.
+ * A call to `cancel` or `fail` inside `work` wins over its later return.
+ *
+ * @example
+ * const task = runTask(async ({ signal }) => fetch(url, { signal }).then(response => response.text()))
+ * const outcome = await task.done
+ */
+declare function runTask<T>(work: (task: Task<T>) => Promise<T> | T, options?: TaskOptions): Task<T>;
+/**
+ * Merges outcomes. A failure wins over a cancellation, and a cancellation wins over success.
+ *
+ * @example
+ * worstOutcome([{ status: 'finished', value: undefined }, { status: 'cancelled', reason: 'Closed' }])
+ * // => { status: 'cancelled', reason: 'Closed' }
+ */
+declare function worstOutcome(outcomes: readonly Outcome<unknown>[]): Outcome;
+//#endregion
+//#region src/watermark.d.ts
+interface WatermarkOptions {
+  /** How far behind the newest time an event can be before it is late. */
+  readonly allowedLatenessMs: number;
+}
+/**
+ * Tracks the newest event time of a stream and marks events that arrive too late.
+ *
+ * A late event is still an event. The caller decides what to do with it, for example count it or flag it in a view.
+ *
+ * @example
+ * const watermark = new Watermark({ allowedLatenessMs: 2000 })
+ * watermark.observe(10_000) // => { late: false }
+ * watermark.observe(7_000) // => { late: true }
+ */
+declare class Watermark {
+  private readonly options;
+  private newestTime;
+  constructor(options: WatermarkOptions);
+  /** The newest time observed. `-Infinity` before the first event. */
+  get newest(): number;
+  observe(time: number): {
+    late: boolean;
+  };
+}
+//#endregion
+export { BatchScheduler, Batcher, BatcherOptions, CatchUpFeed, CatchUpFeedOptions, Cooldown, CooldownOptions, DeliveryStrategy, Demand, DemandUnion, DemandUnionOptions, Events, HandlerContext, Latest, LatestOptions, LeaseTable, LeaseTableOptions, Outcome, RetentionBuffer, RetentionBufferOptions, Scope, SequenceTracker, StreamController, SubscribeOptions, Task, TaskOptions, UseQueueReturn, Watermark, WatermarkOptions, createBatcher, createCatchUpFeed, createCooldown, createLatest, createLeaseTable, createPushStream, createQueue, createScope, createTask, readStream, runTask, worstOutcome };