@abide/abide 0.114.0 → 0.115.0

package/src/shared/reactive/Reactive.ts

@@ -225,6 +225,7 @@ export type Reactive<
     busy(): boolean
     ready(): boolean
     error(): Failures | undefined
+    synced(): boolean
     /**
      * Narrows a caught error to this value's failure of that name.
      *
@@ -731,6 +732,13 @@ class Cell {
     declare tags: string[] | null
     /** Whether `declare` built this value for a mutation, which a sweep invalidates (13.16). */
     declare mutation: boolean
+    /**
+     * Whether what is held was written here since the producer last produced (3.10).
+     *
+     * Only ever true on a value with a body: a value with no producer has nothing to be out of
+     * step with (3.12). Moved by `writtenHere` and `producedAgain` alone, each owning its probe move.
+     */
+    declare local: boolean
     /** `null` on every value declaring no `store`, which is what keeps `serve` from persisting. */
     declare store: Persisted | null
     /**
@@ -881,6 +889,7 @@ class Cell {
                   : tags
         this.mutation =
             (options as { [MUTATION]?: true } | undefined)?.[MUTATION] === true
+        this.local = false
         const store = options?.store
         this.store =
             store === undefined
@@ -1518,6 +1527,9 @@ function drainPending(): void {
  * One production. A write that `identity` deems a repeat mints nothing and wakes nobody (5.2).
  */
 function produce(cell: Cell, produced: unknown): number {
+    // 3.11 — A PRODUCTION THE PRODUCER MADE puts the value back in step; one a write here made is
+    // `writtenHere`'s to report, after it lands.
+    if (cell.local && WRITING === 0) producedAgain(cell)
     // 7.9: AN ACCEPTED PRODUCTION SETTLES THE RELOAD AN INVALIDATE OWED — ahead of the gate, since
     // a write 5.2 collapses was still accepted. Left standing, the next read unserved this value
     // and reloaded over it. A look above (`OWES_ABOVE`) is not this value's mark and stays: 11.8
@@ -2048,6 +2060,13 @@ function absorb(cell: Cell, result: unknown, answered: boolean): void {
             else if (isAsyncGenerator(settled)) {
                 promoteToStream(cell, settled)
                 probesMoved(cell)
+            }
+            // 3.10 — WHAT A WRITE HERE SETTLED TO, and a body's stand-in for an answer it could not
+            // get (16.81), are held as written here rather than produced.
+            else if (!answered) acceptHere(cell, settled)
+            else if (settled instanceof StandIn) {
+                acceptHere(cell, settled.value)
+                writtenHere(cell)
             } else accept(cell, settled)
         },
         (failed) => {
@@ -2414,6 +2433,13 @@ function run(cell: Cell): void {
         promoteToStream(cell, produced)
         return
     }
+    // 16.81 — a stand-in the body could hand back at once: an answer a page started early (41.21)
+    // that the worker answered from a kept copy (16.85).
+    if (!primitive && produced instanceof StandIn) {
+        acceptHere(cell, produced.value)
+        writtenHere(cell)
+        return
+    }
     if (
         cell.bareWrite &&
         typeof (produced as PromiseLike<unknown>).then !== 'function'
@@ -2654,6 +2680,7 @@ function beginAccumulation(cell: Cell, stream: Stream): void {
  * whatever `identity` says about its last element.
  */
 function acceptChunk(cell: Cell, stream: Stream, chunk: unknown): void {
+    if (cell.local) producedAgain(cell)
     stream.chunks.push(chunk)
     cell.ordinal += 1
     // 3.8: `ready` from the first chunk, and `error` cleared by an accepted production (4.11).
@@ -3242,6 +3269,147 @@ function readyNow(cell: Cell): boolean {
     return walkReady(cell, PROBE_PASS)
 }
 
+/**
+ * Whether this value and everything it reads or adopts holds what its producer made (3.10, 3.13).
+ *
+ * `ready`'s quantifier, and for `ready`'s reason: a figure computed from a value written here is no
+ * more the producer's than that value is.
+ */
+function walkSynced(cell: Cell, pass: number): boolean {
+    if (cell.local) return false
+    const adoption = cell.adoption
+    if (cell.sources.length === 0 && adoption === null) return true
+    if (cell.probePass === pass) return true
+    cell.probePass = pass
+    if (adoption !== null && !walkSynced(adoption.source, pass)) return false
+    const sources = cell.sources
+    for (let index = 0; index < sources.length; index += 1)
+        if (!walkSynced(sources[index] as Cell, pass)) return false
+    return true
+}
+
+function syncedNow(cell: Cell): boolean {
+    if (cell.local) return false
+    if (cell.sources.length === 0 && cell.adoption === null) return true
+    PROBE_PASS += 1
+    return walkSynced(cell, PROBE_PASS)
+}
+
+/**
+ * How many writes made here are on the stack, which `produce` reads to tell one from a production.
+ *
+ * A COUNT RATHER THAN A FLAG, so a write made from inside another's gate — a `transform` writing a
+ * second value — leaves the outer one's mark standing when it returns.
+ */
+let WRITING = 0
+
+/** 3.10 — marks a value with a producer as written here, telling the guards that asked. */
+function writtenHere(cell: Cell): void {
+    if (cell.body === null || cell.local) return
+    cell.local = true
+    probesMoved(cell)
+}
+
+/** 3.11 — puts a value back in step with its producer, telling the guards that asked. */
+function producedAgain(cell: Cell): void {
+    if (!cell.local) return
+    cell.local = false
+    probesMoved(cell)
+}
+
+/** `accept`, as a write made here rather than a production. */
+function acceptHere(cell: Cell, value: unknown): unknown {
+    WRITING += 1
+    try {
+        return accept(cell, value)
+    } finally {
+        WRITING -= 1
+    }
+}
+
+/**
+ * A write over a value with a body: held as written here where it moved what is held (3.10).
+ *
+ * A WRITE THE IDENTITY GATE COLLAPSED MOVED NOTHING, so it leaves the value as in step as it was; a
+ * write that settles later is marked now, being a write here whenever it lands.
+ */
+function setOverProducer(cell: Cell, value: unknown): unknown {
+    const ordinal = cell.ordinal
+    cell.generation += 1
+    WRITING += 1
+    let answer: unknown
+    try {
+        answer = setThroughGates(cell, value)
+    } finally {
+        WRITING -= 1
+    }
+    if (
+        answer === undefined &&
+        !isReactive(value) &&
+        (cell.ordinal !== ordinal || isThenable(value))
+    )
+        writtenHere(cell)
+    return answer
+}
+
+/**
+ * What a body hands back in place of an answer it could not get: held as written here (16.81).
+ *
+ * A CLASS, so the one test that tells it from a value is `instanceof`, made only on the arm that
+ * settles a body's promise.
+ */
+class StandIn {
+    value: unknown
+    constructor(value: unknown) {
+        this.value = value
+    }
+}
+
+/** A body's stand-in for the answer it could not get, which `synced` reads false over (16.81). */
+export function standIn(value: unknown): unknown {
+    return new StandIn(value)
+}
+
+/**
+ * Writes `value` as its producer made it, putting it back in step (3.11).
+ *
+ * WHAT A FOLLOWED COPY IS SENT IS THE PRODUCER'S, whoever carries it in: the server's value
+ * arriving over the mux is a production of the copy, not a write made here (18.10).
+ */
+export function produceInto(value: Reactive<unknown>, next: unknown): void {
+    const cell = (value as unknown as Callable)[CELL]
+    // A stream's write stands over its accumulation (9.11), as `STREAM_PROTOTYPE.set` makes it.
+    if (ownStream(cell) !== null) writeStream(cell, next)
+    else {
+        cell.generation += 1
+        setThroughGates(cell, next)
+    }
+    producedAgain(cell)
+}
+
+/** `produceInto` for a patch the producer sent (18.11). */
+export function patchInto(
+    value: Reactive<unknown>,
+    mutate: (value: unknown) => void,
+): void {
+    const cell = (value as unknown as Callable)[CELL]
+    patchCell(cell, mutate)
+    producedAgain(cell)
+}
+
+/**
+ * Refuses `value` as its producer did, leaving what it holds standing (46.7): a call queued under a
+ * stand-in that the server refused once it was delivered.
+ */
+export function refuseInto(value: Reactive<unknown>, failure: unknown): void {
+    refused((value as unknown as Callable)[CELL], failure)
+}
+
+/** Whether `value` holds what was written here, without subscribing — for a caller that is not a reader. */
+export function writtenLocally(value: Reactive<unknown>): boolean {
+    return (value as unknown as Callable)[CELL].local
+}
+
 /**
  * A promise of the value once it is servable and not busy, or of its failure.
  *
@@ -4140,6 +4308,13 @@ export function readyOver(tags: string[] | null): boolean {
     return true
 }
 
+/** Whether every value in the selection is in step with its producer; a reader subscribes to it. */
+export function syncedOver(tags: string[] | null): boolean {
+    trackSignal(tags)
+    for (const cell of inReach(tags)) if (!syncedNow(cell)) return false
+    return true
+}
+
 /**
  * Invalidates every value in the selection, and what each adopts.
  *
@@ -4221,6 +4396,11 @@ const MEMBERS = {
     ready(this: Callable): boolean {
         return isReady(this[CELL])
     },
+    synced(this: Callable): boolean {
+        const cell = this[CELL]
+        probe(cell)
+        return syncedNow(cell)
+    },
     error(this: Callable): unknown {
         const cell = this[CELL]
         // 3.3 ON THE THIRD PROBE. `error` is a probe by the rulebook's own term, so a body
@@ -4239,6 +4419,7 @@ const MEMBERS = {
     isError: isFailedNamed,
     set(this: Callable, value: unknown): unknown {
         const cell = this[CELL]
+        if (cell.body !== null) return setOverProducer(cell, value)
         cell.generation += 1
         // The settled, untransformed write is the overwhelming common shape, and the
         // general path is two call frames and a thenable probe behind it. Inlined here
@@ -4257,7 +4438,9 @@ const MEMBERS = {
         return setThroughGates(cell, value)
     },
     patch(this: Callable, mutate: (value: unknown) => void): void {
-        patchCell(this[CELL], mutate)
+        const cell = this[CELL]
+        patchCell(cell, mutate)
+        writtenHere(cell)
     },
     refresh(this: Callable): void {
         eachAdopted(this[CELL], refreshOne)
@@ -4514,7 +4697,15 @@ const STREAM_PROTOTYPE = brandedPrototype({
             if (cycle !== undefined) throw cycle
             return undefined
         }
-        return writeStream(cell, value)
+        WRITING += 1
+        let answer: unknown
+        try {
+            answer = writeStream(cell, value)
+        } finally {
+            WRITING -= 1
+        }
+        if (answer === undefined) writtenHere(cell)
+        return answer
     },
 })
 
@@ -4536,7 +4727,7 @@ const ADOPTING_PROTOTYPE = brandedPrototype({
     },
     patch(this: Callable, mutate: (value: unknown) => void): void {
         const adoption = this[CELL].adoption
-        if (adoption === null) patchCell(this[CELL], mutate)
+        if (adoption === null) MEMBERS.patch.call(this, mutate)
         else (adoption.source.callable as Reactive<unknown>).patch(mutate)
     },
 })
@@ -4587,6 +4778,9 @@ const SIMPLE_PROTOTYPE = brandedPrototype({
             }
             cell.value = value
             cell.ordinal += 1
+            // 3.10 — a write over a producer is one `synced` hears. Never a production here, so no
+            // `WRITING` count: the short write does not reach `produce`.
+            if (cell.body !== null) writtenHere(cell)
             // `setDirect`, with `plain` known true by `simple`.
             cell.direct = cell.state === CLEAN
             if (cell.readers.length !== 0) markReaders(cell, DIRTY)

package/src/shared/reactive/SELECTION_MEMBERS.ts

@@ -7,6 +7,7 @@
 export const SELECTION_MEMBERS = [
     'busy',
     'ready',
+    'synced',
     'refresh',
     'invalidate',
 ] as const

package/src/shared/reactive/callLoad.ts

@@ -7,6 +7,7 @@
 // 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_OFFLINE } from '../LOAD_OFFLINE.ts'
 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.
@@ -81,13 +82,18 @@ export function callLoad(
     args: unknown,
     signal: AbortSignal | undefined,
     timeout: number | undefined,
+    // 16.81 — read by a browser's wire as its body starts, and by nothing on a server (16.84).
+    offline?: (args: unknown) => unknown,
 ): unknown {
     const ending = signal === undefined ? undefined : new AbortController()
     LOAD_SIGNAL.current = ending?.signal
+    LOAD_OFFLINE.current = offline
     let reached: unknown
     let attended: Attended | undefined
     try {
         reached = reach(args)
+        const standing = LOAD_OFFLINE.standing
+        if (standing !== undefined) standing.value = reached
         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
@@ -101,6 +107,8 @@ export function callLoad(
             (reached as { refresh(): void }).refresh()
     } finally {
         LOAD_SIGNAL.current = undefined
+        LOAD_OFFLINE.current = undefined
+        LOAD_OFFLINE.standing = undefined
     }
     if (!isReactive(reached)) return reached
     const load = loadOf(reached)

package/src/shared/reactive/index.ts

@@ -15,6 +15,7 @@
 
 import type { Failed } from '../Failed.ts'
 import type { Issues } from '../Issues.ts'
+import { OUTBOX_SENDING } from '../OUTBOX_SENDING.ts'
 import { RPC_SERVER } from '../RPC_SERVER.ts'
 import type { Schema } from '../Schema.ts'
 import { isReactive } from './isReactive.ts'
@@ -29,6 +30,7 @@ import {
     type ReactiveOptions,
     readyOver,
     refreshOver,
+    syncedOver,
 } from './Reactive.ts'
 import { outsideScope, scoped } from './scoped.ts'
 import { share } from './share.ts'
@@ -50,13 +52,18 @@ export {
     isStreaming,
     loadOf,
     moveItem,
+    patchInto,
+    produceInto,
     type Reactive,
     type ReactiveOptions,
+    refuseInto,
     rowItem,
     type Store,
     servedCellOf,
+    standIn,
     streamingOrSettled,
     type Transformer,
+    writtenLocally,
 } from './Reactive.ts'
 export { STREAMING } from './STREAMING.ts'
 export {
@@ -82,6 +89,7 @@ export type Selection =
     | {
           busy(): boolean
           ready(): boolean
+          synced(): boolean
           refresh(): void
           invalidate(): void
       }
@@ -477,7 +485,7 @@ function build(
 // tag arm takes none at all.
 type PatternOf<
     Chosen,
-    Member extends 'busy' | 'ready' | 'refresh' | 'invalidate',
+    Member extends 'busy' | 'ready' | 'synced' | 'refresh' | 'invalidate',
 > =
     Chosen extends Record<Member, (pattern?: infer Pattern) => unknown>
         ? Pattern
@@ -497,6 +505,9 @@ export function busy<Chosen extends Selection>(
     pattern?: PatternOf<Chosen, 'busy'>,
 ): boolean {
     const sweep = sweepOf(selection)
+    // 46.11 — a bare `busy` hears a call the outbox is sending, which no value holds.
+    if (sweep === null)
+        return busyOver(sweep) || OUTBOX_SENDING.any?.() === true
     if (sweep !== undefined) return busyOver(sweep)
     return (selection as { busy(pattern: unknown): boolean }).busy(pattern)
 }
@@ -514,6 +525,17 @@ export function ready<Chosen extends Selection>(
     if (sweep !== undefined) return readyOver(sweep)
     return (selection as { ready(pattern: unknown): boolean }).ready(pattern)
 }
+/**
+ * Whether every entry in the selection holds what its producer made — ALL, as `ready` asks (13.18).
+ */
+export function synced<Chosen extends Selection>(
+    selection?: Chosen,
+    pattern?: PatternOf<Chosen, 'synced'>,
+): boolean {
+    const sweep = sweepOf(selection)
+    if (sweep !== undefined) return syncedOver(sweep)
+    return (selection as { synced(pattern: unknown): boolean }).synced(pattern)
+}
 /**
  * Stale-while-revalidate over the selection: reloads it while serving what it holds.
  *

package/src/shared/rpc.ts

@@ -18,6 +18,7 @@ import { GLOBAL_GETS } from './GLOBAL_GETS.ts'
 import { HandlerRoute } from './HandlerRoute.ts'
 import { IN_PROCESS_ORIGIN } from './IN_PROCESS_ORIGIN.ts'
 import { compose, type Middleware } from './Middleware.ts'
+import { outbox, type QueuedCall, sendingFor } from './outbox.ts'
 import { principalRotated } from './principalRotated.ts'
 import { RPC_SERVER } from './RPC_SERVER.ts'
 import {
@@ -56,8 +57,14 @@ import type { Schema } from './Schema.ts'
 
 export type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
 
-/** What a call is handed beside its args (16.48). */
-export type CallOptions = { signal?: AbortSignal }
+/**
+ * What a call is handed beside its args: who may end its load (16.48), and what stands in for an
+ * answer a browser could not get (16.81).
+ */
+export type CallOptions<Args = unknown, Value = unknown> = {
+    signal?: AbortSignal
+    offline?(args: Args): Value
+}
 
 /**
  * A declared handler: callable for its `Reactive`, with the handler's own members and its mount.
@@ -71,8 +78,8 @@ export type CallOptions = { signal?: AbortSignal }
  */
 export type Rpc<Value, Args, Failures = never, Produced = Value> = ((
     ...args: undefined extends Args
-        ? [args?: Args, options?: CallOptions]
-        : [args: Args, options?: CallOptions]
+        ? [args?: Args, options?: CallOptions<Args, NoInfer<Value>>]
+        : [args: Args, options?: CallOptions<Args, NoInfer<Value>>]
 ) => Reactive<
     Value,
     Value,
@@ -88,6 +95,9 @@ export type Rpc<Value, Args, Failures = never, Produced = Value> = ((
      */
     busy(pattern?: Partial<Args>): boolean
     ready(pattern?: Partial<Args>): boolean
+    synced(pattern?: Partial<Args>): boolean
+    /** 46.1 — the calls the outbox holds for this handler, narrowed by a pattern. */
+    outbox(pattern?: Partial<Args>): QueuedCall<Value>[]
     refresh(pattern?: Partial<Args>): void
     invalidate(pattern?: Partial<Args>): void
     isError<Name extends string>(
@@ -404,6 +414,7 @@ export function declare(method: Method): Declare {
                 args,
                 options?.signal,
                 rpc.timeout ?? RPC_SERVER.timeout(),
+                options?.offline as ((args: unknown) => unknown) | undefined,
             )
             RPC_SERVER.reached?.(rpc, args, reached)
             return reached
@@ -457,7 +468,8 @@ export function declare(method: Method): Declare {
         const members = rpc as unknown as Record<string, unknown>
         // 7.10, 7.18 — A TRIGGER ON A SERVER REACHES EVERY BROWSER HOLDING WHAT IT NAMES, through the
         // mux (18.3). `null` in a browser, where the trigger is the copy's own.
-        for (const name of SELECTION_MEMBERS)
+        for (const name of SELECTION_MEMBERS) {
+            if (name === 'busy') continue
             members[name] =
                 name === 'invalidate' || name === 'refresh'
                     ? (pattern?: unknown): unknown => {
@@ -466,6 +478,14 @@ export function declare(method: Method): Declare {
                           return done
                       }
                     : (pattern?: unknown): unknown => face[name](pattern)
+        }
+        // 46.11 — BUSY TOO WHILE A CALL THE OUTBOX HOLDS FOR IT IS IN FLIGHT: a queued call sent is work
+        // in flight for this handler, as a call made now is. 46.1 — and the calls it holds for it.
+        members.busy = (pattern?: unknown): boolean =>
+            (face.busy(pattern) as boolean) ||
+            sendingFor(rpc, pattern as Record<string, unknown> | undefined)
+        members.outbox = (pattern?: unknown): QueuedCall[] =>
+            outbox(rpc as never, pattern as Record<string, unknown> | undefined)
         // 21.8, 18.5 — a `GET` over a `global` value, the value it is serving for some args: a cache
         // may hold it for as long as it lives, and the mux may feed it. A request-local one is a
         // forwarder to a value built per request (11.32).

package/src/shared/rpcRequest.ts

@@ -17,7 +17,7 @@ export type RpcRequest = {
     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`. */
+    /** What `fetch` is handed: the method, the JSON content-type beside a body, and its `cache`. */
     init: RequestInit
     key: string
 }
@@ -40,6 +40,7 @@ export function rpcRequest(
     method: Method,
     route: HandlerRoute | string,
     given: Record<string, unknown> | undefined,
+    cache: RequestCache = 'no-cache',
 ): RpcRequest {
     const { path, rest } = (
         typeof route === 'string' ? new HandlerRoute(route) : route
@@ -50,17 +51,20 @@ export function rpcRequest(
         const text = rest === undefined ? '' : queryText(rest)
         if (text !== '') url = `${url}?${text}`
     } else if (rest !== undefined) body = JSON.stringify(rest)
-    // 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`.
+    // 18.14 — A COPY IS ITS OWN CACHE and keeps its own `max-age`. What it asks the server once it
+    // holds an answer is asked because it went stale, was invalidated or refreshed, and a cache
+    // below it, which hears none of the three, would answer it with the value it was dropping — so
+    // `no-cache`. A page's first load in a page the worker answers is the browser's to switch to
+    // `force-cache` (16.80), where a kept copy is what opens the page without the network (45.18);
+    // the outbox's send asks `no-store`. `rpc.raw` is handed `no-cache`, 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 }
             : {
                   method,
-                  cache: 'no-cache',
+                  cache,
                   headers: { 'content-type': 'application/json' },
                   body,
               }