@abide/abide 0.58.0 → 0.100.0

package/src/shared/rpcRequest.ts

@@ -0,0 +1,73 @@
+// 16.18 — THE REQUEST A CALL IS, WRITTEN ONCE FOR BOTH ENDS. The browser's `wire` sends it, and the
+// server writes the same request into a page's early-call script (41.20) — so the two have to agree
+// to the byte, or the browser's call misses the request that was already started for it. `key` is
+// that agreement: method, URL and body, which is what makes two requests the same one.
+//
+// A `GET` or `DELETE` carries its args in the URL, in `queryText`'s spelling, and a mutation in its
+// body; 19.7 is where text becomes the declared type again.
+
+import { queryText } from './queryText.ts'
+import type { Method } from './rpc.ts'
+
+export type RpcRequest = {
+    method: Method
+    url: string
+    /** The JSON body of a mutation, or `undefined` where the args ride in the URL. */
+    body: string | undefined
+    /** What `fetch` is handed: the method, the JSON content-type beside a body, and `no-cache`. */
+    init: RequestInit
+    key: string
+}
+
+/**
+ * Whether a method carries its args in the URL.
+ *
+ * The half of 16.18 both ends read.
+ */
+export function argsInURL(method: Method): boolean {
+    return method === 'GET' || method === 'DELETE'
+}
+
+/** The request a call is: its URL, body, `fetch` init and the `key` both ends match it by. */
+export function rpcRequest(
+    method: Method,
+    address: string,
+    args: Record<string, unknown> | undefined,
+): RpcRequest {
+    let url = address
+    let body: string | undefined
+    if (argsInURL(method)) {
+        if (args !== undefined) {
+            let text = queryText(args)
+            // AN EMPTY LIST IS ITS NAME WITH NO `=`, which no text value spells — `tags=` is the
+            // one-member list `['']` — so 19.7 reads it back as `[]` rather than losing the member.
+            for (const name in args) {
+                const value = args[name]
+                if (!Array.isArray(value) || value.length !== 0) continue
+                const bare = bareName(name)
+                text = text === '' ? bare : `${text}&${bare}`
+            }
+            if (text !== '') url = `${address}?${text}`
+        }
+    } else if (args !== undefined) body = JSON.stringify(args)
+    // 18.14 — A COPY IS ITS OWN CACHE and keeps its own `max-age`. What it asks the server is asked
+    // because it went stale or was invalidated, and the browser's HTTP cache, which hears neither,
+    // would answer it with the value it was dropping. `rpc.raw` is handed the same, under whatever
+    // `init` its caller passes. `no-cache` rather than `no-store`: a `fetch` the app writes itself to
+    // the same address still reads 21.8's `max-age`.
+    const init: RequestInit =
+        body === undefined
+            ? { method, cache: 'no-cache' }
+            : {
+                  method,
+                  cache: 'no-cache',
+                  headers: { 'content-type': 'application/json' },
+                  body,
+              }
+    return { method, url, body, init, key: `${method} ${url} ${body ?? ''}` }
+}
+
+/** 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/safeUrl.ts

@@ -0,0 +1,68 @@
+// 32.20 — a URL-typed attribute is scheme-checked and a scheme outside the safe set is DROPPED.
+// In #shared beside the escaping because the check has to happen where the value does: a literal
+// `href` is checked at compile time, and an INTERPOLATION cannot be — its value arrives at run
+// time, which is also the only place untrusted data ever arrives. Checking only the literal read
+// as compliance and guarded nothing.
+//
+// The warning on `abide:render` the clause also asks for is `attributeText`'s, which knows the
+// attribute's name.
+import { textOf } from './Raw.ts'
+
+const SAFE_SCHEMES = new Set(['http:', 'https:', 'mailto:', 'tel:'])
+
+/** A URL attribute's text, or `''` where its scheme is outside the safe set. */
+export function safeUrl(value: unknown): string {
+    // A `Raw` reaches here from `<a href={raw(u)}>`, and the brand says "already markup", which is
+    // no claim at all about the scheme. The html is the text to check.
+    const text = textOf(value)
+    const scheme = schemeOf(text)
+    if (scheme === '') return text
+    return SAFE_SCHEMES.has(scheme) ? text : ''
+}
+
+// The scheme A BROWSER will read, lowercased, or '' where the value carries none.
+//
+// BUILT RATHER THAN MATCHED, because the bytes are not the URL. Before a browser looks for a
+// scheme it trims leading C0 controls and spaces and removes every TAB, LF and CR from what is
+// left, so `" javascript:alert(1)"` and `"java\tscript:alert(1)"` are both `javascript:` and both
+// navigate — a regex over the raw value called all three of them relative and safe.
+//
+// An `&#106;avascript:` entity reaches the same place by a third road and is stopped one layer up
+// rather than here: `escapeAttribute` encodes the `&`, so the entity never forms. 32.27 narrowed
+// that rewrite off every OTHER static attribute — static text is the author's own markup — and
+// 32.28 is why this set keeps it: here the encoding is not a formatting rule, it is the whole of
+// what stops the entity, and it is the only guard the scheme check has behind it.
+//
+// The scan stops at the first character no scheme can hold, so a relative reference — the common
+// case — costs one character. The scheme is sliced once at the colon rather than grown per character.
+function schemeOf(text: string): string {
+    let at = 0
+    while (at < text.length && text.charCodeAt(at) <= 0x20) at += 1
+    const start = at
+    let length = 0
+    let stripped = false
+    for (; at < text.length; at += 1) {
+        const code = text.charCodeAt(at)
+        if (code === 9 || code === 10 || code === 13) {
+            stripped = true
+            continue
+        }
+        if (code === 58) {
+            if (length === 0) return ''
+            const scheme = text.slice(start, at)
+            return `${(stripped ? scheme.replace(/[\t\n\r]/g, '') : scheme).toLowerCase()}:`
+        }
+        const lower = code >= 65 && code <= 90 ? code + 32 : code
+        const alpha = lower >= 97 && lower <= 122
+        const allowed =
+            alpha ||
+            (length > 0 &&
+                ((code >= 48 && code <= 57) ||
+                    code === 43 ||
+                    code === 45 ||
+                    code === 46))
+        if (!allowed) return ''
+        length += 1
+    }
+    return ''
+}

package/src/shared/seededDocument.ts

@@ -0,0 +1,36 @@
+// 41.20, 41.21 — THE CALL A HANDLER'S `wire` MAKES, less the follow, for a handler abide mounts
+// itself: the page's early-call script started it where a render made the call, and it is taken
+// from there before it is fetched. Not followed over the mux, which carries app handlers'
+// productions and has none of abide's own to send.
+
+import { answered, answerOf } from './answerOf.ts'
+import type { Failed } from './Failed.ts'
+import { mounted } from './mount.ts'
+import { rpcRequest } from './rpcRequest.ts'
+
+/**
+ * What `GET address` answers in a browser: the early call's answer where there is one.
+ *
+ * A refusal is read as `wire` reads one — the `Failed` the server answered with, returned.
+ *
+ * 41.27 — SETTLED AT ONCE where the server painted the call settled, as `wire`'s body is, so a
+ * value built on it is ready when the page adopts rather than on its loading arm.
+ */
+export function seededDocument<Document>(
+    address: string,
+):
+    | Document
+    | Failed<string, unknown>
+    | Promise<Document | Failed<string, unknown>> {
+    const answer = answerOf(
+        rpcRequest('GET', mounted(address), undefined),
+        false,
+        undefined,
+    )
+    return (
+        answer instanceof Promise ? answer.then(answered) : answered(answer)
+    ) as
+        | Document
+        | Failed<string, unknown>
+        | Promise<Document | Failed<string, unknown>>
+}

package/src/shared/setUpLevels.ts

@@ -0,0 +1,53 @@
+import {
+    currentShare,
+    leaveShare,
+    resumeShare,
+    type ShareScope,
+} from './reactive/share.ts'
+
+/**
+ * Sets up levels `from` to `count - 1` of a page chain — its layouts outermost first, the page
+ * last — and builds none of them.
+ *
+ * THE ONE PLACE THE CHAIN'S RULES ARE WRITTEN. `render`'s `composePage` and the client `Router`
+ * each compose the chain, and what differs between them is what a level's `children` is and what
+ * happens once every level is set up; these three hold for both.
+ *
+ * 41.19, 41.23 — EVERY LEVEL IS SET UP BEFORE ANY IS BUILT, so a page's setup has run before the
+ * layout reading what it wrote is built — on the server, where the layout was painted after that
+ * write, and on the client, where hydrating the layout first read the value before the page had
+ * written it. This sets up and builds nothing; `setUp` leaves its level's build for the caller.
+ *
+ * 10.5 — A PAGE IS A DESCENDANT OF ITS LAYOUT, so each level is set up inside the share scope the
+ * setup above it left — `outer` for the first, and whatever is current at the top of the chain.
+ * Each level is called by the composer rather than from inside the one above it, so without this a
+ * page opened a share chain of its own: the server painted the layout's value and hydration
+ * replaced it with the page's.
+ *
+ * 35.1 — ONE PROPS SHAPE AT EVERY LEVEL: the caller's record with `children` after it, present on
+ * every level and `undefined` until `setUp` hands the level the one below it — so on the innermost,
+ * which has nothing below it. Every compiled page and layout loads its props off this record, and
+ * a level that omits a key the one above carries is a second hidden class for all of them.
+ */
+export function setUpLevels(
+    from: number,
+    count: number,
+    /** The share scope the level above `from` left; `undefined` at the top of the chain. */
+    outer: ShareScope | null | undefined,
+    props: Record<string, () => unknown>,
+    /** Sets level `at` up over `levelProps`, answering the share scope its setup left. */
+    setUp: (
+        at: number,
+        levelProps: Record<string, (() => unknown) | undefined>,
+    ) => ShareScope | null,
+): void {
+    let share = outer === undefined ? currentShare() : outer
+    for (let at = from; at < count; at += 1) {
+        const back = resumeShare(share)
+        try {
+            share = setUp(at, { ...props, children: undefined })
+        } finally {
+            leaveShare(back)
+        }
+    }
+}

package/src/shared/slotValue.ts

@@ -0,0 +1,34 @@
+// 32.23 — A TEMPLATE EXPRESSION A `NotLanded` ABORTED LEAVES WHAT IT LAST RENDERED, which on a
+// server's first render of a page is nothing. 41.4 is the other half and the one that makes this
+// a module rather than a line: a render MUST continue past a value still in flight, so the slot
+// is what aborts and never the document.
+//
+// A THUNK, BECAUSE THE READ IS THE BODY. On the client every binding is already its own `watch`,
+// so 2.12 gives each slot an abortable body for free and a `NotLanded` takes down exactly the one
+// that read it. The server has no such body — `emitComponent` builds the markup as ONE
+// concatenation — so the first unlanded read threw out of `Component()` and `render` died on its
+// first `next()`, losing the static markup, every other slot and the `<head>` with them. Passing
+// the read rather than its result is what gives the slot the body the client's binding already
+// has, and it is one closure per guarded position per render.
+//
+// ONLY THE READ IS INSIDE THE TRY, and the escaping stays OUTSIDE it. Escaping cannot throw a
+// `NotLanded`, and a guard wide enough to cover it would catch one from somewhere that is not the
+// expression — which is the one thing a brand is for. It is also what lets every markup position
+// share this: the value's absence is `undefined` here, and what `undefined` MEANS is already
+// decided where it lands. `escapeText`, `escapeAttribute` and `escapeStyleValue` all read it as
+// '' through `textOf`, `listOf` reads it as absent and iterates zero times (32.22), and an `{#if}`
+// subject reads it as false. One abort, five positions, no fallback decided twice.
+
+import { NotLanded } from './reactive/NotLanded.ts'
+
+/** The value `read` returns, or `undefined` where a `NotLanded` aborted it. */
+export function slotValue(read: () => unknown): unknown {
+    try {
+        return read()
+    } catch (thrown) {
+        // 2.14 — a `NotLanded` and a `Failed` are distinguishable by brand, and only the first is
+        // "not yet". A producer that FAILED is 2.2's throw and belongs to whoever is rendering.
+        if (thrown instanceof NotLanded) return undefined
+        throw thrown
+    }
+}

package/src/shared/spread.ts

@@ -0,0 +1,79 @@
+// 32.11 — WHAT A `{...expr}` SPREADS, on both sides and in both positions.
+//
+// ON A COMPONENT, props: one accessor per key the value carries when the invocation is made, each
+// re-reading the value, so a prop stays a live read (33.5) as an explicit one is. The keys are read
+// once — a prop type with an index signature is where they are enumerated per read (33.11).
+//
+// ON AN ELEMENT, attributes: what the server writes into the tag, and what the client keeps writing.
+// A key the element names explicitly is the explicit attribute's (33.12's rule, held for elements
+// too); a value is written as a named attribute's is (32.37); a function is a listener where the
+// key is `on<event>`, and nothing under an `on<event>` key, nor any function, is ever markup.
+
+import { attributeText, writtenMarkup } from './attributeText.ts'
+import { isEventName } from './isEventName.ts'
+
+/** A `{...expr}` on a component, as one live prop accessor per key the value carries. */
+export function spreadProps(
+    read: () => unknown,
+): Record<string, () => unknown> {
+    const value = read()
+    const props: Record<string, () => unknown> = {}
+    if (value === null || typeof value !== 'object') return props
+    for (const key of Object.keys(value))
+        props[key] = () => (read() as Record<string, unknown> | null)?.[key]
+    return props
+}
+
+// An attribute name the markup can carry: anything but space, quotes, `>`, `/` and `=`.
+const ATTRIBUTE_NAME = /^[^\s"'>/=]+$/
+
+/**
+ * The attributes a spread value carries, as `[name, text]` — `''` for a bare one.
+ *
+ * The explicit names, the listeners and the unwritable are left out. One answer for the markup and
+ * the binding.
+ *
+ * THE LISTENERS COME OUT OF THE SAME WALK, as `[event, listener]` pushed onto `listeners`: a
+ * function under `on<event>` that the element does not name explicitly. The server has nowhere to
+ * put one and hands no array.
+ */
+export function spreadEntries(
+    value: unknown,
+    explicit: readonly string[],
+    listeners: [string, EventListener][] | null = null,
+): [string, string][] {
+    const entries: [string, string][] = []
+    if (value === null || typeof value !== 'object') return entries
+    for (const [name, member] of Object.entries(value)) {
+        const lower = name.toLowerCase()
+        if (explicit.includes(lower)) continue
+        // 32.4 — AN `on<event>` NAME IS NEVER MARKUP, whatever it holds: a string under `onclick`
+        // written as an attribute is an inline handler, script compiled from data.
+        if (isEventName(lower)) {
+            if (listeners !== null && typeof member === 'function')
+                listeners.push([lower.slice(2), member as EventListener])
+            continue
+        }
+        if (typeof member === 'function') continue
+        if (!ATTRIBUTE_NAME.test(name)) continue
+        // 32.37 — the named attribute's answer, so a spread and `name={expr}` never disagree.
+        const text = attributeText(name, member)
+        if (text !== null) entries.push([name, text])
+    }
+    return entries
+}
+
+/**
+ * A spread's attributes as markup, each escaped.
+ *
+ * 32.11 on the server.
+ */
+export function spreadAttributes(
+    value: unknown,
+    explicit: readonly string[],
+): string {
+    let markup = ''
+    for (const [name, text] of spreadEntries(value, explicit))
+        markup += writtenMarkup(name, text)
+    return markup
+}

package/src/shared/takeEarlyCall.ts

@@ -0,0 +1,86 @@
+// 41.21 — A CALL THE PAGE ALREADY STARTED IS TAKEN, NOT MADE AGAIN. What a server-rendered page's
+// early-call script (41.20) left for one request, handed to the first reader that asks for it and to
+// no other: a handler's `wire`, and the principal's document (26.17), which is a handler abide mounts.
+
+import { EARLY_CALLS } from './EARLY_CALLS.ts'
+
+/**
+ * What a call answered: the status and the text — which stays unset where the request itself did
+ * not complete.
+ */
+export type Answer = {
+    status: number | undefined
+    statusText: string | undefined
+    type: string | null | undefined
+    /**
+     * The answer's version, or `null` where it named none (18.5).
+     *
+     * A `null` is a value built per request.
+     */
+    version: string | null | undefined
+    /** The answer's `cache-control`, whose `max-age` is how long the copy may serve it (21.8). */
+    life: string | null | undefined
+    text: string | undefined
+    /**
+     * A binary answer's body read to the end (16.34), set in place of `text` — a body read as text
+     * is not the bytes it carried.
+     */
+    bytes: Uint8Array | undefined
+    /**
+     * A streamed answer's body, left unread so its chunks are taken as they land (16.32).
+     *
+     * Set in place of `text` for a handler the build marked as streaming, and by the early-call
+     * script for any framed answer.
+     */
+    body: ReadableStream<Uint8Array> | null | undefined
+}
+
+/**
+ * What the early-call script leaves per call: the request in flight, and once it has answered, what
+ * it answered.
+ */
+export type EarlyCall = Answer & {
+    promise: Promise<void>
+    /** `1` where the server built the page's markup from this call settled (41.25). */
+    painted: 1 | undefined
+}
+
+function startedCalls(): Record<string, EarlyCall | undefined> | undefined {
+    return (
+        globalThis as unknown as Record<
+            string,
+            Record<string, EarlyCall | undefined> | undefined
+        >
+    )[EARLY_CALLS]
+}
+
+/** The call the page started under `key`, taken so no later reader is answered from it. */
+export function takeEarlyCall(key: string): EarlyCall | undefined {
+    const started = startedCalls()
+    const early = started?.[key]
+    if (early !== undefined)
+        (started as Record<string, EarlyCall | undefined>)[key] = undefined
+    return early
+}
+
+/**
+ * What settles once every call the server painted settled has answered, or `undefined` where none
+ * is still on its way.
+ *
+ * 41.25 — WHAT HYDRATION WAITS FOR, so a call the page was painted from is settled when setup
+ * reads it rather than in flight. The early-call script's promise settles on an answer and on a
+ * failed request alike, so a call that fails ends the wait as one that answers does. A call painted
+ * loading, and one already answered, are not waited on.
+ */
+export function paintedCallsLanded(): Promise<unknown> | undefined {
+    const started = startedCalls()
+    if (started === undefined) return undefined
+    let waiting: Promise<void>[] | undefined
+    for (const key in started) {
+        const early = started[key]
+        if (early?.painted !== 1 || early.text !== undefined) continue
+        if (waiting === undefined) waiting = []
+        waiting.push(early.promise)
+    }
+    return waiting === undefined ? undefined : Promise.all(waiting)
+}

package/src/shared/url.ts

@@ -0,0 +1,140 @@
+// 30.1 — AN ADDRESS FROM A ROUTE LITERAL: the pattern a page is filed under, filled. The types read
+// the literal the way `parseRoutePattern` reads it at run time, so a call that leaves a required
+// segment out is a compile error naming it (30.2, 30.3) rather than an address with a hole in it.
+//
+// 16.10 — RESOLVED AGAINST THE MOUNT at the call, so the same build serves at the root and below it.
+
+import { mounted } from './mount.ts'
+import { queryText } from './queryText.ts'
+import { parseRoutePattern } from './routePattern.ts'
+
+type Parts<P extends string> = P extends `${infer Head}/${infer Tail}`
+    ? Head | Parts<Tail>
+    : P
+
+export type RequiredNames<P extends string> =
+    Parts<P> extends infer Part
+        ? Part extends `[${infer Name}]`
+            ? Name extends `[${string}` | `...${string}`
+                ? never
+                : Name
+            : never
+        : never
+
+export type OptionalNames<P extends string> =
+    Parts<P> extends infer Part
+        ? Part extends `[[${infer Name}]]`
+            ? Name
+            : never
+        : never
+
+export type RestNames<P extends string> =
+    Parts<P> extends infer Part
+        ? Part extends `[...${infer Name}]`
+            ? Name
+            : never
+        : never
+
+export type HasParams<P extends string> = [RequiredNames<P>] extends [never]
+    ? false
+    : true
+
+export type HasSegments<P extends string> = [
+    RequiredNames<P> | OptionalNames<P> | RestNames<P>,
+] extends [never]
+    ? false
+    : true
+
+export type Query = Record<string, unknown> | URLSearchParams
+
+/** The params a route literal takes, by segment kind. */
+export type ParamsOf<P extends string> = {
+    [K in RequiredNames<P>]: string | number
+} & { [K in OptionalNames<P>]?: string | number } & {
+    [K in RestNames<P>]?: string | number | (string | number)[]
+}
+
+/**
+ * 30.26 — the route literals an app files its pages under, which `abide check` declares for the app
+ * it checks. Where nothing declared them any literal is taken, so a plain `tsc` still compiles.
+ */
+// biome-ignore lint/suspicious/noEmptyInterface: filled by declaration merging, per app
+export interface Routes {}
+
+/** 30.26 — what `url` takes: one of the app's route literals, or any where none were declared. */
+export type RouteLiteral = [keyof Routes] extends [never]
+    ? string
+    : Extract<keyof Routes, string>
+
+/**
+ * 23.9 — the params a page filed under `P` reads: what a URL carries, so text, and a rest always a
+ * list — empty where it matched nothing.
+ */
+export type RouteParams<P extends string> = {
+    [K in RequiredNames<P>]: string
+} & { [K in OptionalNames<P>]?: string } & { [K in RestNames<P>]: string[] }
+
+/**
+ * An address from a route literal and its params, resolved against the mount, with an optional
+ * query.
+ */
+export function url<P extends RouteLiteral>(
+    pattern?: P,
+    ...rest: HasParams<P> extends true
+        ? [params: ParamsOf<P>, queryParams?: Query]
+        : [params?: ParamsOf<P>, queryParams?: Query]
+): string {
+    const params = (rest[0] ?? {}) as Record<string, unknown>
+    const query = rest[1]
+    let address = ''
+    for (const segment of parseRoutePattern(pattern ?? '/')) {
+        if (segment.kind === 'static') {
+            address += `/${segment.name}`
+            continue
+        }
+        const value = params[segment.name]
+        if (value === undefined || value === null || value === '') {
+            // 30.4 — an optional left out omits its segment, and so does an empty rest (30.5).
+            if (segment.kind !== 'required') continue
+            throw new Error(
+                `abide: url('${pattern}') was given no '${segment.name}', and the route requires it. RULEBOOK 30.3.`,
+            )
+        }
+        if (segment.kind === 'rest' && Array.isArray(value)) {
+            for (const each of value)
+                address += `/${encodedSegment(pattern, segment.name, each)}`
+            continue
+        }
+        address += `/${encodedSegment(pattern, segment.name, value)}`
+    }
+    if (address === '') address = '/'
+    address = mounted(address)
+    // 30.6 — the query half, last, in the spelling `rpcRequest` writes.
+    const search =
+        query === undefined
+            ? ''
+            : query instanceof URLSearchParams
+              ? query.toString()
+              : queryText(query)
+    return search === '' ? address : `${address}?${search}`
+}
+
+/**
+ * A param value encoded as one path segment; `.` and `..` are refused.
+ *
+ * 30.19 — A VALUE OF `.` OR `..` HAS NO SPELLING AS A SEGMENT: the URL parser collapses it as a
+ * dot-segment, and `%2E` / `%2E%2E` with it, so the address would land on another route. Refused
+ * rather than written, as a missing required segment is (30.3).
+ */
+function encodedSegment(
+    pattern: string | undefined,
+    name: string,
+    value: unknown,
+): string {
+    const text = String(value)
+    if (text === '.' || text === '..')
+        throw new Error(
+            `abide: url('${pattern}') was given '${text}' for '${name}', and no address carries it as a segment — the URL parser resolves it to another route. RULEBOOK 30.19.`,
+        )
+    return encodeURIComponent(text)
+}