functionalscript 0.43.0 → 0.44.0

package/fjs/media/json/types.d.ts

@@ -0,0 +1,25 @@
+/**
+ * TypeScript counterparts of the JSON data model: `Primitive`, `Unknown`,
+ * `Object`, and `Array`.
+ *
+ * `Unknown` is written by hand rather than derived, so that the recursion
+ * reads directly, and is then pinned against the rtti schemas in the sibling
+ * [`./rtti/module.f.mjs`](./rtti/module.f.mjs) with
+ * `Assert<Equal<Unknown, Ts<typeof unknown>>>`. The pin is what keeps the two
+ * descriptions of the same data model from drifting apart.
+ *
+ * @module
+ */
+import type { Entry as ObjectEntry } from '../../types/object/types.ts';
+import type { Ts } from '../../types/rtti/ts/types.ts';
+import type { primitive } from './rtti/module.f.mjs';
+import type { List } from '../../types/list/types.ts';
+export type Primitive = Ts<typeof primitive>;
+export type Unknown = Object | Array | Primitive;
+export type Object = {
+    readonly [k in string]?: Unknown;
+};
+export type Array = readonly Unknown[];
+export type Entry = ObjectEntry<Unknown>;
+export type _Entries = List<Entry>;
+export type _MapEntries = (entries: _Entries) => _Entries;

package/fjs/media/json/types.js

@@ -0,0 +1,13 @@
+/**
+ * TypeScript counterparts of the JSON data model: `Primitive`, `Unknown`,
+ * `Object`, and `Array`.
+ *
+ * `Unknown` is written by hand rather than derived, so that the recursion
+ * reads directly, and is then pinned against the rtti schemas in the sibling
+ * [`./rtti/module.f.mjs`](./rtti/module.f.mjs) with
+ * `Assert<Equal<Unknown, Ts<typeof unknown>>>`. The pin is what keeps the two
+ * descriptions of the same data model from drifting apart.
+ *
+ * @module
+ */
+export {};

package/fjs/media/module.f.d.mts

@@ -0,0 +1,116 @@
+/**
+ * Media-type detection entry point: dialect-tagged JSON recognition layered
+ * on top of the byte-signature / UTF-8 detector.
+ *
+ * `fjs/media/type` classifies raw bytes (magic-byte signatures, UTF-8
+ * text-vs-binary) with no notion of a JSON dialect. `detect` here adds one
+ * more classification step in front of it: when the whole blob is
+ * whole-blob-valid UTF-8 text (as `fjs/media/type` already determined), parse
+ * it as JSON and match the parsed value against the dialects the caller
+ * registered. A match reports that dialect's derived media type; anything that
+ * isn't valid JSON, or matches no registered dialect, falls through to the
+ * `fjs/media/type` verdict unchanged.
+ *
+ * The dialect set is a **parameter**, not an import: `detect(dialects)(bytes)`.
+ * This module therefore knows no dialect of its own — `fjs/media/revision`
+ * exports its own {@link DialectEntry} (`revisionDialect`), and a caller passes
+ * the list it wants recognized. Any format following the `vnd.fjs.<name>`
+ * convention (see `fjs/media/revision/README.md`), in this repo or downstream,
+ * is registerable the same way.
+ *
+ * Detection is semantic, not syntactic: any JSON that satisfies a dialect's
+ * schema is recognized regardless of key order, whitespace, or any other
+ * serialization detail — there is no byte-level shortcut such as a
+ * `{"dialect":` prefix check. The text is parsed **once**, and each entry's
+ * `match` runs on the same parsed value, so N dialects cost N schema walks
+ * rather than N parses.
+ *
+ * A reported `mime_type` is a claim about a blob's *shape*, not a promise that
+ * decoding it succeeds: how strict detection is, is the dialect's own call (see
+ * {@link dialectEntry}'s `extraValidate`). Never route a decode decision
+ * through this verdict — a caller that intends to decode calls its dialect's
+ * decoder, which stays the authority.
+ *
+ * This only classifies an already-buffered `Vec` (`detectVec`'s single-`Vec`
+ * form), because dialect validation needs the whole parsed value. A single
+ * `Vec` already caps at `maxLength` bits (128 KiB — the same bound as the
+ * existing inline-content cap), so dialect detection is naturally
+ * size-bounded. The unbounded streaming detector (`fjs/media/type`
+ * `detectStream`) is untouched and stays a pure byte-signature/UTF-8
+ * classifier with no dialect awareness.
+ *
+ * @module
+ *
+ * @import { Vec } from '../types/bit_vec/types.ts'
+ * @import { DetectMeta } from './type/types.ts'
+ * @import { Struct } from '../types/rtti/types.ts'
+ * @import { Ts, Unknown } from '../types/rtti/ts/types.ts'
+ * @import { Validate } from '../types/rtti/common/types.ts'
+ * @import { DialectEntry } from './types.ts'
+ */
+import type { Vec } from '../types/bit_vec/types.ts';
+import type { DetectMeta } from './type/types.ts';
+import type { Struct } from '../types/rtti/types.ts';
+import type { Ts } from '../types/rtti/ts/types.ts';
+import type { DialectEntry } from './types.ts';
+/**
+ * Registers a dialect for detection: its rtti schema, plus whatever rtti can't
+ * say about it.
+ *
+ * The dialect name is read out of the schema's own `dialect` member — that
+ * member is a string const in a dialect schema, which is what makes the schema
+ * self-discriminating, so a separate name alongside it would be a second copy
+ * that can disagree with the first. It follows that no registration can claim
+ * one dialect while validating another's blobs. The media type is likewise
+ * derived rather than supplied: `application/${dialect}+json`, the mechanical
+ * derivation `fjs/media/revision/README.md` documents.
+ *
+ * `extraValidate` runs *after* structural validation, on the dialect's own
+ * decoded type, and closes the gap rtti leaves — "this string is
+ * cbase32-decodable", "this number is a non-negative safe integer". It returns
+ * `boolean`, so it has no error channel and nothing to report but yes or no,
+ * and it never sees the raw bytes: parsing and the schema walk stay with the
+ * detector. Omitting it gets classification (what a blob claims to be and
+ * structurally looks like); supplying it gets detection as strict as the
+ * dialect's own decoder.
+ *
+ * **The name is neither grammar-checked nor allowlisted.** A schema saying
+ * `dialect: 'foo'` yields `application/foo+json`, and that is intended:
+ * `vnd.fjs.*` is this repo's convention for its *own* formats, not a constraint
+ * on what a caller may detect — another vendor's `vnd.*` blob, or a widely used
+ * name not under `vnd.` at all, is a legitimate thing to register. The name is
+ * not attacker-controlled either: it comes from a schema a programmer wrote and
+ * passed here, never from the blob being classified, so no untrusted string
+ * reaches `mime_type` along this path. (A detector that read the name *out of*
+ * a blob would need the RFC 6838 grammar check and an allowlist; this one does
+ * not.) Registering a name that is not a valid RFC 6838 restricted-name yields
+ * a malformed media type in the registrant's own results, and nowhere else.
+ *
+ * The constraint is `Struct` — every member must be a real rtti `Type`, which
+ * is what rejects a member like `() => 42` at compile time (rtti would read it
+ * as a thunk and `match` would *throw* on the first blob rather than return
+ * `false`). TypeScript cannot also require a direct string `dialect` member
+ * under that constraint, so that half is asserted here instead: loudly, once,
+ * when the entry is constructed. A thunk-form `dialect`
+ * (`() => ['const', 'x']`) is a perfectly valid rtti schema, it just is not
+ * registerable — write the string directly, as `revisionSchema` does.
+ *
+ * @template {Struct} T
+ * @param {T} type
+ * @param {(_: Ts<T>) => boolean} [extraValidate]
+ * @returns {DialectEntry}
+ */
+export declare const dialectEntry: <T extends Struct>(type: T, extraValidate?: (_: Ts<T>) => boolean) => DialectEntry;
+/**
+ * Classifies a whole buffered `Vec` against `dialects`, returning the same
+ * three-way `{ length, mime_type, type }` shape as `fjs/media/type`
+ * `detectVec`, but with dialect-tagged JSON recognized ahead of the plain
+ * `text/plain` fallback. The first entry whose `match` accepts the parsed value
+ * wins; entries that overlap are the registrant's own business, since matching
+ * `dialect` as an exact literal already makes structural validation reject
+ * every other dialect's blob.
+ *
+ * @param {readonly DialectEntry[]} dialects
+ * @returns {(bytes: Vec) => DetectMeta}
+ */
+export declare const detect: (dialects: readonly DialectEntry[]) => (bytes: Vec) => DetectMeta;

package/fjs/media/module.f.mjs

@@ -0,0 +1,152 @@
+/**
+ * Media-type detection entry point: dialect-tagged JSON recognition layered
+ * on top of the byte-signature / UTF-8 detector.
+ *
+ * `fjs/media/type` classifies raw bytes (magic-byte signatures, UTF-8
+ * text-vs-binary) with no notion of a JSON dialect. `detect` here adds one
+ * more classification step in front of it: when the whole blob is
+ * whole-blob-valid UTF-8 text (as `fjs/media/type` already determined), parse
+ * it as JSON and match the parsed value against the dialects the caller
+ * registered. A match reports that dialect's derived media type; anything that
+ * isn't valid JSON, or matches no registered dialect, falls through to the
+ * `fjs/media/type` verdict unchanged.
+ *
+ * The dialect set is a **parameter**, not an import: `detect(dialects)(bytes)`.
+ * This module therefore knows no dialect of its own — `fjs/media/revision`
+ * exports its own {@link DialectEntry} (`revisionDialect`), and a caller passes
+ * the list it wants recognized. Any format following the `vnd.fjs.<name>`
+ * convention (see `fjs/media/revision/README.md`), in this repo or downstream,
+ * is registerable the same way.
+ *
+ * Detection is semantic, not syntactic: any JSON that satisfies a dialect's
+ * schema is recognized regardless of key order, whitespace, or any other
+ * serialization detail — there is no byte-level shortcut such as a
+ * `{"dialect":` prefix check. The text is parsed **once**, and each entry's
+ * `match` runs on the same parsed value, so N dialects cost N schema walks
+ * rather than N parses.
+ *
+ * A reported `mime_type` is a claim about a blob's *shape*, not a promise that
+ * decoding it succeeds: how strict detection is, is the dialect's own call (see
+ * {@link dialectEntry}'s `extraValidate`). Never route a decode decision
+ * through this verdict — a caller that intends to decode calls its dialect's
+ * decoder, which stays the authority.
+ *
+ * This only classifies an already-buffered `Vec` (`detectVec`'s single-`Vec`
+ * form), because dialect validation needs the whole parsed value. A single
+ * `Vec` already caps at `maxLength` bits (128 KiB — the same bound as the
+ * existing inline-content cap), so dialect detection is naturally
+ * size-bounded. The unbounded streaming detector (`fjs/media/type`
+ * `detectStream`) is untouched and stays a pure byte-signature/UTF-8
+ * classifier with no dialect awareness.
+ *
+ * @module
+ *
+ * @import { Vec } from '../types/bit_vec/types.ts'
+ * @import { DetectMeta } from './type/types.ts'
+ * @import { Struct } from '../types/rtti/types.ts'
+ * @import { Ts, Unknown } from '../types/rtti/ts/types.ts'
+ * @import { Validate } from '../types/rtti/common/types.ts'
+ * @import { DialectEntry } from './types.ts'
+ */
+
+import { fromVec } from '../text/utf8/module.f.mjs'
+import { detectVec } from './type/module.f.mjs'
+import { parse } from './json/module.f.mjs'
+import { assert, assertNotNullish } from '../asserts/module.f.mjs'
+import { validate } from '../types/rtti/validate/module.f.mjs'
+
+/** The default refinement: structural validation alone decides the match. */
+const always = () => true
+
+/**
+ * Structural validation followed by the dialect's own refinement.
+ * @template {Struct} T
+ * @param {Validate<T>} v
+ * @returns {(extraValidate: (_: Ts<T>) => boolean) => (u: Unknown) => boolean}
+ */
+const matchWith = v => extraValidate => u => {
+    const [tag, value] = v(u)
+    return tag === 'ok' && extraValidate(value)
+}
+
+/**
+ * Registers a dialect for detection: its rtti schema, plus whatever rtti can't
+ * say about it.
+ *
+ * The dialect name is read out of the schema's own `dialect` member — that
+ * member is a string const in a dialect schema, which is what makes the schema
+ * self-discriminating, so a separate name alongside it would be a second copy
+ * that can disagree with the first. It follows that no registration can claim
+ * one dialect while validating another's blobs. The media type is likewise
+ * derived rather than supplied: `application/${dialect}+json`, the mechanical
+ * derivation `fjs/media/revision/README.md` documents.
+ *
+ * `extraValidate` runs *after* structural validation, on the dialect's own
+ * decoded type, and closes the gap rtti leaves — "this string is
+ * cbase32-decodable", "this number is a non-negative safe integer". It returns
+ * `boolean`, so it has no error channel and nothing to report but yes or no,
+ * and it never sees the raw bytes: parsing and the schema walk stay with the
+ * detector. Omitting it gets classification (what a blob claims to be and
+ * structurally looks like); supplying it gets detection as strict as the
+ * dialect's own decoder.
+ *
+ * **The name is neither grammar-checked nor allowlisted.** A schema saying
+ * `dialect: 'foo'` yields `application/foo+json`, and that is intended:
+ * `vnd.fjs.*` is this repo's convention for its *own* formats, not a constraint
+ * on what a caller may detect — another vendor's `vnd.*` blob, or a widely used
+ * name not under `vnd.` at all, is a legitimate thing to register. The name is
+ * not attacker-controlled either: it comes from a schema a programmer wrote and
+ * passed here, never from the blob being classified, so no untrusted string
+ * reaches `mime_type` along this path. (A detector that read the name *out of*
+ * a blob would need the RFC 6838 grammar check and an allowlist; this one does
+ * not.) Registering a name that is not a valid RFC 6838 restricted-name yields
+ * a malformed media type in the registrant's own results, and nowhere else.
+ *
+ * The constraint is `Struct` — every member must be a real rtti `Type`, which
+ * is what rejects a member like `() => 42` at compile time (rtti would read it
+ * as a thunk and `match` would *throw* on the first blob rather than return
+ * `false`). TypeScript cannot also require a direct string `dialect` member
+ * under that constraint, so that half is asserted here instead: loudly, once,
+ * when the entry is constructed. A thunk-form `dialect`
+ * (`() => ['const', 'x']`) is a perfectly valid rtti schema, it just is not
+ * registerable — write the string directly, as `revisionSchema` does.
+ *
+ * @template {Struct} T
+ * @param {T} type
+ * @param {(_: Ts<T>) => boolean} [extraValidate]
+ * @returns {DialectEntry}
+ */
+export const dialectEntry = (type, extraValidate = always) => {
+    const { dialect } = type
+    assert(typeof dialect === 'string', 'dialectEntry: schema has no direct string `dialect` member')
+    return { dialect, match: matchWith(validate(type))(extraValidate) }
+}
+
+/**
+ * Classifies a whole buffered `Vec` against `dialects`, returning the same
+ * three-way `{ length, mime_type, type }` shape as `fjs/media/type`
+ * `detectVec`, but with dialect-tagged JSON recognized ahead of the plain
+ * `text/plain` fallback. The first entry whose `match` accepts the parsed value
+ * wins; entries that overlap are the registrant's own business, since matching
+ * `dialect` as an exact literal already makes structural validation reject
+ * every other dialect's blob.
+ *
+ * @param {readonly DialectEntry[]} dialects
+ * @returns {(bytes: Vec) => DetectMeta}
+ */
+export const detect = dialects => bytes => {
+    const base = detectVec(bytes)
+    // Only whole-blob-valid UTF-8 text can possibly be JSON; a magic-byte hit
+    // or binary fallback is never a dialect match.
+    if (base.type !== 'text') { return base }
+    // `detectVec`'s `type: 'text'` verdict already means `bytes` is byte-aligned,
+    // whole-blob-valid UTF-8 — the same two conditions `fromVec` checks, via the
+    // same decoder — so `fromVec` cannot return `null` here.
+    const text = assertNotNullish(fromVec(bytes), 'detect: type text implies fromVec succeeds')
+    const [tag, value] = parse(text)
+    if (tag === 'error') { return base }
+    const matched = dialects.find(({ match }) => match(value))
+    return matched === undefined
+        ? base
+        : { ...base, mime_type: `application/${matched.dialect}+json` }
+}

package/fjs/media/nix/module.f.d.mts

@@ -0,0 +1,14 @@
+import type { List as ChunkList } from '../../types/list/types.ts';
+import type { Expression } from './types.ts';
+/**
+ * Serializes an expression into composable chunks, or rejects an invalid identifier.
+ *
+ * @type {(expression: Expression) => ChunkList<string> | undefined}
+ */
+export declare const nix: (expression: Expression) => ChunkList<string> | undefined;
+/**
+ * Serializes an expression with exactly one trailing newline on success.
+ *
+ * @type {(expression: Expression) => string | undefined}
+ */
+export declare const nixToString: (expression: Expression) => string | undefined;

package/fjs/media/nix/module.f.mjs

@@ -0,0 +1,261 @@
+/**
+ * A minimal, checked eDSL for constructing and serializing Nix expressions.
+ *
+ * The tree deliberately models syntax rather than evaluated Nix values. String
+ * expressions are escaped double-quoted strings; the other supported forms are
+ * represented by tagged tuples. See `./types.ts` for the `Expression`
+ * type-level API.
+ *
+ * @module
+ */
+/** @import { List as ChunkList } from '../../types/list/types.ts' */
+import { toArray } from '../../types/list/module.f.mjs'
+import { concat } from '../../types/string/module.f.mjs'
+import { includes } from '../../types/array/module.f.mjs'
+import {
+    digitRange,
+    latinCapitalLetterRange,
+    latinSmallLetterRange,
+    range,
+} from '../../text/ascii/module.f.mjs'
+import { fromRange, get, merge } from '../../types/range_set/module.f.mjs'
+/** @import { Expression, _AttributePath, _Binding, _Reference, _AttributeSet, _NixList, _Application, _OpenSetPattern, _Lambda, _Let, _Chunks } from './types.ts' */
+
+const reservedWords = /** @type {const} */ ([
+    'assert',
+    'else',
+    'if',
+    'in',
+    'inherit',
+    'let',
+    'or',
+    'rec',
+    'then',
+    'with',
+])
+
+const isReservedWord = includes(reservedWords)
+
+const letters = merge
+    (fromRange(latinCapitalLetterRange))
+    (fromRange(latinSmallLetterRange))
+
+const identifierInitial = toArray(merge
+    (letters)
+    (fromRange(range('_'))))
+
+const getIdentifierInitial = get(identifierInitial)
+
+/** @type {(character: string) => boolean} */
+const isIdentifierInitial = character =>
+    getIdentifierInitial(character.charCodeAt(0))
+
+const identifierTrailing = toArray(merge
+    (merge
+        (identifierInitial)
+        (fromRange(digitRange)))
+    (merge
+        (fromRange(range("'")))
+        (fromRange(range('-')))))
+
+const getIdentifierTrailing = get(identifierTrailing)
+
+/** @type {(character: string) => boolean} */
+const isIdentifierTrailing = character =>
+    getIdentifierTrailing(character.charCodeAt(0))
+
+/** @type {(value: string) => boolean} */
+const isIdentifier = value => {
+    const [initial, ...trailing] = value
+    return initial !== undefined
+        && isIdentifierInitial(initial)
+        && trailing.every(isIdentifierTrailing)
+        && !isReservedWord(value)
+}
+
+/** @type {(level: number) => string} */
+const indent = level => '    '.repeat(level)
+
+/** @type {(value: string) => string} */
+const escapeQuoted = value => value
+    .replaceAll('\\', '\\\\')
+    .replaceAll('"', '\\"')
+    .replaceAll('${', '\\${')
+    .replaceAll('\n', '\\n')
+    .replaceAll('\r', '\\r')
+    .replaceAll('\t', '\\t')
+
+/** @type {(value: string) => string} */
+const quoted = value => `"${escapeQuoted(value)}"`
+
+/** @type {(value: string) => string} */
+const attributeName = value =>
+    isIdentifier(value) ? value : quoted(value)
+
+/** @type {(path: _AttributePath) => string} */
+const attributePath = path =>
+    path.map(attributeName).join('.')
+
+/** @type {(value: string) => string} */
+const escapeIndented = value => value
+    .replaceAll("''", "'''")
+    .replaceAll('${', "''${")
+
+/** @type {(line: string) => string} */
+const protectLeadingWhitespace = line => {
+    const contentStart = [...line, 'x'].findIndex(character => character !== ' ' && character !== '\t')
+    const leading = line.slice(0, contentStart)
+        .replaceAll(' ', "''\\ ")
+        .replaceAll('\t', "''\\t")
+    return `${leading}${line.slice(contentStart)}`
+}
+
+/** @type {(reference: _Reference) => string | undefined} */
+const serializeReference = ([, name, ...selection]) =>
+    isIdentifier(name)
+        ? [name, ...selection.map(attributeName)].join('.')
+        : undefined
+
+/** @type {(reference: _Reference) => _Chunks | undefined} */
+const serializeReferenceChunks = reference => {
+    const serialized = serializeReference(reference)
+    return serialized === undefined ? undefined : [serialized]
+}
+
+/** @type {(pattern: _OpenSetPattern) => string | undefined} */
+const serializePattern = ([, ...names]) =>
+    names.every((name, index) => isIdentifier(name) && names.indexOf(name) === index)
+        ? `{ ${[...names, '...'].join(', ')} }`
+        : undefined
+
+/** @type {(chunks: readonly _Chunks[], separator: string) => _Chunks} */
+const joinChunks = (chunks, separator) =>
+    chunks.flatMap((chunk, index) => index === 0 ? chunk : [separator, ...chunk])
+
+/** @type {(prefix: _AttributePath, path: _AttributePath) => boolean} */
+const isPathPrefix = (prefix, path) =>
+    prefix.length <= path.length
+    && prefix.every((name, index) => name === path[index])
+
+/** @type {(a: _AttributePath, b: _AttributePath) => boolean} */
+const pathsConflict = (a, b) =>
+    isPathPrefix(a, b) || isPathPrefix(b, a)
+
+/** @type {(bindings: readonly _Binding[]) => boolean} */
+const bindingsCompatible = bindings =>
+    bindings.every(([, path], index) =>
+        bindings.slice(0, index).every(([, previous]) => !pathsConflict(path, previous)))
+
+/** @type {(bindings: readonly _Binding[], level: number) => _Chunks | undefined} */
+const serializeBindings = (bindings, level) => {
+    if (!bindingsCompatible(bindings)) {
+        return undefined
+    }
+    const serialized = bindings.map(([, path, value]) => {
+        const expression = serialize(value, level)
+        return expression === undefined
+            ? undefined
+            : [indent(level), attributePath(path), ' = ', ...expression, ';']
+    })
+    const defined = serialized.flatMap(value => value === undefined ? [] : [value])
+    return defined.length !== serialized.length
+        ? undefined
+        : joinChunks(defined, '\n')
+}
+
+/** @type {(set: _AttributeSet, level: number) => _Chunks | undefined} */
+const serializeSet = ([, ...bindings], level) => {
+    if (bindings.length === 0) {
+        return ['{}']
+    }
+    const body = serializeBindings(bindings, level + 1)
+    return body === undefined ? undefined : ['{\n', ...body, '\n', indent(level), '}']
+}
+
+/** @type {(list: _NixList) => _Chunks | undefined} */
+const serializeList = ([, ...references]) => {
+    const items = references.map(serializeReference)
+    const definedItems = items.flatMap(item => item === undefined ? [] : [item])
+    return items.includes(undefined)
+        ? undefined
+        : items.length === 0
+            ? ['[ ]']
+            : ['[ ', ...definedItems.flatMap((item, index) => index === 0 ? [item] : [' ', item]), ' ]']
+}
+
+/** @type {(application: _Application, level: number) => _Chunks | undefined} */
+const serializeApplication = ([, fn, ...args], level) => {
+    const serializedFn = serializeReference(fn)
+    const serializedArgs = args.map(argument =>
+        argument[0] === 'ref'
+            ? serializeReferenceChunks(argument)
+            : serializeSet(argument, level))
+    const definedArgs = serializedArgs.flatMap(argument => argument === undefined ? [] : [argument])
+    return serializedFn === undefined || definedArgs.length !== serializedArgs.length
+        ? undefined
+        : [serializedFn, ...definedArgs.flatMap(argument => [' ', ...argument])]
+}
+
+/** @type {(lambda: _Lambda, level: number) => _Chunks | undefined} */
+const serializeLambda = ([, pattern, body], level) => {
+    const serializedPattern = serializePattern(pattern)
+    const serializedBody = serialize(body, level)
+    return serializedPattern === undefined || serializedBody === undefined
+        ? undefined
+        : [serializedPattern, ': ', ...serializedBody]
+}
+
+/** @type {(let_: _Let, level: number) => _Chunks | undefined} */
+const serializeLet = ([, bindings, body], level) => {
+    const serializedBindings = serializeBindings(bindings, level + 1)
+    const serializedBody = serialize(body, level)
+    return serializedBindings === undefined || serializedBody === undefined
+        ? undefined
+        : ['let\n', ...serializedBindings, '\n', indent(level), 'in\n', indent(level), ...serializedBody]
+}
+
+/** @type {(expression: Expression, level: number) => _Chunks | undefined} */
+const serialize = (expression, level) => {
+    if (typeof expression === 'string') {
+        return [quoted(expression)]
+    }
+    switch (expression[0]) {
+        case 'ref': {
+            return serializeReferenceChunks(expression)
+        }
+        case 'set': return serializeSet(expression, level)
+        case 'list': return serializeList(expression)
+        case 'apply': return serializeApplication(expression, level)
+        case 'lambda': return serializeLambda(expression, level)
+        case 'let': return serializeLet(expression, level)
+        case 'indented-string': {
+            const [, value] = expression
+            const contentIndent = indent(level + 1)
+            const content = escapeIndented(value)
+                .split('\n')
+                .map(protectLeadingWhitespace)
+                .map(line => `${contentIndent}${line}`)
+                .join('\n')
+            return ["''\n", content, '\n', indent(level), "''"]
+        }
+    }
+}
+
+/**
+ * Serializes an expression into composable chunks, or rejects an invalid identifier.
+ *
+ * @type {(expression: Expression) => ChunkList<string> | undefined}
+ */
+export const nix = expression => {
+    return serialize(expression, 0)
+}
+
+/**
+ * Serializes an expression with exactly one trailing newline on success.
+ *
+ * @type {(expression: Expression) => string | undefined}
+ */
+export const nixToString = expression => {
+    const chunks = nix(expression)
+    return chunks === undefined ? undefined : `${concat(chunks)}\n`
+}