@abide/abide 0.103.0 → 0.105.0

package/src/shared/framing.ts

@@ -1,46 +1,26 @@
-// 16.32 — A FRAMED ANSWER, read one JSON value per line: the whole line for jsonl, the `data:` line of
-// each event for sse. A line that does not carry the prefix — an sse `event:` line, a blank line — is
-// skipped. One line reader behind both a body read to the end and one read as it lands.
+// 16.32 — A FRAMED ANSWER, read one JSON value per frame: each line for jsonl, the `data` of each
+// event for sse. One reader, `frameReader`, behind both a body read to the end and one read as it
+// lands — and behind `abide watch`, which reads an event stream's events by name. The writer is the
+// server's (`server/streamEvent.ts`).
 //
 // 16.68 — AND ITS LAST FRAME MAY BE A REFUSAL: one that reached the stream after it had answered, so
-// after its status was sent. An sse `event: refusal` and the Problem Details on its `data:` line, or a
+// after its status was sent. An sse `event: refusal` and the Problem Details as its `data`, or a
 // jsonl line `{"$refusal": <Problem Details>}` — read here as the refusal, thrown where it lands.
 
-import { failedFrom, isProblem, type Problem } from './Failed.ts'
+import { failedFrom, isProblem } from './Failed.ts'
+import { REFUSAL_KEY } from './REFUSAL_KEY.ts'
 
-/** The key a jsonl line carries a refusal under (16.68). */
-const REFUSAL_KEY = '$refusal'
+/** The two framings a streamed JSON answer is read in. 17.6. */
+export type Framed = 'jsonl' | 'sse'
 
-/** A framed stream's last frame, as the server writes it for a refusal (16.68). */
-export function refusalFrame(problem: Problem, prefix: string): string {
-    return prefix === ''
-        ? `${JSON.stringify({ [REFUSAL_KEY]: problem })}\n`
-        : `event: refusal\n${prefix}${JSON.stringify(problem)}\n\n`
-}
-
-// What a read of one framed body carries from one line to the next: whether an sse event named the
-// data line after it a refusal.
-type Reading = { refusal: boolean }
-
-// A refusal's frame, read: thrown where it lands among the chunks.
-class Refused {
-    problem: Problem
-    constructor(problem: Problem) {
-        this.problem = problem
-    }
-}
-
-/**
- * What precedes a chunk's JSON on its line: nothing for jsonl, `data: ` for sse, and `null` where
- * the answer is not framed at all.
- */
-export function framingPrefix(type: string | null | undefined): string | null {
+/** How an answer at `type` is framed, or `null` where it is not framed at all. */
+export function framingOf(type: string | null | undefined): Framed | null {
     if (
         type?.startsWith('application/jsonl') ||
         type?.startsWith('application/x-ndjson')
     )
-        return ''
-    if (type?.startsWith('text/event-stream')) return 'data: '
+        return 'jsonl'
+    if (type?.startsWith('text/event-stream')) return 'sse'
     return null
 }
 
@@ -52,24 +32,102 @@ export function framingPrefix(type: string | null | undefined): string | null {
  */
 export function carriesBytes(type: string | null | undefined): boolean {
     if (type === null || type === undefined || type === '') return false
-    if (framingPrefix(type) !== null) return false
+    if (framingOf(type) !== null) return false
     const semicolon = type.indexOf(';')
     const essence = semicolon === -1 ? type : type.slice(0, semicolon)
     return essence !== 'application/json' && !essence.endsWith('+json')
 }
 
+/** One frame: an sse event's name — `message` where it named none — `id` and `data`, or a jsonl line. */
+export type Frame = { name: string; id: string | undefined; data: string }
+
+/**
+ * A framed body's reader, fed its text as it arrives: pushes each frame the text completes onto
+ * `frames` — and, where `ended`, the last one too.
+ *
+ * An event stream is read as the format says (18.27) — fields by name, a comment skipped, `data`
+ * lines joined, the event ending at a blank line. A jsonl line is a frame with nothing but its data.
+ * A closure over the read's own state, which is all it captures.
+ */
+function frameReader(
+    lines: boolean,
+): (text: string, ended: boolean, frames: Frame[]) => void {
+    // The text after the last newline read, held until its line completes.
+    let rest = ''
+    let name = 'message'
+    let id: string | undefined
+    let data: string | undefined
+    return (text, ended, frames) => {
+        // A long line across many reads is held unscanned until its newline lands, or each read
+        // rescans everything before it.
+        if (!ended && !text.includes('\n')) {
+            rest += text
+            return
+        }
+        const read = (rest + text).split('\n')
+        // The unfinished last line waits for the next read; at the end, a blank line ends it.
+        rest = ended ? '' : (read.pop() as string)
+        if (ended) read.push('')
+        for (const line of read) {
+            // A blank line ends an event; a jsonl line is one.
+            if (lines || line === '') {
+                const complete = lines ? line || undefined : data
+                if (complete !== undefined)
+                    frames.push({ name, id, data: complete })
+                name = 'message'
+                id = data = undefined
+                continue
+            }
+            // A field and its value, the one space after the colon dropped and a CRLF's `\r` with
+            // it; a line with no colon is a field with no value. A comment — an event stream's
+            // opener — names the field ``, which is none.
+            const colon = line.indexOf(':')
+            const field = colon === -1 ? line : line.slice(0, colon)
+            if (field !== 'data' && field !== 'event' && field !== 'id')
+                continue
+            let start = colon === -1 ? line.length : colon + 1
+            if (line.charCodeAt(start) === 32) start += 1
+            const value = line.slice(
+                start,
+                line.charCodeAt(line.length - 1) === 13
+                    ? line.length - 1
+                    : line.length,
+            )
+            if (field === 'data')
+                data = data === undefined ? value : `${data}\n${value}`
+            else if (field === 'event') name = value
+            else id = value
+        }
+    }
+}
+
+/**
+ * The chunk a frame carried, or — where it is a refusal (16.68) — that refusal, thrown.
+ *
+ * Per chunk: the reserved key is tested before any key list is built.
+ */
+function chunkOf(frame: Frame, lines: boolean): unknown {
+    const value = JSON.parse(frame.data)
+    const problem = !lines
+        ? frame.name === 'refusal' && value
+        : typeof value === 'object' &&
+          Object.hasOwn(Object(value), REFUSAL_KEY) &&
+          Object.keys(value).length === 1 &&
+          value[REFUSAL_KEY]
+    if (isProblem(problem)) throw failedFrom(problem)
+    return value
+}
+
 /**
- * A streamed answer's chunks: each JSON value its framing carried, or, for bytes (16.46), each
- * `Uint8Array` as it was read — bytes have no framing to split them back into the chunks the
- * handler yielded.
+ * A streamed answer's chunks: each JSON value its `framing` carried, or, for bytes (16.46) — an
+ * unread body with no framing — each `Uint8Array` as it was read: bytes have no framing to split
+ * them back into the chunks the handler yielded.
  */
 export function answerChunks(
     body: ReadableStream<Uint8Array>,
-    type: string | null | undefined,
+    framing: Framed | null,
 ): AsyncIterable<unknown> {
-    return carriesBytes(type)
-        ? bytesStream(body)
-        : framedStream(body, framingPrefix(type) ?? '')
+    return framing === null ? bytesStream(body) : framedStream(body, framing)
 }
 
 /**
@@ -92,113 +150,54 @@ async function* bytesStream(
     }
 }
 
-/** The chunks a framed text carried, every line of it complete. */
-export function framedChunks(text: string, prefix: string): unknown[] {
-    const chunks: unknown[] = []
-    readLines(text, prefix, true, chunks, { refusal: false })
-    for (const chunk of chunks)
-        if (chunk instanceof Refused) throw failedFrom(chunk.problem)
-    return chunks
+/** The chunks a framed text carried, every frame of it complete. */
+export function framedChunks(text: string, framing: Framed): unknown[] {
+    const lines = framing === 'jsonl'
+    const frames: Frame[] = []
+    frameReader(lines)(text, true, frames)
+    return frames.map((frame) => chunkOf(frame, lines))
+}
+
+/** An event stream's events, yielded as each completes. */
+export function eventsOf(
+    body: ReadableStream<Uint8Array>,
+): AsyncGenerator<Frame> {
+    return framedStream(body, 'sse', true) as AsyncGenerator<Frame>
 }
 
 /**
- * A framed body's chunks, yielded as each line completes.
+ * A framed body's chunks — or, where `events`, its frames as they are — yielded as each frame
+ * completes.
  *
  * Canceled when the reader stops reading — a refresh starts a new run and the old one's reader has
  * nothing left to hand anything.
  */
 export async function* framedStream(
     body: ReadableStream<Uint8Array>,
-    prefix: string,
+    framing: Framed,
+    events?: true,
 ): AsyncGenerator<unknown> {
+    const lines = framing === 'jsonl'
     const reader = body.getReader()
     const decoder = new TextDecoder()
-    const chunks: unknown[] = []
-    const reading: Reading = { refusal: false }
-    let buffered = ''
+    const framed = frameReader(lines)
+    const frames: Frame[] = []
     try {
         for (;;) {
             const { done, value } = await reader.read()
-            const decoded = done
-                ? decoder.decode()
-                : decoder.decode(value, { stream: true })
-            // A long line across many reads is held unscanned until its newline lands, or each read
-            // rescans everything before it.
-            if (!done && !decoded.includes('\n')) {
-                buffered += decoded
-                continue
-            }
-            buffered = readLines(
-                buffered + decoded,
-                prefix,
+            framed(
+                done
+                    ? decoder.decode()
+                    : decoder.decode(value, { stream: true }),
                 done,
-                chunks,
-                reading,
+                frames,
             )
-            for (const chunk of chunks) {
-                if (chunk instanceof Refused) throw failedFrom(chunk.problem)
-                yield chunk
-            }
-            chunks.length = 0
+            for (const frame of frames)
+                yield events ? frame : chunkOf(frame, lines)
+            frames.length = 0
             if (done) return
         }
     } finally {
         void reader.cancel().catch(() => {})
     }
 }
-
-/**
- * Parses each complete line of `text` into `chunks`, and the unfinished last one too where `ended`.
- *
- * Answers what is left of `text` after the last newline.
- */
-function readLines(
-    text: string,
-    prefix: string,
-    ended: boolean,
-    chunks: unknown[],
-    reading: Reading,
-): string {
-    let start = 0
-    for (;;) {
-        const newline = text.indexOf('\n', start)
-        if (newline === -1 && !ended) return text.slice(start)
-        const end = newline === -1 ? text.length : newline
-        if (prefix !== '' && text.startsWith('event: refusal', start))
-            reading.refusal = true
-        else if (end > start && text.startsWith(prefix, start)) {
-            const value: unknown = JSON.parse(
-                text.slice(start + prefix.length, end),
-            )
-            chunks.push(refusalIn(value, prefix, reading) ?? value)
-            reading.refusal = false
-        }
-        if (newline === -1) return ''
-        start = newline + 1
-    }
-}
-
-// The refusal a value carries as its frame: the data line an sse event named one, or a jsonl line
-// holding the one reserved key and Problem Details under it.
-function refusalIn(
-    value: unknown,
-    prefix: string,
-    reading: Reading,
-): Refused | undefined {
-    if (prefix !== '')
-        return reading.refusal && isProblem(value)
-            ? new Refused(value)
-            : undefined
-    // Per chunk: the reserved key is tested before any key list is built.
-    if (
-        value === null ||
-        typeof value !== 'object' ||
-        !Object.hasOwn(value, REFUSAL_KEY)
-    )
-        return undefined
-    const keys = Object.keys(value)
-    const problem = (value as Record<string, unknown>)[REFUSAL_KEY]
-    return keys.length === 1 && isProblem(problem)
-        ? new Refused(problem)
-        : undefined
-}

package/src/shared/queryText.ts

@@ -1,18 +1,26 @@
 /**
  * A record of members as a query string.
  *
- * ONE QUERY-STRING RULE for `rpcRequest`'s args (16.18) and `url`'s `Query` (30.6): a member left
+ * 30.28 — ONE QUERY-STRING RULE for `rpcRequest`'s args (16.18) and `url`'s `Query`: a member left
  * `undefined` is omitted, a list is its member repeated, and anything else is its text — `null`
- * included, which 19.7 reads back as `null` where the schema declares it. An empty list writes
- * nothing here; `rpcRequest` spells it as a bare name.
+ * included, which 19.7 reads back as `null` where the schema declares it. AN EMPTY LIST IS ITS NAME
+ * WITH NO `=`, last, which no text value spells — `tags=` is the one-member list `['']` — so 19.7
+ * reads it back as `[]` rather than losing the member.
  */
 export function queryText(members: Record<string, unknown>): string {
     const query = new URLSearchParams()
+    let bare = ''
     for (const [name, value] of Object.entries(members)) {
         if (value === undefined) continue
-        if (Array.isArray(value))
-            for (const each of value) query.append(name, String(each))
-        else query.append(name, String(value))
+        if (!Array.isArray(value)) query.append(name, String(value))
+        else if (value.length === 0) bare += `&${bareName(name)}`
+        else for (const each of value) query.append(name, String(each))
     }
-    return query.toString()
+    const text = query.toString()
+    return text === '' ? bare.slice(1) : text + bare
+}
+
+/** A query member's name in the encoding `URLSearchParams` gives it, without its `=`. */
+export function bareName(name: string): string {
+    return new URLSearchParams([[name, '']]).toString().slice(0, -1)
 }

package/src/shared/reactive/Cursor.ts

@@ -1,14 +1,12 @@
-// THE CURSOR. RULEBOOK 2.5: `for await (… of s)` — the production in flight, then each one after
-// it. On a streaming producer that is one turn per CHUNK, read from the chunk buffer by ordinal,
-// so two chunks between two `await`s are two turns of the loop. On every other value it is the
-// standing production: a burst between two turns collapses to the latest, since nothing else is
-// held. An app that wants every message keeps them — a channel is an array.
+// THE CURSOR. RULEBOOK 2.6: a streaming producer's chunks, read from the chunk buffer by ordinal,
+// so two chunks between two `await`s are two turns of the loop, and a patch or a write over the
+// stream moves no place (5.7, 9.12). Where the run ENDS is the caller's settling, handed to
+// `closeOn`: one run's reader is `Reactive.ts`'s `runChunks`.
 //
 // A NARROW FACE rather than the `Cell`, the same way `tracking.ts` takes a `Tracked`: what a
 // cursor reads is a handful of fields, and naming them keeps the cell's internals out of a
 // second file.
 
-import { PATCHES } from './PATCHES.ts'
 import {
     dropReader,
     newSubscriber,
@@ -17,27 +15,20 @@ import {
 } from './tracking.ts'
 
 /**
- * What a cursor reads, and all of a cell the server is handed (`servedCellOf`).
+ * What a cursor reads of a cell.
  *
  * `ring[index]` carries ordinal `ringBase + index + 1`, so a cursor holding an ordinal finds its
  * place in a stream's chunk buffer without the buffer having to hold one.
  */
 export type Retained = Tracked & {
-    /** The window a `throttle` or a `debounce` holds open, `holding` while a production waits on it. */
-    cap: { holding: boolean } | null
     ordinal: number
     ring: unknown[]
     ringBase: number
-    servable: boolean
-    state: number
-    /**
-     * Non-null on a streaming producer, whose ring is the accumulation of the run being served
-     * (9.1) and is retained whole — the chunks ARE the value.
-     */
-    stream: object | null
-    value: unknown
 }
 
+/** What `take` answers when the cursor has caught up — never a chunk, which may be `undefined`. */
+export const CAUGHT_UP: unique symbol = Symbol('caught up')
+
 // The cursors standing over each source, for a patch to keep the place of the ones behind (5.7).
 const CURSORS = new WeakMap<Retained, Set<Cursor>>()
 
@@ -70,62 +61,39 @@ export function hasCursorBehind(source: Retained): boolean {
 }
 
 /**
- * A live reader of a source's productions, one turn per production, in order.
+ * A reader of a stream's chunks, in order, waking whoever waits on it when one lands.
  *
- * A RECORD, NOT A SCOPE. The four closures this was — `take`, `notify`, `stop` and `next` — shared
- * one environment holding `at`, `waiting`, `source` and `reader`, and a cursor OUTLIVES the call
- * that made it: a `for await` holds one for the life of the loop, so the environment and every
- * function object hanging off it is live that whole time. Fields on a prototype are the object
- * alone, and `at` — read and written on every turn — becomes a property load on a fixed structure
- * rather than a scope load.
+ * A RECORD, NOT A SCOPE. A cursor outlives the call that made it — a `for await` holds one for the
+ * life of the loop — so fields on a prototype are the object alone, and `at`, read and written on
+ * every turn, is a property load on a fixed structure rather than a scope load.
  */
-export class Cursor implements AsyncIterator<unknown> {
+export class Cursor {
     source: Retained
-    /** The ordinal of the last production this cursor handed over. */
+    /** The ordinal of the last chunk this cursor handed over. */
     at: number
-    /**
-     * The patch epoch the value it last handed over stood at.
-     *
-     * A PATCH MINTS NO ORDINAL (5.7) — the follow's version tells a patch from a production by
-     * exactly that — so a cursor over a value patched in place reads the change off the object.
-     */
-    patched: number
-    /**
-     * The turns asked for and not yet answered.
-     *
-     * A QUEUE rather than one slot because a consumer may ask twice before either answer arrives
-     * — `Promise.all([ it.next(), it.next() ])` is the shape, and with one slot the second `next`
-     * overwrote the first's resolver and that promise never settled at all. `for await` asks one
-     * at a time, which is why nothing here said so.
-     */
-    waiting: ((result: IteratorResult<unknown>) => void)[]
+    /** Called once at the next wake, then cleared. */
+    wake: (() => void) | null
+    /** Whether the run `closeOn` was handed has settled. */
+    closed: boolean
+    /** What that run rejected with. */
+    failure: unknown
     reader: Subscriber
 
     constructor(source: Retained, from: number) {
         this.source = source
         this.at = from
-        this.patched = 0
-        this.waiting = []
-        // The one closure left, and it captures this cursor and nothing else. `notify` is
-        // called as a method on the SUBSCRIBER, so it cannot be the cursor's own method —
-        // and widening `Subscriber` with a back-edge would put a field on the shape every
-        // reader in the graph carries for the sake of the few that are cursors.
-        // Registered outside the tracking protocol, so the source it waits on is declared
-        // rather than discovered — see the same shape in `Reactive`'s `settled`.
+        this.wake = null
+        this.closed = false
+        this.failure = undefined
+        // The one closure left, and it captures this cursor and nothing else. `notify` is called as a
+        // method on the SUBSCRIBER, so it cannot be the cursor's own method. Registered outside the
+        // tracking protocol, so the source it waits on is declared rather than discovered — see the
+        // same shape in `Reactive`'s `settled`.
         this.reader = newSubscriber([source], null)
-        // One production per waiting turn, in the order they were asked for: a burst that
-        // lands three productions on a consumer holding two turns answers both.
-        this.reader.notify = (): void => {
-            const waiting = this.waiting
-            while (waiting.length !== 0) {
-                const next = this.take()
-                if (next === null) return
-                ;(waiting.shift() as (result: IteratorResult<unknown>) => void)(
-                    next,
-                )
-            }
-        }
+        this.reader.notify = (): void => this.woken()
         source.readers.push(this.reader)
+        // ONE PLACED PAST EVERY CHUNK is a wake and never behind, so no patch has a place to keep.
+        if (from === Number.POSITIVE_INFINITY) return
         let cursors = CURSORS.get(source)
         if (cursors === undefined) {
             cursors = new Set()
@@ -135,83 +103,60 @@ export class Cursor implements AsyncIterator<unknown> {
     }
 
     /**
-     * One production, or `null` where the cursor has caught up.
+     * The next chunk, or `CAUGHT_UP`.
      *
-     * Reading a stream's chunks by ordinal is what keeps a burst from being a gap or a repeat.
+     * Reading by ordinal is what keeps a burst from being a gap or a repeat.
      */
-    take(): IteratorResult<unknown> | null {
+    take(): unknown {
         const source = this.source
-        let at = this.at
-        if (source.stream === null) {
-            const value = source.value
-            // 6.10: an `undefined` standing is caught up, not a turn.
-            if (value === undefined) return null
-            const patched =
-                value !== null && typeof value === 'object'
-                    ? (PATCHES.written.get(value) ?? 0)
-                    : 0
-            if (at >= source.ordinal && patched === this.patched) return null
-            // 5.9 — A PRODUCTION A WINDOW HOLDS has minted its ordinal and is not yet the value: the
-            // turn is the release's, which wakes this cursor.
-            if (source.cap?.holding === true) return null
-            // The standing production is the only one held, so everything minted or patched
-            // since the last turn collapses into it.
-            this.at = source.ordinal
-            this.patched = patched
-            return { value, done: false }
-        }
-        if (at >= source.ordinal) return null
-        // A run that restarted moved the buffer past this cursor: answer from its start.
-        if (at < source.ringBase) at = source.ringBase
-        const value = source.ring[at - source.ringBase]
-        this.at = at + 1
-        return { value, done: false }
-    }
-
-    next(): Promise<IteratorResult<unknown>> {
-        if (!this.reader.alive)
-            return Promise.resolve({ value: undefined, done: true })
-        // A TURN ALREADY ASKED FOR AND NOT ANSWERED KEEPS THE ORDER: taking from the
-        // ring here while one is queued would hand the later caller the earlier
-        // production.
-        if (this.waiting.length === 0) {
-            const ready = this.take()
-            // NOT `async`, and no `await` on the caught-up arm. A cursor behind a
-            // stream's chunks is the common shape while a burst drains, and an
-            // `async` here would put a microtask tick between every one of those
-            // turns.
-            if (ready !== null) return Promise.resolve(ready)
-        }
-        const waiting = this.waiting
-        return new Promise((resolve) => {
-            waiting.push(resolve)
-        })
+        if (this.at >= source.ordinal) return CAUGHT_UP
+        const value = source.ring[this.at - source.ringBase]
+        this.at += 1
+        return value
     }
 
     /**
-     * Ends the cursor: `for await` calls this on `break`, on `return` and on a throw.
+     * Ends the cursor's run where `run` settles: `closed` is set, `failure` holds a rejection, and
+     * the current `turn` wakes.
      *
-     * It is the only thing that drops the subscriber — a live cursor has no end of its own.
+     * ONE REACTION ON THE CLOSE FOR THE WHOLE RUN, never one per chunk held until the run ends. A
+     * chunk landing in the same turn as the close is still unread when the close wakes the caller,
+     * so a drain before reading `closed` hands it over rather than losing it to whichever settled
+     * first.
      */
-    return(): Promise<IteratorResult<unknown>> {
-        return this.stop()
+    closeOn(run: PromiseLike<unknown>): void {
+        run.then(
+            () => {
+                this.closed = true
+                this.woken()
+            },
+            (error: unknown) => {
+                this.closed = true
+                this.failure = error
+                this.woken()
+            },
+        )
+    }
+
+    /** Settles at the next chunk or the close, whichever lands first. */
+    turn(): Promise<void> {
+        return new Promise((resolve) => {
+            this.wake = resolve
+        })
     }
 
-    throw(): Promise<IteratorResult<unknown>> {
-        return this.stop()
+    private woken(): void {
+        const wake = this.wake
+        this.wake = null
+        wake?.()
     }
 
-    stop(): Promise<IteratorResult<unknown>> {
+    /** Drops the subscriber; nothing else does. */
+    stop(): void {
         const reader = this.reader
         reader.alive = false
         dropReader(this.source, reader)
         CURSORS.get(this.source)?.delete(this)
-        const waiting = this.waiting
-        while (waiting.length !== 0)
-            (waiting.shift() as (result: IteratorResult<unknown>) => void)({
-                value: undefined,
-                done: true,
-            })
-        return Promise.resolve({ value: undefined, done: true })
+        this.wake = null
     }
 }