@abide/abide 0.123.2 → 0.124.0

package/src/shared/reactive/argsContract.ts

@@ -1,7 +1,9 @@
 // WHAT A KEYED VALUE'S ARGS ARE HELD TO, past the face an app is handed: the `args` schema it was
-// declared with (19.7) and the defaults its body's parameter writes (11.29). A `Keyed` is where the
-// contract starts; a server's forwarder and an `Rpc` are faces built over one, and each carries it
-// through `contractOf` so a transport reads it off whichever face it was handed.
+// declared with (19.7), the defaults its body's parameter writes (11.29), and — on a server's `Rpc`
+// — the schema its annotation derives (19.9). A `Keyed` is where the contract starts; a server's
+// forwarder and an `Rpc` are faces built over one, and each carries it through `contractOf` so a
+// transport reads it off whichever face it was handed. What a server adds before a call off the wire
+// reaches here — its text coerced, its path's parameters laid in — is `#server/argsContract.ts`.
 //
 // DEFAULTS BEFORE THE KEY, IN ONE PLACE. 11.27: a call that left a member to the parameter and one
 // that wrote it are one entry, so every reach, call and lookup takes the key through `normalized`
@@ -10,9 +12,11 @@
 //
 // Imports no part of the core, so `scoped.ts` can carry the contract without reaching `Keyed.ts`.
 
+import { DERIVED_ARGS } from '../DERIVED_ARGS.ts'
+import type { Issues } from '../Issues.ts'
 import { putOwn } from '../putOwn.ts'
+import { validationError } from '../refuse.ts'
 import type { Schema } from '../Schema.ts'
-import { canonicalKey } from './canonicalKey.ts'
 import type { Defaults } from './parameterDefaults.ts'
 
 export const ARGS_GATE: unique symbol = Symbol.for('abide.argsGate')
@@ -62,6 +66,35 @@ export function normalized<Args>(
     return defaults === null ? args : withDefaults(args, defaults)
 }
 
+/**
+ * 19.9 — the issues an `Rpc`'s args leave against the schema its annotation derives, `null` where
+ * they hold: `undefined` until the module its handler is loaded through stamps it (`derivedArgs`),
+ * and so in a browser always. A function rather than the schema, so this seam never carries the
+ * validator (19.13).
+ */
+export type HeldToAnnotation = {
+    [DERIVED_ARGS]: ((args: unknown) => Issues<unknown> | null) | undefined
+}
+
+/**
+ * The args a call of `face` is made with: `normalized`, then held to the schema its annotation
+ * derives. Throws the `ValidationError` where they do not hold.
+ *
+ * 15.8, 19.9 — ONE STEP FOR EVERY WAY A HANDLER IS CALLED, in process and over the wire alike: a
+ * type an in-process caller wrote holds nothing at run time (`as never`, a value off JSON), so it is
+ * refused as the wire refuses it rather than handed to the body. 11.27 — the defaults first, so the
+ * check reads what the handler will.
+ */
+export function acceptedArgs(
+    face: Pick<Gated<unknown>, typeof PARAMETER_DEFAULTS> & HeldToAnnotation,
+    given: unknown,
+): unknown {
+    const args = normalized(face, given)
+    const issues = face[DERIVED_ARGS]?.(args) ?? null
+    if (issues !== null) throw validationError(issues)
+    return args
+}
+
 /** The entry key a call with `args` is filed under: `normalized`, then 11.24's canonical form. */
 export function keyOf(
     face: Pick<Gated<unknown>, typeof PARAMETER_DEFAULTS>,
@@ -95,3 +128,97 @@ function withDefaults<Args>(args: Args, defaults: Defaults): Args {
     }
     return (filled ?? given) as Args
 }
+
+/**
+ * The entry key for an `Args` value: its canonical wire form, as a string.
+ *
+ * RULEBOOK 11.24: members sorted by name, `undefined` members dropped, `Date` written ISO.
+ *
+ * 11.26: the key is taken BEFORE any gate runs, because a browser holds no copy of the gate — a
+ * key taken after normalizing is computed one way on a server and another in a browser, and every
+ * handler with a normalizing schema would miss its seed buffer and re-issue the call on hydration.
+ *
+ * 11.64: WHAT THE WIRE FORM CANNOT WRITE IS REFUSED AT THE REACH. `JSON.stringify` does not fail
+ * on any of it — a `Set`, a `Map` and a class instance each have no own enumerable keys and
+ * canonicalize to `{}`, and a non-finite number is written `null` — so two different reaches
+ * produced one key and 1.8 joined the second to the first's standing work. The value was right
+ * for the first caller and wrong for every other one, with nothing to see.
+ */
+export function canonicalKey(args: unknown): string {
+    if (args === undefined) return ''
+    return JSON.stringify(canonical(args, []))
+}
+
+// THE PATH IS A STACK OF STEPS, joined only when a refusal names it. Built as a string per member
+// it was a concatenation for every element and every nested key on every reach, for a message the
+// success path never reads.
+type Steps = (string | number)[]
+
+function canonical(value: unknown, path: Steps): unknown {
+    if (value === null) return value
+    const kind = typeof value
+    if (kind === 'number') {
+        if (!Number.isFinite(value)) throw outside(String(value), path)
+        return value
+    }
+    if (kind !== 'object') {
+        if (kind === 'boolean' || kind === 'string') return value
+        // `undefined` reaches here from an ARRAY element alone — a member is dropped above.
+        throw outside(kind === 'undefined' ? 'undefined' : `a ${kind}`, path)
+    }
+    if (value instanceof Date) return value.toISOString()
+    if (Array.isArray(value)) {
+        const out: unknown[] = []
+        for (let index = 0; index < value.length; index += 1) {
+            path.push(index)
+            out.push(canonical(value[index], path))
+            path.pop()
+        }
+        return out
+    }
+    const prototype = Object.getPrototypeOf(value)
+    if (prototype !== Object.prototype && prototype !== null)
+        throw outside(named(value as object), path)
+    const source = value as Record<string, unknown>
+    const keys = Object.keys(source).sort()
+    // AN ORDINARY OBJECT, AND `putOwn` FOR THE ONE KEY THAT NEEDS IT: `__proto__` is a SETTER on
+    // `Object.prototype`, so `out[key] = …` for that key creates no own property and
+    // `JSON.stringify` never sees it — `{id: 1, __proto__: {role: 'admin'}}` and `{id: 1}` then
+    // canonicalize to one string, and 1.8 joins the second reach to the first's standing work.
+    // `Object.create(null)` closed that too, and V8 builds it in DICTIONARY mode: the shipped key
+    // took 49-56% of the time without it there, and a standing keyed reach 53%, where JSC reads
+    // level to 110% (`abide/bench/sharedCases.ts`, two runs per engine).
+    const out: Record<string, unknown> = {}
+    for (let index = 0; index < keys.length; index += 1) {
+        const key = keys[index] as string
+        const member = source[key]
+        if (member === undefined) continue
+        path.push(key)
+        putOwn(out, key, canonical(member, path))
+        path.pop()
+    }
+    return out
+}
+
+function named(value: object): string {
+    const from = value.constructor as { name?: unknown } | undefined
+    return typeof from?.name === 'string' && from.name !== ''
+        ? `a ${from.name}`
+        : 'a class instance'
+}
+
+function outside(what: string, steps: Steps): Error {
+    let path = ''
+    for (const step of steps)
+        path +=
+            typeof step === 'number'
+                ? `[${step}]`
+                : path === ''
+                  ? step
+                  : `.${step}`
+    return new Error(
+        `An Args key cannot carry ${what} at ${
+            path === '' ? 'the arguments themselves' : `"${path}"`
+        }: the canonical wire form writes it as another entry's key (RULEBOOK 11.64).`,
+    )
+}

package/src/shared/reactive/byOf.ts

@@ -3,6 +3,7 @@
 // the chunk every page loads. The cell is read here, in the core's folder, so its layout stays the
 // core's.
 import { CELL } from './CELL.ts'
+import type { Callable } from './cellShape.ts'
 import { isReactive } from './isReactive.ts'
 
 /** The `by` a `Reactive` declared (32.32), or `null` where it declared none or `value` is not one. */
@@ -10,9 +11,5 @@ export function byOf(
     value: unknown,
 ): string | ((element: unknown) => unknown) | null {
     if (!isReactive(value)) return null
-    return (
-        value as unknown as {
-            [CELL]: { by: string | ((element: unknown) => unknown) | null }
-        }
-    )[CELL].by
+    return (value as unknown as Callable)[CELL].by
 }

package/src/shared/reactive/callLoad.ts

@@ -7,18 +7,16 @@
 // 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 { beginLoadCall, endLoadCall, reachedInLoadCall } from '../loadCall.ts'
 import { aborted, refuse } from '../refuse.ts'
-// Through the barrel, for the cycle it names: rpc reaches this module ahead of the barrel.
+// Through the barrel first, for the cycle it names: rpc reaches this module ahead of the barrel.
+import { isReactive, STREAMING } from './index.ts'
 import {
     abandonLoad,
     failedTransiently,
-    isReactive,
     loadOf,
-    STREAMING,
     streamingOrSettled,
-} from './index.ts'
+} from './producer.ts'
 
 /**
  * Who is waiting on one value's load, and what the last one came to.
@@ -75,7 +73,7 @@ const ATTENDED = new WeakMap<object, Attended>()
  * Reaches `args` through `reach` as a call does, under that call's `signal` and `timeout`.
  *
  * 16.49 — a load this call starts may be ended by it, so its transport is handed a signal of the
- * load's own (`LOAD_SIGNAL`, read by the body as it starts) — the caller's is only one vote.
+ * load's own (`startingLoadCall`, read by the body as it starts) — the caller's is only one vote.
  */
 export function callLoad(
     reach: (args: unknown) => unknown,
@@ -86,14 +84,12 @@ export function callLoad(
     offline?: (args: unknown) => unknown,
 ): unknown {
     const ending = signal === undefined ? undefined : new AbortController()
-    LOAD_SIGNAL.current = ending?.signal
-    LOAD_OFFLINE.current = offline
+    beginLoadCall(ending?.signal, offline)
     let reached: unknown
     let attended: Attended | undefined
     try {
         reached = reach(args)
-        const standing = LOAD_OFFLINE.standing
-        if (standing !== undefined) standing.value = reached
+        reachedInLoadCall(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
@@ -106,9 +102,7 @@ export function callLoad(
         if (again || failedTransiently(reached))
             (reached as { refresh(): void }).refresh()
     } finally {
-        LOAD_SIGNAL.current = undefined
-        LOAD_OFFLINE.current = undefined
-        LOAD_OFFLINE.standing = undefined
+        endLoadCall()
     }
     if (!isReactive(reached)) return reached
     const load = loadOf(reached)