@abide/abide 0.123.2 → 0.124.0

package/src/server/appBuild.ts

@@ -0,0 +1,377 @@
+// THE BUILD OF THE APP UNDER A ROOT, ON DISK: where it lives (38.27), what is in it, whether there
+// is one, and making one where there is not (38.100). `abide build` writes it, and `abide start`,
+// `createApp`, the test preload and the CLI's own reads take it — every one through here, so the
+// layout is spelled once and "is there a build" has one answer.
+//
+// THE COMPILATION IS THE MARKER. A build removes it before writing anything and writes it last, so a
+// build that failed partway leaves no build — `abide start` builds again and says why, rather than
+// booting what is left (38.100).
+//
+// 42.16 — UNDER `bun test`, THE BUILD IS ONE PER STATE OF THE APP'S SOURCES: its directory is named
+// after a hash of what made it, so a build either matches the sources or does not exist, and every
+// test process — every `--parallel` worker, every spawned child — reuses the one that does. Eight
+// workers each building their own copy of a 1.3 s build waited 7–10 s apiece.
+
+import { mkdir, rename, rm, utimes, writeFile } from 'node:fs/promises' // bun exposes no directory creation, rename, removal, mtime write or exclusive create of its own
+import { dirname } from 'node:path' // bun exposes no path helpers of its own
+
+import type { Compilation } from './abideModules.ts'
+import type { AppSources } from './answerRequest.ts'
+import type { Manifest } from './manifestOf.ts'
+import { namesUnder } from './namesUnder.ts'
+import { packageDirectory } from './packageDirectory.ts'
+import { builtSources, serveApp, type ServedApp } from './servedApp.ts'
+
+/** What builds the app under `root` into `out` where nobody has: spawned, or the CLI's own. */
+export type Builder = (root: string, out: string) => Promise<unknown>
+
+/** Where each part of the build in `out` is. */
+export type BuildFiles = {
+    /** The compilation — every `.abide` compiled, and the build's tables — and the marker. */
+    compilation: string
+    /** 38.5 — beside the bundle rather than in it: everything under `client` is the browser's. */
+    manifest: string
+    /** The browser bundle, each file beside its precompressed copies (38.5). */
+    client: string
+    /** 38.18 — every `public` directory, each file at its address. */
+    published: string
+}
+
+// The CLI, spawned rather than imported: the compiler is not reachable from the server seam.
+const ABIDE_BIN = Bun.fileURLToPath(
+    new URL('../../bin/abide.ts', import.meta.url),
+)
+// The framework's own source is part of what made a build: a compiler change is a new build.
+const FRAMEWORK = Bun.fileURLToPath(new URL('../..', import.meta.url))
+const POLL_MS = 50
+// A test build no process has reused for this long is swept by the next one that builds.
+const UNUSED_FOR_MS = 24 * 60 * 60 * 1000
+
+// One lookup per app per test process, however many files in it call `createApp`.
+const TEST_BUILDS = new Map<string, Promise<string>>()
+
+/** Where the build of the app under `root` goes: `.abide` in its package. 38.27. */
+export function buildDirectory(root: string): string {
+    return `${packageDirectory(root)}/.abide`
+}
+
+export function buildFiles(out: string): BuildFiles {
+    return {
+        compilation: `${out}/compilation.json`,
+        manifest: `${out}/manifest.json`,
+        client: `${out}/client`,
+        published: `${out}/public`,
+    }
+}
+
+/**
+ * The files a build into `out` writes, its previous marker removed first — so that from here until
+ * `markBuild`, `out` holds no build.
+ */
+export async function unmarkedBuild(out: string): Promise<BuildFiles> {
+    const files = buildFiles(out)
+    await rm(files.compilation, { force: true })
+    return files
+}
+
+/** Ends a build: its compilation, written whole and last, is what says there is one. */
+export function markBuild(
+    files: BuildFiles,
+    compilation: Compilation,
+): Promise<void> {
+    return writeWhole(files.compilation, JSON.stringify(compilation))
+}
+
+/**
+ * Writes `path` whole: to a name of its own beside it, then renamed over it.
+ *
+ * 38.66 — a reader, or a second build, finds the last complete file there and never a partial one.
+ */
+export async function writeWhole(
+    path: string,
+    content: string | Blob,
+): Promise<void> {
+    const partial = `${path}.${crypto.randomUUID()}.partial`
+    await Bun.write(partial, content)
+    await rename(partial, path)
+}
+
+/** What a build in `out` holds beside its compilation: the manifest, and every file it serves. */
+export async function builtFiles(out: string): Promise<{
+    manifest: Manifest
+    client: Map<string, string>
+    published: Map<string, string>
+}> {
+    const files = buildFiles(out)
+    return {
+        manifest: (await Bun.file(files.manifest).json()) as Manifest,
+        client: pathsUnder(files.client),
+        published: pathsUnder(files.published),
+    }
+}
+
+/**
+ * The build in `out` served to this process's imports, with the sources an `App` is booted over —
+ * or `undefined` where `out` holds no build and `build` made none.
+ *
+ * 38.6 — what `abide start` boots: no compiler is loaded, and every `.abide` the app imports is
+ * answered out of what the build compiled. 38.100 — AN APP NOBODY BUILT IS BUILT, by `build`,
+ * rather than refused; `undefined` builds nothing, for a reader aimed at a build already there.
+ */
+export async function servedBuild(
+    root: string,
+    out: string,
+    build: Builder | undefined,
+): Promise<(ServedApp & { load: () => Promise<AppSources> }) | undefined> {
+    const marker = buildFiles(out).compilation
+    if (!(await Bun.file(marker).exists())) {
+        if (build === undefined) return undefined
+        await build(root, out)
+        // A FRESH HANDLE: one taken before the build wrote the file reads it as empty.
+        if (!(await Bun.file(marker).exists())) return undefined
+    }
+    // Read beside the table's import rather than after it; a boot that never loads drops it.
+    const files = builtFiles(out)
+    files.catch(() => {})
+    const served = await serveApp(
+        root,
+        (await Bun.file(marker).json()) as Compilation,
+    )
+    return {
+        ...served,
+        load: async () =>
+            builtSources({
+                table: served.table,
+                handlers: served.table.handlers,
+                ...(await files),
+            }),
+    }
+}
+
+/** `abide build` of the app under `root` into `out`, run as the CLI. */
+export async function spawnedBuild(root: string, out: string): Promise<void> {
+    const child = Bun.spawn(
+        [process.execPath, ABIDE_BIN, 'build', '--root', root, '--out', out],
+        { stdout: 'ignore', stderr: 'pipe' },
+    )
+    const [exitCode, said] = await Promise.all([
+        child.exited,
+        new Response(child.stderr).text(),
+    ])
+    if (exitCode !== 0)
+        throw new Error(
+            `abide: could not build the app under ${root}.\n${said}`,
+        )
+}
+
+/**
+ * Where this process reads the build of the app under `root` from: its `buildDirectory`, or — `fresh`,
+ * which `bun test` is (42.16) — the build of its sources as they stand, made if no process has.
+ */
+export async function processBuild(
+    root: string,
+    fresh = process.env.NODE_ENV === 'test',
+): Promise<string> {
+    if (!fresh) return buildDirectory(root)
+    let built = TEST_BUILDS.get(root)
+    if (built === undefined) {
+        // UNDER `node_modules`, so a bare import in the built modules resolves as it does from the
+        // app, and so it is ignored wherever `node_modules` is.
+        built = sourceHash(root).then((key) =>
+            sharedBuild(
+                `${packageDirectory(root)}/node_modules/.cache/abide`,
+                `build-${key}`,
+                (out) => spawnedBuild(root, out),
+            ),
+        )
+        TEST_BUILDS.set(root, built)
+    }
+    return built
+}
+
+/** Every file under `directory`, by the name below it to its path. */
+function pathsUnder(directory: string): Map<string, string> {
+    const paths = new Map<string, string>()
+    for (const name of namesUnder(directory))
+        paths.set(name, `${directory}/${name}`)
+    return paths
+}
+
+/**
+ * `builds/key`, made by `build` in exactly one process however many ask at once.
+ *
+ * THE FIRST TO CREATE `key.lock` BUILDS — an exclusive create is atomic, so one process wins — into
+ * a staging directory renamed into place, so nothing reads a half-written build. The rest wait for
+ * it, and take the lock over if the process holding it has ended.
+ */
+export async function sharedBuild(
+    builds: string,
+    key: string,
+    build: (out: string) => Promise<void>,
+): Promise<string> {
+    const out = `${builds}/${key}`
+    const lock = `${out}.lock`
+    await mkdir(builds, { recursive: true })
+    for (;;) {
+        if (await isDirectory(out)) {
+            const now = new Date()
+            await utimes(out, now, now)
+            return out
+        }
+        if (await claim(lock)) {
+            try {
+                if (!(await isDirectory(out))) await buildInto(out, build)
+            } finally {
+                await rm(lock, { force: true })
+            }
+            await sweep(builds, key)
+            return out
+        }
+        if (await holderEnded(lock)) await rm(lock, { force: true })
+        else await Bun.sleep(POLL_MS)
+    }
+}
+
+async function buildInto(
+    out: string,
+    build: (out: string) => Promise<void>,
+): Promise<void> {
+    const staging = `${out}.tmp-${process.pid}`
+    await rm(staging, { recursive: true, force: true })
+    try {
+        await build(staging)
+        await rename(staging, out)
+    } catch (thrown) {
+        await rm(staging, { recursive: true, force: true })
+        // TWO HOLDERS, where one took over a lock the other had just taken over: the first rename
+        // stands, and it is the same build.
+        if (await isDirectory(out)) return
+        throw thrown
+    }
+}
+
+/**
+ * A hash of everything a build of the app under `root` is made from.
+ *
+ * The app's files, its package's manifest and tsconfig and the lockfile above them, the framework's
+ * own source, and `root` itself, since a build carries the paths it was made at.
+ */
+export async function sourceHash(root: string): Promise<string> {
+    const app = packageDirectory(root)
+    const paths = [
+        ...filesUnder(root),
+        ...filesUnder(`${FRAMEWORK}src`),
+        ...filesUnder(`${FRAMEWORK}bin`),
+        `${app}/package.json`,
+        `${app}/tsconfig.json`,
+    ]
+    const lockfile = await lockfileAbove(app)
+    if (lockfile !== undefined) paths.push(lockfile)
+    const contents = await Promise.all(
+        paths.map((path) =>
+            Bun.file(path)
+                .bytes()
+                .catch(() => undefined),
+        ),
+    )
+    const hasher = new Bun.CryptoHasher('sha256')
+    hasher.update(root)
+    for (let at = 0; at < paths.length; at += 1) {
+        const bytes = contents[at]
+        if (bytes === undefined) continue
+        hasher.update(paths[at] as string)
+        hasher.update(bytes)
+    }
+    return hasher.digest('hex').slice(0, 16)
+}
+
+// Sorted, so the hash does not depend on the order a directory lists in. Dot entries and
+// `node_modules` are skipped: neither is the app's source, and the builds live in one.
+function filesUnder(directory: string): string[] {
+    const found: string[] = []
+    for (const name of namesUnder(directory))
+        if (!`/${name}`.includes('/node_modules/'))
+            found.push(`${directory}/${name}`)
+    return found.sort()
+}
+
+async function lockfileAbove(directory: string): Promise<string | undefined> {
+    for (let at = directory; ; at = dirname(at)) {
+        for (const name of ['bun.lock', 'bun.lockb'])
+            if (await Bun.file(`${at}/${name}`).exists()) return `${at}/${name}`
+        if (dirname(at) === at) return undefined
+    }
+}
+
+async function claim(lock: string): Promise<boolean> {
+    try {
+        await writeFile(lock, String(process.pid), { flag: 'wx' })
+        return true
+    } catch (thrown) {
+        if ((thrown as { code?: string }).code === 'EEXIST') return false
+        throw thrown
+    }
+}
+
+async function holderEnded(lock: string): Promise<boolean> {
+    const text = await Bun.file(lock)
+        .text()
+        .catch(() => undefined)
+    // Gone is not ended: the holder finished, and the next pass finds its build.
+    if (text === undefined) return false
+    // Empty is a holder between creating the lock and writing its pid.
+    return text !== '' && !isRunning(Number(text))
+}
+
+/** Removes builds unused for a day, and what an ended process left half-made. */
+async function sweep(builds: string, kept: string): Promise<void> {
+    const names = new Bun.Glob('*').scanSync({ cwd: builds, onlyFiles: false })
+    const removals: Promise<void>[] = []
+    const now = Date.now()
+    for (const name of names) {
+        if (name === kept) continue
+        const staged = /\.tmp-(\d+)$/.exec(name)
+        if (staged !== null) {
+            if (!isRunning(Number(staged[1])))
+                removals.push(
+                    rm(`${builds}/${name}`, { recursive: true, force: true }),
+                )
+            continue
+        }
+        if (name.endsWith('.lock')) continue
+        removals.push(
+            Bun.file(`${builds}/${name}`)
+                .stat()
+                .then((found) =>
+                    now - found.mtimeMs > UNUSED_FOR_MS
+                        ? rm(`${builds}/${name}`, {
+                              recursive: true,
+                              force: true,
+                          })
+                        : undefined,
+                )
+                .catch(() => undefined),
+        )
+    }
+    await Promise.all(removals)
+}
+
+async function isDirectory(path: string): Promise<boolean> {
+    return (
+        (
+            await Bun.file(path)
+                .stat()
+                .catch(() => undefined)
+        )?.isDirectory() === true
+    )
+}
+
+function isRunning(pid: number): boolean {
+    try {
+        process.kill(pid, 0)
+        return true
+    } catch (thrown) {
+        // EPERM is a process that exists and is someone else's.
+        return (thrown as { code?: string }).code === 'EPERM'
+    }
+}

package/src/server/appKit.ts

@@ -1,4 +1,4 @@
-// THE OBJECTIVE-C RUNTIME, over `bun:ffi` — what the desktop launcher (`runDesktop`) drives AppKit
+// THE OBJECTIVE-C RUNTIME, over `bun:ffi` — what the desktop window (`openDesktopWindow`) drives AppKit
 // and WebKit with. Bun's own `WebView` is headless, so a window and a menu bar are this module's.
 //
 // NO STRUCT IS PASSED BY VALUE. A `CGRect` is four doubles in registers on arm64 and a block on the

package/src/server/appPlugins.ts

@@ -1,26 +1,24 @@
-import { appDirectories } from './appDirectories.ts'
+import { packageDirectory } from './packageDirectory.ts'
 
 /**
  * The app's own bundler plugins, loaded from `bunfig.toml`'s `[serve.static] plugins`.
  *
  * 38.43 — declared where bun already has an app declare them, the key `bun-plugin-tailwind`
- * documents. `Bun.build` reads no bunfig, so both client builds read this one — in
- * `appDirectories`, as `config` finds the app's `package.json`.
+ * documents. `Bun.build` reads no bunfig, so both client builds read this one — the app's
+ * package's (`packageDirectory`), beside the `package.json` `config` reads.
  */
 export async function appPlugins(root: string): Promise<Bun.BunPlugin[]> {
-    for (const directory of appDirectories(root)) {
-        const file = Bun.file(`${directory}/bunfig.toml`)
-        if (!(await file.exists())) continue
-        const parsed = Bun.TOML.parse(await file.text()) as {
-            serve?: { static?: { plugins?: string[] } }
-        }
-        const plugins: Bun.BunPlugin[] = []
-        for (const specifier of parsed.serve?.static?.plugins ?? [])
-            plugins.push(
-                (await import(Bun.resolveSync(specifier, directory)))
-                    .default as Bun.BunPlugin,
-            )
-        return plugins
+    const directory = packageDirectory(root)
+    const file = Bun.file(`${directory}/bunfig.toml`)
+    if (!(await file.exists())) return []
+    const parsed = Bun.TOML.parse(await file.text()) as {
+        serve?: { static?: { plugins?: string[] } }
     }
-    return []
+    const plugins: Bun.BunPlugin[] = []
+    for (const specifier of parsed.serve?.static?.plugins ?? [])
+        plugins.push(
+            (await import(Bun.resolveSync(specifier, directory)))
+                .default as Bun.BunPlugin,
+        )
+    return plugins
 }

package/src/server/appTree.ts

@@ -12,15 +12,16 @@
 // A WALK RATHER THAN A GLOB: a glob descends `node_modules` and the build output before a filter
 // can drop them.
 
-import { type Dirent, existsSync, readdirSync } from 'node:fs' // bun has no directory listing or sync existence check of its own
+import { type Dirent, readdirSync } from 'node:fs' // bun has no directory listing of its own
 
-import type { Refusals } from '#compiler/Refusals.ts'
+import type { Diagnostics } from '#compiler/Diagnostics.ts'
 import { ABIDE_ADDRESS } from '#shared/ADDRESSES.ts'
 import {
     PUBLIC_DIRECTORY,
     RESERVED_DIRECTORIES,
 } from '#shared/RESERVED_DIRECTORIES.ts'
 
+import { packageDirectory } from './packageDirectory.ts'
 import {
     DIRECTORY_FILES,
     isBenchFile,
@@ -54,7 +55,7 @@ type AppFiles = {
  *
  * A missing root is an app with nothing in it, not a fault.
  */
-export function appFiles(root: string, refusals: Refusals): AppFiles {
+export function appFiles(root: string, refusals: Diagnostics): AppFiles {
     const files: AppFiles = {
         abide: [],
         handlers: [],
@@ -64,7 +65,7 @@ export function appFiles(root: string, refusals: Refusals): AppFiles {
     }
     // 23.22, 38.25 — a root that is its package's directory holds the package's own files beside its
     // pages.
-    const packaged = existsSync(`${root}/package.json`)
+    const packaged = packageDirectory(root) === root
     walk(root, '', undefined, files, refusals, packaged)
     files.abide.sort()
     files.handlers.sort()
@@ -81,7 +82,7 @@ function walk(
     relative: string,
     reserved: { path: string; name: string } | undefined,
     files: AppFiles,
-    refusals: Refusals,
+    refusals: Diagnostics,
     packaged = false,
 ): void {
     let entries: Dirent[]

package/src/server/argsContract.ts

@@ -0,0 +1,209 @@
+// WHAT A CALL'S ARGS ARE BEFORE ITS HANDLER SEES THEM, on a server: the schema a handler's args are
+// read by, out of the sources it has, and the args a call off the wire is answered with — over http
+// (16.2) and a `GET` followed over the socket mux (18.3). Each lane reads the args off its own
+// transport and answers a refusal in its own form; what every way of calling a handler shares, in
+// process too, is `acceptedArgs` (`#shared/reactive/argsContract.ts`), which this ends in.
+//
+// 19.7 — A URL CARRIES TEXT, so `?id=42` is `'42'` until the schema says the member is a number.
+// Coercion is the pipeline's and not the schema's (19.6): the schema is handed what this made of the
+// text, and refuses what would not coerce. A schema with no document has declared no types, and its
+// args stay the text they arrived as.
+
+import { DERIVED_ARGS } from '#shared/DERIVED_ARGS.ts'
+import { isRecord } from '#shared/isRecord.ts'
+import type { JsonValue } from '#shared/JsonValue.ts'
+import { numberFromText } from '#shared/numberFromText.ts'
+import { bareName } from '#shared/queryText.ts'
+import {
+    acceptedArgs,
+    type Gated,
+    gateOf,
+    type HeldToAnnotation,
+} from '#shared/reactive/argsContract.ts'
+import { refuse } from '#shared/refuse.ts'
+import { validateJson } from '#shared/validateJson.ts'
+
+import type { Mounted } from './mountHandlers.ts'
+
+export type Document = {
+    type?: string | string[]
+    properties?: Record<string, Document>
+    items?: Document
+}
+
+// Each handler's document, read once: 19.7, 20.11 — a third-party schema converts itself on every
+// probe. 19.9 — the one its annotation derives is filed here by `derivedArgs`.
+const DOCUMENTS = new WeakMap<object, Document | undefined>()
+
+const NO_PARAMETERS: Record<string, string | string[]> = {}
+
+/**
+ * The document a handler's args are read by: the one its `args` schema declares, or else the one the
+ * build derived off its annotation (`derivedArgs`), or `undefined`.
+ */
+export function argsDocumentOf(handler: Gated<unknown>): Document | undefined {
+    if (DOCUMENTS.has(handler)) return DOCUMENTS.get(handler)
+    const document = declaredDocument(handler)
+    DOCUMENTS.set(handler, document)
+    return document
+}
+
+function declaredDocument(handler: Gated<unknown>): Document | undefined {
+    const gate = gateOf(handler) as
+        { '~standard'?: { jsonSchema?: { input?: () => unknown } } } | undefined
+    const document = gate?.['~standard']?.jsonSchema?.input?.()
+    return document !== null && typeof document === 'object'
+        ? (document as Document)
+        : undefined
+}
+
+/**
+ * Holds `handler`'s args to `schema`, the one the build derived off its annotation, for every call
+ * of it from now on: in process and over the wire (15.8, 19.9).
+ *
+ * What the module a handler is loaded through calls once its handler is built — a handler file's
+ * face and a `<script server>`'s module — so the schema is there wherever the handler can be
+ * called, whether or not an app mounted it. Not where its `args` gate publishes a document of its
+ * own, which holds the args itself (19.7). Args that did not come are held as an empty record: a
+ * schema is only derived where the handler's args are a required record, so a required member
+ * missing is refused, not read off nothing.
+ */
+export function derivedArgs(
+    handler: HeldToAnnotation & Gated<unknown>,
+    schema: JsonValue,
+): void {
+    // Held already, by the module it loaded through, to the schema its row names as well.
+    if (handler[DERIVED_ARGS] !== undefined) return
+    const declared = declaredDocument(handler)
+    DOCUMENTS.set(handler, declared ?? (schema as Document))
+    if (declared === undefined)
+        handler[DERIVED_ARGS] = (args) => validateJson(schema, args ?? {})
+}
+
+/**
+ * Name and value pairs as args: a name given more than once is a list, one given once its text.
+ *
+ * 16.18 — a query's and a form's members, and 38.61 — `abide call`'s `name=value` words, alike.
+ */
+export function collapsed(
+    entries: URLSearchParams | FormData,
+): Record<string, string | string[]> {
+    const args: Record<string, string | string[]> = {}
+    for (const name of new Set(entries.keys())) {
+        const values = entries.getAll(name) as string[]
+        args[name] = values.length === 1 ? (values[0] as string) : values
+    }
+    return args
+}
+
+/**
+ * The args a call over the wire is answered with, out of the args it sent: the parameters its route
+ * matched laid in, the text a URL or a form carried coerced where `query` says the args are text,
+ * then `acceptedArgs`. Throws the refusal where they are not accepted.
+ *
+ * `query` is the raw `?…` the args were read from — `''` for a form, `undefined` for JSON.
+ * 16.65 — the path's parameters, whatever the method. 16.66 — one the query or the body names as well
+ * is refused rather than one of the two chosen. A JSON body's members are typed already, so the
+ * path's text is coerced to the declared types before it joins them (19.7); text args are coerced
+ * with the rest of the text.
+ */
+export function argsFor(
+    handler: Mounted['handler'],
+    sent: unknown,
+    query: string | undefined,
+    parameters: Record<string, string | string[]> = NO_PARAMETERS,
+): unknown {
+    const document = argsDocumentOf(handler)
+    let args = sent
+    let none = true
+    for (const name in parameters) {
+        none = false
+        if (isRecord(sent) && name in sent)
+            throw refuse(
+                400,
+                `The parameter '${name}' is in the path and in the request as well.`,
+            )
+    }
+    if (!none) {
+        const fromPath =
+            query === undefined
+                ? (coerceArgs(parameters, document, '') as Record<
+                      string,
+                      unknown
+                  >)
+                : parameters
+        args = isRecord(sent) ? { ...sent, ...fromPath } : { ...fromPath }
+    }
+    if (query !== undefined)
+        args = coerceArgs(
+            args as Record<string, string | string[]> | undefined,
+            document,
+            query,
+        )
+    return acceptedArgs(handler, args)
+}
+
+/**
+ * The text args, each member coerced to the type `document` declares.
+ *
+ * `URLSearchParams` reads `rpcRequest`'s empty list, a bare name, as `''` — the same as `tags=`, the
+ * list `['']` — so a declared array tells the two apart by `query`. A text member keeps the `''`.
+ */
+function coerceArgs(
+    args: Record<string, string | string[]> | undefined,
+    document: Document | undefined,
+    query: string,
+): unknown {
+    if (args === undefined || document?.properties === undefined) return args
+    const coerced: Record<string, unknown> = {}
+    for (const [name, text] of Object.entries(args)) {
+        const member = document.properties[name]
+        if (member === undefined) coerced[name] = text
+        else if (
+            text === '' &&
+            typesOf(member).includes('array') &&
+            `&${query.slice(1)}&`.includes(`&${bareName(name)}&`)
+        )
+            coerced[name] = []
+        else coerced[name] = coerceMember(text, member)
+    }
+    return coerced
+}
+
+function typesOf(member: Document): string[] {
+    if (member.type === undefined) return []
+    return Array.isArray(member.type) ? member.type : [member.type]
+}
+
+function coerceMember(text: string | string[], member: Document): unknown {
+    const types = typesOf(member)
+    // A list is its member repeated, and one given once still answers a declared array.
+    if (types.includes('array')) {
+        const items = Array.isArray(text) ? text : [text]
+        const item = member.items
+        return item === undefined
+            ? items
+            : items.map((each) => coerceScalar(each, item))
+    }
+    if (Array.isArray(text)) return text
+    return coerceScalar(text, member)
+}
+
+/**
+ * The text as the first declared type it reads as, in the order the schema lists them.
+ *
+ * Text that reads as none stays text, for the schema to refuse.
+ */
+function coerceScalar(text: string, member: Document): unknown {
+    for (const type of typesOf(member)) {
+        if (type === 'string') return text
+        if (type === 'number' || type === 'integer') {
+            const number = numberFromText(text)
+            if (number !== undefined) return number
+        }
+        if (type === 'boolean' && (text === 'true' || text === 'false'))
+            return text === 'true'
+        if (type === 'null' && text === 'null') return null
+    }
+    return text
+}