@abide/abide 0.124.1 → 0.125.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@abide/abide",
-    "version": "0.124.1",
+    "version": "0.125.1",
     "type": "module",
     "description": "Isomorphic type-safe framework for reactive async interfaces for humans and machines",
     "license": "MIT",

package/src/compiler/appMap.ts

@@ -16,6 +16,8 @@ type MappedRoute = {
     kind: 'page' | 'handler' | 'private'
     /** 23.26 — each matcher its address names, to the anchored pattern it takes a part by. */
     matchers: Record<string, string>
+    /** 38.135 — the rungs a handler's `middleware` names, `[]` for none, `null` where unread. */
+    middleware: string[] | null
 }
 
 /** One hook call, the route it is filed at, and the file making it. */
@@ -42,6 +44,8 @@ export async function appMap(
             file: route.source,
             kind: 'page',
             matchers: route.matchers,
+            // A page declares no rungs of its own: what runs over it is filed by a hook (37.2).
+            middleware: [],
         })
     for (const mount of app.mounts)
         routes.push({
@@ -50,6 +54,7 @@ export async function appMap(
             file: mount.source,
             kind: mount.private ? 'private' : 'handler',
             matchers: mount.matchers,
+            middleware: mount.middleware,
         })
     routes.sort((one, two) =>
         one.address === two.address
@@ -81,7 +86,7 @@ export function mapText(map: Awaited<ReturnType<typeof appMap>>): string {
     const addresses = width(map.routes.map((route) => route.address))
     for (const route of map.routes)
         lines.push(
-            `${route.method.padEnd(methods)}  ${route.address.padEnd(addresses)}  ${route.file}${route.kind === 'private' ? '  (private)' : ''}`,
+            `${route.method.padEnd(methods)}  ${route.address.padEnd(addresses)}  ${route.file}${route.kind === 'private' ? '  (private)' : ''}${rungsText(route.middleware)}`,
         )
     // 23.26 — each matcher once, whichever routes name it: what a part must match to be taken.
     const matchers = new Map<string, string>()
@@ -105,3 +110,11 @@ export function mapText(map: Awaited<ReturnType<typeof appMap>>): string {
     }
     return lines.join('\n')
 }
+
+/** 38.135 — a handler's rungs as the text map prints them after its file, or nothing for none. */
+function rungsText(middleware: string[] | null): string {
+    if (middleware === null) return '  middleware: unread'
+    return middleware.length === 0
+        ? ''
+        : `  middleware: ${middleware.join(', ')}`
+}

package/src/compiler/compileApp.ts

@@ -404,6 +404,7 @@ async function emitApp(
         if (!mount.private)
             handlers[mount.source] = {
                 scope: mount.scope,
+                address: mount.address,
                 client: standIns.get(mount.source) ?? '',
                 args: mount.args,
             }

package/src/compiler/declaredExports.ts

@@ -10,6 +10,7 @@ import {
     isObjectLiteralExpression,
     isPropertyAccessExpression,
     isPropertyAssignment,
+    isSpreadElement,
     isStringLiteral,
     isVariableDeclaration,
 } from 'typescript/unstable/ast/is'
@@ -179,6 +180,10 @@ async function exportsIn(
                             cli: declared?.cli ?? true,
                             mcp: declared?.mcp ?? true,
                             description: declared?.description,
+                            middleware:
+                                declared === undefined
+                                    ? []
+                                    : declared.middleware,
                             copy: declared?.copy,
                             defaults: declared?.defaults,
                             args:
@@ -228,6 +233,7 @@ type DeclaredExport = Pick<
     | 'args'
     | 'result'
     | 'description'
+    | 'middleware'
 > & {
     method: Declared | undefined
     /** 18.15 — what its copy's options declare and the build could not read. */
@@ -249,6 +255,7 @@ async function declaringMethod(
           cli: boolean
           mcp: boolean
           description: string | undefined
+          middleware: string[] | null
           copy: CopyOptions | undefined
           unread: Node[]
           defaulted?: string[]
@@ -321,6 +328,7 @@ async function declaringMethod(
         cli: declaredFor(call, 'cli') ?? !answersResponse,
         mcp: declaredFor(call, 'mcp') ?? !answersResponse,
         description,
+        middleware: rungsNamed(call),
         ...declared,
         defaulted: defaultedMembers(body),
         defaults: literalDefaults(body) ?? undefined,
@@ -602,6 +610,39 @@ function describedAs(
         : undefined
 }
 
+/**
+ * The rung each entry of a handler call's inline `middleware` names, or `null` where its options are
+ * not an object written inline.
+ *
+ * 38.135 — AS WRITTEN, which is what the build can read without running it: an entry is named by
+ * the function it calls or the name it refers to, a spread by what it spreads, and an inline function
+ * `<inline>`. A value that is not an array is read as one entry, so `middleware: homeAccess(…)` names
+ * `homeAccess`.
+ */
+function rungsNamed(
+    call: Node & { arguments?: readonly Node[] },
+): string[] | null {
+    const options = call.arguments?.[1]
+    if (options === undefined) return []
+    if (!isObjectLiteralExpression(options)) return null
+    const written = optionNamed(options, 'middleware')
+    if (written === undefined) return []
+    const entries = isArrayLiteralExpression(written)
+        ? written.elements
+        : [written]
+    const names: string[] = []
+    for (const entry of entries)
+        names.push(rungName(isSpreadElement(entry) ? entry.expression : entry))
+    return names
+}
+
+function rungName(entry: Node): string {
+    const named = isCallExpression(entry) ? entry.expression : entry
+    return isIdentifier(named) || isPropertyAccessExpression(named)
+        ? named.getText()
+        : '<inline>'
+}
+
 /**
  * What a handler call's inline `clients` declares for `surface`, or `undefined` where it does not.
  *

package/src/compiler/handlersUnder.ts

@@ -128,6 +128,7 @@ export async function handlersUnder(
                 cli: false,
                 mcp: false,
                 description: each.description,
+                middleware: each.middleware,
                 copy: each.copy,
                 defaults: each.defaults,
                 args: each.args,

package/src/compiler/hookCalls.ts

@@ -18,6 +18,7 @@ export const HOOK_NAMES: ReadonlySet<string> = new Set([
     'onPrincipal',
     'onLauncher',
     'onMenu',
+    'onRefusal',
 ])
 
 /** One call of one of abide's hooks. */

package/src/compiler/projectShadow.ts

@@ -20,6 +20,7 @@ import {
     SOURCE_SUFFIX,
 } from './splitImports.ts'
 import type {
+    Attribute,
     Body,
     Branch,
     ElementNode,
@@ -489,7 +490,10 @@ function project(file: AbideFile): Projection {
                         const [kind, open] = attribute.lowerName.startsWith(
                             'bind:',
                         )
-                            ? (['elementBind', `${BIND}(`] as const)
+                            ? ([
+                                  'elementBind',
+                                  bindOpenerOf(node, attribute.lowerName),
+                              ] as const)
                             : openerOf(node.tag, attribute.lowerName)
                         slots.set(
                             attribute,
@@ -636,7 +640,7 @@ function project(file: AbideFile): Projection {
  * implicit `any`; an attribute on a component whose tag is no name a call can spell (`invocation`
  * has the rest) is typed by nothing the shadow can see, and says so with `any` rather than with an
  * error the author did not make. A `bind:` operand is not asked about here: the caller opens it
- * with `BIND`, which types it as `any` too.
+ * with `bindOpenerOf`.
  */
 function openerOf(
     tag: string,
@@ -648,6 +652,44 @@ function openerOf(
     return ['attribute', '(']
 }
 
+/**
+ * What a `bind:` operand on an element is opened with: the bind's `set` held to what the element
+ * writes back (32.78), or `BIND` where the element's write is no type the shadow knows.
+ *
+ * A `type` or a `multiple` written as an expression, or one a spread may write, is read as each it
+ * could be, so the `set` is held to the union of their writes.
+ */
+function bindOpenerOf(node: ElementNode, lowerName: string): string {
+    const kind = writesOf(node, lowerName)
+    return kind === undefined
+        ? `${BIND}(`
+        : `${BIND_WRITES}(${JSON.stringify(kind)})(`
+}
+
+/** Which write a `bind:` on an element stands for, as `BIND_WRITES` names its kinds. */
+function writesOf(node: ElementNode, lowerName: string): string | undefined {
+    if (lowerName === 'bind:checked' || lowerName === 'bind:open')
+        return 'boolean'
+    if (lowerName === 'bind:files') return 'files'
+    if (lowerName !== 'bind:value') return undefined
+    if (node.lowerTag === 'textarea') return 'text'
+    if (node.lowerTag !== 'input' && node.lowerTag !== 'select')
+        return undefined
+    const named = node.lowerTag === 'input' ? 'type' : 'multiple'
+    let written: Attribute | undefined
+    let spread = false
+    for (const attribute of node.attributes) {
+        if (attribute.lowerName === named) written = attribute
+        else if (attribute.name === '...') spread = true
+    }
+    if (written?.expression || (written === undefined && spread))
+        return node.lowerTag === 'input' ? 'input' : 'select'
+    if (node.lowerTag === 'select')
+        return written === undefined ? 'option' : 'options'
+    const type = written?.value.trim().toLowerCase()
+    return type === 'number' || type === 'range' ? 'number' : 'text'
+}
+
 const PROP = '__prop'
 // What an inline component's function names the record it is called with, and abide's `props` as
 // its head calls it (32.40) — bound here, since the author imports `props` only where they call it.
@@ -669,6 +711,8 @@ const ON = '__on'
 const ANY = '__any'
 /** 31.3 — what a `bind:` operand is wrapped in on an element and on a component. */
 const BIND = '__bind'
+/** 32.78 — what an element's `bind:` is opened with where the shadow knows what the element writes. */
+const BIND_WRITES = '__bindWrites'
 const BOUND = '__bound'
 
 /** 33.6 — the type a written prop's cell is checked as, which is the framework's own. */
@@ -696,6 +740,12 @@ declare function ${ANY}(value: any): void
 declare function ${PROP}<Value>(value: Value): Value
 declare function ${BIND}<Value>(value: { get(): Value; set(value: Value): unknown }): void
 declare function ${BIND}(value: any): void
+type ${BIND_WRITES}Number<Value> = [Extract<Value, number>] extends [never] ? never : number | undefined
+type ${BIND_WRITES}Text<Value> = [Extract<Value, number>] extends [never] ? string : [Exclude<Value, number>] extends [never] ? number | undefined : string | number | undefined
+type ${BIND_WRITES}Option<Value> = [Extract<Value, string>] extends [never] ? ${BIND_WRITES}Text<Value> : Extract<Value, string> | ${BIND_WRITES}Number<Value>
+type ${BIND_WRITES}Options<Value> = Value extends readonly (infer Item)[] ? [Extract<Item, string>] extends [never] ? string[] : Extract<Item, string>[] : string[]
+type ${BIND_WRITES}Of<Kind, Value> = Kind extends 'boolean' ? boolean : Kind extends 'files' ? File[] : Kind extends 'number' ? number | undefined : Kind extends 'input' ? string | number | undefined : Kind extends 'option' ? ${BIND_WRITES}Option<Value> : Kind extends 'options' ? ${BIND_WRITES}Options<Value> : Kind extends 'select' ? ${BIND_WRITES}Option<Value> | ${BIND_WRITES}Options<Value> : ${BIND_WRITES}Text<Value>
+declare function ${BIND_WRITES}<Kind extends string>(kind: Kind): <Value>(value: { (): Value; set: (value: ${BIND_WRITES}Of<Kind, Value>) => unknown } | { get(): Value; set: (value: ${BIND_WRITES}Of<Kind, Value>) => unknown }) => void
 declare function ${BOUND}<Value>(value: ${REACTIVE}<Value, any, any, any>): Value
 declare function ${BOUND}<Value>(value: { get(): Value; set(value: Value): unknown }): Value
 declare function __restValues<Accessors>(record: Accessors): { [Key in keyof Accessors]: NonNullable<Accessors[Key]> extends () => infer Value ? Value : never }

package/src/compiler/readsIn.ts

@@ -447,6 +447,14 @@ const NULLISH =
     TypeFlags.Any |
     TypeFlags.Unknown
 
+/** A union's members, or the type alone, with every `NULLISH` one aside. */
+async function presentMembers(type: Type): Promise<Type[]> {
+    const present: Type[] = []
+    for (const held of await unionMembers(type))
+        if ((held.flags & NULLISH) === 0) present.push(held)
+    return present
+}
+
 async function admitsNullish(type: Type): Promise<boolean> {
     for (const member of await unionMembers(type))
         if ((member.flags & NULLISH) !== 0) return true
@@ -737,11 +745,11 @@ function valueLeaves(node: Node, leaves: Node[]): void {
     }
 }
 
-// 23.1 — the four values `route` holds, each a `Reactive` of its own.
-const ROUTE_MEMBERS = new Set(['url', 'params', 'name', 'navigating'])
+// 23.1 — the five values `route` holds, each a `Reactive` of its own.
+const ROUTE_MEMBERS = new Set(['url', 'params', 'name', 'index', 'navigating'])
 
 /**
- * 31.15 — `route`'s four values, each read by name as a name bound to a `Reactive` is.
+ * 31.15 — `route`'s five values, each read by name as a name bound to a `Reactive` is.
  *
  * `route.params.id` reads `route.params().id`, and the explicit call keeps compiling (31.7). Told
  * by the symbol, as `props` is, so an app's own `route` is not abide's.
@@ -1224,11 +1232,10 @@ async function ownMembers(
         asked.push(
             valueOf(node).then(async (value) => {
                 if (value === undefined) return
-                for (const held of await unionMembers(value))
+                for (const held of await presentMembers(value))
                     if (
-                        (held.flags & NULLISH) === 0 &&
                         (await checker.getPropertyOfType(held, member)) !==
-                            undefined
+                        undefined
                     )
                         return void owned.add(node)
             }),
@@ -1282,7 +1289,9 @@ async function liftedMutators(
         asked.push(
             valueOf(node).then(async (value) => {
                 if (value === undefined) return
-                let types: Type[] = [value]
+                // `null` and `undefined` aside at the root as at every step down: `drafts?.push(d)`
+                // over a `Reactive<Draft[] | undefined>` is a mutator on an array.
+                let types = await presentMembers(value)
                 for (const step of steps)
                     types = await stepTypes(checker, types, step)
                 if (types.length === 0) return
@@ -1310,34 +1319,30 @@ async function stepTypes(
     step: string | undefined,
 ): Promise<Type[]> {
     const next: Type[] = []
-    for (const type of types)
-        for (const held of await unionMembers(type)) {
-            if ((held.flags & NULLISH) !== 0) continue
-            if (step !== undefined) {
-                const member = await checker.getPropertyOfType(held, step)
-                const stepped =
-                    member === undefined
-                        ? undefined
-                        : await checker.getTypeOfSymbol(member)
-                if (stepped !== undefined)
-                    next.push(...(await unionMembers(stepped)))
-                continue
-            }
-            if (await checker.isArrayType(held)) {
-                const [element] = await checker.getTypeArguments(
-                    held as TypeReference,
-                )
-                if (element !== undefined)
-                    next.push(...(await unionMembers(element)))
-                continue
-            }
-            for (const index of await checker.getIndexInfosOfType(held))
-                next.push(...(await unionMembers(index.valueType)))
+    // `types` is present members already: the root's, or this walk's own.
+    for (const held of types) {
+        if (step !== undefined) {
+            const member = await checker.getPropertyOfType(held, step)
+            const stepped =
+                member === undefined
+                    ? undefined
+                    : await checker.getTypeOfSymbol(member)
+            if (stepped !== undefined)
+                next.push(...(await presentMembers(stepped)))
+            continue
         }
-    const present: Type[] = []
-    for (const type of next)
-        if ((type.flags & NULLISH) === 0) present.push(type)
-    return present
+        if (await checker.isArrayType(held)) {
+            const [element] = await checker.getTypeArguments(
+                held as TypeReference,
+            )
+            if (element !== undefined)
+                next.push(...(await presentMembers(element)))
+            continue
+        }
+        for (const index of await checker.getIndexInfosOfType(held))
+            next.push(...(await presentMembers(index.valueType)))
+    }
+    return next
 }
 
 /**

package/src/server/PageRender.ts

@@ -11,7 +11,6 @@
 import { EARLY_CALLS } from '#shared/EARLY_CALLS.ts'
 import { HandlerRoute } from '#shared/HandlerRoute.ts'
 import { KEEP_HEADER } from '#shared/KEEP_HEADER.ts'
-import { KEEP_OPENED } from '#shared/KEEP_OPENED.ts'
 import type { Rpc } from '#shared/rpc.ts'
 import { type RpcRequest, rpcRequest } from '#shared/rpcRequest.ts'
 
@@ -141,18 +140,18 @@ export class PageRender {
  * one `principal.caller` reads for the rest of the request. 41.13 — every call the render makes is
  * left for the browser's own call to be answered from. 41.29 — BUT NOT A PAGE A SCRIPT FETCHED, which
  * nothing hydrates: its entries would answer the next call this caller makes with what the render
- * saw, a sign-in since included — save the one the worker fetched for the navigation it answers,
- * which is the page that hydrates (45.23). 41.30 — SAVE ONE THE WORKER KEEPS, whose early calls are
- * what a later open of it starts.
+ * saw, a sign-in since included. The worker asks for the navigation it answers as that navigation
+ * (45.25), so the page that hydrates is never one a script fetched. 41.30 — SAVE ONE THE WORKER
+ * KEEPS, whose early calls are what a later open of it starts.
  */
 export function beginPageRender(request: Request): PageRender {
     const caller = callerOrMint()
     const keep = request.headers.get(KEEP_HEADER)
-    const hydrated =
-        keep === KEEP_OPENED ||
-        request.headers.get('sec-fetch-dest') !== 'empty'
     const page = new PageRender(
-        hydrated
+        // A WORKER'S NAVIGATION IS STILL ONE: forwarded unchanged (45.25) it arrives `navigate` with
+        // its destination `empty`, and no script's fetch can ask in that mode.
+        request.headers.get('sec-fetch-dest') !== 'empty' ||
+            request.headers.get('sec-fetch-mode') === 'navigate'
             ? seedFor(caller)
             : keep !== null
               ? callsOnly()

package/src/server/abideModules.ts

@@ -135,6 +135,8 @@ export function serveCompilation(root: string, compilation: Compilation): void {
 // plugin per compilation because the filter is fixed at registration, and the runtime's `onLoad`
 // cannot fall through, so the filter names the handler files and nothing else. The face it names
 // is resolved by `modulesPlugin`, registered once.
+// 16.88 — AND GIVES IT ITS ADDRESS, so a test importing the file calls, links and matches it (44.51)
+// with no app booted.
 // 15.8, 19.9 — AND HOLDS ITS HANDLER TO THE SCHEMA ITS ANNOTATION DERIVES, once the face has built it:
 // this module is what every import of the file is answered with — the server's mount, a test's own
 // import, a component's under `mount` — so a call is held to it whoever makes it.
@@ -153,15 +155,20 @@ function handlerFilesPlugin(
                 },
                 (args) => {
                     const face = JSON.stringify(`${args.path}${HANDLER_SUFFIX}`)
-                    const schema = faces.get(args.path)?.args
-                    return {
-                        contents:
-                            `export { default } from ${face}\n` +
-                            (schema === undefined
-                                ? ''
-                                : `import __handler from ${face}\nimport { derivedArgs as __derivedArgs } from '${SERVER_SPECIFIER}'\n__derivedArgs(__handler, ${JSON.stringify(schema)})\n`),
-                        loader: 'js',
-                    }
+                    const { address, args: schema } = faces.get(
+                        args.path,
+                    ) as HandlerFace
+                    const lines = [
+                        `export { default } from ${face}`,
+                        `import __handler from ${face}`,
+                        `import { addressed as __addressed, derivedArgs as __derivedArgs } from '${SERVER_SPECIFIER}'`,
+                        `__addressed(__handler, ${JSON.stringify(address)})`,
+                    ]
+                    if (schema !== undefined)
+                        lines.push(
+                            `__derivedArgs(__handler, ${JSON.stringify(schema)})`,
+                        )
+                    return { contents: `${lines.join('\n')}\n`, loader: 'js' }
                 },
             )
         },
@@ -489,11 +496,17 @@ function compiledAt(served: Held, path: string): CompiledFile {
 // what an app's own module calls is a function of plain props answering a `Component` (35.4), which
 // `render` invokes with nothing. The component is the module's one export (34.17).
 // 38.119 — and it carries what `mount` hydrates it with: the same accessors, and its browser module.
+// 38.134 — a prop written as a getter is read through it on every read, as a parent's would be.
 function boundModule(path: string): string {
     return `import component from ${JSON.stringify(path)}
 export default (props = {}) => {
     const accessors = {}
     for (const key in props) {
+        const live = Object.getOwnPropertyDescriptor(props, key)?.get
+        if (live !== undefined) {
+            accessors[key] = () => live.call(props)
+            continue
+        }
         const value = props[key]
         accessors[key] = () => value
     }

package/src/server/addressed.ts

@@ -0,0 +1,14 @@
+import { mounted } from '#shared/mount.ts'
+
+/**
+ * Gives a handler its address: `route` under the mount, read when it is reported.
+ *
+ * 16.88 — ONE WRITER, READ LATE: the mount is the configuration's, so the address a file's module
+ * is given as it loads is the one a boot would give it, and a later call only names the route again.
+ */
+export function addressed(handler: object, route: string): void {
+    Object.defineProperty(handler, 'address', {
+        get: () => mounted(route),
+        configurable: true,
+    })
+}