@abide/abide 0.58.0 → 0.100.0

package/src/shared/reactive/watch.ts

@@ -0,0 +1,310 @@
+// The effect. RULEBOOK 12.2: runs immediately, and again whenever a reactive value it
+// read changes.
+//
+// TWO FORMS, ONE DISCRIMINATED BY ARITY. The bare form is TRACKED — 14.6 makes the body a
+// tracked context, so what it reads is discovered by running it. The narrowed form is
+// given its sources (12.3) and runs only when those change, so its body is not a tracked
+// context at all and a read inside it subscribes to nothing.
+//
+// ARITY RATHER THAN SHAPE, and the reason is a seam: telling an `Effect` from a `Reactive`
+// by inspection means reading the brand, which lives in `Reactive.ts` — and `Reactive.ts`
+// imports the narrowed form from here. A second argument is the author saying which form
+// they meant, and it needs nothing from the other module but a type.
+
+import { namedLogger } from '../log.ts'
+import { UNEXPECTED } from '../UNEXPECTED.ts'
+import { WORK } from '../WORK.ts'
+import { CELL } from './CELL.ts'
+import { NotLanded } from './NotLanded.ts'
+import type { Reactive } from './Reactive.ts'
+import { currentScope, runInScope } from './scoping.ts'
+import {
+    detach,
+    detachProbes,
+    newSubscriber,
+    type Subscriber,
+    TRACKING,
+    type Tracked,
+    truncate,
+    untracked,
+} from './tracking.ts'
+
+export type Disposer = () => void
+// biome-ignore lint/suspicious/noConfusingVoidType: `void` is an EFFECT'S RETURN POSITION and is load-bearing. `undefined` there refuses the ordinary effect — a block body that returns nothing infers `void`, which is not assignable to `undefined` — so the rule's own fix would reject every caller that does not return a disposer.
+export type Effect = () => void | Disposer
+
+const WATCH_LOG = namedLogger('abide:watch')
+
+/**
+ * Warns on `abide:watch` and hands the throw to `onError` where there is one.
+ *
+ * 12.6 — a read of a failed value inside an effect arrives here as the throw that read is.
+ */
+function reportThrow(thrown: unknown, message: string): void {
+    WATCH_LOG.warning(message, thrown)
+    UNEXPECTED.report?.(thrown)
+}
+
+/**
+ * Reports an effect's throw, then re-throws it in a browser.
+ *
+ * 12.7 — A BROWSER HAS NO `onError`, so the throw goes on out to surface as an uncaught error. A
+ * server's has been handed it, and re-thrown there it would fail the handler or the render whose
+ * write woke this effect — a second report of one failure, against code that did not fail.
+ */
+function effectThrew(thrown: unknown): void {
+    reportThrow(
+        thrown,
+        'an effect threw, and its watch is stopped. RULEBOOK 12.6, 12.8.',
+    )
+    if (typeof document !== 'undefined') throw thrown
+}
+
+/**
+ * Runs a disposer untracked, reporting a throw from it rather than letting it stop the effect's
+ * rerun.
+ *
+ * 14.10 — UNTRACKED, because a teardown runs wherever the stop was called from: a watch stopped
+ * inside another's effect subscribed that effect to whatever the disposer read.
+ */
+function runDisposer(dispose: Disposer): void {
+    try {
+        untracked(dispose, undefined, undefined)
+    } catch (thrown) {
+        reportThrow(thrown, 'a disposer threw. RULEBOOK 12.6.')
+    }
+}
+
+/**
+ * Where the watches a component's setup opens are collected, or `undefined` outside a setup.
+ *
+ * 12.4 — A SETUP'S WATCHES ARE ITS SCOPE'S: the scope is made before the setup runs and its `stops`
+ * is the collector, so what the setup opens has its owner from the start — a routed level's
+ * included, whose markup is deferred (41.19). The setup's code is the author's and calls `watch`
+ * with no scope in hand, which is why this is ambient rather than an argument.
+ */
+const OWNING: { stops: Disposer[] | undefined; free: boolean } = {
+    stops: undefined,
+    free: false,
+}
+
+/** Collects every watch opened from here into `stops`; answers the collector it replaced. */
+export function collectWatches(
+    stops: Disposer[] | undefined,
+): Disposer[] | undefined {
+    const previous = OWNING.stops
+    OWNING.stops = stops
+    return previous
+}
+
+/**
+ * Hands `dispose` to the setup being collected, if one is, and to the scope it was opened in, if
+ * there is one; answers it.
+ *
+ * 12.5 — the scope is a server's request (`currentScope`), which a browser never has.
+ */
+export function owned(dispose: Disposer): Disposer {
+    if (OWNING.free) return dispose
+    const stops = OWNING.stops
+    if (stops !== undefined) stops.push(dispose)
+    currentScope()?.stops.push(dispose)
+    return dispose
+}
+
+/**
+ * Whether something opened now has an owner to be handed to — a setup being collected, or a scope.
+ *
+ * Asked before allocating the stop a value built here would hand over, so a value built anywhere
+ * else allocates nothing for it.
+ */
+export function owning(): boolean {
+    return (
+        !OWNING.free &&
+        (OWNING.stops !== undefined || currentScope() !== undefined)
+    )
+}
+
+/**
+ * Runs `open`, and answers what it answers, with every watch it opens owned by its caller alone.
+ *
+ * FOR A WATCH WHOSE LIFE IS ALREADY HELD — a followed `GET`'s feed, stopped when its last follower
+ * leaves — and which a request or a setup it happened to start in would otherwise stop when that
+ * one ends.
+ */
+export function unowned<Result>(open: () => Result): Result {
+    const previous = OWNING.free
+    OWNING.free = true
+    try {
+        return open()
+    } finally {
+        OWNING.free = previous
+    }
+}
+
+/** Runs `effect` now, and again whenever a reactive value it read changes. */
+export function watch(effect: Effect): Disposer
+/** Runs `effect` now and whenever one of `sources` changes; its own reads subscribe to nothing. */
+export function watch(
+    // `never` for what a source accepts: it is subscribed to and never written, and a list of
+    // sources holding different values has no one `Stored` to be inferred as.
+    // SPELLED OUT RATHER THAN ALIASED: the compiler tells a position that holds the `Reactive` by
+    // the type's own symbol (31.3), and behind an alias `watch([n], …)` lowered to `watch([n()], …)`.
+    sources:
+        | Reactive<unknown, never, unknown, unknown>
+        | Reactive<unknown, never, unknown, unknown>[],
+    effect: Effect,
+): Disposer
+export function watch(first: unknown, second?: Effect): Disposer {
+    if (second === undefined) return owned(watchTracked(first as Effect))
+    // An app hands over the VALUES; the reader list lives on each one's record. Copied
+    // rather than aliased, because the reader keeps this array for its whole life and the
+    // app's own array is the app's to mutate.
+    const given = (Array.isArray(first) ? first : [first]) as {
+        [CELL]: Tracked
+    }[]
+    const sources: Tracked[] = []
+    for (let index = 0; index < given.length; index += 1)
+        sources.push((given[index] as { [CELL]: Tracked })[CELL])
+    return owned(watchOver(sources, null, second))
+}
+
+/**
+ * Runs `effect` now and again whenever one of the declared `sources` changes, untracked.
+ *
+ * THE NARROWED FORM, and what `s.watch` is (12.9). The sources are pushed into rather than
+ * discovered, so there is no tracked context, no cursor and no divergence — which is also why a
+ * read inside one of these subscribes to nothing.
+ *
+ * `adopter` says what is being asked for: `null` is an effect, which the end of the turn may run,
+ * and a value is an adoption's MIRROR into it, which carries a value and cannot wait — see
+ * `isMirror` and `adopter` in `tracking.ts`.
+ */
+export function watchOver(
+    sources: Tracked[],
+    adopter: Tracked | null,
+    effect: Effect,
+): Disposer {
+    // biome-ignore lint/suspicious/noConfusingVoidType: `void` is an EFFECT'S RETURN POSITION and is load-bearing. `undefined` there refuses the ordinary effect — a block body that returns nothing infers `void`, which is not assignable to `undefined` — so the rule's own fix would reject every caller that does not return a disposer.
+    let dispose: Disposer | void
+    // The sources are declared rather than tracked. `detach` still tears this down: it truncates
+    // from the cursor, and the cursor of a body that never tracked is zero.
+    const reader: Subscriber = newSubscriber(sources, adopter)
+    // 11.32 — the scope a rerun reads through: see `watchTracked`.
+    const scope = currentScope()
+    reader.notify = (): void => {
+        if (!reader.alive) return
+        // 12.1: the disposer runs before each rerun of its effect.
+        if (typeof dispose === 'function') runDisposer(dispose)
+        dispose = undefined
+        // `running` is what `markReaders` reads to skip a body already on the stack.
+        // A subscriber that never sets it has no re-entrancy guard at all: an effect
+        // that writes something it reads re-entered itself once per write, unbounded.
+        reader.running = true
+        // UNTRACKED, AND THE CLEAR IS WHAT MAKES IT SO. The sources are given rather
+        // than discovered, but the effect still RUNS wherever it was reached from — a
+        // `s.watch` opened inside a `watch` had its reads attributed to the OUTER
+        // reader, which then re-ran on a value it never read. A mirror is the same
+        // shape one turn up: it runs inside the mark walk, and 4.7 has the `transform`
+        // it calls there running untracked.
+        const previous = TRACKING.reader
+        TRACKING.reader = null
+        try {
+            WORK.wakes += 1
+            dispose = runInScope(scope, effect, undefined)
+        } catch (thrown) {
+            TRACKING.reader = previous
+            reader.running = false
+            // `NotLanded` is not an effect that failed, it is one whose turn has not
+            // come — and the source that has not landed is one this reader is already
+            // subscribed to, so its landing is what runs this again.
+            if (thrown instanceof NotLanded) return
+            // 12.8: one that throws once usually throws every run, and a watch
+            // re-running into the same throw is a loop with a log line per iteration.
+            reader.alive = false
+            detach(reader)
+            effectThrew(thrown)
+            return
+        }
+        TRACKING.reader = previous
+        reader.running = false
+    }
+    for (let index = 0; index < sources.length; index += 1)
+        (sources[index] as Tracked).readers.push(reader)
+    reader.notify()
+    // ONCE, however many owners stop it — a setup's scope and a request's both can — since 12.1
+    // gives the disposer one run at teardown.
+    return (): void => {
+        if (!reader.alive) return
+        reader.alive = false
+        detach(reader)
+        if (typeof dispose === 'function') runDisposer(dispose)
+    }
+}
+
+/**
+ * The bare form: runs `effect` as a tracked context, re-running when anything it read changes.
+ *
+ * UNOWNED — the caller holds the stop. `watch` is this handed to its owners (`owned`); a template
+ * binding's `Scope` and a `{#try}`'s retry hold their own, and call this direct.
+ *
+ * A SECOND BODY BESIDE `watchOver` ON PURPOSE, and it reads as the duplication it is: the two
+ * differ by the cursor reset, the probe rebuild and the tail trim, and the rest is the same lines.
+ * ONE BODY WITH A `tracked` FLAG WAS BUILT AND MEASURED, under V8 against this pair, interleaved
+ * four runs a side: `write a value that changed` — one bound watch — went 15.6 ns to 21.4 in every
+ * run, and `mount 50 readers` +12% (+7% under JSC). Three flag tests cannot cost 6 ns. The likely
+ * mechanism, inferred rather than traced: every closure made from one literal shares its call-site
+ * feedback, so the template binding's `effect()` call became every `s.watch` effect's and every
+ * adoption mirror's too. Two literals keep that call site to the effects a template makes.
+ */
+export function watchTracked(effect: Effect): Disposer {
+    // biome-ignore lint/suspicious/noConfusingVoidType: `void` is an EFFECT'S RETURN POSITION and is load-bearing. `undefined` there refuses the ordinary effect — a block body that returns nothing infers `void`, which is not assignable to `undefined` — so the rule's own fix would reject every caller that does not return a disposer.
+    let dispose: Disposer | void
+    const reader: Subscriber = newSubscriber([], null)
+    // 11.32 — A RERUN READS THROUGH THE SCOPE THE WATCH WAS OPENED IN, not the ambient one. The
+    // drain that reruns it runs in whichever request's turn scheduled it, so without this an
+    // effect a load aborted (11.63) reruns reading — and subscribing to — another request's
+    // values. The same move `run` makes for a body.
+    const scope = currentScope()
+    reader.notify = (): void => {
+        if (!reader.alive) return
+        // 12.1: the disposer runs before each rerun, and once more at teardown.
+        if (typeof dispose === 'function') runDisposer(dispose)
+        dispose = undefined
+        // A conditional read makes the previous run's list the wrong list — but
+        // rebuilding it wholesale is what the cursor in `tracking` exists to
+        // avoid, so the list is walked rather than cleared.
+        const previous = TRACKING.reader
+        TRACKING.reader = reader
+        reader.cursor = 0
+        if (reader.probeSources.length !== 0) detachProbes(reader)
+        reader.running = true
+        try {
+            WORK.wakes += 1
+            dispose = runInScope(scope, effect, undefined)
+        } catch (thrown) {
+            reader.running = false
+            TRACKING.reader = previous
+            if (reader.cursor < reader.sources.length) truncate(reader)
+            // The abort reaches here too: an effect that read a value which has
+            // not landed is not an effect that failed, it is one whose turn has
+            // not come. The read subscribed before it threw, so the value landing
+            // is what runs it.
+            if (thrown instanceof NotLanded) return
+            // 12.8: one that throws once usually throws every run.
+            reader.alive = false
+            detach(reader)
+            effectThrew(thrown)
+            return
+        }
+        reader.running = false
+        TRACKING.reader = previous
+        if (reader.cursor < reader.sources.length) truncate(reader)
+    }
+    reader.notify()
+    return (): void => {
+        if (!reader.alive) return
+        reader.alive = false
+        detach(reader)
+        if (typeof dispose === 'function') runDisposer(dispose)
+    }
+}

package/src/shared/refuse.ts

@@ -0,0 +1,224 @@
+// HOW A REFUSAL IS DECLARED AND HOW ONE IS MADE WITHOUT DECLARING IT. `refuse(status)` is
+// the undeclared form (17.4) and `refuse.named(name)` mints a factory for a named one
+// (15.3): the bare call is the plain case, and the member is the one that says more.
+//
+// FOUR NAMES AND NO MORE. 15.9 caps what this framework may declare at `NotFound`,
+// `ValidationError`, `Aborted` and the `HttpError` 17.4 names — everything else is the app's,
+// through `refuse.named`. A fifth built-in here is a refusal an app cannot have predicted and
+// cannot narrow against a name it never wrote. `Aborted` is the one the app asks for itself: it
+// comes back only from a call the app handed a signal and then aborted (16.49).
+
+import { FAILURE_STATUS_TEXT } from './FAILURE_STATUS_TEXT.ts'
+import { type Failed, failed, isFailed } from './Failed.ts'
+import type { Issues } from './Issues.ts'
+import type { JsonValue } from './JsonValue.ts'
+import { namedLogger } from './log.ts'
+import { type Found, runSchema, type Schema } from './Schema.ts'
+
+/** The `abide:refuse` logger (28.9) — 15.13 and 15.15's namespace. */
+const REFUSE_LOG = namedLogger('abide:refuse')
+
+/**
+ * An undeclared refusal: a status, and a message that defaults to its reason phrase.
+ *
+ * 17.4, 17.5: a status and nothing else. No data and no options bag for any — an
+ * undeclared refusal has no name to narrow on, so data on it could only be read by
+ * something that already knew what it was, and something that knew would have declared it.
+ * 17.8 — no message is the status's reason phrase.
+ */
+export function refuse(
+    status: number,
+    message?: string,
+): Failed<'HttpError', undefined> {
+    return failed(
+        'HttpError',
+        status,
+        message ?? FAILURE_STATUS_TEXT[status] ?? 'HttpError',
+        undefined,
+    )
+}
+
+/**
+ * A declared refusal's factory, with its `.is` narrowing.
+ *
+ * 15.3: STATUS 400 BY DEFAULT, which is the answer to "the caller sent something this
+ * cannot work with" — the case an app declares a refusal for most often. 15.8 is the one
+ * exception the framework itself makes, and it says 422 out loud below.
+ *
+ * THE FACTORY IS THE VALUE, and `.is` hangs off it: the declaration site is the only place
+ * that knows the name, so it is the only place that can hand back a narrowing that cannot
+ * be spelled wrong. An app comparing `error.name === 'NotFound'` by hand is a string
+ * literal nothing checks.
+ */
+type Declared<Name extends string, Data> = ((
+    data?: Data,
+) => Failed<Name, Data>) & {
+    is: (error: unknown) => error is Failed<Name, Data>
+}
+
+/**
+ * The two overloads of `refuse.named`: bare, or with a data `schema`.
+ *
+ * 15.18 — DATA IS DECLARED BY ITS `schema` AND BY NOTHING ELSE, so the name is never written
+ * twice. TypeScript has no partial inference: an app that could hand `Data` over as a type
+ * argument had to hand `Name` over beside it, spelling `<'TooBig', …>('TooBig')`. Taken off the
+ * schema, both are inferred — and a message function is typed by the data it is given.
+ */
+type Named = {
+    <Name extends string>(
+        name: Name,
+        status?: number,
+        message?: string,
+    ): Declared<Name, undefined>
+    <Name extends string, Data extends JsonValue>(
+        name: Name,
+        status: number | undefined,
+        message: string | ((data: Data) => string) | undefined,
+        options: { schema: Schema<Data> },
+    ): Declared<Name, Data>
+}
+
+refuse.named = named as Named
+
+/**
+ * Mints the factory for a named refusal: `refuse.named`'s body.
+ *
+ * The one body both overloads share, and what the framework's own declarations call with their
+ * `Data` spelled out — they are trusted, and a schema run on every 404 would buy nothing.
+ */
+function named<Name extends string, Data>(
+    name: Name,
+    status = 400,
+    message?: string | ((data: Data) => string),
+    options?: { schema?: Schema<Data> },
+): Declared<Name, Data> {
+    // 15.13 — resolved once, here, rather than on every construction.
+    const fallback = FAILURE_STATUS_TEXT[status] ?? name
+    const make = (data?: Data): Failed<Name, Data> => {
+        // 15.11 AND 15.14: the data is checked at construction, and before the message
+        // function — a formatter reading data the schema was about to refuse is a message
+        // about a value that never existed. Synchronously, but that is 19.12 rather than
+        // anything this call site arranges: no `Schema` may answer any other way.
+        //
+        // 15.15: A REFUSAL HERE WARNS RATHER THAN STOPPING THE `Failed` BEING BUILT, which
+        // is 15.4 holding even against this. The schema is the app checking its own
+        // refusal payload; getting that wrong is a bug in the app's error path, and taking
+        // the refusal down with it means the caller receives nothing at all — the original
+        // failure disappears behind a second one.
+        //
+        // 15.4 IS UNCONDITIONAL, so the call is wrapped. `runSchema` has two exits — a `Checked`
+        // for a bad VALUE and a THROW for a bad SCHEMA (a predicate, 19.3; an async one, 19.12;
+        // a `JsonSchema` keyword `validateJson` does not implement) — and only the first was
+        // being handled here. The three that throw took the `Failed` with them, which is exactly
+        // the harm 15.15 above says it exists to prevent.
+        //
+        // BOTH EXITS WARN, which is the rest of 15.15. Wrapped and discarded, the call had no
+        // observable effect at all: an app whose refusal payload does not match its own schema
+        // paid the walk and was told nothing, and neither did a schema this cannot run.
+        if (options?.schema !== undefined && data !== undefined)
+            try {
+                const checked = runSchema(options.schema, data)
+                if (checked.issues !== null)
+                    REFUSE_LOG.warning(name, checked.issues)
+            } catch (thrown) {
+                REFUSE_LOG.warning(name, thrown)
+            }
+        return failed(
+            name,
+            status,
+            messageFor(name, message, fallback, data as Data),
+            data as Data,
+        )
+    }
+    // 15.6 is what makes this a name comparison rather than an `instanceof`: the refusal
+    // may have been rebuilt from JSON on the other side of a wire.
+    make.is = (error: unknown): error is Failed<Name, Data> =>
+        isFailed(error) && error.name === name
+    return make
+}
+
+/**
+ * A refusal's message: the given one, what a message function makes of the data, or the fallback.
+ *
+ * 15.12: A FUNCTION `message` RUNS AT CONSTRUCTION, on the data — not at read, so the
+ * string is fixed by the time anything can see it and cannot answer differently twice.
+ *
+ * 15.13: NO MESSAGE IS THE STATUS'S REASON PHRASE (17.8), or the NAME for a status with none —
+ * and so is a message function that threw. A formatter that failed is a bug in the app, and
+ * taking the construction down with it would turn a cosmetic fault into a refusal the caller
+ * never receives — 15.4 has constructing a `Failed` inert, and a formatter is not an exception.
+ *
+ * AND WARNED on `abide:refuse`, which is the rest of 15.13.
+ */
+function messageFor<Data>(
+    name: string,
+    message: string | ((data: Data) => string) | undefined,
+    fallback: string,
+    data: Data,
+): string {
+    if (message === undefined) return fallback
+    if (typeof message !== 'function') return message
+    try {
+        return message(data)
+    } catch (thrown) {
+        REFUSE_LOG.warning(name, thrown)
+        return fallback
+    }
+}
+
+/**
+ * The `NotFound` refusal, at 404.
+ *
+ * 15.7: the address nothing answers. Both halves — no route matched, and no handler
+ * mounted at that address and method — are one refusal, because a caller cannot tell them
+ * apart and telling them apart is what an enumeration attack is.
+ */
+export const notFound = named<'NotFound', { path: string; method: string }>(
+    'NotFound',
+    404,
+)
+
+/**
+ * The `Aborted` refusal, at 499.
+ *
+ * 16.49: a load every caller of which aborted. 499 is the status a server logs for a request its
+ * client closed, and the one thing true of this refusal is that nobody is waiting for the answer.
+ */
+export const aborted = named<'Aborted', undefined>('Aborted', 499)
+
+/**
+ * The shared `ValidationError` factory, at 422.
+ *
+ * 15.8: 422 rather than `refuse.named`'s 400, and the difference is not decoration. A 400
+ * is "this request is malformed"; a 422 is "it parsed and the contents are wrong", which
+ * is exactly what a schema that ran and refused has found out.
+ *
+ * THE FACTORY IS BUILT ONCE and the export is a thin generic over it. `Issues<T>` varies
+ * per call site and a `Failed`'s `data` does not care which shape it holds, so minting a
+ * factory per call would allocate one to throw away and hand back a `.is` that compares
+ * the same string the shared one does.
+ */
+const validation = named<'ValidationError', JsonValue>('ValidationError', 422)
+
+/** A `ValidationError` refusal at 422, carrying the issues it found. */
+export function validationError<T>(
+    data?: Issues<T>,
+): Failed<'ValidationError', Issues<T>> {
+    return validation(data as JsonValue) as unknown as Failed<
+        'ValidationError',
+        Issues<T>
+    >
+}
+
+/**
+ * Args run through their gate: the accepted value, or a thrown `ValidationError`.
+ *
+ * 11.27, 16.17 — THE `args` GATE, for both places it stands: a keyed entry's run and a rung's
+ * `ctx.args()`. Here rather than in `Schema.ts` for that module's own reason — it cannot build the
+ * refusal it throws.
+ */
+export function checkArgs<Args>(gate: Schema<Args>, args: unknown): Args {
+    const answer = runSchema(gate, args)
+    if (answer.issues !== null) throw validationError<Found>(answer.issues)
+    return answer.value as Args
+}

package/src/shared/route.ts

@@ -0,0 +1,29 @@
+// 23.1 — WHERE WE ARE, as four values rather than one over a composite, so a reader of `params`
+// does not wake for a hash change and a progress bar reading `navigating` does not wake for either.
+//
+// FILLED BY WHOEVER RESOLVES THE ADDRESS: the client router per navigation, and a server's page lane
+// per request — where a module-level `reactive` is already one instance per request (11.32).
+
+import type { Params } from './matchRoute.ts'
+import { ambient } from './reactive/index.ts'
+
+/** The current address: its `url`, `params`, pattern `name`, and whether it is `navigating`. */
+export const route = {
+    url: ambient<URL>(),
+    params: ambient<Params>(),
+    /** 23.6 — the resolution path: the literal the address resolved to, `/invoices/[id]`. */
+    name: ambient<string>(),
+    navigating: ambient(false),
+}
+
+/**
+ * Sets `route`'s url, params and name to an address just resolved.
+ *
+ * 23.2 — ONE `URL` PER NAVIGATION, built here as the route resolves, so a reader holding the last
+ * one is not handed a value that moved under it.
+ */
+export function arrive(at: string, pattern: string, params: Params): void {
+    route.url.set(new URL(at))
+    route.params.set(params)
+    route.name.set(pattern)
+}