@rocicorp/zero 0.26.1 → 0.26.2-canary.1

package/out/zero-cache/src/types/streams.js.map

@@ -1 +1 @@
-{"version":3,"file":"streams.js","sources":["../../../../../zero-cache/src/types/streams.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport {resolver} from '@rocicorp/resolver';\nimport {\n  pipeline,\n  Readable,\n  Transform,\n  Writable,\n  type DuplexOptions,\n} from 'node:stream';\nimport {\n  createWebSocketStream,\n  type CloseEvent,\n  type ErrorEvent,\n  type MessageEvent,\n  type WebSocket,\n} from 'ws';\nimport {assert} from '../../../shared/src/asserts.ts';\nimport {BigIntJSON, type JSONValue} from '../../../shared/src/bigint-json.ts';\nimport {Queue} from '../../../shared/src/queue.ts';\nimport * as v from '../../../shared/src/valita.ts';\nimport {Subscription, type Options} from './subscription.ts';\nimport {\n  closeWithError,\n  expectPingsForLiveness,\n  sendPingsForLiveness,\n} from './ws.ts';\n\n// Consistent with Postgres keepalives, and shorter than the\n// commonly used default idle timeout of 1 minute.\nconst PING_INTERVAL_MS = 30_000;\n\nexport type Source<T> = AsyncIterable<T> & {\n  /**\n   * Immediately terminates all current iterations (i.e. {@link AsyncIterator.next next()})\n   * will return `{value: undefined, done: true}`), and prevents any subsequent iterations\n   * from yielding any values.\n   *\n   * @param err Terminate the iteration by throwing the `err` instead.\n   */\n  cancel: (err?: Error) => void;\n\n  /**\n   * The presence of a `pipeline` iterable allows the usual \"consumed-on-iterate\" semantics\n   * to be overridden.\n   *\n   * This is suitable for transport layers that serialize messages across processes, such\n   * as the {@link streamOut()} method; pipelining allows the transport to send messages\n   * as they arrive without waiting for the previous message to be acked, streaming\n   * them to the receiving process where they are presumably queued and processed without\n   * a per-message ack delay. The receiving end of the transport then responds with acks\n   * asynchronously as the receiving end processes the messages.\n   */\n  pipeline?: AsyncIterable<{value: T; consumed: () => void}> | undefined;\n};\n\nexport type Sink<T> = {\n  push(message: T): void;\n};\n\n/**\n * Back-pressure-aware transformation of a WebSocket into\n * upstream and downstream {@link Subscription} objects.\n */\n// TODO: Change {@link streamIn} and {@link streamOut} to use this\n//       under the covers so that internal communication is also\n//       responsive to backpressure.\nexport function stream<In extends JSONValue, Out extends JSONValue>(\n  lc: LogContext,\n  ws: WebSocket,\n  inSchema: v.Type<In>,\n  outOptions: Options<Out> = {},\n  inOptions: Options<In> = {},\n  streamOptions: DuplexOptions = {},\n): {outstream: Sink<Out>; instream: Source<In>} {\n  const endpoint = ws.url ?? 'client';\n  function close(err?: unknown) {\n    if (ws.readyState !== ws.CLOSED && ws.readyState !== ws.CLOSING) {\n      if (err) {\n        closeWithError(lc, ws, err);\n      } else {\n        lc.info?.(`closing connection to ${endpoint}`);\n        ws.close();\n      }\n    }\n  }\n\n  const instream = Subscription.create<In>({\n    ...inOptions,\n    cleanup: (unconsumed, err) => {\n      inOptions.cleanup?.(unconsumed, err);\n      close(err);\n    },\n  });\n  const outstream = Subscription.create<Out>({\n    ...outOptions,\n    cleanup: (unconsumed, err) => {\n      outOptions.cleanup?.(unconsumed, err);\n      close(err);\n    },\n  });\n\n  const duplex = createWebSocketStream(ws, {\n    ...streamOptions,\n    decodeStrings: false,\n  });\n\n  // Outgoing transform.\n  function streamOut() {\n    // Mainly used for verifying that back-pressure kicks in tests.\n    duplex.on('drain', () => lc.debug?.(`drained messages to ${endpoint}`));\n\n    pipeline(\n      Readable.from(outstream),\n      new Transform({\n        objectMode: true,\n        transform: (msg, _encoding, callback) =>\n          callback(null, BigIntJSON.stringify(msg)),\n      }),\n      duplex,\n      err => (err ? outstream.fail(err) : outstream.cancel()),\n    );\n  }\n\n  if (ws.readyState === ws.CONNECTING) {\n    ws.on('open', () => {\n      lc.info?.(`connected to ${endpoint}`);\n      streamOut();\n    });\n  } else {\n    streamOut();\n  }\n\n  // Incoming transform.\n  pipe({\n    source: duplex,\n    sink: instream,\n    parse: chunk => {\n      const json = BigIntJSON.parse(chunk.toString());\n      return v.parse(json, inSchema, 'passthrough');\n    },\n  });\n\n  sendPingsForLiveness(lc, ws, PING_INTERVAL_MS);\n\n  return {outstream, instream};\n}\n\ntype PipeOptions<T> = {\n  source: Readable;\n  sink: Subscription<T>;\n  parse: (buffer: Buffer) => T | null;\n  bufferMessages?: number;\n};\n\nexport function pipe<T>({source, sink, parse, bufferMessages}: PipeOptions<T>) {\n  bufferMessages ??= 0;\n  assert(bufferMessages >= 0, 'bufferMessages must be non-negative');\n  const pending: Promise<unknown>[] = [];\n\n  pipeline(\n    source,\n    new Writable({\n      decodeStrings: false,\n      write: (chunk, _encoding, callback) => {\n        let msg: T | null;\n        try {\n          if ((msg = parse(chunk)) === null) {\n            callback();\n            return;\n          }\n        } catch (err) {\n          callback(ensureError(err));\n          return;\n        }\n        // Inbound backpressure is exerted by unconsumed messages in the\n        // subscription. A buffer can be used to allow messages to queue up in\n        // in the Subscription object, which allows the consumer to \"peek\" at\n        // whether there are more messages immediately available\n        // (via {@link Subscription.queued}.\n        const {result} = sink.push(msg);\n        pending.push(result);\n        void result.then(() => pending.shift());\n\n        if (pending.length <= bufferMessages) {\n          // immediately allow more messages\n          callback();\n        } else {\n          // wait for the oldest result in the pending queue\n          pending[0].then(\n            () => callback(),\n            err => callback(ensureError(err)),\n          );\n        }\n      },\n      destroy: (err, callback) => {\n        if (err) {\n          sink.fail(ensureError(err));\n        }\n        // Otherwise, final will handle the cancel.\n        callback();\n      },\n      final: callback => {\n        sink.cancel();\n        callback();\n      },\n    }),\n    err => (err ? sink.fail(err) : sink.cancel()),\n  );\n}\n\nfunction ensureError(err: unknown) {\n  return err instanceof Error ? err : new Error(String(err));\n}\n\nconst ackSchema = v.object({ack: v.number()});\n\ntype Ack = v.Infer<typeof ackSchema>;\n\ntype Streamed<T> = {\n  /** Application-level message. */\n  msg: T;\n\n  /** ID used for the Ack message. */\n  id: number;\n};\n\nexport async function streamOut<T extends JSONValue>(\n  lc: LogContext,\n  source: Source<T>,\n  sink: WebSocket,\n): Promise<void> {\n  sendPingsForLiveness(lc, sink, PING_INTERVAL_MS);\n\n  const closer = WebSocketCloser.forSource(lc, sink, source);\n\n  const acks = new Queue<Ack>();\n  sink.addEventListener('message', ({data}) => {\n    try {\n      if (typeof data !== 'string') {\n        throw new Error('Expected string message');\n      }\n      acks.enqueue(v.parse(JSON.parse(data), ackSchema));\n    } catch (e) {\n      lc.error?.(`error parsing ack`, e);\n      closer.close(e);\n    }\n  });\n\n  try {\n    let nextID = 0;\n    const {pipeline} = source;\n    if (pipeline) {\n      lc.debug?.(`started pipelined outbound stream`);\n      for await (const {value: msg, consumed} of pipeline) {\n        const id = ++nextID;\n        const data = BigIntJSON.stringify({msg, id} satisfies Streamed<T>);\n        // Enable for debugging. Otherwise too verbose.\n        // lc.debug?.(`pipelining`, data);\n        sink.send(data);\n\n        void (async () => {\n          const {ack} = await acks.dequeue();\n          // lc.debug?.(`received ack`, ack);\n          if (ack !== id) {\n            throw new Error(`Unexpected ack for ${id}: ${ack}`);\n          }\n          consumed();\n        })();\n      }\n    } else {\n      lc.debug?.(`started synchronous outbound stream`);\n      for await (const msg of source) {\n        const id = ++nextID;\n        const data = BigIntJSON.stringify({msg, id} satisfies Streamed<T>);\n        // Enable for debugging. Otherwise too verbose.\n        // lc.debug?.(`sending`, data);\n        sink.send(data);\n\n        const {ack} = await acks.dequeue();\n        if (ack !== id) {\n          throw new Error(`Unexpected ack for ${id}: ${ack}`);\n        }\n      }\n    }\n    closer.close();\n  } catch (e) {\n    closer.close(e);\n  }\n}\n\nexport async function streamIn<T extends JSONValue>(\n  lc: LogContext,\n  source: WebSocket,\n  schema: v.Type<T>,\n): Promise<Source<T>> {\n  expectPingsForLiveness(lc, source, PING_INTERVAL_MS);\n\n  const streamedSchema = v.object({\n    msg: schema,\n    id: v.number(),\n  });\n\n  const sink: Subscription<T, Streamed<T>> = new Subscription<T, Streamed<T>>(\n    {\n      consumed: ({id}) => source.send(JSON.stringify({ack: id} satisfies Ack)),\n      cleanup: () => closer.close(),\n    },\n    ({msg}) => msg,\n  );\n\n  const closer = WebSocketCloser.forSink(lc, source, sink, handleMessage);\n\n  function handleMessage(event: MessageEvent) {\n    const data = event.data.toString();\n    if (!sink.active) {\n      lc.warn?.('dropping ws message received after close', data);\n      return;\n    }\n    try {\n      const value = BigIntJSON.parse(data);\n      const msg = v.parse(value, streamedSchema, 'passthrough');\n      // Enable for debugging. Otherwise too verbose.\n      // lc.debug?.(`received`, data);\n      sink.push(msg);\n    } catch (e) {\n      closer.close(e);\n    }\n  }\n\n  await closer.connected;\n  return sink;\n}\n\nclass WebSocketCloser {\n  readonly #lc: LogContext;\n  readonly #ws: WebSocket;\n  readonly #closeStream: () => void;\n  readonly #messageHandler: ((e: MessageEvent) => void | undefined) | null;\n  readonly #connected = resolver();\n\n  get connected(): Promise<void> {\n    return this.#connected.promise;\n  }\n\n  static forSource<T>(lc: LogContext, ws: WebSocket, stream: Source<T>) {\n    // If the websocket is closed, call cancel() to notify the Source of\n    // any unconsumed messages.\n    return new WebSocketCloser(lc, ws, () => stream.cancel());\n  }\n\n  static forSink<T>(\n    lc: LogContext,\n    ws: WebSocket,\n    stream: Subscription<T, Streamed<T>>,\n    messageHandler: (e: MessageEvent) => void | undefined,\n  ) {\n    // If the websocket is closed, call end() to allow the downstream Sink\n    // to process any pending messages before closing the stream.\n    return new WebSocketCloser(lc, ws, () => stream.end(), messageHandler);\n  }\n\n  private constructor(\n    lc: LogContext,\n    ws: WebSocket,\n    closeStream: () => void,\n    messageHandler?: (e: MessageEvent) => void | undefined,\n  ) {\n    this.#lc = lc;\n    this.#ws = ws;\n    this.#closeStream = closeStream;\n    this.#messageHandler = messageHandler ?? null;\n\n    ws.addEventListener('open', this.#handleOpen);\n    ws.addEventListener('close', this.#handleClose);\n    ws.addEventListener('error', this.#handleError);\n    if (this.#messageHandler) {\n      ws.addEventListener('message', this.#messageHandler);\n    }\n\n    switch (ws.readyState) {\n      case ws.CONNECTING:\n        break; // expected for new connections. resolve or reject in handlers.\n      case ws.OPEN:\n        this.#connected.resolve();\n        break;\n      default:\n        this.#connected.reject(\n          new Error(`websocket already in state ${ws.readyState}`),\n        );\n        break;\n    }\n  }\n\n  get #conn(): string {\n    return 'connection' + (this.#ws.url ? ` to ${this.#ws.url}` : '');\n  }\n\n  #handleOpen = () => {\n    this.#lc.info?.(`${this.#conn} established`);\n    this.#connected.resolve();\n  };\n\n  #handleClose = (e: CloseEvent) => {\n    const {code, reason, wasClean} = e;\n    this.#lc.info?.(`${this.#conn} closed`, {\n      code,\n      reason,\n      wasClean,\n    });\n    this.close();\n    this.#connected.reject(`${this.#conn} closed with code ${code}`);\n  };\n\n  #handleError = ({message, error}: ErrorEvent) => {\n    if (this.#ws.readyState === this.#ws.OPEN) {\n      this.#lc.error?.(`error in ${this.#conn}`, message, error);\n    }\n    this.#connected.reject(error);\n  };\n\n  close(err?: unknown) {\n    if (err) {\n      this.#lc.error?.(`closing stream with error`, err);\n    }\n    this.#closeStream();\n    if (!this.closed()) {\n      this.#ws.close();\n    }\n  }\n\n  closed() {\n    return (\n      this.#ws.readyState === this.#ws.CLOSED ||\n      this.#ws.readyState === this.#ws.CLOSING\n    );\n  }\n}\n"],"names":["streamOut","v.parse","parse","v.object","v.number","pipeline","stream"],"mappings":"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"}
+{"version":3,"file":"streams.js","names":["#lc","#ws","#closeStream","#messageHandler","#connected","#handleOpen","#handleClose","#handleError","#conn"],"sources":["../../../../../zero-cache/src/types/streams.ts"],"sourcesContent":["import type {LogContext} from '@rocicorp/logger';\nimport {resolver} from '@rocicorp/resolver';\nimport {\n  pipeline,\n  Readable,\n  Transform,\n  Writable,\n  type DuplexOptions,\n} from 'node:stream';\nimport {\n  createWebSocketStream,\n  type CloseEvent,\n  type ErrorEvent,\n  type MessageEvent,\n  type WebSocket,\n} from 'ws';\nimport {assert} from '../../../shared/src/asserts.ts';\nimport {BigIntJSON, type JSONValue} from '../../../shared/src/bigint-json.ts';\nimport {Queue} from '../../../shared/src/queue.ts';\nimport * as v from '../../../shared/src/valita.ts';\nimport {Subscription, type Options} from './subscription.ts';\nimport {\n  closeWithError,\n  expectPingsForLiveness,\n  sendPingsForLiveness,\n} from './ws.ts';\n\n// Consistent with Postgres keepalives, and shorter than the\n// commonly used default idle timeout of 1 minute.\nconst PING_INTERVAL_MS = 30_000;\n\nexport type Source<T> = AsyncIterable<T> & {\n  /**\n   * Immediately terminates all current iterations (i.e. {@link AsyncIterator.next next()})\n   * will return `{value: undefined, done: true}`), and prevents any subsequent iterations\n   * from yielding any values.\n   *\n   * @param err Terminate the iteration by throwing the `err` instead.\n   */\n  cancel: (err?: Error) => void;\n\n  /**\n   * The presence of a `pipeline` iterable allows the usual \"consumed-on-iterate\" semantics\n   * to be overridden.\n   *\n   * This is suitable for transport layers that serialize messages across processes, such\n   * as the {@link streamOut()} method; pipelining allows the transport to send messages\n   * as they arrive without waiting for the previous message to be acked, streaming\n   * them to the receiving process where they are presumably queued and processed without\n   * a per-message ack delay. The receiving end of the transport then responds with acks\n   * asynchronously as the receiving end processes the messages.\n   */\n  pipeline?: AsyncIterable<{value: T; consumed: () => void}> | undefined;\n};\n\nexport type Sink<T> = {\n  push(message: T): void;\n};\n\n/**\n * Back-pressure-aware transformation of a WebSocket into\n * upstream and downstream {@link Subscription} objects.\n */\n// TODO: Change {@link streamIn} and {@link streamOut} to use this\n//       under the covers so that internal communication is also\n//       responsive to backpressure.\nexport function stream<In extends JSONValue, Out extends JSONValue>(\n  lc: LogContext,\n  ws: WebSocket,\n  inSchema: v.Type<In>,\n  outOptions: Options<Out> = {},\n  inOptions: Options<In> = {},\n  streamOptions: DuplexOptions = {},\n): {outstream: Sink<Out>; instream: Source<In>} {\n  const endpoint = ws.url ?? 'client';\n  function close(err?: unknown) {\n    if (ws.readyState !== ws.CLOSED && ws.readyState !== ws.CLOSING) {\n      if (err) {\n        closeWithError(lc, ws, err);\n      } else {\n        lc.info?.(`closing connection to ${endpoint}`);\n        ws.close();\n      }\n    }\n  }\n\n  const instream = Subscription.create<In>({\n    ...inOptions,\n    cleanup: (unconsumed, err) => {\n      inOptions.cleanup?.(unconsumed, err);\n      close(err);\n    },\n  });\n  const outstream = Subscription.create<Out>({\n    ...outOptions,\n    cleanup: (unconsumed, err) => {\n      outOptions.cleanup?.(unconsumed, err);\n      close(err);\n    },\n  });\n\n  const duplex = createWebSocketStream(ws, {\n    ...streamOptions,\n    decodeStrings: false,\n  });\n\n  // Outgoing transform.\n  function streamOut() {\n    // Mainly used for verifying that back-pressure kicks in tests.\n    duplex.on('drain', () => lc.debug?.(`drained messages to ${endpoint}`));\n\n    pipeline(\n      Readable.from(outstream),\n      new Transform({\n        objectMode: true,\n        transform: (msg, _encoding, callback) =>\n          callback(null, BigIntJSON.stringify(msg)),\n      }),\n      duplex,\n      err => (err ? outstream.fail(err) : outstream.cancel()),\n    );\n  }\n\n  if (ws.readyState === ws.CONNECTING) {\n    ws.on('open', () => {\n      lc.info?.(`connected to ${endpoint}`);\n      streamOut();\n    });\n  } else {\n    streamOut();\n  }\n\n  // Incoming transform.\n  pipe({\n    source: duplex,\n    sink: instream,\n    parse: chunk => {\n      const json = BigIntJSON.parse(chunk.toString());\n      return v.parse(json, inSchema, 'passthrough');\n    },\n  });\n\n  sendPingsForLiveness(lc, ws, PING_INTERVAL_MS);\n\n  return {outstream, instream};\n}\n\ntype PipeOptions<T> = {\n  source: Readable;\n  sink: Subscription<T>;\n  parse: (buffer: Buffer) => T | null;\n  bufferMessages?: number;\n};\n\nexport function pipe<T>({source, sink, parse, bufferMessages}: PipeOptions<T>) {\n  bufferMessages ??= 0;\n  assert(bufferMessages >= 0, 'bufferMessages must be non-negative');\n  const pending: Promise<unknown>[] = [];\n\n  pipeline(\n    source,\n    new Writable({\n      decodeStrings: false,\n      write: (chunk, _encoding, callback) => {\n        let msg: T | null;\n        try {\n          if ((msg = parse(chunk)) === null) {\n            callback();\n            return;\n          }\n        } catch (err) {\n          callback(ensureError(err));\n          return;\n        }\n        // Inbound backpressure is exerted by unconsumed messages in the\n        // subscription. A buffer can be used to allow messages to queue up in\n        // in the Subscription object, which allows the consumer to \"peek\" at\n        // whether there are more messages immediately available\n        // (via {@link Subscription.queued}.\n        const {result} = sink.push(msg);\n        pending.push(result);\n        void result.then(() => pending.shift());\n\n        if (pending.length <= bufferMessages) {\n          // immediately allow more messages\n          callback();\n        } else {\n          // wait for the oldest result in the pending queue\n          pending[0].then(\n            () => callback(),\n            err => callback(ensureError(err)),\n          );\n        }\n      },\n      destroy: (err, callback) => {\n        if (err) {\n          sink.fail(ensureError(err));\n        }\n        // Otherwise, final will handle the cancel.\n        callback();\n      },\n      final: callback => {\n        sink.cancel();\n        callback();\n      },\n    }),\n    err => (err ? sink.fail(err) : sink.cancel()),\n  );\n}\n\nfunction ensureError(err: unknown) {\n  return err instanceof Error ? err : new Error(String(err));\n}\n\nconst ackSchema = v.object({ack: v.number()});\n\ntype Ack = v.Infer<typeof ackSchema>;\n\ntype Streamed<T> = {\n  /** Application-level message. */\n  msg: T;\n\n  /** ID used for the Ack message. */\n  id: number;\n};\n\nexport async function streamOut<T extends JSONValue>(\n  lc: LogContext,\n  source: Source<T>,\n  sink: WebSocket,\n): Promise<void> {\n  sendPingsForLiveness(lc, sink, PING_INTERVAL_MS);\n\n  const closer = WebSocketCloser.forSource(lc, sink, source);\n\n  const acks = new Queue<Ack>();\n  sink.addEventListener('message', ({data}) => {\n    try {\n      if (typeof data !== 'string') {\n        throw new Error('Expected string message');\n      }\n      acks.enqueue(v.parse(JSON.parse(data), ackSchema));\n    } catch (e) {\n      lc.error?.(`error parsing ack`, e);\n      closer.close(e);\n    }\n  });\n\n  try {\n    let nextID = 0;\n    const {pipeline} = source;\n    if (pipeline) {\n      lc.debug?.(`started pipelined outbound stream`);\n      for await (const {value: msg, consumed} of pipeline) {\n        const id = ++nextID;\n        const data = BigIntJSON.stringify({msg, id} satisfies Streamed<T>);\n        // Enable for debugging. Otherwise too verbose.\n        // lc.debug?.(`pipelining`, data);\n        sink.send(data);\n\n        void (async () => {\n          const {ack} = await acks.dequeue();\n          // lc.debug?.(`received ack`, ack);\n          if (ack !== id) {\n            throw new Error(`Unexpected ack for ${id}: ${ack}`);\n          }\n          consumed();\n        })();\n      }\n    } else {\n      lc.debug?.(`started synchronous outbound stream`);\n      for await (const msg of source) {\n        const id = ++nextID;\n        const data = BigIntJSON.stringify({msg, id} satisfies Streamed<T>);\n        // Enable for debugging. Otherwise too verbose.\n        // lc.debug?.(`sending`, data);\n        sink.send(data);\n\n        const {ack} = await acks.dequeue();\n        if (ack !== id) {\n          throw new Error(`Unexpected ack for ${id}: ${ack}`);\n        }\n      }\n    }\n    closer.close();\n  } catch (e) {\n    closer.close(e);\n  }\n}\n\nexport async function streamIn<T extends JSONValue>(\n  lc: LogContext,\n  source: WebSocket,\n  schema: v.Type<T>,\n): Promise<Source<T>> {\n  expectPingsForLiveness(lc, source, PING_INTERVAL_MS);\n\n  const streamedSchema = v.object({\n    msg: schema,\n    id: v.number(),\n  });\n\n  const sink: Subscription<T, Streamed<T>> = new Subscription<T, Streamed<T>>(\n    {\n      consumed: ({id}) => source.send(JSON.stringify({ack: id} satisfies Ack)),\n      cleanup: () => closer.close(),\n    },\n    ({msg}) => msg,\n  );\n\n  const closer = WebSocketCloser.forSink(lc, source, sink, handleMessage);\n\n  function handleMessage(event: MessageEvent) {\n    const data = event.data.toString();\n    if (!sink.active) {\n      lc.warn?.('dropping ws message received after close', data);\n      return;\n    }\n    try {\n      const value = BigIntJSON.parse(data);\n      const msg = v.parse(value, streamedSchema, 'passthrough');\n      // Enable for debugging. Otherwise too verbose.\n      // lc.debug?.(`received`, data);\n      sink.push(msg);\n    } catch (e) {\n      closer.close(e);\n    }\n  }\n\n  await closer.connected;\n  return sink;\n}\n\nclass WebSocketCloser {\n  readonly #lc: LogContext;\n  readonly #ws: WebSocket;\n  readonly #closeStream: () => void;\n  readonly #messageHandler: ((e: MessageEvent) => void | undefined) | null;\n  readonly #connected = resolver();\n\n  get connected(): Promise<void> {\n    return this.#connected.promise;\n  }\n\n  static forSource<T>(lc: LogContext, ws: WebSocket, stream: Source<T>) {\n    // If the websocket is closed, call cancel() to notify the Source of\n    // any unconsumed messages.\n    return new WebSocketCloser(lc, ws, () => stream.cancel());\n  }\n\n  static forSink<T>(\n    lc: LogContext,\n    ws: WebSocket,\n    stream: Subscription<T, Streamed<T>>,\n    messageHandler: (e: MessageEvent) => void | undefined,\n  ) {\n    // If the websocket is closed, call end() to allow the downstream Sink\n    // to process any pending messages before closing the stream.\n    return new WebSocketCloser(lc, ws, () => stream.end(), messageHandler);\n  }\n\n  private constructor(\n    lc: LogContext,\n    ws: WebSocket,\n    closeStream: () => void,\n    messageHandler?: (e: MessageEvent) => void | undefined,\n  ) {\n    this.#lc = lc;\n    this.#ws = ws;\n    this.#closeStream = closeStream;\n    this.#messageHandler = messageHandler ?? null;\n\n    ws.addEventListener('open', this.#handleOpen);\n    ws.addEventListener('close', this.#handleClose);\n    ws.addEventListener('error', this.#handleError);\n    if (this.#messageHandler) {\n      ws.addEventListener('message', this.#messageHandler);\n    }\n\n    switch (ws.readyState) {\n      case ws.CONNECTING:\n        break; // expected for new connections. resolve or reject in handlers.\n      case ws.OPEN:\n        this.#connected.resolve();\n        break;\n      default:\n        this.#connected.reject(\n          new Error(`websocket already in state ${ws.readyState}`),\n        );\n        break;\n    }\n  }\n\n  get #conn(): string {\n    return 'connection' + (this.#ws.url ? ` to ${this.#ws.url}` : '');\n  }\n\n  #handleOpen = () => {\n    this.#lc.info?.(`${this.#conn} established`);\n    this.#connected.resolve();\n  };\n\n  #handleClose = (e: CloseEvent) => {\n    const {code, reason, wasClean} = e;\n    this.#lc.info?.(`${this.#conn} closed`, {\n      code,\n      reason,\n      wasClean,\n    });\n    this.close();\n    this.#connected.reject(`${this.#conn} closed with code ${code}`);\n  };\n\n  #handleError = ({message, error}: ErrorEvent) => {\n    if (this.#ws.readyState === this.#ws.OPEN) {\n      this.#lc.error?.(`error in ${this.#conn}`, message, error);\n    }\n    this.#connected.reject(error);\n  };\n\n  close(err?: unknown) {\n    if (err) {\n      this.#lc.error?.(`closing stream with error`, err);\n    }\n    this.#closeStream();\n    if (!this.closed()) {\n      this.#ws.close();\n    }\n  }\n\n  closed() {\n    return (\n      this.#ws.readyState === this.#ws.CLOSED ||\n      this.#ws.readyState === this.#ws.CLOSING\n    );\n  }\n}\n"],"mappings":"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"}

package/out/zero-cache/src/types/strings.js

@@ -1,15 +1,12 @@
+//#region ../zero-cache/src/types/strings.ts
 function elide(val, maxBytes) {
-  const encoder = new TextEncoder();
-  if (encoder.encode(val).length <= maxBytes) {
-    return val;
-  }
-  val = val.substring(0, maxBytes - 3);
-  while (encoder.encode(val + "...").length > maxBytes) {
-    val = val.substring(0, val.length - 1);
-  }
-  return val + "...";
+	const encoder = new TextEncoder();
+	if (encoder.encode(val).length <= maxBytes) return val;
+	val = val.substring(0, maxBytes - 3);
+	while (encoder.encode(val + "...").length > maxBytes) val = val.substring(0, val.length - 1);
+	return val + "...";
 }
-export {
-  elide
-};
-//# sourceMappingURL=strings.js.map
+//#endregion
+export { elide };
+
+//# sourceMappingURL=strings.js.map

package/out/zero-cache/src/types/strings.js.map

@@ -1 +1 @@
-{"version":3,"file":"strings.js","sources":["../../../../../zero-cache/src/types/strings.ts"],"sourcesContent":["export function elide(val: string, maxBytes: number) {\n  const encoder = new TextEncoder();\n  if (encoder.encode(val).length <= maxBytes) {\n    return val;\n  }\n  val = val.substring(0, maxBytes - 3);\n  while (encoder.encode(val + '...').length > maxBytes) {\n    val = val.substring(0, val.length - 1);\n  }\n  return val + '...';\n}\n"],"names":[],"mappings":"AAAO,SAAS,MAAM,KAAa,UAAkB;AACnD,QAAM,UAAU,IAAI,YAAA;AACpB,MAAI,QAAQ,OAAO,GAAG,EAAE,UAAU,UAAU;AAC1C,WAAO;AAAA,EACT;AACA,QAAM,IAAI,UAAU,GAAG,WAAW,CAAC;AACnC,SAAO,QAAQ,OAAO,MAAM,KAAK,EAAE,SAAS,UAAU;AACpD,UAAM,IAAI,UAAU,GAAG,IAAI,SAAS,CAAC;AAAA,EACvC;AACA,SAAO,MAAM;AACf;"}
+{"version":3,"file":"strings.js","names":[],"sources":["../../../../../zero-cache/src/types/strings.ts"],"sourcesContent":["export function elide(val: string, maxBytes: number) {\n  const encoder = new TextEncoder();\n  if (encoder.encode(val).length <= maxBytes) {\n    return val;\n  }\n  val = val.substring(0, maxBytes - 3);\n  while (encoder.encode(val + '...').length > maxBytes) {\n    val = val.substring(0, val.length - 1);\n  }\n  return val + '...';\n}\n"],"mappings":";AAAA,SAAgB,MAAM,KAAa,UAAkB;CACnD,MAAM,UAAU,IAAI,aAAa;AACjC,KAAI,QAAQ,OAAO,IAAI,CAAC,UAAU,SAChC,QAAO;AAET,OAAM,IAAI,UAAU,GAAG,WAAW,EAAE;AACpC,QAAO,QAAQ,OAAO,MAAM,MAAM,CAAC,SAAS,SAC1C,OAAM,IAAI,UAAU,GAAG,IAAI,SAAS,EAAE;AAExC,QAAO,MAAM"}

package/out/zero-cache/src/types/subscription.js

@@ -1,228 +1,268 @@
-import { resolver } from "@rocicorp/resolver";
 import { assert } from "../../../shared/src/asserts.js";
-class Subscription {
-  /**
-   * Convenience factory method for creating a {@link Subscription} with internal message type
-   * `M` as a subtype of `T`, defaulting to the same type. The default `publish` method publishes
-   * the message of type `M` directly to the AsyncIterable.
-   */
-  static create(options = {}, publish = (m) => m) {
-    return new Subscription(options, publish);
-  }
-  // Consumers waiting to consume messages (i.e. an async iteration awaiting the next message).
-  #consumers = [];
-  // Messages waiting to be dequeued.
-  #messages = [];
-  // Messages dequeued but not yet consumed.
-  #consuming = /* @__PURE__ */ new Set();
-  #pipelineEnabled;
-  // Sentinel value signaling that the subscription is "done" and no more
-  // messages can be added.
-  #sentinel = void 0;
-  #coalesce;
-  #consumed;
-  #cleanup;
-  #publish;
-  /**
-   * @param publish function for converting the internally pushed / coalesced message
-   *        of type `M` to the external type `T` exposed via async iteration.
-   */
-  constructor(options = {}, publish) {
-    const {
-      coalesce,
-      consumed = () => {
-      },
-      cleanup = () => {
-      },
-      pipeline = coalesce === void 0
-    } = options;
-    this.#coalesce = !coalesce ? void 0 : (curr, prev) => {
-      try {
-        return coalesce(curr.value, prev.value);
-      } finally {
-        prev.resolve("coalesced");
-      }
-    };
-    this.#consumed = (entry) => {
-      consumed(entry.value);
-      this.#consuming.delete(entry);
-      entry.resolve("consumed");
-    };
-    this.#cleanup = (entries, err) => {
-      cleanup(
-        entries.map((e) => e.value),
-        err
-      );
-      entries.forEach((e) => e.resolve("unconsumed"));
-    };
-    this.#publish = publish;
-    this.#pipelineEnabled = pipeline;
-  }
-  /**
-   * Pushes the next message to be consumed, and returns a `result` that resolves to the
-   * eventual {@link Result} of the `value`.
-   *
-   * If there is an existing unconsumed message and the Subscription has a
-   * {@link Options#coalesce coalesce} function, the specified `value` will be coalesced
-   * with the pending message. In this case, the result of the pending message
-   * is resolved to `coalesced`, regardless of the `coalesce` function implementation.
-   *
-   * If the subscription is in a terminal state, the message is dropped and the
-   * result resolves to `unconsumed`.
-   */
-  push(value) {
-    const { promise: result, resolve } = resolver();
-    const entry = { value, resolve };
-    if (this.#sentinel) {
-      entry.resolve("unconsumed");
-      return { result };
-    }
-    const consumer = this.#consumers.shift();
-    if (consumer) {
-      consumer.resolve(entry);
-    } else if (this.#coalesce && this.#messages.length && this.#messages[this.#messages.length - 1] !== "terminus") {
-      const prev = this.#messages[this.#messages.length - 1];
-      assert(prev !== "terminus", "prev should not be terminus after check");
-      this.#messages[this.#messages.length - 1] = {
-        value: this.#coalesce(entry, prev),
-        resolve
-      };
-    } else {
-      this.#messages.push(entry);
-    }
-    return { result };
-  }
-  /** False if the subscription has been canceled or has failed. */
-  get active() {
-    return this.#sentinel === void 0;
-  }
-  /** The number of messages waiting to be dequeued. */
-  get queued() {
-    return this.#messages.length;
-  }
-  /** The number of messages dequeued but not yet "consumed" */
-  get consuming() {
-    return this.#consuming.size;
-  }
-  /**
-   * Cancels the subscription after any queued messages are consumed. This is
-   * meant for the producer-side code.
-   *
-   * Any messages pushed after calling `end()` will be unconsumed as if
-   * `cancel()` were called (once the first set of pending messages is
-   * consumed). In particular, if a coalesce function is defined, the new
-   * messages will not be coalesced with the messages enqueued before `end()`
-   * was called. However, to effect the intent of memory efficiency, multiple
-   * messages pushed after calling `end()` will be coalesced together.
-   *
-   */
-  end() {
-    if (this.#sentinel) ;
-    else if (this.#messages.length === 0) {
-      this.cancel();
-    } else {
-      this.#messages.push("terminus");
-    }
-  }
-  /**
-   * Cancels the subscription immediately, cleans up, and terminates any iteration.
-   * This is intended for the consumer to call when it is no longer interested
-   * in the subscription.
-   *
-   * @param err If an `err` is specified, an iteration over the Subscription /
-   *        Sink will throw the `err` (equivalent to the producer calling
-   *        {@link fail()}). If undefined, the iteration will exit gracefully.
-   */
-  cancel(err) {
-    this.#terminate(err ?? "canceled");
-  }
-  /** Fails the subscription, cleans up, and throws from any iteration. */
-  fail(err) {
-    this.#terminate(err);
-  }
-  #terminate(sentinel) {
-    if (!this.#sentinel) {
-      this.#sentinel = sentinel;
-      this.#cleanup(
-        [...this.#consuming, ...this.#messages.filter((m) => m !== "terminus")],
-        sentinel instanceof Error ? sentinel : void 0
-      );
-      this.#messages.splice(0);
-      for (let consumer = this.#consumers.shift(); consumer; consumer = this.#consumers.shift()) {
-        sentinel === "canceled" ? consumer.resolve(null) : consumer.reject(sentinel);
-      }
-    }
-  }
-  get pipeline() {
-    return this.#pipelineEnabled ? { [Symbol.asyncIterator]: () => this.#pipeline() } : void 0;
-  }
-  #pipeline() {
-    return {
-      next: async () => {
-        const entry = this.#messages.shift();
-        if (entry === "terminus") {
-          this.cancel();
-          return { value: void 0, done: true };
-        }
-        if (entry !== void 0) {
-          this.#consuming.add(entry);
-          return {
-            value: {
-              value: this.#publish(entry.value),
-              consumed: () => this.#consumed(entry)
-            }
-          };
-        }
-        if (this.#sentinel === "canceled") {
-          return { value: void 0, done: true };
-        }
-        if (this.#sentinel) {
-          return Promise.reject(this.#sentinel);
-        }
-        const consumer = resolver();
-        this.#consumers.push(consumer);
-        const result = await consumer.promise;
-        if (result !== null) {
-          this.#consuming.add(result);
-          return {
-            value: {
-              value: this.#publish(result.value),
-              consumed: () => this.#consumed(result)
-            }
-          };
-        }
-        return { value: void 0, done: true };
-      },
-      return: (value) => {
-        this.cancel();
-        return Promise.resolve({ value, done: true });
-      }
-    };
-  }
-  [Symbol.asyncIterator]() {
-    const delegate = this.#pipeline();
-    let prevConsumed = () => {
-    };
-    return {
-      next: async () => {
-        prevConsumed();
-        const entry = await delegate.next();
-        if (entry.done) {
-          return entry;
-        }
-        const { value, consumed } = entry.value;
-        prevConsumed = consumed;
-        return { value };
-      },
-      return: (value) => {
-        prevConsumed();
-        this.cancel();
-        return Promise.resolve({ value, done: true });
-      }
-    };
-  }
-}
-export {
-  Subscription
+import { resolver } from "@rocicorp/resolver";
+//#region ../zero-cache/src/types/subscription.ts
+/**
+* A Subscription abstracts a continuous, logically infinite stream of messages intended
+* for serial processing. Unlike the more general Node `Stream` API, a Subscription has
+* a limited API with specific semantics:
+*
+* * **Serial processing**: Messages must be consumed via the {@link AsyncIterable}
+*   interface, e.g.
+*   ```ts
+*   const subscription = server.subscribe(parameters);
+*
+*   for await (const message of subscription) {
+*     await process(message);  // fully process the message before consuming the next
+*   }
+*   ```
+*
+*   Moreover, the consumer is expected to completely process each message before
+*   requesting the next. This is important for cleanup semantics (explained later).
+*
+* * **cancel()**, not close(): The underlying data in a subscription is logically infinite
+*   and only terminated when the consumer is no longer interested in receiving the messages
+*   (or requires a Subscription with a different configuration). As such, there is no API
+*   for gracefully closing the subscription after pending messages are consumed; rather,
+*   cancellation is immediate, and upon cancellation, pending messages are dropped. A
+*   Subscription can also be terminated with exceptional (i.e. `Error`) circumstances,
+*   for which the behavior is equivalent.
+*
+* * **Coalescing** (optional): A producer can configure pending messages in the Subscription
+*   to be merged together with a {@link Options.coalesce coalesce} function. This is useful
+*   for semantics in which the consumer is not necessarily interested in every incremental
+*   change, but rather the cumulative change since the last processed message. A
+*   Subscription with coalescing is guaranteed to have at most one outstanding message,
+*   regardless of how quickly messages are produced and consumed. This effectively constrains
+*   the amount of outstanding work in the system.
+*
+* ### Resource Tracking and Cleanup
+*
+* Because message consumption is constrained to the async iteration API, standard
+* control flow mechanisms allow the producer to perform bookkeeping without any
+* explicit cleanup actions on the part of the consumer. This includes:
+*
+* * **Per-message cleanup**: Each request for the {@link AsyncIterator.next next}
+*   message, or the termination of the iteration, signals that the consumer has
+*   finished processing the previous message. The producer of a Subscription can
+*   supply a {@link Options.consumed consumed} callback to receive these processed
+*   messages, allowing it to clean up attached resources (e.g. TransactionPools, etc.).
+*
+* * **Per-subscription cleanup**: The producer of a Subscription can supply a
+*   {@link Options.cleanup cleanup} callback that is invoked when the Subscription
+*   is terminated, either explicitly via {@link Subscription.cancel cancel()} /
+*   {@link Subscription.fail fail()}, or implicitly when an iteration is exited via a
+*  `break`, `return`, or `throw` statement. All unconsumed messages are passed to the
+*   call back to facilitate bookkeeping.
+*
+* @param T The external message type, published to the AsyncIterable
+* @param M The internal message type used in the producer-side interfaces
+*          (e.g. {@link push}, {@link Options.consumed}, {@link Options.coalesce},
+*          and {@link Options.cleanup}). This is often the same as the external type
+*          T, but may be diverged to facilitate internal bookkeeping.
+*/
+var Subscription = class Subscription {
+	/**
+	* Convenience factory method for creating a {@link Subscription} with internal message type
+	* `M` as a subtype of `T`, defaulting to the same type. The default `publish` method publishes
+	* the message of type `M` directly to the AsyncIterable.
+	*/
+	static create(options = {}, publish = (m) => m) {
+		return new Subscription(options, publish);
+	}
+	#consumers = [];
+	#messages = [];
+	#consuming = /* @__PURE__ */ new Set();
+	#pipelineEnabled;
+	#sentinel = void 0;
+	#coalesce;
+	#consumed;
+	#cleanup;
+	#publish;
+	/**
+	* @param publish function for converting the internally pushed / coalesced message
+	*        of type `M` to the external type `T` exposed via async iteration.
+	*/
+	constructor(options = {}, publish) {
+		const { coalesce, consumed = () => {}, cleanup = () => {}, pipeline = coalesce === void 0 } = options;
+		this.#coalesce = !coalesce ? void 0 : (curr, prev) => {
+			try {
+				return coalesce(curr.value, prev.value);
+			} finally {
+				prev.resolve("coalesced");
+			}
+		};
+		this.#consumed = (entry) => {
+			consumed(entry.value);
+			this.#consuming.delete(entry);
+			entry.resolve("consumed");
+		};
+		this.#cleanup = (entries, err) => {
+			cleanup(entries.map((e) => e.value), err);
+			entries.forEach((e) => e.resolve("unconsumed"));
+		};
+		this.#publish = publish;
+		this.#pipelineEnabled = pipeline;
+	}
+	/**
+	* Pushes the next message to be consumed, and returns a `result` that resolves to the
+	* eventual {@link Result} of the `value`.
+	*
+	* If there is an existing unconsumed message and the Subscription has a
+	* {@link Options#coalesce coalesce} function, the specified `value` will be coalesced
+	* with the pending message. In this case, the result of the pending message
+	* is resolved to `coalesced`, regardless of the `coalesce` function implementation.
+	*
+	* If the subscription is in a terminal state, the message is dropped and the
+	* result resolves to `unconsumed`.
+	*/
+	push(value) {
+		const { promise: result, resolve } = resolver();
+		const entry = {
+			value,
+			resolve
+		};
+		if (this.#sentinel) {
+			entry.resolve("unconsumed");
+			return { result };
+		}
+		const consumer = this.#consumers.shift();
+		if (consumer) consumer.resolve(entry);
+		else if (this.#coalesce && this.#messages.length && this.#messages[this.#messages.length - 1] !== "terminus") {
+			const prev = this.#messages[this.#messages.length - 1];
+			assert(prev !== "terminus", "prev should not be terminus after check");
+			this.#messages[this.#messages.length - 1] = {
+				value: this.#coalesce(entry, prev),
+				resolve
+			};
+		} else this.#messages.push(entry);
+		return { result };
+	}
+	/** False if the subscription has been canceled or has failed. */
+	get active() {
+		return this.#sentinel === void 0;
+	}
+	/** The number of messages waiting to be dequeued. */
+	get queued() {
+		return this.#messages.length;
+	}
+	/** The number of messages dequeued but not yet "consumed" */
+	get consuming() {
+		return this.#consuming.size;
+	}
+	/**
+	* Cancels the subscription after any queued messages are consumed. This is
+	* meant for the producer-side code.
+	*
+	* Any messages pushed after calling `end()` will be unconsumed as if
+	* `cancel()` were called (once the first set of pending messages is
+	* consumed). In particular, if a coalesce function is defined, the new
+	* messages will not be coalesced with the messages enqueued before `end()`
+	* was called. However, to effect the intent of memory efficiency, multiple
+	* messages pushed after calling `end()` will be coalesced together.
+	*
+	*/
+	end() {
+		if (this.#sentinel) {} else if (this.#messages.length === 0) this.cancel();
+		else this.#messages.push("terminus");
+	}
+	/**
+	* Cancels the subscription immediately, cleans up, and terminates any iteration.
+	* This is intended for the consumer to call when it is no longer interested
+	* in the subscription.
+	*
+	* @param err If an `err` is specified, an iteration over the Subscription /
+	*        Sink will throw the `err` (equivalent to the producer calling
+	*        {@link fail()}). If undefined, the iteration will exit gracefully.
+	*/
+	cancel(err) {
+		this.#terminate(err ?? "canceled");
+	}
+	/** Fails the subscription, cleans up, and throws from any iteration. */
+	fail(err) {
+		this.#terminate(err);
+	}
+	#terminate(sentinel) {
+		if (!this.#sentinel) {
+			this.#sentinel = sentinel;
+			this.#cleanup([...this.#consuming, ...this.#messages.filter((m) => m !== "terminus")], sentinel instanceof Error ? sentinel : void 0);
+			this.#messages.splice(0);
+			for (let consumer = this.#consumers.shift(); consumer; consumer = this.#consumers.shift()) sentinel === "canceled" ? consumer.resolve(null) : consumer.reject(sentinel);
+		}
+	}
+	get pipeline() {
+		return this.#pipelineEnabled ? { [Symbol.asyncIterator]: () => this.#pipeline() } : void 0;
+	}
+	#pipeline() {
+		return {
+			next: async () => {
+				const entry = this.#messages.shift();
+				if (entry === "terminus") {
+					this.cancel();
+					return {
+						value: void 0,
+						done: true
+					};
+				}
+				if (entry !== void 0) {
+					this.#consuming.add(entry);
+					return { value: {
+						value: this.#publish(entry.value),
+						consumed: () => this.#consumed(entry)
+					} };
+				}
+				if (this.#sentinel === "canceled") return {
+					value: void 0,
+					done: true
+				};
+				if (this.#sentinel) return Promise.reject(this.#sentinel);
+				const consumer = resolver();
+				this.#consumers.push(consumer);
+				const result = await consumer.promise;
+				if (result !== null) {
+					this.#consuming.add(result);
+					return { value: {
+						value: this.#publish(result.value),
+						consumed: () => this.#consumed(result)
+					} };
+				}
+				return {
+					value: void 0,
+					done: true
+				};
+			},
+			return: (value) => {
+				this.cancel();
+				return Promise.resolve({
+					value,
+					done: true
+				});
+			}
+		};
+	}
+	[Symbol.asyncIterator]() {
+		const delegate = this.#pipeline();
+		let prevConsumed = () => {};
+		return {
+			next: async () => {
+				prevConsumed();
+				const entry = await delegate.next();
+				if (entry.done) return entry;
+				const { value, consumed } = entry.value;
+				prevConsumed = consumed;
+				return { value };
+			},
+			return: (value) => {
+				prevConsumed();
+				this.cancel();
+				return Promise.resolve({
+					value,
+					done: true
+				});
+			}
+		};
+	}
 };
-//# sourceMappingURL=subscription.js.map
+//#endregion
+export { Subscription };
+
+//# sourceMappingURL=subscription.js.map