@tokamakdev/plugin 0.1.0-beta.107 → 0.1.0-beta.112

package/src/rpc/channel.mjs

@@ -0,0 +1,219 @@
+import { encode, decode, dataCloneError } from './values.mjs';
+import { takeStream, receiveStream } from './streams.mjs';
+import { packFrame, unpackFrame } from './frames.mjs';
+
+function deferred() {
+  let resolve, reject;
+  const promise = new Promise((yes, no) => { resolve = yes; reject = no; });
+  promise.catch(() => {});
+  return { promise, resolve, reject };
+}
+
+function cancelSource(source, reason) {
+  source.cancelled = true;
+  source.cleanup ??= Promise.resolve().then(() => source.port.cancel(reason));
+  return source.cleanup;
+}
+
+/** One invocation's values and demand-driven byte streams over a WebSocket. */
+export function openChannel(socket) {
+  const ready = deferred(), received = deferred(), closed = deferred();
+  const outgoing = new Map(), incoming = new Map();
+  const pending = new Set();
+  let nextStream = 0, sent = false, delivered = false, completed = false, ended = false, failure;
+  socket.binaryType = 'arraybuffer';
+
+  function close(reason = new DOMException('RPC connection closed.', 'AbortError')) {
+    if (ended) return;
+    ended = true;
+    failure = reason;
+    ready.reject(reason);
+    received.reject(reason);
+    for (const port of incoming.values()) {
+      port.reading?.reject(reason);
+      port.cancelling?.reject(reason);
+    }
+    const cleanup = [...outgoing.values()].map(source => cancelSource(source, reason));
+    incoming.clear();
+    outgoing.clear();
+    socket.removeEventListener('open', onOpen);
+    socket.removeEventListener('message', onMessage);
+    socket.removeEventListener('close', onClose);
+    socket.removeEventListener('error', onClose);
+    try { socket.close(1000); } catch { /* The transport can already be closed. */ }
+    Promise.allSettled(cleanup).then(() => closed.resolve(reason));
+  }
+
+  function finish() {
+    if (completed && outgoing.size === 0 && pending.size === 0) close();
+  }
+
+  function prepare(type, id, value) {
+    if (ended) throw failure;
+    const encoded = encode(value);
+    const ids = encoded.streams.map(() => nextStream++);
+    const frame = packFrame({ type, id, data: encoded.data, streams: ids }, encoded.buffers);
+    const acquired = [];
+    try {
+      for (const stream of encoded.streams) acquired.push({ port: takeStream(stream), reading: false, cancelled: false });
+    } catch (error) {
+      for (const source of acquired) cancelSource(source, error).catch(() => {});
+      throw error;
+    }
+    ids.forEach((stream, index) => outgoing.set(stream, acquired[index]));
+    return frame;
+  }
+
+  async function transmit(frame) {
+    await ready.promise;
+    if (ended) throw failure;
+    try { await socket.send(frame); }
+    catch (error) { close(error); throw error; }
+  }
+
+  function write(type, id, value) {
+    return transmit(prepare(type, id, value));
+  }
+
+  function reply(type, id, failed, value) {
+    try { return write(type, id, { failed, value }); }
+    catch { return write(type, id, { failed: true, value: dataCloneError() }); }
+  }
+
+  function remoteStream(id) {
+    if (!Number.isSafeInteger(id) || id < 0 || incoming.has(id)) throw dataCloneError();
+    const port = { reading: null, cancelling: null, done: false };
+    incoming.set(id, port);
+    return receiveStream({
+      read() {
+        if (ended) return Promise.reject(failure);
+        if (port.done || port.cancelling) return Promise.resolve({ done: true });
+        if (port.reading) throw dataCloneError();
+        port.reading = deferred();
+        write('pull', id).catch(close);
+        return port.reading.promise;
+      },
+      cancel(reason) {
+        if (ended) return Promise.reject(failure);
+        if (port.done) return Promise.resolve();
+        if (port.cancelling) return port.cancelling.promise;
+        port.cancelling = deferred();
+        port.reading?.resolve({ done: true });
+        port.reading = null;
+        try { write('cancel', id, reason).catch(close); }
+        catch (error) { close(error); }
+        return port.cancelling.promise;
+      },
+    });
+  }
+
+  async function pull(id) {
+    const source = outgoing.get(id);
+    if (!source || source.reading || source.cancelled || source.done) throw dataCloneError();
+    source.reading = true;
+    let value, failed = false;
+    try { value = await source.port.read(); }
+    catch (error) { value = error; failed = true; }
+    if (source.cancelled || ended) return;
+    source.reading = false;
+    source.done = failed || value.done;
+    await reply('read', id, failed, value);
+  }
+
+  async function cancel(id, reason) {
+    const source = outgoing.get(id);
+    if (source?.done) {
+      source.cancelled = true;
+      await write('cancelled', id, { terminal: true });
+      outgoing.delete(id);
+      finish();
+      return;
+    }
+    let value, failed = false;
+    try { if (source) await cancelSource(source, reason); }
+    catch (error) { value = error; failed = true; }
+    if (ended) return;
+    await reply('cancelled', id, failed, value);
+    outgoing.delete(id);
+    finish();
+  }
+
+  function release(id) {
+    const source = outgoing.get(id);
+    if (!source?.done || source.cancelled) throw dataCloneError();
+    outgoing.delete(id);
+    finish();
+  }
+
+  function settle(type, id, result) {
+    const port = incoming.get(id);
+    if (!port) throw dataCloneError();
+    if (type === 'cancelled' && result?.terminal === true) {
+      if (!port.terminal) throw dataCloneError();
+      result = port.terminal.failed ? port.terminal : { failed: false, value: undefined };
+    }
+    if (typeof result?.failed !== 'boolean') throw dataCloneError();
+    if (type === 'read' && port.cancelling) {
+      if (result.failed || result.value.done) port.terminal = result;
+      return;
+    }
+    const waiting = type === 'read' ? port.reading : port.cancelling;
+    if (!waiting) throw dataCloneError();
+    if (result.failed) waiting.reject(result.value);
+    else waiting.resolve(result.value);
+    port.reading = null;
+    if (type === 'cancelled' || result.failed || result.value.done) {
+      port.done = true;
+      const acknowledgement = type === 'read' ? write('release', id) : Promise.resolve();
+      acknowledgement.then(() => { incoming.delete(id); finish(); }).catch(close);
+    }
+  }
+
+  function onMessage(event) {
+    try {
+      const frame = unpackFrame(event.data);
+      const streams = frame.streams.map(remoteStream);
+      const value = decode({ ...frame, streams });
+      switch (frame.type) {
+        case 'value':
+          if (delivered) throw dataCloneError();
+          delivered = true;
+          received.resolve(value);
+          break;
+        case 'pull': pull(frame.id).catch(close); break;
+        case 'cancel': cancel(frame.id, value).catch(close); break;
+        case 'release': release(frame.id); break;
+        case 'read': case 'cancelled': settle(frame.type, frame.id, value); break;
+        default: throw dataCloneError();
+      }
+    } catch (error) { close(error); }
+  }
+
+  function onOpen() { ready.resolve(); }
+  function onClose(event) { close(event.error); }
+  socket.addEventListener('open', onOpen);
+  socket.addEventListener('message', onMessage);
+  socket.addEventListener('close', onClose);
+  socket.addEventListener('error', onClose);
+  if (socket.readyState === 1) onOpen();
+  if (socket.readyState > 1) close();
+  return {
+    receive: received.promise,
+    closed: closed.promise,
+    close,
+    waitUntil(promise) {
+      const task = Promise.resolve(promise);
+      pending.add(task);
+      const settled = () => { pending.delete(task); finish(); };
+      task.then(settled, settled);
+    },
+    // The callee ends unused input streams after its work and result streams settle.
+    complete() { completed = true; finish(); },
+    async send(value) {
+      if (sent || completed) throw new TypeError('This RPC invocation has already sent its value.');
+      const frame = prepare('value', undefined, value);
+      sent = true;
+      await transmit(frame);
+    },
+  };
+}

package/src/rpc/client.mjs

@@ -0,0 +1,29 @@
+import { openChannel } from './channel.mjs';
+import { dataCloneError } from './values.mjs';
+
+/** Invoke one operation over a socket owned by the caller. */
+export async function invoke(socket, method, args) {
+  const channel = openChannel(socket);
+  let result;
+  try {
+    await channel.send({ method, args });
+    result = await channel.receive;
+    if (typeof result?.failed !== 'boolean') throw dataCloneError();
+  } catch (error) {
+    channel.close(error);
+    throw error;
+  }
+  if (result.failed) throw result.value;
+  return result.value;
+}
+
+/** Generate only the declared public operations, with their `capabilities`; each call owns its connection. */
+export function createClient(methods, endpoint, capabilities) {
+  const client = Object.fromEntries(methods.map(method => [method, async (...args) => {
+    const url = new URL(endpoint, globalThis.location?.href);
+    if (url.protocol === 'http:') url.protocol = 'ws:';
+    if (url.protocol === 'https:') url.protocol = 'wss:';
+    return invoke(new WebSocket(url), method, args);
+  }]));
+  return Object.assign(client, { capabilities: Object.freeze({ ...capabilities }) });
+}

package/src/rpc/endpoint.mjs

@@ -0,0 +1,47 @@
+import { openChannel } from './channel.mjs';
+import { dataCloneError } from './values.mjs';
+
+/** Upgrade a same-origin frontend request into one RPC invocation. */
+export function rpcResponse(request, createWorker, methods, ctx) {
+  if (request.method !== 'GET') return new Response('Method not allowed', { status: 405 });
+  const origin = request.headers.get('origin');
+  if (origin && origin !== new URL(request.url).origin) return new Response('Forbidden', { status: 403 });
+  if (request.headers.get('upgrade')?.toLowerCase() !== 'websocket') {
+    return new Response('WebSocket required', { status: 426 });
+  }
+  const [client, server] = Object.values(new WebSocketPair());
+  server.accept();
+  ctx.waitUntil(serveRpc(server, createWorker, methods, ctx));
+  return new Response(null, { status: 101, webSocket: client });
+}
+
+/** Serve one invocation, retaining it until the connection's streams settle. */
+export function serveRpc(socket, createWorker, methods, ctx) {
+  const channel = openChannel(socket);
+  const waitUntil = promise => {
+    ctx.waitUntil(promise);
+    channel.waitUntil(promise);
+  };
+  const context = new Proxy(ctx, {
+    get(target, key) {
+      if (key === 'waitUntil') return waitUntil;
+      const value = Reflect.get(target, key, target);
+      return typeof value === 'function' ? value.bind(target) : value;
+    },
+  });
+  async function handle() {
+    try {
+      const request = await channel.receive;
+      if (!request || typeof request.method !== 'string' || !Array.isArray(request.args)) throw dataCloneError();
+      if (!methods.includes(request.method)) throw new TypeError(`Unknown RPC method: ${request.method}`);
+      const worker = createWorker(context);
+      const value = await worker[request.method](...request.args);
+      await channel.send({ failed: false, value });
+    } catch (error) {
+      try { await channel.send({ failed: true, value: error }); }
+      catch { await channel.send({ failed: true, value: dataCloneError() }); }
+    } finally { channel.complete(); }
+  }
+  handle().catch(channel.close);
+  return channel.closed;
+}

package/src/rpc/frames.mjs

@@ -0,0 +1,35 @@
+import { dataCloneError } from './values.mjs';
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder('utf-8', { fatal: true });
+
+/** A length-prefixed metadata record followed by its binary buffers. */
+export function packFrame(metadata, buffers) {
+  const header = encoder.encode(JSON.stringify({ ...metadata, buffers: buffers.map(buffer => buffer.byteLength) }));
+  const frame = new Uint8Array(4 + header.byteLength + buffers.reduce((size, buffer) => size + buffer.byteLength, 0));
+  new DataView(frame.buffer).setUint32(0, header.byteLength);
+  frame.set(header, 4);
+  let offset = 4 + header.byteLength;
+  for (const buffer of buffers) {
+    frame.set(new Uint8Array(buffer), offset);
+    offset += buffer.byteLength;
+  }
+  return frame.buffer;
+}
+
+export function unpackFrame(frame) {
+  if (!(frame instanceof ArrayBuffer) || frame.byteLength < 4) throw dataCloneError();
+  const length = new DataView(frame).getUint32(0);
+  if (length > frame.byteLength - 4) throw dataCloneError();
+  const metadata = JSON.parse(decoder.decode(new Uint8Array(frame, 4, length)));
+  if (!Array.isArray(metadata.buffers) || !Array.isArray(metadata.streams)) throw dataCloneError();
+  let offset = 4 + length;
+  const buffers = metadata.buffers.map(size => {
+    if (!Number.isSafeInteger(size) || size < 0 || size > frame.byteLength - offset) throw dataCloneError();
+    const buffer = frame.slice(offset, offset + size);
+    offset += size;
+    return buffer;
+  });
+  if (offset !== frame.byteLength) throw dataCloneError();
+  return { ...metadata, buffers };
+}

package/src/rpc/http.mjs

@@ -0,0 +1,28 @@
+function headers(value) {
+  return [...value].filter(([name]) => name !== 'set-cookie')
+    .concat(value.getSetCookie().map(cookie => ['set-cookie', cookie]));
+}
+
+export function encodeRequest(request) {
+  return {
+    url: request.url, method: request.method, headers: headers(request.headers),
+    body: request.body, redirect: request.redirect, cf: request.cf,
+  };
+}
+
+export function decodeRequest(value) {
+  return new Request(value.url, { ...value, duplex: 'half' });
+}
+
+export function encodeResponse(response) {
+  if (!(response instanceof Response)) throw new TypeError('Service fetch must return a Response');
+  if (response.status === 101) throw new TypeError('Service binding WebSocket upgrades are not supported');
+  return {
+    status: response.status, statusText: response.statusText,
+    headers: headers(response.headers), body: response.body,
+  };
+}
+
+export function decodeResponse(value) {
+  return new Response(value.body, value);
+}

package/src/rpc/streams.mjs

@@ -0,0 +1,52 @@
+import { dataCloneError } from './values.mjs';
+
+const chunkSize = 64 * 1024;
+
+/** Lock a byte stream for the transport, reading only in response to receiver demand. */
+export function takeStream(stream) {
+  let reader, byob = true, remaining = new Uint8Array(0);
+  try { reader = stream.getReader({ mode: 'byob' }); }
+  catch { byob = false; reader = stream.getReader(); }
+  return {
+    async read() {
+      if (byob) return reader.read(new Uint8Array(chunkSize));
+      while (remaining.byteLength === 0) {
+        const next = await reader.read();
+        if (next.done) return next;
+        if (!(next.value instanceof Uint8Array) || (typeof SharedArrayBuffer !== 'undefined' && next.value.buffer instanceof SharedArrayBuffer)) {
+          const error = dataCloneError();
+          // Cleanup cannot delay or replace the invalid chunk's failure.
+          reader.cancel(error).catch(() => {});
+          throw error;
+        }
+        remaining = next.value;
+      }
+      const value = remaining.slice(0, chunkSize);
+      remaining = remaining.subarray(value.byteLength);
+      return { done: false, value };
+    },
+    cancel: reason => { remaining = new Uint8Array(0); return reader.cancel(reason); },
+  };
+}
+
+/** A byte stream backed by a transport port's read and cancel operations. */
+export function receiveStream(port) {
+  return new ReadableStream({
+    type: 'bytes',
+    async pull(controller) {
+      const { done, value } = await port.read();
+      if (done) {
+        controller.close();
+        controller.byobRequest?.respond(0);
+        return;
+      }
+      if (!(value instanceof Uint8Array) || value.byteLength === 0 || value.byteLength > chunkSize) {
+        const error = dataCloneError();
+        Promise.resolve().then(() => port.cancel(error)).catch(() => {});
+        throw error;
+      }
+      controller.enqueue(value);
+    },
+    cancel: reason => port.cancel(reason),
+  });
+}

package/src/rpc/values.mjs

@@ -0,0 +1,136 @@
+const arrays = [
+  Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array,
+  Int32Array, Uint32Array, Float32Array, Float64Array, BigInt64Array, BigUint64Array,
+];
+if (typeof Float16Array !== 'undefined') arrays.push(Float16Array);
+const views = new Map(arrays.map(Type => [Type.name, Type]));
+views.set('DataView', DataView);
+
+export function dataCloneError() {
+  return new DOMException('Value is outside the supported RPC contract.', 'DataCloneError');
+}
+
+function byteStream(value) {
+  if (value.locked) throw dataCloneError();
+  return value;
+}
+
+function properties(value, visit, keys = Object.keys(value)) {
+  return keys.map(key => [key, visit(value[key])]);
+}
+
+function errorProperties(value, visit) {
+  const keys = Object.getOwnPropertyNames(value).filter(key => !['name', 'message', 'stack'].includes(key));
+  return properties(value, visit, keys);
+}
+
+function encodeObject(value, visit, buffers, streams) {
+  if (Array.isArray(value)) return ['array', value.length, properties(value, visit)];
+  if (value instanceof Date) return ['date', visit(Date.prototype.getTime.call(value))];
+  if (value instanceof RegExp) return ['regexp', value.source, value.flags];
+  if (value instanceof Map) return ['map', [...value].map(([key, entry]) => [visit(key), visit(entry)])];
+  if (value instanceof Set) return ['set', [...value].map(visit)];
+  if (value instanceof DOMException) return ['exception', value.name, value.message, errorProperties(value, visit)];
+  if (value instanceof Error) return ['error', value.name, value.message, errorProperties(value, visit)];
+  if (value instanceof ReadableStream) return ['stream', streams.push(byteStream(value)) - 1];
+  if (value instanceof ArrayBuffer) {
+    if (value.detached) throw dataCloneError();
+    return ['buffer', buffers.push(value) - 1];
+  }
+  if (ArrayBuffer.isView(value)) {
+    const name = [...views].find(([, Type]) => Object.getPrototypeOf(value) === Type.prototype)?.[0];
+    if (!name) throw dataCloneError();
+    return ['view', name, visit(value.buffer), value.byteOffset, value.byteLength];
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== null && prototype !== Object.prototype) throw dataCloneError();
+  return ['record', properties(value, visit)];
+}
+
+/** Describe a value graph; the transport copies buffers and transfers streams after validation. */
+export function encode(value) {
+  const nodes = [], buffers = [], streams = [], seen = new Map();
+  function visit(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;
+    if (typeof value === 'undefined') return ['undefined'];
+    if (typeof value === 'bigint') return ['bigint', String(value)];
+    if (typeof value === 'number') {
+      return Number.isFinite(value) && !Object.is(value, -0) ? value : ['number', Object.is(value, -0) ? '-0' : String(value)];
+    }
+    if (typeof value !== 'object') throw dataCloneError();
+    if (seen.has(value)) return ['ref', seen.get(value)];
+    const index = nodes.length;
+    seen.set(value, index);
+    nodes.push(null);
+    nodes[index] = encodeObject(value, visit, buffers, streams);
+    return ['ref', index];
+  }
+  const root = visit(value);
+  return { data: JSON.stringify({ root, nodes }), buffers, streams };
+}
+
+function setProperties(value, entries, read) {
+  for (const [key, entry] of entries) {
+    Object.defineProperty(value, key, { value: read(entry), enumerable: true, configurable: true, writable: true });
+  }
+}
+
+function allocate(node, read, buffers, streams) {
+  const [tag, value, extra, offset, length] = node;
+  switch (tag) {
+    case 'array': return new Array(value);
+    case 'record': return {};
+    case 'map': return new Map();
+    case 'set': return new Set();
+    case 'date': return new Date(read(value));
+    case 'regexp': return new RegExp(value, extra);
+    case 'error': return Object.assign(new Error(extra), { name: value });
+    case 'exception': return new DOMException(extra, value);
+    case 'buffer': {
+      if (!(buffers[value] instanceof ArrayBuffer)) throw dataCloneError();
+      return buffers[value];
+    }
+    case 'stream': {
+      if (!(streams[value] instanceof ReadableStream)) throw dataCloneError();
+      return streams[value];
+    }
+    case 'view': {
+      const Type = views.get(value);
+      if (!Type) throw dataCloneError();
+      return new Type(read(extra), offset, length / (Type.BYTES_PER_ELEMENT ?? 1));
+    }
+    default: throw dataCloneError();
+  }
+}
+
+function populate(value, node, read) {
+  switch (node[0]) {
+    case 'array': setProperties(value, node[2], read); break;
+    case 'record': setProperties(value, node[1], read); break;
+    case 'error': case 'exception': setProperties(value, node[3], read); break;
+    case 'map': for (const [key, entry] of node[1]) value.set(read(key), read(entry)); break;
+    case 'set': for (const entry of node[1]) value.add(read(entry)); break;
+  }
+}
+
+/** Reconstruct a graph using buffers and streams owned by this receiver. */
+export function decode({ data, buffers = [], streams = [] }) {
+  const { root, nodes } = JSON.parse(data), values = new Map(), pending = new Set();
+  function read(value) {
+    if (!Array.isArray(value)) return value;
+    const [tag, entry] = value;
+    if (tag === 'undefined') return undefined;
+    if (tag === 'bigint') return BigInt(entry);
+    if (tag === 'number') return Number(entry);
+    if (tag !== 'ref' || !Number.isInteger(entry) || entry < 0 || entry >= nodes.length) throw dataCloneError();
+    if (values.has(entry)) return values.get(entry);
+    if (pending.has(entry)) throw dataCloneError();
+    pending.add(entry);
+    const result = allocate(nodes[entry], read, buffers, streams);
+    values.set(entry, result);
+    populate(result, nodes[entry], read);
+    pending.delete(entry);
+    return result;
+  }
+  return read(root);
+}

package/src/streams.ts

@@ -0,0 +1,120 @@
+import { encodeJson } from "./codec.js";
+import type { Overflow } from "./context.js";
+
+type Source<T> = (next: (value: T) => void, error: (error: unknown) => void, close: () => void) => () => void;
+
+/** A byte stream of newline-delimited JSON values of type `T`, which `decodeValues` reads. */
+export type JsonStream<T> = ReadableStream<Uint8Array> & {
+  /** Type only: the values the stream carries. */
+  readonly "~values"?: T;
+};
+const maxBufferedBytes = 1024 * 1024;
+
+/**
+ * Adapts a push source with explicit cancellation, buffering up to 1 MiB for a slow reader. Past
+ * that, `overflow` ends the stream with `QuotaExceededError` or drops the oldest buffered values.
+ * An error ends the stream at once; closing it delivers what is buffered first.
+ */
+export function byteStream(subscribe: Source<Uint8Array>, overflow: Overflow = "error"): ReadableStream<Uint8Array> {
+  const buffered: Uint8Array[] = [];
+  let bytes = 0;
+  let end: { error?: unknown } | undefined;
+  let stop = () => {};
+  let wake = () => {};
+  const finish = (error?: unknown) => {
+    if (end) return;
+    end = { error };
+    if (error !== undefined) buffered.length = 0;
+    stop();
+    wake();
+  };
+  const push = (value: Uint8Array) => {
+    if (end) return;
+    buffered.push(value);
+    bytes += value.byteLength;
+    while (bytes > maxBufferedBytes) {
+      const oldest = overflow === "dropOldest" && buffered.length > 1 ? buffered.shift() : undefined;
+      if (!oldest) {
+        finish(new DOMException("The stream consumer is too slow", "QuotaExceededError"));
+        return;
+      }
+      bytes -= oldest.byteLength;
+    }
+    wake();
+  };
+  return new ReadableStream<Uint8Array>({
+    start() {
+      try {
+        stop = subscribe(push, finish, () => { finish(); });
+        if (end) stop();
+      } catch (error) { finish(error); }
+    },
+    async pull(controller) {
+      while (!buffered.length && !end) await new Promise<void>((resolve) => { wake = resolve; });
+      const value = buffered.shift();
+      if (value) {
+        bytes -= value.byteLength;
+        controller.enqueue(value);
+      } else if (end?.error === undefined) controller.close();
+      else controller.error(end.error);
+    },
+    cancel() { finish(); },
+  }, { highWaterMark: 0 });
+}
+
+/** Encodes a typed push source as newline-delimited JSON. Errors terminate the stream. */
+export function valueStream<T>(subscribe: Source<T>, overflow: Overflow = "error"): JsonStream<T> {
+  return byteStream((next, error, close) => subscribe((value) => {
+    try {
+      const payload = encodeJson(value);
+      const line = new Uint8Array(payload.byteLength + 1);
+      line.set(payload);
+      line[payload.byteLength] = 10;
+      next(line);
+    } catch (failure) { error(failure); }
+  }, error, close), overflow);
+}
+
+/** Decodes JSON values; ending iteration cancels the source. */
+export async function* decodeValues<T>(source: JsonStream<T> | Promise<JsonStream<T>>, signal: AbortSignal = new AbortController().signal): AsyncGenerator<T, void, unknown> {
+  const reader = (await source).getReader();
+  const cancel = () => { void reader.cancel().catch(() => undefined); };
+  if (signal.aborted) cancel();
+  else signal.addEventListener("abort", cancel, { once: true });
+  try {
+    yield* readValues<T>(reader, signal);
+  } finally {
+    // An errored source rejects cancel with its original failure.
+    await reader.cancel().catch(() => undefined);
+    signal.removeEventListener("abort", cancel);
+    reader.releaseLock();
+  }
+}
+
+async function* readValues<T>(reader: ReadableStreamDefaultReader<Uint8Array>, signal: AbortSignal): AsyncGenerator<T, void, unknown> {
+  const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: false });
+  let pending = "";
+  let complete = false;
+  while (!complete) {
+    const { value, done } = await reader.read();
+    if (signal.aborted) return;
+    complete = done;
+    pending += decoder.decode(value, { stream: !done });
+    let newline: number;
+    while ((newline = pending.indexOf("\n")) !== -1) {
+      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- yielding lets the caller abort.
+      if (signal.aborted) return;
+      const line = pending.slice(0, newline);
+      pending = pending.slice(newline + 1);
+      yield parseValue<T>(line);
+    }
+    if (pending.length > maxBufferedBytes) throw new RangeError("The stream value exceeds 1 MiB");
+  }
+  if (pending) yield parseValue<T>(pending);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters -- the consumer supplies the decoded type.
+function parseValue<T>(line: string): T {
+  if (line.length > maxBufferedBytes) throw new RangeError("The stream value exceeds 1 MiB");
+  return JSON.parse(line) as T;
+}