@abide/abide 0.58.0 → 0.100.0

package/src/shared/answerOf.ts

@@ -0,0 +1,141 @@
+// 41.21 — A CALL THE PAGE ALREADY STARTED IS TAKEN, NOT MADE AGAIN, and what a call answered is read
+// one way whoever made it: a handler's `wire`, and a handler abide mounts itself (`seededDocument`).
+
+import { failedFrom, isProblem } from './Failed.ts'
+import { carriesBytes, framedChunks, framingPrefix } from './framing.ts'
+import { principalRotated } from './principalRotated.ts'
+import { refuse } from './refuse.ts'
+import type { RpcRequest } from './rpcRequest.ts'
+import { type Answer, takeEarlyCall } from './takeEarlyCall.ts'
+import { VERSION_HEADER } from './VERSION_HEADER.ts'
+
+/**
+ * A call's answer: the early call's where the page started one, fetched where it did not.
+ *
+ * 41.27 — SETTLED AT ONCE ONLY WHERE THE SERVER PAINTED IT SETTLED. One it painted in flight is in
+ * flight while the page adopts, however early its answer landed, so the arm adopted is the arm
+ * painted and the answer then swaps it as any answer does.
+ *
+ * 16.32 — a `streams` caller is handed a framed answer's body unread; any other has it read to the
+ * end.
+ */
+export function answerOf(
+    request: RpcRequest,
+    streams: boolean,
+    signal: AbortSignal | undefined,
+): Answer | Promise<Answer> {
+    const early = takeEarlyCall(request.key)
+    if (early === undefined) return fetched(request, streams, signal)
+    if (early.painted === 1) {
+        const landed = landedAnswer(early)
+        if (landed !== undefined) return landed
+    }
+    return early.promise.then((): Answer | Promise<Answer> => {
+        const landed = landedAnswer(early)
+        if (landed !== undefined) return landed
+        // The early call failed as a request — or read a binary as text, which lost its bytes — so
+        // this one is made again.
+        if (early.body === undefined || early.body === null)
+            return fetched(request, streams, signal)
+        if (streams) return early
+        const read = new Response(early.body)
+        return carriesBytes(early.type) && succeeded(early.status)
+            ? read
+                  .bytes()
+                  .then((bytes) => ({ ...early, bytes, body: undefined }))
+            : read.text().then((text) => ({ ...early, text, body: undefined }))
+    })
+}
+
+/**
+ * An early call's answer where it has landed read: as text, or — for one the server painted, whose
+ * body the runner reads to the end so hydration waits on it — as bytes, decoded where the answer is
+ * not a binary.
+ */
+function landedAnswer(early: Answer): Answer | undefined {
+    if (readAsText(early)) return early
+    if (early.bytes === undefined) return undefined
+    return carriesBytes(early.type) && succeeded(early.status)
+        ? early
+        : {
+              ...early,
+              text: new TextDecoder().decode(early.bytes),
+              bytes: undefined,
+          }
+}
+
+/** Whether an early call's answer arrived as text that is what it carried — no binary read as one. */
+function readAsText(early: Answer): boolean {
+    return (
+        early.text !== undefined &&
+        !(carriesBytes(early.type) && succeeded(early.status))
+    )
+}
+
+function succeeded(status: number | undefined): boolean {
+    return status !== undefined && status >= 200 && status < 300
+}
+
+/**
+ * Fetches a call's answer; a framed answer to a streaming copy keeps its body unread (16.32).
+ *
+ * Anything else is read to its end: as bytes where it is a binary (16.34), as text otherwise.
+ */
+async function fetched(
+    request: RpcRequest,
+    streams: boolean,
+    signal: AbortSignal | undefined,
+): Promise<Answer> {
+    const answer = await fetch(
+        request.url,
+        signal === undefined ? request.init : { ...request.init, signal },
+    )
+    // THE HANDLER SIGNED THIS CALLER IN OR OUT, and the cookie is already the browser's.
+    principalRotated(answer)
+    const type = answer.headers.get('content-type')
+    const binary = answer.ok && carriesBytes(type)
+    // A streaming copy reads bytes as they land too (16.46), as it does a framed answer's lines.
+    const unread =
+        streams && answer.ok && (binary || framingPrefix(type) !== null)
+    return {
+        status: answer.status,
+        statusText: answer.statusText,
+        type,
+        version: answer.headers.get(VERSION_HEADER),
+        life: answer.headers.get('cache-control'),
+        text: unread || binary ? undefined : await answer.text(),
+        bytes: !unread && binary ? await answer.bytes() : undefined,
+        body: unread ? answer.body : undefined,
+    }
+}
+
+/**
+ * What a call's body hands back: the value, nothing (16.31), or the refusal it was answered with.
+ *
+ * The refusal (15.1) is rebuilt as the `Failed` the server returned. RETURNED, so the value refuses
+ * (15.5) rather than failing the way a network error does.
+ *
+ * 16.32 — A FRAMED STREAM IS COLLECTED INTO THE CHUNKS IT CARRIED, which is the value a streaming
+ * handler holds once its run has closed — for a copy the build did not mark as streaming, whose
+ * value is one production. A marked one reads its body as it lands (`framedStream`).
+ */
+export function answered(answer: Answer): unknown {
+    const status = answer.status ?? 0
+    if (status === 204) return undefined
+    const ok = succeeded(status)
+    if (ok) {
+        // 16.34 — a binary decodes back to the bytes it was.
+        if (answer.bytes !== undefined) return answer.bytes
+        const prefix = framingPrefix(answer.type)
+        if (prefix !== null) return framedChunks(answer.text ?? '', prefix)
+    }
+    let body: unknown
+    try {
+        body = answer.text === '' ? undefined : JSON.parse(answer.text ?? '')
+    } catch {
+        body = undefined
+    }
+    if (ok) return body
+    if (isProblem(body)) return failedFrom(body)
+    return refuse(status, answer.statusText || undefined)
+}

package/src/shared/applyPatch.ts

@@ -0,0 +1,173 @@
+// 18.11 — WHAT A PATCH WROTE, WRITTEN AGAIN HERE: a JSON Patch (RFC 6902) applied in order, each op's
+// `path` a JSON Pointer (RFC 6901). Called inside the value's own `s.patch`, so the rows it reaches are
+// the rows 32.33 remakes. A browser replays the server's writes.
+//
+// A pointer walks own properties alone, and an array step is an index or, for `add`, `-`. Every op a
+// patch records passes, so the check costs a browser replaying its server nothing, and an op naming
+// `__proto__` or a member off the prototype chain is refused at 400 rather than reached. A `test` that fails is 409, the patch's precondition rather than its form.
+import { putOwn } from './putOwn.ts'
+import type { PatchOp } from './reactive/PATCH_SINKS.ts'
+import { structural } from './reactive/structural.ts'
+import { refuse } from './refuse.ts'
+
+type Container = Record<string | number, unknown>
+
+/** Applies `ops` to `root` in order, in place; throws the refusal of the first one it cannot. */
+export function applyPatch(root: unknown, ops: PatchOp[]): void {
+    for (const op of ops) {
+        if (op.op === 'add') add(root, op.path, op.value)
+        else if (op.op === 'remove') remove(root, op.path)
+        else if (op.op === 'replace') replace(root, op.path, op.value)
+        else if (op.op === 'move') {
+            const moved = valueAt(root, op.from)
+            remove(root, op.from)
+            add(root, op.path, moved)
+        } else if (op.op === 'copy')
+            add(root, op.path, structuredClone(valueAt(root, op.from)))
+        else if (op.op === 'test') {
+            if (!structural(valueAt(root, op.path), op.value))
+                throw refuse(
+                    409,
+                    `abide: a patch's test failed at \`${op.path}\`.`,
+                )
+        } else
+            throw refuse(
+                400,
+                `abide: a patch named an operation JSON Patch has not.`,
+            )
+    }
+}
+
+/** The unescaped steps of a JSON Pointer: `''` is the root, and `~1` is `/` and `~0` is `~`. */
+function stepsOf(pointer: string): string[] {
+    if (pointer === '') return []
+    if (!pointer.startsWith('/'))
+        throw refuse(
+            400,
+            `abide: a patch path must start with \`/\` — not \`${pointer}\`.`,
+        )
+    const steps = pointer.slice(1).split('/')
+    for (let at = 0; at < steps.length; at += 1)
+        steps[at] = (steps[at] as string)
+            .replaceAll('~1', '/')
+            .replaceAll('~0', '~')
+    return steps
+}
+
+/** The container a pointer's last step is taken in, walked own property by own property. */
+function parentOf(root: unknown, steps: string[]): Container {
+    let held = root
+    for (let at = 0; at < steps.length - 1; at += 1)
+        held = stepInto(held, steps[at] as string)
+    if (held === null || typeof held !== 'object')
+        throw refuse(
+            400,
+            `abide: a patch path runs through a value that holds nothing.`,
+        )
+    return held as Container
+}
+
+function stepInto(held: unknown, step: string): unknown {
+    if (
+        held === null ||
+        typeof held !== 'object' ||
+        !Object.hasOwn(held, keyIn(held, step))
+    )
+        throw refuse(400, `abide: a patch named a path with no \`${step}\`.`)
+    return (held as Container)[keyIn(held, step)]
+}
+
+/** An array's step as its index, where it is one; any other container's as the key it is. */
+function keyIn(held: object, step: string): string | number {
+    if (!Array.isArray(held)) return step
+    if (!/^(0|[1-9][0-9]*)$/.test(step))
+        throw refuse(400, `abide: a patch named \`${step}\` in an array.`)
+    return Number(step)
+}
+
+function valueAt(root: unknown, pointer: string): unknown {
+    let held = root
+    for (const step of stepsOf(pointer)) held = stepInto(held, step)
+    return held
+}
+
+function add(root: unknown, pointer: string, value: unknown): void {
+    const steps = stepsOf(pointer)
+    if (steps.length === 0) {
+        replaceRoot(root, value)
+        return
+    }
+    const parent = parentOf(root, steps)
+    const last = steps[steps.length - 1] as string
+    if (Array.isArray(parent)) {
+        if (last === '-') {
+            parent.push(value)
+            return
+        }
+        const index = keyIn(parent, last) as number
+        if (index > parent.length)
+            throw refuse(400, `abide: a patch added past the end of an array.`)
+        parent.splice(index, 0, value)
+    } else putOwn(parent, last, value)
+}
+
+function remove(root: unknown, pointer: string): void {
+    const steps = stepsOf(pointer)
+    if (steps.length === 0)
+        throw refuse(400, `abide: a patch cannot remove the whole value.`)
+    const parent = parentOf(root, steps)
+    const key = keyIn(parent, steps[steps.length - 1] as string)
+    if (!Object.hasOwn(parent, key))
+        throw refuse(
+            400,
+            `abide: a patch removed \`${key}\`, which is not there.`,
+        )
+    if (Array.isArray(parent)) parent.splice(key as number, 1)
+    else delete parent[key]
+}
+
+function replace(root: unknown, pointer: string, value: unknown): void {
+    const steps = stepsOf(pointer)
+    if (steps.length === 0) {
+        replaceRoot(root, value)
+        return
+    }
+    const parent = parentOf(root, steps)
+    const key = keyIn(parent, steps[steps.length - 1] as string)
+    if (!Object.hasOwn(parent, key))
+        throw refuse(
+            400,
+            `abide: a patch replaced \`${key}\`, which is not there.`,
+        )
+    putOwn(parent, key, value)
+}
+
+/**
+ * The whole value replaced in place, since `s.patch` mutates what it serves rather than swapping it.
+ *
+ * An array takes the new one's elements and an object its members; a value of another shape cannot
+ * be replaced by mutation, so a patch writing one is refused.
+ */
+function replaceRoot(root: unknown, value: unknown): void {
+    if (Array.isArray(root) && Array.isArray(value)) {
+        root.splice(0, root.length, ...value)
+        return
+    }
+    if (
+        root !== null &&
+        typeof root === 'object' &&
+        !Array.isArray(root) &&
+        value !== null &&
+        typeof value === 'object' &&
+        !Array.isArray(value)
+    ) {
+        for (const key of Object.keys(root)) delete (root as Container)[key]
+        for (const key of Object.keys(value))
+            putOwn(root as Container, key, (value as Container)[key])
+        return
+    }
+    throw refuse(
+        400,
+        `abide: a patch replaced the whole value with one of another shape.`,
+    )
+}

package/src/shared/armAnchor.ts

@@ -0,0 +1,17 @@
+import { REGION_OPEN } from './ANCHORS.ts'
+
+// 41.24 — A REGION HOLDING ONE ARM AT A TIME NAMES THE ARM THE SERVER PAINTED in its open anchor,
+// `[0`, `[1` and on: an `{#if}` chain's arm, and a `{#try}`'s catch as its arm `1` (32.16). The
+// spelling is written here and read here, so the compiler and the client cannot disagree about it.
+// A bare `REGION_OPEN` names none — a region the browser filled, a `{#try}` whose body painted, or
+// one the server left empty (41.4) — and is adopted as it stands.
+
+/** An open anchor's data naming `arm`. */
+export function armAnchor(arm: number): string {
+    return `${REGION_OPEN}${arm}`
+}
+
+/** The arm an open anchor's data names, or `undefined` where it names none. */
+export function namedArm(data: string): number | undefined {
+    return data.length === 1 ? undefined : Number(data.slice(1))
+}

package/src/shared/attributeText.ts

@@ -0,0 +1,50 @@
+// 32.37 — WHAT A VALUE WRITES INTO AN ATTRIBUTE, the one answer the server's markup, a client
+// binding, a row built in the browser and a `{...expr}` spread all take. `null` is the attribute
+// ABSENT: for `null` and `undefined` everywhere, and for a falsy value on an attribute HTML reads by
+// presence. A URL attribute's text is scheme-checked here too (32.20), after the absence is decided
+// — `safeUrl(undefined)` is `''`, which would have written an empty `href` where none was asked for.
+// And WARNED HERE, the one place that has both the interpolation and the attribute's name: a
+// literal the compiler drops never reaches it.
+
+import { BOOLEAN_ATTRIBUTES } from './BOOLEAN_ATTRIBUTES.ts'
+import { escapeAttribute } from './escapeText.ts'
+import { RENDER_LOG } from './log.ts'
+import { textOf } from './Raw.ts'
+import { safeUrl } from './safeUrl.ts'
+import { URL_ATTRIBUTES } from './URL_ATTRIBUTES.ts'
+
+/**
+ * The text a value writes into an attribute, or `null` for the attribute absent.
+ *
+ * The name as the element carries it; both leaves hold the folded form, and an SVG attribute keeps
+ * its case on the element (`viewBox`), so the fold is for the lookup alone.
+ */
+export function attributeText(name: string, value: unknown): string | null {
+    if (value === null || value === undefined) return null
+    const folded = name.toLowerCase()
+    // PRESENT BY TRUTHINESS, and a string that made it present is its text: `hidden` reads
+    // `until-found`, where the presence alone would hide the content from find-in-page for good.
+    if (BOOLEAN_ATTRIBUTES.has(folded))
+        return value ? (typeof value === 'string' ? value : '') : null
+    const text = textOf(value)
+    if (!URL_ATTRIBUTES.has(folded)) return text
+    const safe = safeUrl(text)
+    if (safe !== text)
+        RENDER_LOG.warning(
+            `abide: \`${name}\` was handed a URL whose scheme is not http:, https:, mailto: or tel:, and is written empty. RULEBOOK 32.20.`,
+        )
+    return safe
+}
+
+/** The same answer as the bytes the server's tag carries, leading space included, or nothing. */
+export function attributeMarkup(name: string, value: unknown): string {
+    return writtenMarkup(name, attributeText(name, value))
+}
+
+/** Text `attributeText` already answered, as those bytes — which a spread holds once per entry. */
+export function writtenMarkup(name: string, text: string | null): string {
+    if (text === null) return ''
+    if (text === '' && BOOLEAN_ATTRIBUTES.has(name.toLowerCase()))
+        return ` ${name}`
+    return ` ${name}="${escapeAttribute(text)}"`
+}

package/src/shared/boundValue.ts

@@ -0,0 +1,58 @@
+// WHAT A `bind:` OPERAND HOLDS, read and written — the one place its two forms are told apart: a
+// `Reactive` (32.5, 32.6) or an explicit `{ get, set }` pair (the registry's `bind:value={{get, set}}`),
+// on an element and on a component alike.
+// THE BRAND IS READ FIRST (1.6): a `Reactive` is callable and has members of its own.
+
+import { isReactive } from './reactive/isReactive.ts'
+import { pairReactive } from './reactive/pairReactive.ts'
+
+type Pair = { get(): unknown; set(value: unknown): void }
+
+/** The value a `bind:` operand holds, read so the caller subscribes. */
+export function boundValue(operand: unknown): unknown {
+    if (isReactive(operand)) return (operand as () => unknown)()
+    return (operand as Pair | null | undefined)?.get?.()
+}
+
+/**
+ * The value held, without subscribing whoever asks.
+ *
+ * What a listener reads to decide what to write.
+ */
+export function heldValue(operand: unknown): unknown {
+    if (isReactive(operand))
+        return (operand as unknown as { peek(): unknown }).peek()
+    return (operand as Pair | null | undefined)?.get?.()
+}
+
+/** Writes a value through a `bind:` operand. */
+export function writeBound(operand: unknown, value: unknown): void {
+    if (isReactive(operand))
+        (operand as unknown as { set(value: unknown): void }).set(value)
+    else (operand as Pair | null | undefined)?.set?.(value)
+}
+
+/**
+ * A `bind:` on a component, as the prop accessor the child is handed.
+ *
+ * 32.6 — its value to a child that reads the prop, and a `Reactive` to the cell a child that
+ * writes it builds (`propCell`) — the caller's own, or one over the pair. HERE rather than in the
+ * cell, which cannot tell a pair from a value that happens to have a `get` and a `set`: a `Map`
+ * passed without `bind:`.
+ */
+export function boundProp(hold: () => unknown): (held?: true) => unknown {
+    return (held) => {
+        const operand = hold()
+        if (!held) return boundValue(operand)
+        return isReactive(operand) ? operand : pairReactive(operand as Pair)
+    }
+}
+
+/**
+ * Whether a `bind:group` member is checked: the group's value is its own value, or holds it.
+ *
+ * 32.8.
+ */
+export function groupHolds(group: unknown, value: unknown): boolean {
+    return Array.isArray(group) ? group.includes(value) : group === value
+}