@abide/abide 0.58.0 → 0.100.0

package/src/shared/index.ts

@@ -0,0 +1,117 @@
+// The isomorphic authoring surface — what an app reaches through `@abide/abide`.
+// Same callable, same name, same intent on both sides: the reactive value and the
+// types its probes narrow to live here, and nothing in this seam may import #ui or
+// #server.
+//
+// ONE FACTORY. `state`, `memo` and `channel` are gone — `reactive` carries all three through its
+// overloads, a channel being a value whose array every caller appends to.
+//
+// ONE REFUSAL TYPE beside it. `Failed` is the only thing a producer answers in place of a
+// value (15.1), so it is in this seam rather than the server's: the same object crosses a
+// wire, fills `s.error` and narrows through `s.isError`.
+
+// 33.23 — an element's attributes, typed as a component's props.
+export type { Attributes } from './Attributes.ts'
+// 32.37 — what a value writes into an attribute, on both sides.
+export { attributeMarkup, attributeText } from './attributeText.ts'
+// EMITTED CODE'S: the value a `bind:` operand holds, as the server writes it into the tag (32.5).
+export { boundProp, boundValue, groupHolds } from './boundValue.ts'
+export { type Cookies, cookies } from './cookies.ts'
+export { csp } from './csp.ts'
+export {
+    escapeAttribute,
+    escapeStyleValue,
+    escapeText,
+} from './escapeText.ts'
+export { type Failed, isFailed } from './Failed.ts'
+// 25 — the account of the app.
+export { type Health, health } from './health.ts'
+export type { Issues, Paths } from './Issues.ts'
+export type { JsonValue } from './JsonValue.ts'
+export { jsonSchema } from './jsonSchema.ts'
+// 32.15's run-time half. In this seam because BOTH sides ask it what a `{#for}` subject iterates
+// as — the server's emitted block, the client's `updateList`, and the markup a client builds for a
+// row — so the one function is the one answer.
+export { listOf } from './listOf.ts'
+export { type Logger, type LogRecord, log } from './log.ts'
+export type { Middleware } from './Middleware.ts'
+export type { Params } from './matchRoute.ts'
+// 38.89 — a desktop app's menu items, exported by the route's layouts and page.
+export {
+    type MenuEntry,
+    type MenuItem,
+    type MenuRole,
+    menuItem,
+} from './menuItem.ts'
+// `navigate` ALONE, of everything routing needs. This barrel is what an app resolves through the
+// bare `@abide/abide` specifier, and the matcher, the pattern grammar and `routeOf` are reached by path
+// from the two places that have them — the build and the client router. Putting them here would
+// widen the public surface with names no clause or registry row gives an author, and drag both
+// modules into the static closure of the entry every page imports.
+export { navigate } from './navigate.ts'
+export { online } from './online.ts'
+export { type Principal, principal } from './principal.ts'
+// EMITTED CODE'S: a prop the child writes (33.6, 33.7).
+export {
+    propCell,
+    propCells,
+    propOr,
+    restValues,
+    withoutKeys,
+} from './propCell.ts'
+export { props } from './props.ts'
+// `markupRun` and `RAW_WRITES` are EMITTED CODE'S: a text run anchored while it holds markup (32.30).
+export { markupRun, RAW_WRITES, Raw, raw } from './Raw.ts'
+export {
+    busy,
+    // 10.5's pair — not an app's names: an emitted component opens its instance's share scope
+    // with them, on both sides, and `importClause` binds them under `__`.
+    currentShare,
+    type Disposer,
+    type Effect,
+    enterShare,
+    flushSync,
+    type Identity,
+    invalidate,
+    isReactive,
+    type Keyed,
+    leaveShare,
+    NotLanded,
+    type Reactive,
+    type ReactiveOptions,
+    reactive,
+    ready,
+    refresh,
+    resumeShare,
+    type Selection,
+    type Shared,
+    type Store,
+    structural,
+    type Transformer,
+    watch,
+} from './reactive/index.ts'
+export { aborted, notFound, refuse, validationError } from './refuse.ts'
+export { route } from './route.ts'
+export type { Schema, StandardSchemaV1 } from './Schema.ts'
+export { safeUrl } from './safeUrl.ts'
+// EMITTED CODE'S, not an author's — no REGISTRY row, the way `escapeText` and `listOf` have
+// none. A markup position that aborts on an unlanded read (32.23) is the compiler's business.
+export { slotValue } from './slotValue.ts'
+// EMITTED CODE'S — 32.11's spread, as props and as markup.
+export { spreadAttributes, spreadProps } from './spread.ts'
+// 30.1 — the address builder, and the types that read a route literal for it.
+export {
+    type HasParams,
+    type HasSegments,
+    type OptionalNames,
+    type ParamsOf,
+    type Query,
+    type RequiredNames,
+    type RestNames,
+    type RouteLiteral,
+    type RouteParams,
+    type Routes,
+    url,
+} from './url.ts'
+export { validateJson } from './validateJson.ts'
+export { writePath } from './writePath.ts'

package/src/shared/isEventName.ts

@@ -0,0 +1,10 @@
+/**
+ * Whether a lowercased attribute name is an `on<event>` listener.
+ *
+ * 32.4 — an `on<event>` attribute is a listener, whether the compiler reads it off a tag or a
+ * spread hands it over at run time: one predicate, so the two cannot drift on which names are
+ * listeners.
+ */
+export function isEventName(lowerName: string): boolean {
+    return lowerName.length > 2 && lowerName.startsWith('on')
+}

package/src/shared/isRecord.ts

@@ -0,0 +1,4 @@
+/** Whether a value is a plain keyed object: not `null`, and not an array. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+}

package/src/shared/issuesOf.ts

@@ -0,0 +1,18 @@
+/**
+ * Issues in the shape `Issues<T>` gives them for the value refused: by path for an object or an
+ * array, the bare list for anything else.
+ *
+ * DECIDED BY THE VALUE, because the value is all the runtime holds — `T` is erased. A scalar has
+ * no path to key by, so every issue about one stands on `''`, and handing back `{ '': [...] }`
+ * there is the wrapper `Issues<T>` says a reader never unwraps: `error().data[0]` read `undefined`.
+ */
+export function issuesOf(
+    found: Record<string, string[]>,
+    value: unknown,
+): Record<string, string[]> | string[] {
+    if (typeof value === 'object' && value !== null) return found
+    const listed: string[] = []
+    for (const path in found)
+        for (const said of found[path] as string[]) listed.push(said)
+    return listed
+}

package/src/shared/jsonSchema.ts

@@ -0,0 +1,50 @@
+import type { JsonValue } from './JsonValue.ts'
+import type { StandardSchemaV1 } from './Schema.ts'
+import { validateJson } from './validateJson.ts'
+
+/**
+ * A JSON Schema document as a Standard Schema, carrying its own validator.
+ *
+ * A document is data and something has to read it, so the edge to `validateJson` is made HERE, by
+ * the call that declares one — a page that never calls this never carries the validator (19.13),
+ * with no slot to fill and nothing for the compiler to spot. A bare document handed as a `Schema`
+ * is refused (19.14).
+ *
+ * A STANDARD SCHEMA, because that is the form that already reports WHERE: each issue's path is
+ * `validateJson`'s own, split at the dots `runSchema` joins it back at. And the document is
+ * exposed where a Standard Schema exposes its JSON Schema, so 20.11's one probe publishes it with
+ * no case of its own.
+ */
+export function jsonSchema<T>(document: JsonValue): StandardSchemaV1<T> {
+    return {
+        '~standard': {
+            version: 1,
+            vendor: 'abide',
+            validate(value: unknown) {
+                const found = validateJson(document, value) as
+                    | Record<string, string[]>
+                    | string[]
+                    | null
+                if (found === null) return { value: value as T }
+                const issues: { message: string; path: string[] }[] = []
+                // A value that is not an object came back as the bare list, every issue on `''`.
+                if (Array.isArray(found)) {
+                    for (const message of found)
+                        issues.push({ message, path: [] })
+                    return { issues }
+                }
+                for (const path in found)
+                    for (const message of found[path] as string[])
+                        issues.push({
+                            message,
+                            path: path === '' ? [] : path.split('.'),
+                        })
+                return { issues }
+            },
+            jsonSchema: {
+                input: () => document,
+                output: () => document,
+            },
+        },
+    } as StandardSchemaV1<T>
+}

package/src/shared/listOf.ts

@@ -0,0 +1,20 @@
+/**
+ * What a `{#for}` subject iterates as: an array, or an async iterable as itself.
+ *
+ * 32.15, 32.22 — nothing for an absent subject, an ASYNC iterable handed back as itself, and
+ * anything else as an array. Named by the async brand AND the absence of the sync one, in that
+ * order, because `for … of` prefers the sync brand where a value carries both. A subject carrying
+ * neither fails on the spread. An array is not copied: a reconcile reads it synchronously and
+ * keeps only its items.
+ */
+export function listOf(subject: unknown): unknown[] | AsyncIterable<unknown> {
+    if (subject == null) return []
+    if (Array.isArray(subject)) return subject
+    if (
+        typeof (subject as AsyncIterable<unknown>)[Symbol.asyncIterator] ===
+            'function' &&
+        typeof (subject as Iterable<unknown>)[Symbol.iterator] !== 'function'
+    )
+        return subject as AsyncIterable<unknown>
+    return [...(subject as Iterable<unknown>)]
+}

package/src/shared/log.ts

@@ -0,0 +1,284 @@
+// SECTION 28 — the logger, on both sides. A line is written to the console AND published to
+// `log.records` (28.1), so a subscriber — `abide logs`, a test, a page — sees exactly what the
+// terminal saw.
+//
+// THE RECORDS ARE BUILT ON FIRST ASK. The reactive core warns through this module, so a
+// `reactive` built at this module's evaluation would be a cycle evaluated in the wrong order;
+// built on the first line or the first read of `log.records`, the core has long since loaded.
+//
+// 28.11, 28.12 — IN A BROWSER, `DEBUG` IS THE DOCUMENT'S: the server names it in a `<meta>` it writes
+// into the head, and the browser's own stored `debug` answers only where the document carries none.
+
+import { DEBUG_META } from './DEBUG_META.ts'
+import { paint } from './paint.ts'
+import { type Reactive, reactive } from './reactive/index.ts'
+
+type Level = 'debug' | 'info' | 'warning' | 'error'
+
+export type LogRecord = {
+    time: string
+    level: Level
+    namespace: string
+    message: string
+    trace: string
+}
+
+export type Logger = ((...args: unknown[]) => void) & {
+    info(...args: unknown[]): void
+    warning(...args: unknown[]): void
+    error(...args: unknown[]): void
+    debug(...args: unknown[]): void
+    named(name: string): Logger
+    enabled(): boolean
+    readonly records: Reactive<LogRecord[]>
+}
+
+/**
+ * The slot a line's trace id is read through, filled by the server.
+ *
+ * Where a line's trace id comes from once section 24 fills it in — a slot rather than an import, so
+ * the isomorphic logger does not drag the server's request scope into a browser bundle.
+ */
+export const TRACE: { current: () => string } = { current: () => '' }
+
+const DEFAULT_BUFFER = 1000
+
+let records: Reactive<LogRecord[]> | undefined
+let kept = DEFAULT_BUFFER
+
+function recordsValue(): Reactive<LogRecord[]> {
+    if (records === undefined) {
+        const configured = Number(environment('ABIDE_MAX_LOG_BUFFER_COUNT'))
+        kept =
+            Number.isInteger(configured) && configured >= 0
+                ? configured
+                : DEFAULT_BUFFER
+        // 28.1 — one array for the process, which `/__abide/logs` follows (28.2).
+        records = reactive<LogRecord[]>([], { global: true })
+    }
+    return records
+}
+
+/**
+ * Appends `record` to `log.records`, trimming to the buffer it keeps.
+ *
+ * THE TRIM IS AMORTISED: grown to twice the buffer and cut back in one move, rather than a `shift`
+ * per line that moves every record still held.
+ */
+function keep(list: LogRecord[], record: LogRecord): void {
+    list.push(record)
+    if (list.length >= kept * 2 || (kept === 0 && list.length > 0))
+        list.splice(0, list.length - kept)
+}
+
+/**
+ * The document's `DEBUG`, read once per document.
+ *
+ * READ ONCE PER DOCUMENT, as `MOUNT` is: every gated line asks, and a document with no `DEBUG` has no
+ * `<meta>` for the selector to find, so each ask walked the whole document and then storage. The
+ * server writes the tag ahead of the script, and a stored setting changed after load answers on the
+ * next load, as debug-npm's does.
+ */
+let documentDebugRead: string | undefined
+
+function environment(name: string): string | undefined {
+    if (typeof process !== 'undefined') return process.env[name]
+    if (name !== 'DEBUG') return undefined
+    documentDebugRead ??= documentDebug() ?? ''
+    return documentDebugRead
+}
+
+/** The document's `DEBUG`, or the browser's own stored one where it carries none (28.11, 28.12). */
+export function documentDebug(): string | undefined {
+    if (typeof document === 'undefined') return undefined
+    const named = document
+        .querySelector(`meta[name="${DEBUG_META}"]`)
+        ?.getAttribute('content')
+    if (named !== null && named !== undefined) return named
+    // A sandboxed frame refuses storage outright, and that is no setting at all.
+    try {
+        return localStorage.getItem('debug') ?? undefined
+    } catch {
+        return undefined
+    }
+}
+
+/**
+ * The compiled `DEBUG` patterns: namespaces included, and namespaces excluded.
+ *
+ * 28.10 — THE debug-npm GRAMMAR: a list split on commas or whitespace, `*` any run of characters,
+ * and a leading `-` an exclusion that beats every inclusion. Compiled once per distinct `DEBUG`.
+ */
+type Gate = { include: RegExp[]; exclude: RegExp[] }
+let gateFor: string | undefined
+let gate: Gate = { include: [], exclude: [] }
+
+function currentGate(): Gate {
+    const debug = environment('DEBUG') ?? ''
+    if (debug === gateFor) return gate
+    gateFor = debug
+    const include: RegExp[] = []
+    const exclude: RegExp[] = []
+    for (const part of debug.split(/[\s,]+/)) {
+        if (part === '') continue
+        const negated = part.startsWith('-')
+        const body = (negated ? part.slice(1) : part)
+            .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+            .replaceAll('*', '.*')
+        ;(negated ? exclude : include).push(new RegExp(`^${body}$`))
+    }
+    gate = { include, exclude }
+    return gate
+}
+
+/** Whether `DEBUG` enables a namespace's gated lines (28.7). */
+function isEnabled(namespace: string): boolean {
+    const { include, exclude } = currentGate()
+    for (const pattern of exclude) if (pattern.test(namespace)) return false
+    for (const pattern of include) if (pattern.test(namespace)) return true
+    return false
+}
+
+/**
+ * The format a line is written in: `tsv`, `json` or `readable`.
+ *
+ * 36.8 and 36.9 — read per line rather than at load: a test or a host setting the environment
+ * after import is still answered.
+ */
+function formatOf(): 'tsv' | 'json' | 'readable' {
+    const format = environment('ABIDE_LOG_FORMAT')
+    if (format === 'tsv' || format === 'json') return format
+    if (typeof process === 'undefined') return 'readable'
+    return process.stdout.isTTY === true ? 'readable' : 'tsv'
+}
+
+/** Whether a line written to stdout may carry ANSI color: a terminal, unless `NO_COLOR` says not. */
+export function useColor(): boolean {
+    if (typeof process === 'undefined') return false
+    if (environment('NO_COLOR') !== undefined) return false
+    if (environment('FORCE_COLOR') !== undefined) return true
+    return process.stdout.isTTY === true
+}
+
+// The ANSI style `paint` writes each level in.
+const LEVEL_COLOR: Record<Level, string> = {
+    debug: '90',
+    info: '36',
+    warning: '33',
+    error: '31',
+}
+
+function messageOf(args: unknown[]): string {
+    let message = ''
+    for (let at = 0; at < args.length; at += 1) {
+        const arg = args[at]
+        if (at > 0) message += ' '
+        if (typeof arg === 'string') message += arg
+        else if (typeof globalThis.Bun?.inspect === 'function')
+            message += Bun.inspect(arg)
+        else if (arg instanceof Error) message += arg.stack ?? arg.message
+        else
+            try {
+                message += JSON.stringify(arg)
+            } catch {
+                message += String(arg)
+            }
+    }
+    return message
+}
+
+function write(
+    namespace: string,
+    level: Level,
+    args: unknown[],
+    time = new Date().toISOString(),
+): void {
+    const record: LogRecord = {
+        time,
+        level,
+        namespace,
+        message: messageOf(args),
+        trace: TRACE.current(),
+    }
+    const format = formatOf()
+    let line: string
+    if (format === 'json') line = JSON.stringify(record)
+    else if (format === 'tsv')
+        line = `${record.time}\t${level}\t${namespace}\t${record.trace}\t${record.message.replaceAll('\n', '\\n')}`
+    else {
+        const color = useColor()
+        line = `${paint(color, '90', record.time)} ${paint(color, LEVEL_COLOR[level], level)} ${paint(color, '1', namespace)} ${record.message}`
+    }
+    if (level === 'error') console.error(line)
+    else if (level === 'warning') console.warn(line)
+    else console.log(line)
+    recordsValue().patch((list) => keep(list, record))
+}
+
+/** A logger under `namespace`, which 28.5 builds from the app's name and 28.9 from `abide:`. */
+export function namedLogger(namespace: string): Logger {
+    return loggerOver(() => namespace)
+}
+
+/** Both lanes' render logger (28.9): the server's escalations and 32.20's dropped URLs. */
+export const RENDER_LOG = namedLogger('abide:render')
+
+/**
+ * A logger whose namespace is asked per line.
+ *
+ * The namespace is ASKED per line rather than held, which is all `log` needs over a named logger.
+ */
+function loggerOver(namespaceOf: () => string): Logger {
+    // 28.3 — the bare call always writes. 28.4 — so do warnings and errors.
+    const logger = ((...args: unknown[]): void => {
+        write(namespaceOf(), 'info', args)
+    }) as Logger
+    logger.info = (...args) => {
+        const namespace = namespaceOf()
+        if (isEnabled(namespace)) write(namespace, 'info', args)
+    }
+    logger.debug = (...args) => {
+        const namespace = namespaceOf()
+        if (isEnabled(namespace)) write(namespace, 'debug', args)
+    }
+    logger.warning = (...args) => write(namespaceOf(), 'warning', args)
+    logger.error = (...args) => write(namespaceOf(), 'error', args)
+    // 28.5 — another segment, below this one. 28.13 — asked per line too, so a logger named at module
+    // load, before the app's name resolved, writes under the name once it has.
+    logger.named = (name) => loggerOver(() => `${namespaceOf()}:${name}`)
+    logger.enabled = () => isEnabled(namespaceOf())
+    Object.defineProperty(logger, 'records', { get: recordsValue })
+    return logger
+}
+
+/**
+ * The slot the derived app name is read through, filled by the server's `config`.
+ *
+ * 28.5 — the app's name is the root every `log.named` hangs off: the environment's, or what 27.3
+ * derived, which the server's `config` fills in here.
+ */
+export const APP_NAME: { derived: () => string | undefined } = {
+    derived: () => undefined,
+}
+
+function appName(): string {
+    return environment('APP_NAME') ?? APP_NAME.derived() ?? 'app'
+}
+
+/**
+ * Writes a span as an `info` line under the app's namespace, stamped with its start.
+ *
+ * 24.3, 24.4 — A SPAN IS A LINE under the app's own namespace, stamped with when it STARTED. Written
+ * whatever `DEBUG` says: an app that opened one asked for it.
+ */
+export function writeSpan(startedAt: string, message: string): void {
+    write(appName(), 'info', [message], startedAt)
+}
+
+/**
+ * The app's logger, under the app's name.
+ *
+ * THE DEFAULT NAMESPACE IS READ PER LINE, like the format: `APP_NAME` set by a host after this
+ * module loaded still names the line.
+ */
+export const log: Logger = loggerOver(appName)

package/src/shared/matchRoute.ts

@@ -0,0 +1,99 @@
+import type { Segment } from './routePattern.ts'
+
+/**
+ * The params a pattern matched, by name: a string, or a list for a rest.
+ *
+ * The params are strings because that is what a URL carries; `ParamsOf<P>` accepts a number on the
+ * way OUT (30.3) and the address is built from it, but nothing on the way back in has a type to
+ * restore.
+ */
+export type Params = Record<string, string | string[]>
+
+/**
+ * A pathname's non-empty parts, each percent-decoded, or `undefined` where one will not decode.
+ *
+ * The pathname taken apart, once. `firstMatch` walks a whole table against ONE address, so the
+ * split and the per-part decode belong to the walk rather than to each candidate in it, or a
+ * table of n routes splits and decodes the address n times.
+ *
+ * `undefined` FOR AN ADDRESS THAT WILL NOT PERCENT-DECODE, which names nothing: the server answers
+ * it 400 (15.16) and the router leaves it to the document (30.10). A throw here reached the
+ * router's link listeners, which are the one place nothing catches it.
+ */
+export function partsOf(pathname: string): string[] | undefined {
+    const parts: string[] = []
+    try {
+        for (const part of pathname.split('/'))
+            if (part !== '') parts.push(decodeURIComponent(part))
+    } catch {
+        return undefined
+    }
+    return parts
+}
+
+/**
+ * Whether `segments` match the front of `parts`.
+ *
+ * 35.2 — with the same meaning each segment kind has in a route: the directories an error page
+ * stands for cover every address below them.
+ */
+export function coversPrefix(segments: Segment[], parts: string[]): boolean {
+    return walk(segments, 0, parts, 0, true) !== null
+}
+
+// ONE SEGMENT AT A TIME, and the params built on the way back out: a candidate that fails
+// allocates nothing, and one pattern that matches allocates one record. 30.4 — AN OPTIONAL IS TRIED
+// TAKEN, THEN LEFT OUT, so `/[[lang]]/docs` matches `/docs` as well as `/en/docs`: taking the part
+// greedily and never trying without it is how a left-out optional stopped omitting its segment.
+function walk(
+    segments: Segment[],
+    index: number,
+    parts: string[],
+    at: number,
+    prefix: boolean,
+): Params | null {
+    if (index === segments.length)
+        return prefix || at === parts.length ? {} : null
+    const segment = segments[index] as Segment
+    // 30.5 — A REST TAKES WHAT IS LEFT, including nothing, and it is last by construction.
+    if (segment.kind === 'rest') return { [segment.name]: parts.slice(at) }
+    const part = parts[at]
+    if (segment.kind === 'optional') {
+        if (part !== undefined) {
+            const taken = walk(segments, index + 1, parts, at + 1, prefix)
+            if (taken !== null) {
+                taken[segment.name] = part
+                return taken
+            }
+        }
+        return walk(segments, index + 1, parts, at, prefix)
+    }
+    if (part === undefined) return null
+    if (segment.kind === 'static' && part !== segment.name) return null
+    const params = walk(segments, index + 1, parts, at + 1, prefix)
+    if (params !== null && segment.kind === 'required')
+        params[segment.name] = part
+    return params
+}
+
+/**
+ * The first route whose pattern matches `parts`, with its params, or `undefined`.
+ *
+ * 30.9 — THE FIRST PATTERN THAT MATCHES WINS, over a table already ranked most-specific-first.
+ * BOTH SEAMS WALK THIS ONE. The server resolving an address and the client router resolving the
+ * same one is the isomorphism 30.8 rests on.
+ *
+ * Walked rather than compiled to a regex: a route table is matched once per navigation, so the
+ * walk is never the cost, and a regex would have to encode three segment kinds in a grammar nobody
+ * reading the table can see.
+ */
+export function firstMatch<T extends { segments: Segment[] }>(
+    routes: T[],
+    parts: string[],
+): { route: T; params: Params } | undefined {
+    for (const route of routes) {
+        const params = walk(route.segments, 0, parts, 0, false)
+        if (params !== null) return { route, params }
+    }
+    return undefined
+}