@abide/abide 0.123.3 → 0.124.0

package/src/ui/Router.ts

@@ -1,7 +1,7 @@
 import { CURRENT_ROUTER, type NavigateOptions } from '#shared/CURRENT_ROUTER.ts'
 import { decodedOrKept } from '#shared/decodedOrKept.ts'
 import { ERROR_META } from '#shared/ERROR_META.ts'
-import { firstMatch, type Params, partsOf } from '#shared/matchRoute.ts'
+import { firstMatch, partsOf } from '#shared/matchRoute.ts'
 import { unmounted } from '#shared/mount.ts'
 import { NAVIGATION_HEADER } from '#shared/NAVIGATION_HEADER.ts'
 import { OFFLINE_SAVED } from '#shared/OFFLINE_CACHES.ts'
@@ -13,6 +13,12 @@ import { paintedCallsLanded } from '#shared/takeEarlyCall.ts'
 import { LAYER_NAVIGATE } from './LAYER_NAMES.ts'
 import { LevelChain, type PageModule } from './LevelChain.ts'
 import { beginLayer, endLayer } from './measureLayer.ts'
+import {
+    type Bearing,
+    type Found,
+    outcomeOf,
+    type Settled,
+} from './outcomeOf.ts'
 import { pageRegion, type Region } from './regions.ts'
 
 export type Route = {
@@ -30,8 +36,6 @@ export type Route = {
 
 type Compiled = Route & { segments: Segment[] }
 
-type Found = { route: Compiled; params: Params }
-
 /** A window's scroll, `[scrollX, scrollY]`. */
 type Scroll = readonly [number, number]
 
@@ -151,7 +155,7 @@ export class Router {
      * as the address below the app's root. Every way in — a click, an intent, back and forward, a
      * hydration — is matched here.
      */
-    match(pathname: string): Found | undefined {
+    match(pathname: string): Found<Compiled> | undefined {
         const below = unmounted(pathname)
         const parts = below === undefined ? undefined : partsOf(below)
         return parts === undefined ? undefined : firstMatch(this.routes, parts)
@@ -209,28 +213,17 @@ export class Router {
         options: NavigateOptions,
         step: Step,
     ): Promise<void> {
-        const target =
-            typeof url === 'string' ? new URL(url, location.href) : url
-        // A CROSS-ORIGIN ADDRESS IS NOT A ROUTE. Handing it to `pushState` throws, and treating
-        // it as a miss would leave the caller with a navigation that silently did nothing.
-        if (target.origin !== location.origin || this.errorPage) {
-            location.href = target.href
-            return
-        }
-        const found = this.match(target.pathname)
-        if (found === undefined) {
-            // NOT A ROUTE THIS BUILD KNOWS, so it is the server's to answer — which is a document
-            // load, and the one case where 30.7 does not apply because there is no route to run.
-            location.href = target.href
-            return
-        }
-        // 30.21, 30.23, 30.24 — THE ROUTE STANDING, AT ITS OWN PATH: another query, another fragment or
-        // the same address. The page reads its address through `route`, so it follows rather than
-        // being rebuilt, and there is no path for `middleware` to decide anything new about.
-        if (found.route === this.standing && this.mounted === target.pathname) {
-            this.follow(target, options, found, step)
-            return
+        const bearing: Bearing<Compiled> = {
+            target: typeof url === 'string' ? new URL(url, location.href) : url,
+            origin: location.origin,
+            errorPage: this.errorPage,
+            standing: this.standing,
+            mounted: this.mounted,
+            match: (pathname) => this.match(pathname),
         }
+        const before = outcomeOf(bearing)
+        if (before.kind !== 'ask') return this.settle(before, options, step)
+        const found = before.found
         const ticket = this.supersede()
         route.navigating.set(true)
         // EVERY WAY OUT CLEARS WHAT THE WAY IN SET: a load that fails, a setup that throws and a
@@ -239,70 +232,61 @@ export class Router {
         try {
             // 30.15 — THE SERVER IS ASKED ALONGSIDE THE LOAD, so its `middleware` decides the
             // navigation for the price of the one round trip the chunks already cost.
+            // 30.27 — `loadOrMiss`, because a rejection here was dropped by the click's `void`,
+            // and the link did nothing.
             const [answer, loaded] = await Promise.all([
-                ask(target, ticket.signal),
+                ask(bearing.target, ticket.signal),
                 loadOrMiss(found.route),
             ])
             // SUPERSEDED, so this navigation is over. Nothing has been touched yet, which is the
             // whole reason the ticket is checked here rather than after the mount — and
             // `navigating` stays the newer navigation's to clear.
             if (ticket.signal.aborted) return
-            // 30.32 — OFFLINE, THE DOCUMENT LOAD BELOW CAN ONLY PAINT THE BROWSER'S ERROR PAGE over a
-            // page that works. A history step has already moved the bar, so it is left to the
-            // document.
-            if (
-                answer === undefined &&
-                !navigator.onLine &&
-                step.direction === 'push'
-            ) {
+            const after = outcomeOf(bearing, {
+                found,
+                answer,
+                loaded: loaded !== undefined,
+                online: navigator.onLine,
+                pushed: step.direction === 'push',
+            })
+            if (after.kind === 'offline') {
                 // 45.12 — UNLESS THE SERVICE WORKER SAVED THE PAGE, which the document load is
                 // then answered with.
-                if ((await savedOffline(target)) && !ticket.signal.aborted)
-                    location.href = target.href
-                return
-            }
-            // 30.18 — A REFUSAL, A RESPONSE MIDDLEWARE ANSWERED ITSELF, or no answer at all: the
-            // document asks again and paints whatever the server says. A fetch that failed —
-            // offline, or a redirect to another origin that CORS will not let it follow — goes to
-            // the address it was sent to.
-            // 30.27 — AND CHUNKS THAT WOULD NOT LOAD, with the server down or a deploy that removed
-            // them: a rejection here was dropped by the click's `void`, and the link did nothing.
-            if (answer?.status !== 204 || loaded === undefined) {
-                location.href = answer?.url ?? target.href
-                return
-            }
-            // 30.17 — REDIRECTED, and the server already said yes to where it landed: the answer is
-            // the 204 at the end of the chain. That address is mounted in place of the one asked
-            // for, and a route the client has no row for is the document's (30.10).
-            const landed = answer.redirected ? new URL(answer.url) : target
-            const landing = answer.redirected
-                ? this.match(landed.pathname)
-                : found
-            if (landing === undefined) {
-                location.href = landed.href
-                return
-            }
-            // 30.23 — THE ROUTE STANDING, AT ANOTHER PATH: `middleware` has said yes to the path, and
-            // the page it matched is the one already mounted, so it follows.
-            if (landing.route === this.standing) {
-                this.follow(landed, options, landing, step)
+                if (
+                    (await savedOffline(bearing.target)) &&
+                    !ticket.signal.aborted
+                )
+                    location.href = after.href
                 return
             }
+            if (after.kind !== 'mount') return this.settle(after, options, step)
             const arriving =
-                landing === found ? loaded : await loadOrMiss(landing.route)
+                after.found === found
+                    ? loaded
+                    : await loadOrMiss(after.found.route)
             if (ticket.signal.aborted) return
             if (arriving === undefined) {
-                location.href = landed.href
+                location.href = after.at.href
                 return
             }
             await this.write(ticket, step.direction, () =>
-                this.commit(landed, landing, arriving, options, step),
+                this.commit(after.at, after.found, arriving, options, step),
             )
         } finally {
             if (this.navigation === ticket) route.navigating.set(false)
         }
     }
 
+    /** Executes an outcome that loads nothing: a document load, or a step within the page. */
+    private settle(
+        outcome: Settled<Compiled>,
+        options: NavigateOptions,
+        step: Step,
+    ): void {
+        if (outcome.kind === 'document') location.href = outcome.href
+        else this.follow(outcome.at, options, outcome.found, step)
+    }
+
     /**
      * Moves the address within the standing page, leaving the page mounted.
      *
@@ -317,7 +301,7 @@ export class Router {
     follow(
         target: URL,
         options: NavigateOptions,
-        found: Found,
+        found: Found<Compiled>,
         step: Step,
     ): void {
         this.supersede()
@@ -447,7 +431,7 @@ export class Router {
      */
     private commit(
         target: URL,
-        found: Found,
+        found: Found<Compiled>,
         arriving: PageModule[],
         options: NavigateOptions,
         step: Step,
@@ -515,7 +499,7 @@ export class Router {
      *
      * 23.1 — WRITTEN BEFORE THE ARRIVING PAGE'S SETUP, which reads it.
      */
-    private arriveAt(target: URL, found: Found): void {
+    private arriveAt(target: URL, found: Found<Compiled>): void {
         arrive(target.href, found.route.pattern, found.params)
         this.standing = found.route
         this.mounted = target.pathname

package/src/ui/outboxQueue.ts

@@ -19,14 +19,8 @@ import { failedFrom, isFailed, problemOf } from '#shared/Failed.ts'
 import type { Problem } from '#shared/Failed.ts'
 import { showLine, type ShownCall, showSending } from '#shared/outbox.ts'
 import { onPrincipalRotated } from '#shared/principalRotated.ts'
-import {
-    isReactive,
-    produceInto,
-    type Reactive,
-    reactive,
-    refuseInto,
-    standIn,
-} from '#shared/reactive/index.ts'
+import { isReactive, type Reactive, reactive } from '#shared/reactive/index.ts'
+import { produceInto, refuseInto, standIn } from '#shared/reactive/producer.ts'
 import { rpcRequest } from '#shared/rpcRequest.ts'
 
 const DATABASE = 'abide-outbox'

package/src/ui/outcomeOf.ts

@@ -0,0 +1,120 @@
+import type { Params } from '#shared/matchRoute.ts'
+
+/** A route an address matched, and the params it matched with. */
+export type Found<RouteRow> = { route: RouteRow; params: Params }
+
+/**
+ * What a navigation knows before it asks anything: where it is going, and what stands.
+ *
+ * `match` is the router's own, so 16.10's mount and 30.9's ranking are decided where they always
+ * were.
+ */
+export type Bearing<RouteRow> = {
+    target: URL
+    /** The document's origin, which an address outside of is no route (30.10). */
+    origin: string
+    /** 35.18 — the document is an error page's, so leaving it is a document load. */
+    errorPage: boolean
+    /** The route the standing page was matched by. */
+    standing: RouteRow | undefined
+    /** The path the standing chain was mounted for. */
+    mounted: string | undefined
+    match: (pathname: string) => Found<RouteRow> | undefined
+}
+
+/** What the ask and the load came back with (30.15). */
+export type Heard<RouteRow> = {
+    /** The route the ask was made for — the `ask` outcome's `found`. */
+    found: Found<RouteRow>
+    /** The server's answer; `undefined` where the fetch failed. */
+    answer: { status: number; url: string; redirected: boolean } | undefined
+    /** Whether the asked-for route's chunks loaded. */
+    loaded: boolean
+    online: boolean
+    /** Whether the navigation pushes, rather than arriving at a history step the bar already took. */
+    pushed: boolean
+}
+
+/**
+ * How a navigation ends.
+ *
+ * `document` hands `href` to a document load. `follow` moves the address within the standing page.
+ * `ask` is the first call's answer where the server must be asked first. `offline` is 30.32's: the
+ * page stays, unless the service worker saved `href` (45.12). `mount` mounts `found` at `at`.
+ */
+type Outcome<RouteRow> =
+    | Settled<RouteRow>
+    | { kind: 'ask'; found: Found<RouteRow> }
+    | { kind: 'offline'; href: string }
+    | { kind: 'mount'; at: URL; found: Found<RouteRow> }
+
+/** An outcome that loads nothing, which either call can answer. */
+export type Settled<RouteRow> =
+    | { kind: 'document'; href: string }
+    | { kind: 'follow'; at: URL; found: Found<RouteRow> }
+
+/**
+ * Decides how a navigation ends, from what it knows: called once before the ask, and once more
+ * with what was `heard` where the first call answered `ask`.
+ *
+ * Decides and touches nothing — the router executes the answer. A `mount` whose `found` is not
+ * `heard.found` lands on a route whose chunks were not loaded yet, and the router hands that
+ * address to the document where they will not load (30.27).
+ */
+export function outcomeOf<RouteRow>(
+    bearing: Bearing<RouteRow>,
+): Settled<RouteRow> | Extract<Outcome<RouteRow>, { kind: 'ask' }>
+export function outcomeOf<RouteRow>(
+    bearing: Bearing<RouteRow>,
+    heard: Heard<RouteRow>,
+): Settled<RouteRow> | Extract<Outcome<RouteRow>, { kind: 'offline' | 'mount' }>
+export function outcomeOf<RouteRow>(
+    bearing: Bearing<RouteRow>,
+    heard?: Heard<RouteRow>,
+): Outcome<RouteRow> {
+    const target = bearing.target
+    if (heard === undefined) {
+        // A CROSS-ORIGIN ADDRESS IS NOT A ROUTE. Handing it to `pushState` throws, and treating
+        // it as a miss would leave the caller with a navigation that silently did nothing.
+        if (target.origin !== bearing.origin || bearing.errorPage)
+            return { kind: 'document', href: target.href }
+        const found = bearing.match(target.pathname)
+        // 30.10 — NOT A ROUTE THIS BUILD KNOWS, so it is the server's to answer — which is a
+        // document load, and the one case where 30.7 does not apply because there is no route.
+        if (found === undefined) return { kind: 'document', href: target.href }
+        // 30.21, 30.23, 30.24 — THE ROUTE STANDING, AT ITS OWN PATH: another query, another
+        // fragment or the same address. The page reads its address through `route`, so it follows
+        // rather than being rebuilt, and there is no path for `middleware` to decide anything new
+        // about.
+        if (
+            found.route === bearing.standing &&
+            bearing.mounted === target.pathname
+        )
+            return { kind: 'follow', at: target, found }
+        return { kind: 'ask', found }
+    }
+    const answer = heard.answer
+    // 30.32 — OFFLINE, THE DOCUMENT LOAD BELOW CAN ONLY PAINT THE BROWSER'S ERROR PAGE over a page
+    // that works. A history step has already moved the bar, so it is left to the document.
+    if (answer === undefined && !heard.online && heard.pushed)
+        return { kind: 'offline', href: target.href }
+    // 30.18 — A REFUSAL, A RESPONSE MIDDLEWARE ANSWERED ITSELF, or no answer at all: the document
+    // asks again and paints whatever the server says. A fetch that failed — offline, or a redirect
+    // to another origin that CORS will not let it follow — goes to the address it was sent to.
+    // 30.27 — AND CHUNKS THAT WOULD NOT LOAD, with the server down or a deploy that removed them.
+    if (answer?.status !== 204 || !heard.loaded)
+        return { kind: 'document', href: answer?.url ?? target.href }
+    // 30.17 — REDIRECTED, and the server already said yes to where it landed: the answer is the
+    // 204 at the end of the chain. That address is mounted in place of the one asked for, and a
+    // route the client has no row for is the document's (30.10).
+    const landed = answer.redirected ? new URL(answer.url) : target
+    const landing = answer.redirected
+        ? bearing.match(landed.pathname)
+        : heard.found
+    if (landing === undefined) return { kind: 'document', href: landed.href }
+    // 30.23 — THE ROUTE STANDING, AT ANOTHER PATH: `middleware` has said yes to the path, and the
+    // page it matched is the one already mounted, so it follows.
+    if (landing.route === bearing.standing)
+        return { kind: 'follow', at: landed, found: landing }
+    return { kind: 'mount', at: landed, found: landing }
+}

package/src/ui/socketWire.ts

@@ -8,15 +8,15 @@ import { mounted } from '#shared/mount.ts'
 import type { BrowserFrame, ServerFrame } from '#shared/muxFrames.ts'
 import { onPrincipalRotated } from '#shared/principalRotated.ts'
 import { canonicalKey } from '#shared/reactive/argsContract.ts'
+import { type Reactive } from '#shared/reactive/index.ts'
+import { patchEpoch, writtenSince } from '#shared/reactive/patchMarks.ts'
 import {
     heldGenerationOf,
     loadOf,
     patchInto,
     produceInto,
-    type Reactive,
     writtenLocally,
-} from '#shared/reactive/index.ts'
-import { patchEpoch, writtenSince } from '#shared/reactive/patchMarks.ts'
+} from '#shared/reactive/producer.ts'
 
 import { HYDRATE_LOG } from './Mismatch.ts'
 import { undelivered, whenDelivered } from './outboxQueue.ts'

package/src/ui/wire.ts

@@ -29,13 +29,13 @@ import { isFailed } from '#shared/Failed.ts'
 import { answerChunks } from '#shared/framing.ts'
 import { HandlerRoute } from '#shared/HandlerRoute.ts'
 import type { JsonValue } from '#shared/JsonValue.ts'
-import { LOAD_OFFLINE } from '#shared/LOAD_OFFLINE.ts'
-import { LOAD_SIGNAL } from '#shared/LOAD_SIGNAL.ts'
-import { reactive, standIn, structural } from '#shared/reactive/index.ts'
+import { standForLoadCall, startingLoadCall } from '#shared/loadCall.ts'
+import { reactive, structural } from '#shared/reactive/index.ts'
 import {
     declareDefaults,
     type Defaults,
 } from '#shared/reactive/parameterDefaults.ts'
+import { standIn } from '#shared/reactive/producer.ts'
 import { declare, type Method } from '#shared/rpc.ts'
 import { type RpcRequest, rpcRequest } from '#shared/rpcRequest.ts'
 
@@ -72,11 +72,11 @@ export function wire(
     // ONE PARAMETER, so the value is keyed by args whatever the handler declared (16.6's arity rule):
     // an unkeyed handler is reached with no args, which is one key.
     const body = (args: Record<string, unknown> | undefined) => {
-        // 16.49, 16.81 — the load's own signal and stand-in, set by the call starting it and read
-        // before anything awaits.
-        const signal = LOAD_SIGNAL.current
+        // 16.49, 16.81 — the load's own signal and stand-in, as the call starting it carried them.
+        const starting = startingLoadCall()
+        const signal = starting.signal
         const request = requestOf(args)
-        let offline = LOAD_OFFLINE.current
+        let offline = starting.offline
         // A reload no call started — a refresh, or the one `whenOnline` asks — that gets no answer
         // waits before asking again, where asking at once would get none on every tick.
         const retryIn = offline === undefined ? UNANSWERED_RETRY_MS : 0
@@ -93,8 +93,7 @@ export function wire(
                 ? queuedCall(request, address, args)
                 : undefined
         let standing: { value: unknown } | undefined
-        if (queued !== undefined)
-            LOAD_OFFLINE.standing = standing = { value: undefined }
+        if (queued !== undefined) standing = standForLoadCall()
         const stoodIn = (failed: Answer): unknown => {
             const value = (offline as (args: unknown) => unknown)(args)
             if (queued === undefined) {
@@ -145,7 +144,7 @@ export function wire(
     ): AsyncGenerator<unknown> {
         // 16.49 — read on the first line: the core's pump takes the first step inside the reach, so
         // this runs while the call that started the load still has its signal set.
-        const signal = LOAD_SIGNAL.current
+        const signal = startingLoadCall().signal
         const request = requestOf(args)
         const answer = await answerOf(request, true, signal)
         if (answer.ok) answeredOnce.add(request.key)

package/src/shared/LOAD_OFFLINE.ts

@@ -1,15 +0,0 @@
-/**
- * The `offline` of the call that is starting a load, while it starts.
- *
- * 16.81 — SET AROUND THE REACH as `LOAD_SIGNAL` is, and read by the browser's wire as its body
- * starts: what stands in for an answer the call could not get. A leaf, because `callLoad` sets it
- * and the wire reads it.
- */
-export const LOAD_OFFLINE: {
-    current: ((args: unknown) => unknown) | undefined
-    /**
-     * Where the body that queues the call asks for the value the call reached, which `callLoad`
-     * fills once the reach returns: what the delivered answer lands in (46.7).
-     */
-    standing: { value: unknown } | undefined
-} = { current: undefined, standing: undefined }

package/src/shared/LOAD_SIGNAL.ts

@@ -1,10 +0,0 @@
-/**
- * The abort signal of the call that is starting a load, while it starts.
- *
- * 16.49 — THE SIGNAL OF THE CALL THAT IS STARTING A LOAD, set around the reach and read by a
- * transport's body as it starts: the browser's wire hands it to `fetch`, so a load every caller
- * aborted ends its request too. A leaf, because `callLoad` sets it and the wire reads it.
- */
-export const LOAD_SIGNAL: { current: AbortSignal | undefined } = {
-    current: undefined,
-}

package/src/shared/issuesOf.ts

@@ -1,18 +0,0 @@
-/**
- * Issues in the shape `Issues<T>` gives them for the value refused: by path for an object or an
- * array, the bare list for anything else.
- *
- * DECIDED BY THE VALUE, because the value is all the runtime holds — `T` is erased. A scalar has
- * no path to key by, so every issue about one stands on `''`, and handing back `{ '': [...] }`
- * there is the wrapper `Issues<T>` says a reader never unwraps: `error().data[0]` read `undefined`.
- */
-export function issuesOf(
-    found: Record<string, string[]>,
-    value: unknown,
-): Record<string, string[]> | string[] {
-    if (typeof value === 'object' && value !== null) return found
-    const listed: string[] = []
-    for (const path in found)
-        for (const said of found[path] as string[]) listed.push(said)
-    return listed
-}

package/src/shared/reactive/ENTRY_LIVES.ts

@@ -1,7 +0,0 @@
-/**
- * When each entry of a `Keyed` declaring `ttl` last produced, and how long it lives, by entry cell.
- *
- * 11.45. A leaf because `Keyed.ts` writes it and `Reactive.ts` reads it (`deadlineOf`), and the
- * second cannot import the first.
- */
-export const ENTRY_LIVES = new WeakMap<object, { at: number; ms: number }>()