diff --git a/packages/chord/CHANGELOG.md b/packages/chord/CHANGELOG.md index 5d2dda138..973cf7f2e 100644 --- a/packages/chord/CHANGELOG.md +++ b/packages/chord/CHANGELOG.md @@ -10,6 +10,7 @@ - `WatchHandle` and `WatchEnd`, the one watch API, moved from Durable: a serialized exact-frame observation with `value`, `start(listener)`, `stop()`, and `closed`. `WatchEnd` reasons are `stopped`, `cancelled`, `retired`, `ended`, `listener_error`, and `failed`. - `Watch`, the one watch handle implementation, moved from Durable: a source creates one per watch and feeds it with `advance(value, ops, context)`, `retire(context)` (last frame `[["r", null]]`, then `retired`), `end()` or `end({ error })`, and `observeCancellation(signal)`. More than 100 undelivered frames collapse to one root replacement `[["r", newest]]`; termination drops the listener and every reference into the source. +- `Watchable`: a value that changes and can be watched (`value`, `watch(context)` returning a `WatchHandle`), the common interface of documents, derives and other observable values. - `NativeWatchHandle` and its implementation `NativeWatch`: the same lifecycle for in-process values, with listener `(value, context)` and no ops; an overflow collapses to the newest value. ## [1.4.0] - 2026-10-21 diff --git a/packages/chord/src/index.ts b/packages/chord/src/index.ts index d81b621b5..3523e27f1 100644 --- a/packages/chord/src/index.ts +++ b/packages/chord/src/index.ts @@ -78,6 +78,13 @@ export { replicatedState, } from "./state.ts"; export type { Ctx, GetOptions, Readable, RefStatus, Shape, StateEvent } from "./types.ts"; -export { NativeWatch, type NativeWatchHandle, Watch, type WatchEnd, type WatchHandle } from "./watch.ts"; +export { + NativeWatch, + type NativeWatchHandle, + Watch, + type Watchable, + type WatchEnd, + type WatchHandle, +} from "./watch.ts"; export { acceptWebSockets, type WebSocketAcceptOptions, type WebSocketServerLike } from "./websocket.ts"; export { type Frame, PROTOCOL_VERSION } from "./wire.ts"; diff --git a/packages/chord/src/watch.ts b/packages/chord/src/watch.ts index 3b8a19044..d0bbcc6a9 100644 --- a/packages/chord/src/watch.ts +++ b/packages/chord/src/watch.ts @@ -30,6 +30,17 @@ export interface WatchHandle { readonly closed: Promise; } +/** + * A value that changes and can be watched: documents, derives, members of references. Values are immutable by + * convention (JSON for state); each watch starts at the current value and then gets one frame per change. + */ +export interface Watchable { + /** The current value. */ + readonly value: T; + /** A watch holding the current value, then one frame per change; the context's cancellation ends it. */ + watch(context: Context): Promise>; +} + /** Serialized observation of an in-process value: as `WatchHandle`, but a change is a new value without ops. */ export interface NativeWatchHandle { /** Acquisition value before start; latest delivered value afterward. */