@abide/abide 0.58.0 → 0.100.0

package/src/shared/reactive/SELECTION_MEMBERS.ts

@@ -0,0 +1,12 @@
+/**
+ * The members every selection answers, narrowed by a pattern where the value is keyed.
+ *
+ * 13.4. The one list both forwarders read: a `Keyed` forwarded per scope (`scoped.ts`) and an
+ * `Rpc` handing them to its handler (`rpc.ts`).
+ */
+export const SELECTION_MEMBERS = [
+    'busy',
+    'ready',
+    'refresh',
+    'invalidate',
+] as const

package/src/shared/reactive/STREAMING.ts

@@ -0,0 +1,5 @@
+/**
+ * What `streamingOrSettled` answers once a value turns out to stream (9.6), told apart from a value
+ * that settled to `undefined` — which is loaded, and so a settling of its own.
+ */
+export const STREAMING: unique symbol = Symbol('abide.streaming')

package/src/shared/reactive/argsContract.ts

@@ -0,0 +1,97 @@
+// WHAT A KEYED VALUE'S ARGS ARE HELD TO, past the face an app is handed: the `args` schema it was
+// declared with (19.7) and the defaults its body's parameter writes (11.29). A `Keyed` is where the
+// contract starts; a server's forwarder and an `Rpc` are faces built over one, and each carries it
+// through `contractOf` so a transport reads it off whichever face it was handed.
+//
+// DEFAULTS BEFORE THE KEY, IN ONE PLACE. 11.27: a call that left a member to the parameter and one
+// that wrote it are one entry, so every reach, call and lookup takes the key through `normalised`
+// — a caller that keyed the args as passed would file the same call twice, right in the value and
+// wrong in the work.
+//
+// Imports no part of the core, so `scoped.ts` can carry the contract without reaching `Keyed.ts`.
+
+import { putOwn } from '../putOwn.ts'
+import type { Schema } from '../Schema.ts'
+import { canonicalKey } from './canonicalKey.ts'
+import type { Defaults } from './parameterDefaults.ts'
+
+export const ARGS_GATE: unique symbol = Symbol.for('abide.argsGate')
+export const PARAMETER_DEFAULTS: unique symbol = Symbol.for(
+    'abide.parameterDefaults',
+)
+
+/**
+ * The contract a face carries: its `args` schema and its parameter defaults.
+ *
+ * Declared on what the framework builds rather than on `Keyed`, so no app type names it — and
+ * declared rather than stamped, so a face that forgets to carry it does not compile.
+ */
+export type Gated<Args> = {
+    [ARGS_GATE]: Schema<Args> | undefined
+    [PARAMETER_DEFAULTS]: Defaults | null
+}
+
+/** The contract `face` carries, for a face built over it to carry — none where it is not keyed. */
+export function contractOf(
+    face: Partial<Gated<unknown>> | undefined,
+): Gated<unknown> {
+    return {
+        [ARGS_GATE]: face?.[ARGS_GATE],
+        [PARAMETER_DEFAULTS]: face?.[PARAMETER_DEFAULTS] ?? null,
+    }
+}
+
+/** The `args` schema `face` carries, for a transport to coerce by (19.7). */
+export function gateOf(
+    face: Pick<Gated<unknown>, typeof ARGS_GATE>,
+): Schema<unknown> | undefined {
+    return face[ARGS_GATE]
+}
+
+/**
+ * `args` with every member the face's parameter defaults filled where it is `undefined` (11.27).
+ *
+ * `args` itself where the face has no defaults or nothing was missing, so a caller that passed
+ * every member allocates nothing and a second application is free.
+ */
+export function normalised<Args>(
+    face: Pick<Gated<unknown>, typeof PARAMETER_DEFAULTS>,
+    args: Args,
+): Args {
+    const defaults = face[PARAMETER_DEFAULTS]
+    return defaults === null ? args : withDefaults(args, defaults)
+}
+
+/** The entry key a call with `args` is filed under: `normalised`, then 11.24's canonical form. */
+export function keyOf(
+    face: Pick<Gated<unknown>, typeof PARAMETER_DEFAULTS>,
+    args: unknown,
+): string {
+    return canonicalKey(normalised(face, args))
+}
+
+// ABSENT ARGS ARE `{}`: a wire writes the two alike (an empty query), so read apart they are one
+// call keyed two ways by the side it was made on — and a pattern with a default is a record by its
+// own spelling.
+function withDefaults<Args>(args: Args, defaults: Defaults): Args {
+    if (args !== undefined && (typeof args !== 'object' || args === null))
+        return args
+    const given = (args ?? {}) as Record<string, unknown>
+    const { names, values } = defaults
+    let filled: Record<string, unknown> | null = null
+    for (let index = 0; index < names.length; index += 1) {
+        const name = names[index] as string
+        if (given[name] !== undefined) continue
+        filled ??= { ...given }
+        const value = values[index]
+        // A fresh copy of an object default, as the body's own evaluation makes one per call.
+        putOwn(
+            filled,
+            name,
+            typeof value === 'object' && value !== null
+                ? structuredClone(value)
+                : value,
+        )
+    }
+    return (filled ?? given) as Args
+}

package/src/shared/reactive/byOf.ts

@@ -0,0 +1,18 @@
+// A LEAF OF ITS OWN for `isReactive`'s reason: `rowKeyOf` is on the `@abide/abide/runtime` barrel every
+// compiled client module resolves through, and reaching `Reactive.ts` from there puts the core in
+// the chunk every page loads. The cell is read here, in the core's folder, so its layout stays the
+// core's.
+import { CELL } from './CELL.ts'
+import { isReactive } from './isReactive.ts'
+
+/** The `by` a `Reactive` declared (32.32), or `null` where it declared none or `value` is not one. */
+export function byOf(
+    value: unknown,
+): string | ((element: unknown) => unknown) | null {
+    if (!isReactive(value)) return null
+    return (
+        value as unknown as {
+            [CELL]: { by: string | ((element: unknown) => unknown) | null }
+        }
+    )[CELL].by
+}

package/src/shared/reactive/callLoad.ts

@@ -0,0 +1,200 @@
+// A CALL REACHING A LOAD, and what the calls waiting on it decide about it: who may end it (16.48),
+// how long it may go without progress (16.59), and whether the call after an ended one starts
+// another (16.62, 15.19). The policy the core's load primitives — `loadOf`, `abandonLoad`,
+// `streamingOrSettled` — are spent on, kept beside them rather than inside `Reactive.ts`: the core
+// is in every page's static closure, and only a page holding a handler calls a load.
+//
+// ONE RECORD PER VALUE, IN A SIDE TABLE, not a field on the cell. Every value would carry the field
+// and only a called one ever fills it, so the table is what keeps a plain `reactive` paying nothing.
+
+import { LOAD_SIGNAL } from '../LOAD_SIGNAL.ts'
+import { aborted, refuse } from '../refuse.ts'
+// Through the barrel, for the cycle it names: rpc reaches this module ahead of the barrel.
+import {
+    abandonLoad,
+    failedTransiently,
+    isReactive,
+    loadOf,
+    STREAMING,
+    streamingOrSettled,
+} from './index.ts'
+
+/**
+ * Who is waiting on one value's load, and what the last one came to.
+ *
+ * 16.48 — WHO IS WAITING ON A LOAD. Calls with the same args join one load (1.8), so one caller's
+ * signal is not the load's to end: a call with no signal pins it, and a load no call pinned ends
+ * once every signal handed to it has aborted. Replaced per load, so a refresh starts the count
+ * again — and kept past an abort, which is what 16.62 reads.
+ *
+ * The abort LISTENER is the record itself (`handleEvent`), so a load is one record and no
+ * closure over the call that started it. `declare`d fields, every one set in the constructor in one
+ * order, so the shape is fixed there and the bundle carries no field list.
+ */
+class Attended {
+    declare value: object
+    declare load: number
+    declare pinned: boolean
+    declare signals: Set<AbortSignal> | null
+    declare ending: AbortController | undefined
+    /** 16.61 — whether this load's clock is running, so a join starts none. */
+    declare timed: boolean
+    /** 16.62 — whether 16.48 ended this load, until a call reaches the value again. */
+    declare abandoned: boolean
+
+    constructor(
+        value: object,
+        load: number,
+        ending: AbortController | undefined,
+    ) {
+        this.value = value
+        this.load = load
+        this.pinned = false
+        this.signals = null
+        this.ending = ending
+        this.timed = false
+        this.abandoned = false
+    }
+
+    handleEvent(): void {
+        const value = this.value
+        if (ATTENDED.get(value) !== this || loadOf(value) !== this.load) return
+        if (this.pinned) return
+        for (const each of this.signals as Set<AbortSignal>)
+            if (!each.aborted) return
+        this.ending?.abort()
+        abandonLoad(value, aborted())
+        this.abandoned = true
+    }
+}
+
+const ATTENDED = new WeakMap<object, Attended>()
+
+/**
+ * Reaches `args` through `reach` as a call does, under that call's `signal` and `timeout`.
+ *
+ * 16.49 — a load this call starts may be ended by it, so its transport is handed a signal of the
+ * load's own (`LOAD_SIGNAL`, read by the body as it starts) — the caller's is only one vote.
+ */
+export function callLoad(
+    reach: (args: unknown) => unknown,
+    args: unknown,
+    signal: AbortSignal | undefined,
+    timeout: number | undefined,
+): unknown {
+    const ending = signal === undefined ? undefined : new AbortController()
+    LOAD_SIGNAL.current = ending?.signal
+    let reached: unknown
+    let attended: Attended | undefined
+    try {
+        reached = reach(args)
+        attended = ATTENDED.get(reached as object)
+        // 16.62 — the callers of an aborted load stopped waiting, and this one has not.
+        // 15.19 — and of one whose last answer failed transiently, which runs again here where an
+        // unkeyed handler has no reach of its own to run it.
+        let again = false
+        if (attended?.abandoned) {
+            attended.abandoned = false
+            again = loadOf(reached) === undefined
+        }
+        if (again || failedTransiently(reached))
+            (reached as { refresh(): void }).refresh()
+    } finally {
+        LOAD_SIGNAL.current = undefined
+    }
+    if (!isReactive(reached)) return reached
+    const load = loadOf(reached)
+    // Landed as it was reached, or nothing in flight: there is no load to end or to time.
+    if (load === undefined) return reached
+    if (attended === undefined || attended.load !== load) {
+        // The first call to reach this load is the one that started it, where one started it at
+        // all — a refresh starts a load no call handed a signal to, and `ending` is then inert.
+        attended = new Attended(reached, load, ending)
+        ATTENDED.set(reached, attended)
+    }
+    attend(attended, signal)
+    if (!attended.timed) timeLoad(attended, timeout)
+    return reached
+}
+
+/** Files a call's signal, or its pin, against the load it reached (16.48). */
+function attend(attended: Attended, signal: AbortSignal | undefined): void {
+    if (signal === undefined) {
+        attended.pinned = true
+        return
+    }
+    let signals = attended.signals
+    if (signals === null) {
+        signals = new Set()
+        attended.signals = signals
+        // A SIGNAL OUTLIVES THE LOADS HANDED IT — a page's own controller — so its listener goes
+        // when the load settles, or it pins every value it was ever handed until it aborts.
+        const forget = (): void => {
+            for (const each of signals as Set<AbortSignal>)
+                each.removeEventListener('abort', attended)
+        }
+        void Promise.resolve(attended.value).then(forget, forget)
+    } else if (signals.has(signal)) return
+    signals.add(signal)
+    if (signal.aborted) attended.handleEvent()
+    else signal.addEventListener('abort', attended, { once: true })
+}
+
+/**
+ * Ends a load that goes `milliseconds` without progress, refusing it 504.
+ *
+ * 16.12, 16.58, 16.59 — `timeout` ON EVERY CALL: a load that goes that long without progress — its
+ * answer, or a stream's next chunk — is ended where it stands, as 16.49 ends one, and refuses 504.
+ * ONE CLOCK PER LOAD: a call joining a load (1.8) is not a reason to give it longer, and the first
+ * clock would end the load at its own time whatever a second one did — so a join starts none.
+ */
+function timeLoad(attended: Attended, milliseconds: number | undefined): void {
+    if (milliseconds === undefined || !Number.isFinite(milliseconds)) return
+    attended.timed = true
+    const reached = attended.value
+    const load = attended.load
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const arm = (): void => {
+        clearTimeout(timer)
+        timer = setTimeout(() => {
+            if (loadOf(reached) === load) abandonLoad(reached, refuse(504))
+        }, milliseconds)
+    }
+    let settled = false
+    let wake = (): void => {}
+    const end = (): void => {
+        settled = true
+        clearTimeout(timer)
+        wake()
+    }
+    // A CHUNK IS PROGRESS. The live cursor wakes on each, and outlives the run — it waits on the
+    // next one — so the run settling is a wake of its own, and is what lets the cursor go.
+    const followChunks = async (): Promise<void> => {
+        const cursor = (reached as AsyncIterable<unknown>)[
+            Symbol.asyncIterator
+        ]()
+        try {
+            while (!settled) {
+                await new Promise<void>((resolve) => {
+                    wake = resolve
+                    cursor.next().then(
+                        () => resolve(),
+                        () => resolve(),
+                    )
+                })
+                if (settled || loadOf(reached) !== load) return
+                arm()
+            }
+        } finally {
+            void cursor.return?.(undefined)
+        }
+    }
+    arm()
+    // 9.6 — a value behind rungs only turns out to stream once the onion resolves, so the question
+    // is asked then, by the one wait that also hears a value settle or refuse.
+    streamingOrSettled(reached).then((settled) => {
+        if (settled !== STREAMING) return end()
+        void Promise.resolve(reached).then(end, end)
+        if (loadOf(reached) === load) void followChunks()
+    }, end)
+}

package/src/shared/reactive/canonicalKey.ts

@@ -0,0 +1,95 @@
+import { putOwn } from '../putOwn.ts'
+
+/**
+ * The entry key for an `Args` value: its canonical wire form, as a string.
+ *
+ * RULEBOOK 11.24: members sorted by name, `undefined` members dropped, `Date` written ISO.
+ *
+ * 11.26: the key is taken BEFORE any gate runs, because a browser holds no copy of the gate — a
+ * key taken after normalising is computed one way on a server and another in a browser, and every
+ * handler with a normalising schema would miss its seed buffer and re-issue the call on hydration.
+ *
+ * 11.64: WHAT THE WIRE FORM CANNOT WRITE IS REFUSED AT THE REACH. `JSON.stringify` does not fail
+ * on any of it — a `Set`, a `Map` and a class instance each have no own enumerable keys and
+ * canonicalise to `{}`, and a non-finite number is written `null` — so two different reaches
+ * produced one key and 1.8 joined the second to the first's standing work. The value was right
+ * for the first caller and wrong for every other one, with nothing to see.
+ */
+export function canonicalKey(args: unknown): string {
+    if (args === undefined) return ''
+    return JSON.stringify(canonical(args, []))
+}
+
+// THE PATH IS A STACK OF STEPS, joined only when a refusal names it. Built as a string per member
+// it was a concatenation for every element and every nested key on every reach, for a message the
+// success path never reads.
+type Steps = (string | number)[]
+
+function canonical(value: unknown, path: Steps): unknown {
+    if (value === null) return value
+    const kind = typeof value
+    if (kind === 'number') {
+        if (!Number.isFinite(value)) throw outside(String(value), path)
+        return value
+    }
+    if (kind !== 'object') {
+        if (kind === 'boolean' || kind === 'string') return value
+        // `undefined` reaches here from an ARRAY element alone — a member is dropped above.
+        throw outside(kind === 'undefined' ? 'undefined' : `a ${kind}`, path)
+    }
+    if (value instanceof Date) return value.toISOString()
+    if (Array.isArray(value)) {
+        const out: unknown[] = []
+        for (let index = 0; index < value.length; index += 1) {
+            path.push(index)
+            out.push(canonical(value[index], path))
+            path.pop()
+        }
+        return out
+    }
+    const prototype = Object.getPrototypeOf(value)
+    if (prototype !== Object.prototype && prototype !== null)
+        throw outside(named(value as object), path)
+    const source = value as Record<string, unknown>
+    const keys = Object.keys(source).sort()
+    // AN ORDINARY OBJECT, AND `putOwn` FOR THE ONE KEY THAT NEEDS IT: `__proto__` is a SETTER on
+    // `Object.prototype`, so `out[key] = …` for that key creates no own property and
+    // `JSON.stringify` never sees it — `{id: 1, __proto__: {role: 'admin'}}` and `{id: 1}` then
+    // canonicalise to one string, and 1.8 joins the second reach to the first's standing work.
+    // `Object.create(null)` closed that too, and V8 builds it in DICTIONARY mode: the shipped key
+    // took 49-56% of the time without it there, and a standing keyed reach 53%, where JSC reads
+    // level to 110% (`harness/scripts/sharedCases.ts`, two runs per engine).
+    const out: Record<string, unknown> = {}
+    for (let index = 0; index < keys.length; index += 1) {
+        const key = keys[index] as string
+        const member = source[key]
+        if (member === undefined) continue
+        path.push(key)
+        putOwn(out, key, canonical(member, path))
+        path.pop()
+    }
+    return out
+}
+
+function named(value: object): string {
+    const from = value.constructor as { name?: unknown } | undefined
+    return typeof from?.name === 'string' && from.name !== ''
+        ? `a ${from.name}`
+        : 'a class instance'
+}
+
+function outside(what: string, steps: Steps): Error {
+    let path = ''
+    for (const step of steps)
+        path +=
+            typeof step === 'number'
+                ? `[${step}]`
+                : path === ''
+                  ? step
+                  : `.${step}`
+    return new Error(
+        `An Args key cannot carry ${what} at ${
+            path === '' ? 'the arguments themselves' : `"${path}"`
+        }: the canonical wire form writes it as another entry's key (RULEBOOK 11.64).`,
+    )
+}

package/src/shared/reactive/chunksOfStream.ts

@@ -0,0 +1,51 @@
+import { chunksFrom } from './Reactive.ts'
+
+/**
+ * The chunks of a streaming value, as they land, ending when its run closes.
+ *
+ * The live cursor is the wake and not the source: a cursor outlives the run (it waits on the next
+ * one), and a chunk landing in the same turn as the close could be lost to whichever settled first
+ * — so each wake sends what the accumulation holds past what has already gone, and the close sends
+ * the rest.
+ */
+export async function* chunksOfStream(value: unknown): AsyncGenerator<unknown> {
+    const stream = value as PromiseLike<unknown> & AsyncIterable<unknown>
+    let closed = false
+    let failure: unknown
+    // ONE REACTION ON THE CLOSE FOR THE WHOLE STREAM, which wakes whichever wait is current. A
+    // `Promise.race` against the close per chunk left one reaction per chunk on it, held until the
+    // stream ended.
+    let wake: () => void = () => {}
+    void Promise.resolve(stream).then(
+        () => {
+            closed = true
+            wake()
+        },
+        (error: unknown) => {
+            closed = true
+            failure = error
+            wake()
+        },
+    )
+    const cursor = stream[Symbol.asyncIterator]()
+    let sent = 0
+    let woken = cursor.next()
+    try {
+        for (;;) {
+            if (!closed)
+                await new Promise<void>((resolve, reject) => {
+                    wake = resolve
+                    woken.then(() => resolve(), reject)
+                })
+            for (const chunk of chunksFrom(value, sent)) {
+                sent += 1
+                yield chunk
+            }
+            if (closed) break
+            woken = cursor.next()
+        }
+    } finally {
+        void cursor.return?.(undefined)
+    }
+    if (failure !== undefined) throw failure
+}