@abide/abide 0.124.1 → 0.125.0

package/src/shared/online.ts

@@ -7,12 +7,16 @@
 // PURE, SO AN APP THAT NEVER NAMES `online` DOES NOT SHIP IT: the listeners are a side effect at
 // load, and a top-level side effect keeps the module in the shared chunk whether anything reads it.
 
+// A BODY RATHER THAN A VALUE where there is a window, so each scope's instance asks again: a test
+// process has both a DOM and a server render, and the render's `online` is 23.8's (22.11).
+
+import { isServer } from './isServer.ts'
 import { ambient } from './reactive/index.ts'
 
 /** Whether the caller can reach the app, as a `Reactive<boolean>`. */
 export const online = /* @__PURE__ */ (() => {
     if (typeof window === 'undefined') return ambient<boolean>(true)
-    const value = ambient<boolean>(navigator.onLine)
+    const value = ambient<boolean>(() => isServer() || navigator.onLine)
     window.addEventListener('online', () => value.set(true))
     window.addEventListener('offline', () => value.set(false))
     return value

package/src/shared/reactive/Keyed.ts

@@ -23,6 +23,7 @@ import { KEYED_BRAND } from './KEYED_BRAND.ts'
 import { matchesPattern } from './matchesPattern.ts'
 import { NotLanded } from './NotLanded.ts'
 import { parameterDefaults } from './parameterDefaults.ts'
+import { armPoll, refreshIdle, refuseBadPoll } from './poll.ts'
 import {
     abandonDeferred,
     createReactive,
@@ -344,7 +345,8 @@ export function createKeyed<
     // 11.45: A KEYED `ttl` IS THE LIFE OF AN ENTRY, not of a production inside one, so it is
     // taken off the options every entry is built from — forwarded, it would build the
     // unkeyed mechanism in every entry and evict nothing from this map.
-    const { ttl, args, throttle, debounce, ...rest } = options ?? {}
+    // 7.20 — and `poll`, so one timer walks the entries rather than one per entry.
+    const { ttl, args, throttle, debounce, poll, ...rest } = options ?? {}
     const gate = args as Schema<Args> | undefined
     const entryOptions = rest
     // 5.14, at the factory: a keyed value is capped one way or the other.
@@ -375,6 +377,15 @@ export function createKeyed<
             for (const entry of entries.values()) unwatchStore(entry)
         })
 
+    // 7.20, 7.23 — one timer over the entries held at each tick: an evicted entry is out of the map.
+    if (poll !== undefined) {
+        refuseBadPoll(`${label}()`, poll)
+        const stop = armPoll(poll, () => {
+            for (const entry of entries.values()) refreshIdle(entry)
+        })
+        if (owning()) owned(stop)
+    }
+
     function askMembership(): void {
         const reader = TRACKING.reader
         if (reader !== null) trackProbe(membership, reader)

package/src/shared/reactive/Reactive.ts

@@ -40,6 +40,7 @@ import { isThenable } from './isThenable.ts'
 import { NO_INITIAL } from './NO_INITIAL.ts'
 import { NotLanded } from './NotLanded.ts'
 import { logOf, PatchLog, type PatchOp, sendInvalidate } from './patchLog.ts'
+import { armPoll, refreshIdle, refuseBadPoll } from './poll.ts'
 import { REACTIVE_BRAND } from './REACTIVE_BRAND.ts'
 import { recordWrites } from './recordWrites.ts'
 import { runInScope } from './scoping.ts'
@@ -55,7 +56,6 @@ import { STREAMING } from './STREAMING.ts'
 import {
     CHECK,
     CLEAN,
-    detach,
     DIRTY,
     dropProbeReader,
     newSubscriber,
@@ -147,6 +147,13 @@ export type ReactiveOptions<
      * once — see `expiryFor`.
      */
     ttl?: number
+    /**
+     * A refresh every this many milliseconds.
+     *
+     * RULEBOOK 7.20 through 7.25: `s.refresh` on a clock, skipped while the value is busy and
+     * stopped with the value. Inert on a value with no producer (7.24).
+     */
+    poll?: number
     /**
      * The gate on the way in, run before `transform` on every way in.
      *
@@ -1012,8 +1019,8 @@ function serve(cell: Cell, value: unknown): void {
     // servable — `armNext` reads the deadline off a production that has landed, and from
     // `produce` it would be reading one that had not.
     if (cell.expiry !== null) armNext(cell, cell.expiry)
-    // 8.8: every production that reaches a reader is written, and nothing else is — a write the
-    // identity gate collapsed never arrives here.
+    // 8.8: every production that reaches a reader is written but the two `persist` withholds, and
+    // nothing else is — a write the identity gate collapsed never arrives here.
     if (cell.store !== null) persist(cell, cell.store, value)
 }
 
@@ -1677,7 +1684,8 @@ function run(cell: Cell): void {
     // where the cascade would try: `a` reads `b` and `b` reads `a`. Without this the
     // recursion is unbounded and the failure is a stack overflow rather than a value.
     if (cell.running) return
-    // A released orphan read again (12.14) — see `tombstone`.
+    // A released orphan read again (12.14) — see `tombstone`. A released stream's run is its next
+    // start: the generator its body hands back is promoted onto the stream it already has (9.6).
     if (!cell.alive) revive(cell as unknown as Subscriber)
     cell.generation += 1
     cell.state = CLEAN
@@ -1847,11 +1855,13 @@ function landOpening(cell: Cell): void {
  * WHAT STARTS A PRODUCER, for the three callers that start one: construction, `refresh`
  * and `invalidate`. A stream is dispatched HERE rather than inside `run`, which a recompute
  * walks per node per write — and a stream is never recomputed, having no tracked source to
- * be marked by (14.13).
+ * be marked by (14.13). A RELEASED stream (12.16) is the exception: it is owed a run, and the
+ * run is what revives it and settles the debt, where a start here would leave the debt for the
+ * next read to start it a second time.
  */
 function startProducer(cell: Cell): void {
     const stream = ownStream(cell)
-    if (stream === null) run(cell)
+    if (stream === null || !cell.alive) run(cell)
     else startStream(cell, stream)
 }
 
@@ -3203,11 +3213,19 @@ function settleRestore(
         restore(cell, persisted, value)
         return
     }
-    // A MISS IS THE VALUE WITHOUT A STORE: the body runs, or the initial value lands (8.3).
+    // A MISS IS THE VALUE WITHOUT A STORE: the body runs, or the initial value lands (8.3). The
+    // body's run is a production the store is filled from; the initial value is the declaration,
+    // and writing it back on every miss is what a server render did to a browser's store (8.8).
     if (cell.body !== null) startProducer(cell)
     else if (initial === undefined) landOpening(cell)
-    else if (initial !== NO_INITIAL) open(cell, initial)
-    else endLoad(cell, false)
+    else if (initial !== NO_INITIAL) {
+        persisted.withheld = true
+        try {
+            open(cell, initial)
+        } finally {
+            persisted.withheld = false
+        }
+    } else endLoad(cell, false)
 }
 
 /**
@@ -3218,13 +3236,13 @@ function settleRestore(
  * it back.
  */
 function restore(cell: Cell, persisted: Persisted, value: unknown): void {
-    persisted.restoring = true
+    persisted.withheld = true
     try {
         const stream = cell.stream
         if (stream === null) produce(cell, value)
         else restoreStream(cell, stream, value as unknown[])
     } finally {
-        persisted.restoring = false
+        persisted.withheld = false
     }
 }
 
@@ -3263,7 +3281,7 @@ function restoreStream(cell: Cell, stream: Stream, chunks: unknown[]): void {
  * asked at all and the written value stands in its place. Asking took the value BACKWARDS and left
  * it there: `s.set(99)` over a store still holding 1 leaves a `set` in flight, a `refresh` in the
  * same turn read 1 and produced it, and the queued write then landed 99 in the store — the cell
- * serving 1 and the store holding 99 for the life of the value, with `restoring` stopping the
+ * serving 1 and the store holding 99 for the life of the value, with `withheld` stopping the
  * reverted value from being written back and no probe moving to say so.
  */
 function rereadStore(cell: Cell, persisted: Persisted): void {
@@ -3353,13 +3371,12 @@ function settleMiss(cell: Cell): void {
 }
 
 /**
- * Writes a production to the store, unless it is a restore or a stream's.
+ * Writes a production to the store, unless 8.8 withholds it or it is a stream's.
  *
- * A restore is what was just read, and a stream is written at its close (8.9) — neither is
- * persisted from here.
+ * A stream is written at its close (8.9), not from here.
  */
 function persist(cell: Cell, persisted: Persisted, value: unknown): void {
-    if (persisted.restoring || cell.stream !== null) return
+    if (persisted.withheld || cell.stream !== null) return
     writeStore(cell, persisted, value)
 }
 
@@ -3874,22 +3891,22 @@ function orphan(cell: Cell): void {
  * Left subscribed, a value a dropped row built stayed on its sources' reader lists for the life of
  * the page, and an adopting one's mirror ran on every write to what it adopted. Released, it holds
  * what it last served; a read that reaches it later — it escaped its owner — runs the body again
- * and subscribes afresh, so it is never stale, and from then on it is nobody's to release. A
- * stream is stopped rather than owed: it is never recomputed (14.13), only started.
+ * and subscribes afresh, so it is never stale, and from then on it is nobody's to release. 12.16 — a
+ * stream's run is stopped and it is owed the same run: the body's next start (9.6), which serves
+ * what the stopped one held until it says something (9.7) — a stream nothing pumps is the one value
+ * a later read could never bring current.
  */
 function releaseOrphan(cell: Cell): void {
     cell.orphaned = false
-    const stream = cell.stream
     const own = ownStream(cell)
     if (own !== null) stopStream(own)
     dropAdoption(cell)
     cell.aborted = false
-    if (cell.body !== null && stream === null) {
-        // OWED A RUN, so a read that reaches it again runs it — and `run` revives it first.
-        tombstone(cell as unknown as Subscriber)
-        cell.state = DIRTY
-        cell.direct = false
-    } else detach(cell as unknown as Subscriber)
+    // OWED A RUN, so a read that reaches it again runs it — and `run` revives it first. No `body`
+    // test: only a value with one is ever orphaned (`createReactive`).
+    tombstone(cell as unknown as Subscriber)
+    cell.state = DIRTY
+    cell.direct = false
 }
 
 RELEASING.unread = (source: Tracked): void => releaseOrphan(source as Cell)
@@ -3987,5 +4004,16 @@ export function createReactive<
         else if (initial !== NO_INITIAL) open(cell, initial)
     } else if (deferred) cell.loading = true
     else startProducer(cell)
+    // 7.20, 7.23, 7.24 — a `Keyed` takes `poll` off its entries' options and polls them itself.
+    const poll = options?.poll
+    if (poll !== undefined) {
+        refuseBadPoll(label, poll)
+        if (reloads(cell)) {
+            const stop = armPoll(poll, () =>
+                refreshIdle(self as unknown as Reactive<unknown>),
+            )
+            if (owning()) owned(stop)
+        }
+    }
     return self as unknown as Reactive<Stored, Accepted, Failures, Produced>
 }

package/src/shared/reactive/cellShape.ts

@@ -102,9 +102,10 @@ export type Persisted = {
     /** The value's own `ttl`, taken once, and infinity where it declares none (8.13). */
     ttl: number
     /**
-     * Set while a restore mints its production, so what was just read is not written back (8.8).
+     * Set while a production 8.8 does not write back is minted: a restore, which is what was just
+     * read, and the initial value a miss falls back to, which the store never held.
      */
-    restoring: boolean
+    withheld: boolean
     writing: boolean
     pending: boolean
     /**
@@ -601,7 +602,7 @@ export class Cell {
                           ? store(args as never)
                           : store) as Store<unknown>,
                       ttl: options?.ttl ?? Number.POSITIVE_INFINITY,
-                      restoring: false,
+                      withheld: false,
                       writing: false,
                       pending: false,
                       unconfirmed: undefined,

package/src/shared/reactive/poll.ts

@@ -0,0 +1,49 @@
+// A REFRESH ON A CLOCK. RULEBOOK 7.20 through 7.25: `poll` is `s.refresh` (7.4) run every `poll`
+// milliseconds, which is what an app otherwise writes as a `setInterval` in `onStart` and a
+// `clearInterval` in `onStop` — and then has to remember for every value, keyed entry and request.
+//
+// NO FIELD ON THE CELL. The timer's stop is handed to whatever ends the value — its owner, or its
+// `Keyed` — so a value declaring no `poll` carries nothing for it, and the read and write paths
+// never see it. A `Keyed` polls with ONE timer over the entries it holds at each tick, so an entry
+// its `ttl` evicted is out of the walk by being out of the map.
+
+import { LONGEST_DELAY } from '../LONGEST_DELAY.ts'
+import type { Disposer } from './watch.ts'
+
+/**
+ * Throws where `poll` is not a positive number of milliseconds (7.25).
+ *
+ * At construction, as 5.14 is: a zero or negative interval is a refresh per turn, and the app
+ * still has a stack for it here.
+ */
+export function refuseBadPoll(label: string, poll: number | undefined): void {
+    if (poll !== undefined && !(poll > 0))
+        throw new Error(
+            `${label} declares poll: ${poll}. A poll is a positive number of milliseconds.`,
+        )
+}
+
+/**
+ * Runs `tick` every `poll` milliseconds, never holding the process open, and answers its stop.
+ *
+ * 7.22 FOLLOWS 6.4's FEATURE TEST: Bun's `Timer` carries `unref`, a browser's number does not and
+ * has no process to hold. `Infinity` arms nothing; a finite interval past what a timer holds runs
+ * at the longest one it does.
+ */
+export function armPoll(poll: number, tick: () => void): Disposer {
+    if (poll === Number.POSITIVE_INFINITY) return () => {}
+    const timer = setInterval(tick, Math.min(poll, LONGEST_DELAY))
+    const unref = (timer as { unref?: () => void }).unref
+    if (typeof unref === 'function') unref.call(timer)
+    return () => clearInterval(timer)
+}
+
+/**
+ * Refreshes `value` unless it is busy (7.21).
+ *
+ * A refresh over a load in flight supersedes it, so a producer slower than its interval would
+ * otherwise never land.
+ */
+export function refreshIdle(value: { busy(): boolean; refresh(): void }): void {
+    if (!value.busy()) value.refresh()
+}

package/src/shared/reactive/scoped.ts

@@ -20,6 +20,7 @@ import { brandedPrototype, MEMBER_KEYS, signalMoved } from './Reactive.ts'
 import { currentScope, runInScope, SCOPING } from './scoping.ts'
 import { SELECTION_MEMBERS } from './SELECTION_MEMBERS.ts'
 import { newTracked, type Tracked, TRACKING, trackProbe } from './tracking.ts'
+import { owning, unowned } from './watch.ts'
 
 const UNBUILT: unique symbol = Symbol('abide.unbuilt')
 
@@ -38,6 +39,11 @@ class Filed {
     home: unknown
     make: () => unknown
     global: boolean
+    /**
+     * 12.17 — whether the declaration had an owner. A home declared with none — a module's, which is
+     * every handler's — is the process's, and is built as one wherever it is first reached.
+     */
+    declaredOwned: boolean
     /**
      * 3.3, 13.19 — what a probe asked before the value was built here subscribes to, moved by the
      * build: the home's. A scope files its own in `instances` under this one as its key, and drops
@@ -49,6 +55,7 @@ class Filed {
         this.make = make
         this.home = lazy ? UNBUILT : make()
         this.global = global
+        this.declaredOwned = owning()
         this.unbuilt = newTracked()
     }
 }
@@ -66,7 +73,9 @@ function instanceOf(filed: Filed): Record<PropertyKey, unknown> {
     const scope = filed.global ? undefined : currentScope()
     if (scope === undefined) {
         if (filed.home === UNBUILT) {
-            filed.home = runInScope(undefined, () => filed.make(), undefined)
+            filed.home = filed.declaredOwned
+                ? runInScope(undefined, filed.make, undefined)
+                : unowned(() => runInScope(undefined, filed.make, undefined))
             signalMoved(filed.unbuilt)
         }
         return filed.home as Record<PropertyKey, unknown>

package/src/shared/reactive/scoping.ts

@@ -25,6 +25,14 @@ export type Scope = {
 
 export type Scoping = {
     current(): Scope | undefined
+    /**
+     * The stops of the server work running — a request's scope, or a `render` outside every request —
+     * or `undefined` where none is.
+     *
+     * 12.5 — what a `watch` opened in that work is stopped with. 22.11 — and whether the work running
+     * is a server's at all.
+     */
+    serverStops(): (() => void)[] | undefined
     /**
      * Runs `body` with `scope` as the current one, and `undefined` as no scope at all.
      *
@@ -46,6 +54,12 @@ export function currentScope(): Scope | undefined {
     return provider === null ? undefined : provider.current()
 }
 
+/** What a `watch` opened now is stopped with on a server — 12.5 — or `undefined` in a browser. */
+export function serverStops(): (() => void)[] | undefined {
+    const provider = SCOPING.provider
+    return provider === null ? undefined : provider.serverStops()
+}
+
 /**
  * Runs `body` under `scope` and returns what it returns.
  *

package/src/shared/reactive/watch.ts

@@ -11,6 +11,7 @@
 // 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 { isServer } from '../isServer.ts'
 import { namedLogger } from '../log.ts'
 import { UNEXPECTED } from '../UNEXPECTED.ts'
 import { WORK } from '../WORK.ts'
@@ -18,7 +19,7 @@ import { CELL } from './CELL.ts'
 import type { Callable } from './cellShape.ts'
 import { NotLanded } from './NotLanded.ts'
 import type { Reactive } from './Reactive.ts'
-import { currentScope, runInScope } from './scoping.ts'
+import { currentScope, runInScope, serverStops } from './scoping.ts'
 import {
     detach,
     newSubscriber,
@@ -49,9 +50,10 @@ function reportThrow(thrown: unknown, message: string): void {
 /**
  * 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: to
- * the caller of `watch` on a first run, and on a rerun to the drain, which reports it and runs the
- * rest of its queue (`drainPending`). A server's has been handed it, and re-thrown there it would
+ * 12.7 — A BROWSER'S THROW GOES ON OUT to surface as an uncaught error: to the caller of `watch` on
+ * a first run, and on a rerun to the drain, which reports it and runs the rest of its queue
+ * (`drainPending`) — and its `onError`, handed it already, is not handed it again (`onError.ts`).
+ * 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.
  */
@@ -60,7 +62,8 @@ function effectThrew(thrown: unknown): void {
         thrown,
         'an effect threw, and its watch is stopped. RULEBOOK 12.6, 12.8.',
     )
-    if (typeof document !== 'undefined') throw thrown
+    // 22.11, NOT `typeof document`: a test process's in-process render has one, and re-threw.
+    if (!isServer()) throw thrown
 }
 
 /**
@@ -104,16 +107,24 @@ export function collectWatches(
  * 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.
+ * 12.5 — the scope is a server's request, or its render outside every request (`serverStops`),
+ * 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)
+    serverStops()?.push(dispose)
     return dispose
 }
 
+/**
+ * Whether a component's setup is being collected now: a browser's, since a server's never is.
+ */
+export function settingUp(): boolean {
+    return OWNING.stops !== undefined
+}
+
 /**
  * Whether something opened now has an owner to be handed to — a setup being collected, or a scope.
  *
@@ -123,7 +134,7 @@ export function owned(dispose: Disposer): Disposer {
 export function owning(): boolean {
     return (
         !OWNING.free &&
-        (OWNING.stops !== undefined || currentScope() !== undefined)
+        (OWNING.stops !== undefined || serverStops() !== undefined)
     )
 }
 

package/src/shared/resultsOf.ts

@@ -0,0 +1,21 @@
+import type { AssistantEvent } from './AssistantEvent.ts'
+import type { Rpc } from './rpc.ts'
+
+/** What every call to `handler` in `events` answered, in order, a failed call's left out. 44.51. */
+export function resultsOf<Value>(
+    events: readonly AssistantEvent[],
+    // Any handler at all: its args, failures and production are no part of what it answered.
+    handler: Rpc<Value, never, unknown, unknown>,
+): Value[] {
+    const values: Value[] = []
+    for (const event of events)
+        if (
+            event.type === 'result' &&
+            !event.failed &&
+            event.handler !== undefined &&
+            event.handler.method === handler.method &&
+            event.handler.address === handler.address
+        )
+            values.push(event.value as Value)
+    return values
+}

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)
 }