@abide/abide 0.104.0 → 0.105.0

package/src/shared/reactive/index.ts

@@ -33,7 +33,6 @@ import {
 import { outsideScope, scoped } from './scoped.ts'
 import { share } from './share.ts'
 
-export { chunksOfStream } from './chunksOfStream.ts'
 export { isReactive } from './isReactive.ts'
 export { isKeyed, type Keyed } from './Keyed.ts'
 export { NotLanded } from './NotLanded.ts'
@@ -42,6 +41,7 @@ export { NotLanded } from './NotLanded.ts'
 // first that imports the core directly meets `MEMBER_KEYS` before it is initialized.
 export {
     abandonLoad,
+    chunksOfStream,
     deadlineOf,
     failedTransiently,
     flushSync,
@@ -368,14 +368,17 @@ export function reactive(
 ): unknown {
     const keyed = isKeyedBody(given[0])
     // 11.32 — ON A SERVER, OUTSIDE A REQUEST, THE VALUE IS FILED: a forwarder to one instance per
-    // request, and to the one built here where there is no request at all. `global` is what keeps
-    // a value process-wide (11.34).
-    if (
-        outsideScope(
-            (given[1] as { global?: boolean } | undefined)?.global === true,
+    // request, and to the one built here where there is no request at all — or, for a value with a
+    // `store`, built where it is first reached (11.71). `global` is what keeps a value process-wide
+    // (11.34).
+    const options = given[1] as
+        | { global?: boolean; store?: unknown }
+        | undefined
+    if (outsideScope(options?.global === true))
+        return scoped(
+            () => build(given, keyed),
+            !keyed && options?.store !== undefined,
         )
-    )
-        return scoped(() => build(given, keyed))
     return build(given, keyed)
 }
 

package/src/shared/reactive/pairReactive.ts

@@ -4,7 +4,7 @@
 // the pair's, and nothing stands here — the value moves when what `get` reads does, as an element's
 // `bind:value={{get, set}}` does.
 //
-// A PROTOTYPE, NOT A BRANCH in the core's `set`, for `brandedPrototype`'s reason: `simpleShape`
+// A PROTOTYPE, NOT A BRANCH in the core's `set`, for `brandedPrototype`'s reason: `seat`
 // leaves a seat it does not own alone, and the adoption path reaches this `set` through the
 // callable it adopted.
 

package/src/shared/reactive/scoped.ts

@@ -24,9 +24,10 @@ const UNBUILT: unique symbol = Symbol('abide.unbuilt')
 /**
  * What a forwarder resolves through: the home, and how to build the same value again in a scope.
  *
- * 16.64 — A HANDLER'S HOME IS BUILT WHERE IT IS FIRST REACHED, and every other value's where it is
- * declared. Building a value with a body starts the body (1.7), and at import that ran the handler
- * — a mutation fired at boot, for a request nobody had made.
+ * 11.71 AND 16.64 — A HANDLER'S HOME, AND AN UNKEYED VALUE'S WITH A `store`, IS BUILT WHERE IT IS
+ * FIRST REACHED, and every other value's where it is declared. Building a value starts its body
+ * (1.7) and reads its store (8.14), and at import that ran a handler for a request nobody had made,
+ * and a store reading `cookies()` where there is no request.
  *
  * A `global` handler (11.34) is filed only to be built late: every request reaches the home, built
  * outside each of them, so it is the one value its option says it is.

package/src/shared/reactive/share.ts

@@ -16,6 +16,12 @@ import type { Reactive } from './Reactive.ts'
 export type ShareScope = {
     parent: ShareScope | null
     values: Map<string, unknown>
+    /**
+     * 39.1 — the routed level the instance stands in, opaque here (`Level`). Carried down the chain
+     * so a component mounted after its level — an arm opening, a row grown — finds the level its
+     * `<head>` joins through the scope it resumes, as it finds a shared key.
+     */
+    level: unknown
 }
 
 // The instance being rendered or mounted, or `null` outside one. A dynamic scope like
@@ -62,7 +68,11 @@ export function share<Key extends string, Value>(
  */
 export function enterShare(): ShareScope | null {
     const previous = CURRENT
-    CURRENT = { parent: previous, values: new Map() }
+    CURRENT = {
+        parent: previous,
+        values: new Map(),
+        level: previous === null ? undefined : previous.level,
+    }
     return previous
 }
 

package/src/shared/routePattern.ts

@@ -10,13 +10,6 @@
 // A LEAF: nothing imported but another leaf, because the compiler, the client router and a server
 // router all read it and a constant crossing a seam lives where nothing pulls a graph in behind it.
 
-import { LAUNCHER_PAGE } from './LAUNCHER_FILES.ts'
-import {
-    HOLDS_SERVER,
-    RESERVED_DIRECTORIES,
-    SERVER_DIRECTORY,
-} from './RESERVED_DIRECTORIES.ts'
-
 type SegmentKind = 'static' | 'required' | 'optional' | 'rest'
 
 /** One `/`-separated piece of a route literal, classified by kind. */
@@ -47,122 +40,6 @@ export function parseRoutePattern(pattern: string): Segment[] {
     return out
 }
 
-/** Whether a source is a page, a layout, an error page or a component. */
-export type FileKind = 'page' | 'layout' | 'error' | 'component'
-
-/**
- * Whether the `.abide` at `path` is a page, a layout, an error page or a component.
- *
- * 23.21 — WHERE IT SITS, THEN ITS NAME. Every `.abide` directly in an address directory is a page
- * but a `layout.abide`, an `error.abide` and the root's `launcher.abide`; one under a fence is a
- * component whatever it is called.
- * One test for every reader: the build's routes, the checker's `Routes` and the `route.params` a
- * page is typed by.
- *
- * `path` is RELATIVE TO THE APP'S ROOT: its directories are its route, so an absolute path would
- * read the machine's directories as the app's.
- */
-export function fileKind(path: string): FileKind {
-    if (placeOf(path) !== 'address' || path === LAUNCHER_PAGE)
-        return 'component'
-    const name = path.slice(path.lastIndexOf('/') + 1)
-    if (name === 'layout.abide') return 'layout'
-    if (name === 'error.abide') return 'error'
-    return 'page'
-}
-
-/** Where a file sits in an app, which is what it is to every reader (`placeOf`). */
-export type Place =
-    | 'address'
-    | 'server'
-    | 'public'
-    | 'lib'
-    | 'tests'
-    | 'dependency'
-    | 'skipped'
-
-/**
- * Where the file at `path`, relative to the app's root, sits — THE ONE ANSWER every walk, fence and
- * emit reads, so no two of them disagree about a path.
- *
- * - `dependency` — 34.24: a package's, outside the root or under `node_modules`, whose directories
- *   are its package's layout and none of the app's;
- * - `skipped` — under a dot directory, which no walk of the app enters;
- * - `server`, `public`, `lib` or `tests` — 23.15: under that fence, the nearest to the root deciding,
- *   save a `server` under a `lib` or a `tests`, which is `server` — the fence the browser's bundle
- *   is checked against (16.29) is never hidden by one above it (23.16);
- * - `address` — 23.14: everywhere else, its directories the segments of its route.
- */
-export function placeOf(path: string): Place {
-    if (path.startsWith('../') || path.startsWith('/')) return 'dependency'
-    const parts = path.split('/')
-    // A `lib` or a `tests` met first, which a `server` below it still overrides.
-    let fence: Place | undefined
-    // The last part is the file itself, which is never a directory.
-    for (let index = 0; index < parts.length - 1; index += 1) {
-        const part = parts[index] as string
-        if (skipped(part))
-            return (
-                fence ?? (part === 'node_modules' ? 'dependency' : 'skipped')
-            )
-        if (fence !== undefined) {
-            if (part === SERVER_DIRECTORY) return 'server'
-        } else if (RESERVED_DIRECTORIES.has(part)) {
-            if (!HOLDS_SERVER.has(part)) return part as Place
-            fence = part as Place
-        }
-    }
-    return fence ?? 'address'
-}
-
-/** Whether a walk of the app passes over the entry `name`: a dot file or directory, or `node_modules`. */
-export function skipped(name: string): boolean {
-    return name.startsWith('.') || name === 'node_modules'
-}
-
-/**
- * The route a file answers at — its path below the root without its extension.
- *
- * 23.14 — `media/[id].abide` and `media/getGrid.ts` are `/media/[id]` and `/media/getGrid`; an
- * `index.abide`, a `layout.abide` and an `error.abide` are their directory's. `path` is relative to
- * the app's root, as `fileKind`'s is.
- */
-export function routeOf(path: string): string {
-    const parts = path.split('/')
-    const file = parts.pop() as string
-    // The extension alone: `[...rest].abide` carries dots of its own.
-    if (!DIRECTORY_FILES.has(file)) parts.push(file.replace(EXTENSION, ''))
-    return `/${parts.filter((part) => part !== '').join('/')}`
-}
-
-const EXTENSION = /\.(?:abide|ts)$/
-
-/** 23.14, 23.18 — the names whose route is their directory's, and so a route's wherever they stand. */
-export const DIRECTORY_FILES = new Set([
-    'index.abide',
-    'layout.abide',
-    'error.abide',
-])
-
-/**
- * The route the hooks and private handlers of the file at `path` are filed at.
- *
- * 37.1 — an address's own route; under a `lib` or a `tests` directory, the route of the directory
- * holding it, so a component an admin page renders runs under the admin route's rungs; under a
- * `server` or a `public` directory, and for a dependency's file, the root's.
- */
-export function scopeOf(path: string): string {
-    // 38.82 — the launcher answers at no route, and files what it calls at the root's.
-    if (path === LAUNCHER_PAGE) return '/'
-    const place = placeOf(path)
-    if (place === 'address') return routeOf(path)
-    if (place !== 'lib' && place !== 'tests') return '/'
-    const parts = path.split('/')
-    // The fence `placeOf` named is the first one, and its name is its place.
-    const fence = parts.indexOf(place)
-    return `/${parts.slice(0, fence).join('/')}`
-}
-
 /**
  * A `sort` comparator over two parsed patterns: negative where `a` is the more specific.
  *

package/src/shared/rpc.ts

@@ -14,8 +14,8 @@
 // handler's own.
 
 import { type Failed, isFailedNamed } from './Failed.ts'
-import { filledSegments } from './filledPath.ts'
 import { GLOBAL_GETS } from './GLOBAL_GETS.ts'
+import { HandlerRoute } from './HandlerRoute.ts'
 import { compose, type Middleware } from './Middleware.ts'
 import { principalRotated } from './principalRotated.ts'
 import { RPC_SERVER } from './RPC_SERVER.ts'
@@ -49,8 +49,7 @@ import { MUTATION } from './reactive/MUTATION.ts'
 import { SELECTION_MEMBERS } from './reactive/SELECTION_MEMBERS.ts'
 import { isForwarder } from './reactive/scoped.ts'
 import { checkArgs } from './refuse.ts'
-import { parseRoutePattern, type Segment } from './routePattern.ts'
-import { pathRefusal, rpcRequest } from './rpcRequest.ts'
+import { rpcRequest } from './rpcRequest.ts'
 import type { Schema } from './Schema.ts'
 
 export type Method = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
@@ -374,28 +373,22 @@ export function declare(method: Method): Declare {
         //
         // 15.8 — AND REFUSED AHEAD OF THE HANDLER where the args leave a parameter of its route no
         // spelling (30.3, 30.19), as the wire refuses them: a render and the browser's call then
-        // reach the same refusal, and there is no request for the render to report. The route is
-        // parsed once per address, which is stamped after the declaration (16.10).
-        let routed: string | undefined
-        let routeSegments: Segment[] | null = null
+        // reach the same refusal, and there is no request for the render to report.
+        //
+        // THE ROUTE IS COMPILED ONCE PER ADDRESS, which is stamped after the declaration (16.10),
+        // and every call, `rpc.url` and `rpc.raw` read it.
+        let route: HandlerRoute | undefined
+        const routeAt = (address: string): HandlerRoute => {
+            if (route?.address !== address) route = new HandlerRoute(address)
+            return route
+        }
         const call = (given?: unknown, options?: CallOptions): unknown => {
             const args = normalized(contract, given)
-            const address = rpc.address
-            if (address !== routed) {
-                routed = address
-                routeSegments =
-                    address?.includes('[') === true
-                        ? parseRoutePattern(address)
-                        : null
-            }
-            if (routeSegments !== null) {
+            const route =
+                rpc.address === undefined ? undefined : routeAt(rpc.address)
+            if (route?.segments !== undefined) {
                 try {
-                    filledSegments(
-                        routeSegments,
-                        (args ?? {}) as Record<string, unknown>,
-                        routed as string,
-                        pathRefusal,
-                    )
+                    route.path(args as Record<string, unknown> | undefined)
                 } catch (refused) {
                     return reactive(() => refused)
                 }
@@ -428,13 +421,13 @@ export function declare(method: Method): Declare {
             guarded: rungs.length > 0,
             isError: isFailedNamed,
             url(args?: Record<string, unknown>): string {
-                return rpcRequest(method, addressOf(rpc), args).url
+                return rpcRequest(method, routeAt(addressOf(rpc)), args).url
             },
             raw(
                 args?: Record<string, unknown>,
                 init?: RequestInit,
             ): Promise<Response> {
-                const asked = rpcRequest(method, addressOf(rpc), args)
+                const asked = rpcRequest(method, routeAt(addressOf(rpc)), args)
                 // `Headers`, not a spread — the caller's may be a `Headers` itself, which spreads empty.
                 const headers = new Headers(asked.init.headers)
                 for (const [name, value] of new Headers(init?.headers))

package/src/shared/rpcRequest.ts

@@ -3,13 +3,13 @@
 // to the byte, or the browser's call misses the request that was already started for it. `key` is
 // that agreement: method, URL and body, which is what makes two requests the same one.
 //
-// A `GET` or `DELETE` carries its args in the URL, in `queryText`'s spelling, and a mutation in its
-// body; 19.7 is where text becomes the declared type again. 16.9 — whatever the method, a parameter
-// of the handler's route rides in the path, and the server puts it back among the args (16.65).
+// A `GET` or `DELETE` carries its args in the URL, in `queryText`'s spelling (30.28), and a mutation
+// in its body; 19.7 is where text becomes the declared type again. 16.9 — whatever the method, a
+// parameter of the handler's route rides in the path, and the server puts it back among the args
+// (16.65).
 
-import { filledPath, parametersOf } from './filledPath.ts'
+import { HandlerRoute } from './HandlerRoute.ts'
 import { queryText } from './queryText.ts'
-import { validationError } from './refuse.ts'
 import type { Method } from './rpc.ts'
 
 export type RpcRequest = {
@@ -31,44 +31,25 @@ export function argsInURL(method: Method): boolean {
     return method === 'GET' || method === 'DELETE'
 }
 
-/** The request a call is: its URL, body, `fetch` init and the `key` both ends match it by. */
+/**
+ * The request a call is: its URL, body, `fetch` init and the `key` both ends match it by.
+ *
+ * `route` is the handler's, compiled where the caller holds one; an address is compiled here.
+ */
 export function rpcRequest(
     method: Method,
-    address: string,
+    route: HandlerRoute | string,
     given: Record<string, unknown> | undefined,
 ): RpcRequest {
-    let args = given
-    let url = address
+    const { path, rest } = (
+        typeof route === 'string' ? new HandlerRoute(route) : route
+    ).split(given)
+    let url = path
     let body: string | undefined
-    // A route with parameters: they are written into the path and leave the args, so the query or
-    // body never carries one twice (16.66). 15.8 — one no address carries (30.3, 30.19) is refused as
-    // args a gate refused, so every caller answers it as the wire answers a 422.
-    if (address.includes('[')) {
-        const params = given ?? {}
-        url = filledPath(address, params, address, pathRefusal)
-        const inPath = parametersOf(address)
-        let rest: Record<string, unknown> | undefined
-        for (const name in params) {
-            if (inPath.has(name)) continue
-            rest ??= {}
-            rest[name] = params[name]
-        }
-        args = rest
-    }
     if (argsInURL(method)) {
-        if (args !== undefined) {
-            let text = queryText(args)
-            // AN EMPTY LIST IS ITS NAME WITH NO `=`, which no text value spells — `tags=` is the
-            // one-member list `['']` — so 19.7 reads it back as `[]` rather than losing the member.
-            for (const name in args) {
-                const value = args[name]
-                if (!Array.isArray(value) || value.length !== 0) continue
-                const bare = bareName(name)
-                text = text === '' ? bare : `${text}&${bare}`
-            }
-            if (text !== '') url = `${url}?${text}`
-        }
-    } else if (args !== undefined) body = JSON.stringify(args)
+        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
@@ -85,13 +66,3 @@ export function rpcRequest(
               }
     return { method, url, body, init, key: `${method} ${url} ${body ?? ''}` }
 }
-
-/** 15.8 — a parameter no address carries, refused as args a gate refused. */
-export function pathRefusal(name: string, message: string): unknown {
-    return validationError<Record<string, unknown>>({ [name]: [message] })
-}
-
-/** A query member's name in the encoding `URLSearchParams` gives it, without its `=`. */
-export function bareName(name: string): string {
-    return new URLSearchParams([[name, '']]).toString().slice(0, -1)
-}

package/src/shared/takeEarlyCall.ts

@@ -5,44 +5,19 @@
 import { EARLY_CALLS } from './EARLY_CALLS.ts'
 
 /**
- * What a call answered: the status and the text — which stays unset where the request itself did
- * not complete.
+ * What the early-call script leaves per call: the request in flight, and once it has answered, the
+ * `Response`. The script decides nothing about it — `answerOf` reads it as it reads any answer.
  */
-export type Answer = {
-    status: number | undefined
-    statusText: string | undefined
-    type: string | null | undefined
-    /**
-     * The answer's version, or `null` where it named none (18.5).
-     *
-     * A `null` is a value built per request.
-     */
-    version: string | null | undefined
-    /** The answer's `cache-control`, whose `max-age` is how long the copy may serve it (21.8). */
-    life: string | null | undefined
-    text: string | undefined
-    /**
-     * A binary answer's body read to the end (16.34), set in place of `text` — a body read as text
-     * is not the bytes it carried.
-     */
-    bytes: Uint8Array | undefined
-    /**
-     * A streamed answer's body, left unread so its chunks are taken as they land (16.32).
-     *
-     * Set in place of `text` for a handler the build marked as streaming, and by the early-call
-     * script for any framed answer.
-     */
-    body: ReadableStream<Uint8Array> | null | undefined
-}
-
-/**
- * What the early-call script leaves per call: the request in flight, and once it has answered, what
- * it answered.
- */
-export type EarlyCall = Answer & {
-    promise: Promise<void>
+export type EarlyCall = {
+    promise: Promise<unknown>
     /** `1` where the server built the page's markup from this call settled (41.25). */
     painted: 1 | undefined
+    /**
+     * Set once the request has answered — and, where `painted`, once its body is read to the end into
+     * `bytes`, so hydration's wait covers the body too. Unset where the request failed.
+     */
+    response: Response | undefined
+    bytes: ArrayBuffer | undefined
 }
 
 function startedCalls(): Record<string, EarlyCall | undefined> | undefined {
@@ -75,10 +50,10 @@ export function takeEarlyCall(key: string): EarlyCall | undefined {
 export function paintedCallsLanded(): Promise<unknown> | undefined {
     const started = startedCalls()
     if (started === undefined) return undefined
-    let waiting: Promise<void>[] | undefined
+    let waiting: Promise<unknown>[] | undefined
     for (const key in started) {
         const early = started[key]
-        if (early?.painted !== 1 || early.text !== undefined) continue
+        if (early?.painted !== 1 || early.response !== undefined) continue
         if (waiting === undefined) waiting = []
         waiting.push(early.promise)
     }

package/src/shared/url.ts

@@ -89,7 +89,7 @@ export function url<P extends RouteLiteral>(
     const address = mounted(
         filledPath(pattern ?? '/', params, `url('${pattern}')`),
     )
-    // 30.6 — the query half, last, in the spelling `rpcRequest` writes.
+    // 30.6 — the query half, last; 30.28 — in the spelling an `Rpc`'s args are written in.
     const search =
         query === undefined
             ? ''