@abide/abide 0.124.0 → 0.125.0

package/src/shared/route.ts

@@ -1,4 +1,4 @@
-// 23.1 — WHERE WE ARE, as four values rather than one over a composite, so a reader of `params`
+// 23.1 — WHERE WE ARE, as five 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
@@ -7,23 +7,37 @@
 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`. */
+/**
+ * The current address: its `url`, `params`, pattern `name`, its `index` in this document's history,
+ * 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>(),
+    /**
+     * 23.28, 23.29 — the entry's place in the history this app's router wrote: 0 where a document
+     * load arrived, and one past the entry it was pushed from.
+     */
+    index: ambient(0),
     navigating: ambient(false),
 }
 
 /**
- * Sets `route`'s url, params and name to an address just resolved.
+ * Sets `route`'s url, params, name and index 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 {
+export function arrive(
+    at: string,
+    pattern: string,
+    params: Params,
+    index: number,
+): void {
     route.url.set(new URL(at))
     route.params.set(params)
     route.name.set(pattern)
+    route.index.set(index)
 }

package/src/shared/rpc.ts

@@ -183,9 +183,44 @@ export type RpcContext<Args = unknown> = { request: Request; args: () => Args }
  */
 const SENT: unique symbol = Symbol('abide.sent')
 
-export type RpcOptions<Args = unknown> = {
+/**
+ * What a rung's `next` answers as a declaration types it: opaque, so what the rung answers in the
+ * handler's place is told apart from the answer it passes on.
+ */
+declare const REACHED: unique symbol
+type Reached = { readonly [REACHED]: true }
+
+/**
+ * The refusals a declaration's rungs answer with, read off what each answers.
+ *
+ * 16.86 — A REFUSAL A RUNG NAMES IS THE `Rpc`'s, and one it does not name is not: a `Failed` whose
+ * name is `string` (a `Middleware` declaring no refusals) would widen every name the union narrows
+ * by, and a rung answering `unknown` names none.
+ */
+type RungRefusals<Answers extends readonly unknown[]> =
+    Answers[number] extends infer Answer
+        ? Answer extends Failed<infer Name, unknown>
+            ? string extends Name
+                ? never
+                : Answer
+            : never
+        : never
+
+export type RpcOptions<
+    Args = unknown,
+    Answers extends readonly unknown[] = unknown[],
+> = {
     description?: string
-    middleware?: Rung<RpcContext<Args>, unknown>[]
+    /**
+     * 16.86 — one rung per answer in `Answers`, each read in context: a rung's own refusals are
+     * inferred where the list is written at the declaration.
+     */
+    middleware?: {
+        [At in keyof Answers]: (
+            next: (ctx?: RpcContext<Args>) => Promise<Reached>,
+            ctx: RpcContext<Args>,
+        ) => Answers[At] | Promise<Answers[At]>
+    }
     timeout?: number
     clients?: Clients
     crossOrigin?: boolean | string[]
@@ -221,20 +256,34 @@ type Held<Accepted> = Accepted extends
  * which is why a value handed in takes the address's alone: it has decided its own.
  */
 type Declare = {
-    <Stored, Args, Accepted, Failures, Produced>(
+    <
+        Stored,
+        Args,
+        Accepted,
+        Failures,
+        Produced,
+        Answers extends readonly unknown[] = unknown[],
+    >(
         handler: Keyed<Stored, Args, Accepted, Failures, Produced>,
-        options?: RpcOptions<Args>,
-    ): Rpc<Stored, Args, Failures, Produced>
-    <Stored, Accepted, Failures, Produced>(
+        options?: RpcOptions<Args, Answers>,
+    ): Rpc<Stored, Args, Failures | RungRefusals<Answers>, Produced>
+    <
+        Stored,
+        Accepted,
+        Failures,
+        Produced,
+        Answers extends readonly unknown[] = unknown[],
+    >(
         handler: Reactive<Stored, Accepted, Failures, Produced>,
-        options?: RpcOptions<undefined>,
-    ): Rpc<Stored, undefined, Failures, Produced>
+        options?: RpcOptions<undefined, Answers>,
+    ): Rpc<Stored, undefined, Failures | RungRefusals<Answers>, Produced>
     // 11.2 — a stream whose parameter is optional is keyed, for `reactive`'s reason.
     <
         Body extends (args?: never) => unknown,
         Shaped = ChunkOf<Body>[],
         Gate = Schema<ChunkOf<Body>[]>,
         ArgsGate = Schema<Parameters<Body>[0]>,
+        Answers extends readonly unknown[] = unknown[],
     >(
         handler: Body & OptionalParameter<Body> & Streams<Body> & Plain,
         options?: Shaping<
@@ -244,36 +293,49 @@ type Declare = {
             Gate,
             ArgsGate
         > &
-            RpcOptions<Parameters<Body>[0]>,
+            RpcOptions<Parameters<Body>[0], Answers>,
     ): Rpc<
         Kept<Shaped>,
         Parameters<Body>[0],
-        Refusals<Shaped, Gate, ChunkOf<Body>[], ArgsGate, Parameters<Body>[0]>,
+        | Refusals<Shaped, Gate, ChunkOf<Body>[], ArgsGate, Parameters<Body>[0]>
+        | RungRefusals<Answers>,
         ChunkOf<Body>
     >
-    <Chunk, Shaped = Chunk[], Gate = Schema<Chunk[]>>(
+    <
+        Chunk,
+        Shaped = Chunk[],
+        Gate = Schema<Chunk[]>,
+        Answers extends readonly unknown[] = unknown[],
+    >(
         handler: (() =>
             AsyncGenerator<Chunk> | Promise<AsyncGenerator<Chunk>>) &
             Plain,
-        options?: Shaping<Chunk[], Shaped, never, Gate> & RpcOptions<undefined>,
-    ): Rpc<Kept<Shaped>, undefined, Refusals<Shaped, Gate, Chunk[]>, Chunk>
+        options?: Shaping<Chunk[], Shaped, never, Gate> &
+            RpcOptions<undefined, Answers>,
+    ): Rpc<
+        Kept<Shaped>,
+        undefined,
+        Refusals<Shaped, Gate, Chunk[]> | RungRefusals<Answers>,
+        Chunk
+    >
     <
         Chunk,
         Args,
         Shaped = Chunk[],
         Gate = Schema<Chunk[]>,
         ArgsGate = Schema<Args>,
+        Answers extends readonly unknown[] = unknown[],
     >(
         handler: ((
             args: Args,
         ) => AsyncGenerator<Chunk> | Promise<AsyncGenerator<Chunk>>) &
             Plain,
         options?: Shaping<Chunk[], Shaped, Args, Gate, ArgsGate> &
-            RpcOptions<Args>,
+            RpcOptions<Args, Answers>,
     ): Rpc<
         Kept<Shaped>,
         Args,
-        Refusals<Shaped, Gate, Chunk[], ArgsGate, Args>,
+        Refusals<Shaped, Gate, Chunk[], ArgsGate, Args> | RungRefusals<Answers>,
         Chunk
     >
     // 11.2 — an optional parameter is keyed, and ahead of the arm below for `reactive`'s reason.
@@ -282,6 +344,7 @@ type Declare = {
         Shaped = Awaited<ReturnType<Body>>,
         Gate = Schema<Awaited<ReturnType<Body>>>,
         ArgsGate = Schema<Parameters<Body>[0]>,
+        Answers extends readonly unknown[] = unknown[],
     >(
         handler: Body & OptionalParameter<Body> & Plain,
         options?: Shaping<
@@ -291,7 +354,7 @@ type Declare = {
             Gate,
             ArgsGate
         > &
-            RpcOptions<Parameters<Body>[0]>,
+            RpcOptions<Parameters<Body>[0], Answers>,
     ): Rpc<
         Kept<Shaped>,
         Parameters<Body>[0],
@@ -302,17 +365,25 @@ type Declare = {
               Awaited<ReturnType<Body>>,
               ArgsGate,
               Parameters<Body>[0]
-          >,
+          >
+        | RungRefusals<Answers>,
         AdoptedProduced<ReturnType<Body>, Kept<Shaped>>
     >
-    <Computed, Shaped = Awaited<Computed>, Gate = Schema<Awaited<Computed>>>(
+    <
+        Computed,
+        Shaped = Awaited<Computed>,
+        Gate = Schema<Awaited<Computed>>,
+        Answers extends readonly unknown[] = unknown[],
+    >(
         handler: (() => Computed) & Plain,
         options?: Shaping<Awaited<Computed>, Shaped, never, Gate> &
-            RpcOptions<undefined>,
+            RpcOptions<undefined, Answers>,
     ): Rpc<
         Kept<Shaped>,
         undefined,
-        AdoptedFailures<Computed> | Refusals<Shaped, Gate, Awaited<Computed>>,
+        | AdoptedFailures<Computed>
+        | Refusals<Shaped, Gate, Awaited<Computed>>
+        | RungRefusals<Answers>,
         AdoptedProduced<Computed, Kept<Shaped>>
     >
     <
@@ -321,23 +392,34 @@ type Declare = {
         Shaped = Awaited<Computed>,
         Gate = Schema<Awaited<Computed>>,
         ArgsGate = Schema<Args>,
+        Answers extends readonly unknown[] = unknown[],
     >(
         handler: ((args: Args) => Computed) & Plain,
         options?: Shaping<Awaited<Computed>, Shaped, Args, Gate, ArgsGate> &
-            RpcOptions<Args>,
+            RpcOptions<Args, Answers>,
     ): Rpc<
         Kept<Shaped>,
         Args,
         | AdoptedFailures<Computed>
-        | Refusals<Shaped, Gate, Awaited<Computed>, ArgsGate, Args>,
+        | Refusals<Shaped, Gate, Awaited<Computed>, ArgsGate, Args>
+        | RungRefusals<Answers>,
         AdoptedProduced<Computed, Kept<Shaped>>
     >
     // 16.1 — a value, `reactive`'s value overload given an address. Last, so a function is a body.
-    <Accepted, Shaped = Accepted, Gate = Schema<Accepted>>(
+    <
+        Accepted,
+        Shaped = Accepted,
+        Gate = Schema<Accepted>,
+        Answers extends readonly unknown[] = unknown[],
+    >(
         handler: Held<Accepted>,
         options?: Shaping<Accepted, Shaped, never, Gate> &
-            RpcOptions<undefined>,
-    ): Rpc<Kept<Shaped>, undefined, Refusals<Shaped, Gate, Accepted>>
+            RpcOptions<undefined, Answers>,
+    ): Rpc<
+        Kept<Shaped>,
+        undefined,
+        Refusals<Shaped, Gate, Accepted> | RungRefusals<Answers>
+    >
 }
 
 /** What a handler's selection members answer before a call has built its value: no entries' answers. */
@@ -379,7 +461,11 @@ export function declare(method: Method): Declare {
         // 16.11, 16.12 — THE RUNGS, IN REGISTRATION ORDER, around the reach. Built once, at the
         // declaration (16.14); a value keyed by args, so a second call with the same args in one
         // request joins the first (1.8) and a server files one per request (11.32).
-        const rungs = options?.middleware ?? []
+        // `Reached` is the declaration's view of `next`; at run time it answers the handler's value.
+        const rungs = (options?.middleware ?? []) as readonly Rung<
+            RpcContext,
+            unknown
+        >[]
         // A rung that handed `next` a context of its own making chose those args.
         const argsOf = (ctx: RpcContext): unknown =>
             SENT in ctx ? (ctx as { [SENT]: unknown })[SENT] : ctx.args()

package/src/shared/seededDocument.ts

@@ -22,13 +22,12 @@ export function seededDocument<Document>(
     | Document
     | Failed<string, unknown>
     | Promise<Document | Failed<string, unknown>> {
-    const answer = answerOf(
-        rpcRequest('GET', mounted(address), undefined),
-        false,
-        undefined,
-    )
+    const request = rpcRequest('GET', mounted(address), undefined)
+    const answer = answerOf(request, false, undefined)
     return (
-        answer instanceof Promise ? answer.then(answered) : answered(answer)
+        answer instanceof Promise
+            ? answer.then((settled) => answered(settled, request))
+            : answered(answer, request)
     ) as
         | Document
         | Failed<string, unknown>

package/src/shared/storedValue.ts

@@ -0,0 +1,32 @@
+import { isRecord } from './isRecord.ts'
+import { runSchema, type Schema } from './Schema.ts'
+
+/** The deadline a value written now with `ttl` runs out at, `null` where it never does (8.26). */
+export function expiresAfter(ttl: number): number | null {
+    return Number.isFinite(ttl) ? Date.now() + ttl : null
+}
+
+/**
+ * The value a shipped store read back, `undefined` where its `ttl` has passed.
+ *
+ * 8.27 — THE `schema` A RESTORE SKIPS (8.5) RUNS HERE, on what was read: a refusal throws, which
+ * the value takes as a miss and warns about (8.15) — an entry an older build wrote is one an app
+ * wants to hear about rather than serve. Shared by `webStore` and the server's `sqliteStore`.
+ */
+export function storedValue(
+    kept: unknown,
+    schema: Schema<unknown> | undefined,
+    where: string,
+): unknown {
+    if (!isRecord(kept) || !('value' in kept))
+        throw new Error(`${where} holds something no abide store wrote.`)
+    const expires = kept.expires
+    if (typeof expires === 'number' && expires <= Date.now()) return undefined
+    if (schema === undefined) return kept.value
+    const checked = runSchema(schema, kept.value)
+    if (checked.issues !== null)
+        throw new Error(
+            `${where} holds a value its schema refuses: ${JSON.stringify(checked.issues)}`,
+        )
+    return checked.value
+}

package/src/shared/webStore.ts

@@ -0,0 +1,54 @@
+import type { Store } from './reactive/index.ts'
+import type { Schema } from './Schema.ts'
+import { expiresAfter, storedValue } from './storedValue.ts'
+
+/**
+ * A `Store` kept in this browser's `localStorage`, or its `sessionStorage`, under `key`.
+ *
+ * 8.23 — WHERE THERE IS NO WEB STORAGE, A SERVER, THE STORE IS INERT: every `get` a miss and every
+ * `set` nothing, so the value a server renders is the one it would render with no store (8.3).
+ * The storage is looked up on each call rather than held, since a browser that refuses storage
+ * throws on the lookup — and a throw there is 8.15's miss and 8.12's warning, not a broken module.
+ */
+export function webStore<Stored>(
+    key: string,
+    options?: { area?: 'local' | 'session'; schema?: Schema<Stored> },
+): Store<Stored> {
+    const name = options?.area === 'session' ? 'sessionStorage' : 'localStorage'
+    const schema = options?.schema as Schema<unknown> | undefined
+    const where = `${name}[${JSON.stringify(key)}]`
+    const area = (): Storage | undefined =>
+        (globalThis as unknown as Record<string, Storage | undefined>)[name]
+    return {
+        get: () => {
+            const storage = area()
+            if (storage === undefined) return undefined
+            const text = storage.getItem(key)
+            if (text === null) return undefined
+            const value = storedValue(JSON.parse(text), schema, where)
+            // 8.26 — an entry past its deadline is gone, not merely skipped.
+            if (value === undefined) storage.removeItem(key)
+            return value as Stored | undefined
+        },
+        set: (value, retention) => {
+            area()?.setItem(
+                key,
+                JSON.stringify({ value, expires: expiresAfter(retention.ttl) }),
+            )
+        },
+        // 8.24 — another document's write arrives as a `storage` event; this document's own never does.
+        watch: (changed) => {
+            if (typeof globalThis.addEventListener !== 'function')
+                return () => {}
+            const listener = (event: StorageEvent): void => {
+                if (
+                    event.storageArea === area() &&
+                    (event.key === key || event.key === null)
+                )
+                    changed()
+            }
+            globalThis.addEventListener('storage', listener)
+            return () => globalThis.removeEventListener('storage', listener)
+        },
+    }
+}

package/src/ui/Router.ts

@@ -105,7 +105,12 @@ export class Router {
      * nothing hydrates over it, and leaving it is a document load.
      */
     private readonly errorPage: boolean
-    /** The place in this document's history of the entry the address bar stands at (`Entry`). */
+    /**
+     * The place in this document's history of the entry the address bar stands at (`Entry`).
+     *
+     * 23.28 — `route.index` IS THIS, moved where `route.url` is (`arrive`) rather than here: a back
+     * step moves this before the page it arrives at has loaded.
+     */
     private index: number
     /**
      * 30.29 — the scroll each entry was left at, by its `index`.
@@ -127,6 +132,14 @@ export class Router {
      * Read off the compiled `<style>` blocks. Nothing here looks at the document's stylesheets.
      */
     private readonly transitions: boolean
+    /**
+     * 30.38 — what settles each `step` still waiting on the browser to say it has arrived.
+     *
+     * Settled ALL AT ONCE by the next arrival, rather than one per `popstate`: a browser that folds
+     * two queued `history.go`s into one traversal fires one event, and a step waiting for a second
+     * would never settle.
+     */
+    private readonly stepping: (() => void)[]
 
     constructor(region: Region, routes: Compiled[], transitions: boolean) {
         this.region = region
@@ -146,6 +159,7 @@ export class Router {
         this.scrolls = []
         this.prefetched = new Set()
         this.transitions = transitions
+        this.stepping = []
     }
 
     /**
@@ -199,12 +213,31 @@ export class Router {
      * within the standing page, back over an in-page `#anchor` jump, is `follow`'s: nothing asked,
      * nothing remounted. 30.29 — the scroll is put back once the page it belongs to is mounted.
      */
-    popped(): Promise<void> {
-        return this.travel(
-            location.href,
-            { replace: true, keepScroll: true },
-            this.stepped(),
-        )
+    async popped(): Promise<void> {
+        try {
+            await this.travel(
+                location.href,
+                { replace: true, keepScroll: true },
+                this.stepped(),
+            )
+        } finally {
+            for (const arrived of this.stepping.splice(0)) arrived()
+        }
+    }
+
+    /**
+     * Steps the history by `by` entries, settling once the entry stepped to is arrived at.
+     *
+     * 30.38 — THE BROWSER MOVES THE BAR LATER and says so only by `popstate`, so the step settles in
+     * `popped`, once the arriving page is mounted and its scroll put back. 30.39 — `history.go(0)`
+     * reloads the document, which no `navigate` does, so a step of none is over before it starts.
+     */
+    step(by: number): Promise<void> {
+        if (by === 0) return Promise.resolve()
+        return new Promise((arrived) => {
+            this.stepping.push(arrived)
+            history.go(by)
+        })
     }
 
     /** `go`, arriving as `step` says: a push, or a history step with the scroll it restores. */
@@ -313,7 +346,7 @@ export class Router {
             options.replace === true || target.href === location.href,
             [scrollX, scrollY],
         )
-        arrive(target.href, found.route.pattern, found.params)
+        arrive(target.href, found.route.pattern, found.params, this.index)
         this.mounted = target.pathname
         if (step.scroll !== undefined) scrollTo(step.scroll[0], step.scroll[1])
         else if (options.keepScroll !== true && target.hash !== '')
@@ -500,7 +533,7 @@ export class Router {
      * 23.1 — WRITTEN BEFORE THE ARRIVING PAGE'S SETUP, which reads it.
      */
     private arriveAt(target: URL, found: Found<Compiled>): void {
-        arrive(target.href, found.route.pattern, found.params)
+        arrive(target.href, found.route.pattern, found.params, this.index)
         this.standing = found.route
         this.mounted = target.pathname
     }

package/src/ui/outboxQueue.ts

@@ -186,7 +186,7 @@ async function sendLine(): Promise<void> {
                 retryLater()
                 return
             }
-            const value = answeredValue(answer)
+            const value = answeredValue(answer, call)
             if (isFailed(value)) {
                 call.error = problemOf(value)
                 await shelf.put(call)

package/src/ui/wire.ts

@@ -101,7 +101,7 @@ export function wire(
                 return standIn(value)
             }
             return enqueue(queued, standing as { value: unknown }, value).then(
-                (kept) => (kept ? standIn(value) : answered(failed)),
+                (kept) => (kept ? standIn(value) : answered(failed, request)),
             )
         }
         // 16.83 — BEHIND CALLS NOT YET DELIVERED A CALL WAITS ITS TURN, rather than overtaking them.
@@ -120,9 +120,9 @@ export function wire(
             // asked of the network once there is one.
             if (answer.kept) {
                 whenOnline(args, 0)
-                return standIn(answered(answer))
+                return standIn(answered(answer, request))
             }
-            return answered(answer)
+            return answered(answer, request)
         }
         const answer = answerOf(request, false, signal)
         return answer instanceof Promise ? answer.then(settle) : settle(answer)
@@ -153,7 +153,7 @@ export function wire(
             yield* answerChunks(answer.body, answer.framing)
             return
         }
-        const value = answered(answer)
+        const value = answered(answer, request)
         if (isFailed(value)) throw value
         if (Array.isArray(value)) yield* value
     }

package/src/shared/KEEP_OPENED.ts

@@ -1,7 +0,0 @@
-/**
- * The value of the offline worker's `abide-keep` header on the page a navigation opens, which then
- * hydrates and so is seeded as one (41.29, 45.23) — a page saved behind the one opened is not.
- *
- * A leaf, because the server writes it into the worker's script and reads it off the request.
- */
-export const KEEP_OPENED = 'open'