@loomcli/core 0.6.0 → 0.8.0

package/dist/parse.js

@@ -0,0 +1,601 @@
+import { MisplacedOptionError, MissingValueError, RepeatedOptionError, UnexpectedArgumentError, UnexpectedValueError, UnknownCommandError, UnknownOptionError, } from './errors.js';
+import { emptyValues, isSupplied } from './options.js';
+/**
+ * Whether a word is an option word: `--` and at least one more character, or `-` and an ASCII
+ * letter. Every other word is a plain word, so `-`, `-5`, and `-.5` are values or arguments. The
+ * parser and `locate` read each word through this rule.
+ */
+function isOptionWord(word) {
+    return word.startsWith('--') ? word.length > 2 : /^-[A-Za-z]/u.test(word);
+}
+/** A word the grammar never consumes as a separate value: an option word or the bare `--`. */
+function refusesValue(word) {
+    return word === '--' || isOptionWord(word);
+}
+/** Whether an option collects every occurrence: a multiple string option. */
+function collects(option) {
+    return option.type === 'string' && option.multiple;
+}
+/**
+ * Whether every occurrence of an option adds to it: a multiple string option collects each, and a
+ * counted option counts each, so neither is ever a repeat.
+ */
+function accumulates(option) {
+    return option.type === 'count' || collects(option);
+}
+/** Whether an occurrence of an option repeats one an earlier word supplied. */
+function repeats(context, option) {
+    const values = option.global ? context.values.globals : context.values.locals;
+    return !accumulates(option) && isSupplied(values, option.name);
+}
+/**
+ * What a spelling with nothing attached supplies, by its value class: a Boolean's own value, one
+ * occurrence of a count, or a string option's implied value. A string option that takes the next
+ * word has no value of its own, so it answers `undefined`.
+ */
+function bareValue(option, spelling) {
+    switch (option.valueClass) {
+        case 'boolean': {
+            return { kind: 'value', option, spelling, value: option.value };
+        }
+        case 'count': {
+            return { kind: 'value', option, spelling, value: 1 };
+        }
+        case 'implied': {
+            return { implied: true, kind: 'value', option, spelling, value: option.implied };
+        }
+        case 'separate': {
+            return undefined;
+        }
+        default: {
+            const exhaustive = option;
+            return exhaustive;
+        }
+    }
+}
+/**
+ * A repeated occurrence supplies nothing, and a string option still takes the value its form
+ * names, so the words after it read as they would have.
+ */
+function repeated(option, spelling, takesNext) {
+    return { occurrences: [{ kind: 'repeated', option, spelling }], takesNext };
+}
+/** Whether a string option with no value in its own word takes the next word as its value. */
+function takesSeparate(next) {
+    return next !== undefined && !refusesValue(next);
+}
+/**
+ * A string option whose value is the next word: that word, unless the words ran out or it is a word
+ * the grammar never consumes as a value.
+ */
+function separateValue(option, spelling, next) {
+    if (next === undefined) {
+        return { occurrences: [{ kind: 'awaiting', option, spelling }], takesNext: false };
+    }
+    if (refusesValue(next)) {
+        return { occurrences: [{ kind: 'missing', option, spelling }], takesNext: false };
+    }
+    return { occurrences: [{ kind: 'value', option, spelling, value: next }], takesNext: true };
+}
+/** A word that starts with `--`, split at its first `=` into the spelling and the value it carries. */
+function readLong(context, word, next) {
+    const equals = word.indexOf('=');
+    const spelling = equals === -1 ? word : word.slice(0, equals);
+    const inline = equals === -1 ? undefined : word.slice(equals + 1);
+    const option = context.table.get(spelling);
+    if (!option) {
+        return { occurrences: [{ kind: 'unknown', spelling }], takesNext: false };
+    }
+    if (repeats(context, option)) {
+        const separate = option.valueClass === 'separate' && inline === undefined && takesSeparate(next);
+        return repeated(option, spelling, separate);
+    }
+    return longValue({ inline, option, spelling }, next);
+}
+/**
+ * The value a declared long spelling supplies: a Boolean's own value or one occurrence of a count,
+ * neither of which takes `=`, or a string option's value after `=`, else its implied value, else
+ * the next word.
+ */
+function longValue(long, next) {
+    const { inline, option, spelling } = long;
+    if (inline === undefined) {
+        const bare = bareValue(option, spelling);
+        return bare ? { occurrences: [bare], takesNext: false } : separateValue(option, spelling, next);
+    }
+    const occurrence = option.type === 'string'
+        ? { kind: 'value', lead: `${spelling}=`, option, spelling, value: inline }
+        : { kind: 'unexpected', option, spelling, value: inline };
+    return { occurrences: [occurrence], takesNext: false };
+}
+/**
+ * A Boolean letter is set, and a counted letter adds one, and the walk continues; a `=` after
+ * either is a value it cannot take.
+ */
+function valuelessLetter(option, spelling, rest) {
+    const occurrence = rest.startsWith('=')
+        ? { kind: 'unexpected', option, spelling, value: rest.slice(1) }
+        : { kind: 'value', option, spelling, value: option.type === 'boolean' ? option.value : 1 };
+    return { ends: occurrence.kind !== 'value', occurrences: [occurrence], takesNext: false };
+}
+/**
+ * A value letter ends the group: the rest of the word is its value, with one leading `=` stripped.
+ * When nothing remains, a letter with an implied value supplies it, and any other takes the next
+ * word as its value.
+ */
+function valueLetter(group, letter, rest) {
+    const { option, spelling } = letter;
+    if (rest === '') {
+        const bare = bareValue(option, spelling);
+        return bare
+            ? { ends: true, occurrences: [bare], takesNext: false }
+            : { ends: true, ...separateValue(option, spelling, group.next) };
+    }
+    const value = rest.startsWith('=') ? rest.slice(1) : rest;
+    const lead = group.word.slice(0, group.word.length - value.length);
+    return {
+        ends: true,
+        occurrences: [{ kind: 'value', lead, option, spelling, value }],
+        takesNext: false,
+    };
+}
+/**
+ * Whether a letter repeats an option an earlier letter of its group or an earlier word supplied. A
+ * counted letter adds another occurrence instead, and so would a multiple option's.
+ */
+function repeatsInGroup(group, option) {
+    return (group.set.has(option.name) && !accumulates(option)) || repeats(group.context, option);
+}
+/** The letter at one index of a group, read against the group's table. */
+function readLetter(group, index) {
+    const spelling = `-${group.letters[index] ?? ''}`;
+    const option = group.context.table.get(spelling);
+    const rest = group.letters.slice(index + 1).join('');
+    if (!option) {
+        return { ends: true, occurrences: [{ kind: 'unknown', spelling }], takesNext: false };
+    }
+    if (repeatsInGroup(group, option)) {
+        const takesNext = option.valueClass === 'separate' && rest === '' && takesSeparate(group.next);
+        return { ends: true, ...repeated(option, spelling, takesNext) };
+    }
+    group.set.add(option.name);
+    return option.type === 'string'
+        ? valueLetter(group, { option, spelling }, rest)
+        : valuelessLetter(option, spelling, rest);
+}
+/**
+ * A short group under the `getopt` rule, one code point per letter. The walk stops at a value
+ * letter or at the first letter that faults, a repeated one included, so the characters after it
+ * are never read as letters.
+ */
+function readGroup(context, word, next) {
+    const letters = word.slice(1).match(/./gsu) ?? [];
+    const group = { context, letters, next, set: new Set(), word };
+    const occurrences = [];
+    for (const index of group.letters.keys()) {
+        const letter = readLetter(group, index);
+        occurrences.push(...letter.occurrences);
+        if (letter.ends) {
+            return { occurrences, takesNext: letter.takesNext };
+        }
+    }
+    return { occurrences, takesNext: false };
+}
+/** One option word read against one table, with the word after it as its possible value. */
+function readOptionWord(context, word, next) {
+    return word.startsWith('--') ? readLong(context, word, next) : readGroup(context, word, next);
+}
+/** Whether an occurrence is of a Command's own option, which routing holds back until it ends. */
+function isOwnOccurrence(occurrence) {
+    return 'option' in occurrence && occurrence.kind !== 'awaiting' && !occurrence.option.global;
+}
+/** Stamps the next occurrence or positional with its order in the words. */
+function stamp(state) {
+    state.at = state.read;
+    state.read += 1;
+}
+/** Holds a fault unless one read earlier is held already. */
+function keep(state, fault) {
+    if (state.fault === undefined || fault.at < state.fault.at) {
+        state.fault = fault;
+    }
+}
+/**
+ * The visible Commands below one Command that declare a spelling, as paths from the root in
+ * authoring order. A hidden or deprecated Command, and every Command below it, is left out, as a
+ * listing leaves it out.
+ */
+function declarers(command, path, spelling) {
+    const found = [];
+    for (const [name, child] of command.children) {
+        const below = [...path, name];
+        if (!child.hidden && child.deprecated === undefined) {
+            if (child.table.has(spelling)) {
+                found.push(below);
+            }
+            found.push(...declarers(child, below, spelling));
+        }
+    }
+    return found;
+}
+/** The fault a spelling the routed Command's table does not hold reports. */
+function unplaced(state, spelling) {
+    const commands = declarers(state.command, state.path, spelling);
+    return commands.length > 0
+        ? new MisplacedOptionError(spelling, commands)
+        : new UnknownOptionError(spelling);
+}
+/** Holds a fault unless an earlier word already holds one, and notes a fault on a global option. */
+function hold(state, error, global) {
+    keep(state, { at: state.at, error });
+    state.globalFault ||= global;
+    return false;
+}
+/**
+ * Records one supplied value in the map its kind and its declaration decide: a count adds its
+ * occurrence, and a bare spelling's implied value notes its position, so validation supplies the
+ * prepared output there.
+ */
+function write(values, occurrence) {
+    const { option, value } = occurrence;
+    const { name } = option;
+    if (typeof value === 'boolean') {
+        values.booleans.set(name, value);
+    }
+    else if (typeof value === 'number') {
+        values.counts.set(name, (values.counts.get(name) ?? 0) + value);
+    }
+    else {
+        const position = writeString(values, option, value);
+        if (occurrence.implied) {
+            values.implied.set(name, [...(values.implied.get(name) ?? []), position]);
+        }
+    }
+}
+/**
+ * Records one string value: the option's one value, or the next of a multiple option's list.
+ * Answers the position the value took, `0` for a scalar and its index in the list otherwise.
+ */
+function writeString(values, option, value) {
+    const { name } = option;
+    if (!collects(option)) {
+        values.strings.set(name, value);
+        return 0;
+    }
+    const list = values.lists.get(name);
+    if (list) {
+        list.push(value);
+        return list.length - 1;
+    }
+    values.lists.set(name, [value]);
+    return 0;
+}
+/**
+ * Lists one supplied option name at the order it was read in. A parent's own option binds after
+ * routing, so it can join the list behind names read after it.
+ */
+function note(state, entry) {
+    const later = state.supplied.findIndex(({ at }) => at > entry.at);
+    state.supplied.splice(later === -1 ? state.supplied.length : later, 0, entry);
+}
+/**
+ * Lists the held-back options while routing is still open, each under the name the reached
+ * Command's own entry gives its spelling, so a reader offers none of them again. A spelling that
+ * Command does not hold lists nothing.
+ */
+function noteHeld(state) {
+    for (const { at, occurrence } of state.pending) {
+        const entry = state.command.table.get(occurrence.spelling);
+        if (entry && !state.supplied.some(({ name }) => name === entry.name)) {
+            note(state, { at, name: entry.name });
+        }
+    }
+}
+/** Writes one value an occurrence supplied. The reading already ended its walk at a repeat. */
+function supply(state, occurrence) {
+    const { option, spelling } = occurrence;
+    const values = option.global ? state.values.globals : state.values.locals;
+    if (!values.spellings.has(option.name)) {
+        note(state, { at: state.at, name: option.name });
+    }
+    // A collecting option records its last occurrence, because each one overwrites the entry.
+    values.spellings.set(option.name, spelling);
+    write(values, occurrence);
+    return true;
+}
+/**
+ * The failure a spelling reports where the routed Command reads it: one its table lacks, or one it
+ * declares with another value class than the parent's declaration routing read it by.
+ */
+function spellingFault(state, occurrence) {
+    const { spelling } = occurrence;
+    return occurrence.kind === 'unknown'
+        ? unplaced(state, spelling)
+        : new MisplacedOptionError(spelling, [[...state.path]]);
+}
+/** Applies one occurrence, and answers whether the word's next occurrence is read. */
+function applyOccurrence(state, occurrence) {
+    if (occurrence.kind === 'value') {
+        return supply(state, occurrence);
+    }
+    if (occurrence.kind === 'unknown' || occurrence.kind === 'misplaced') {
+        return hold(state, spellingFault(state, occurrence), false);
+    }
+    const { option, spelling } = occurrence;
+    if (occurrence.kind === 'awaiting') {
+        state.awaiting = { global: option.global, name: option.name, spelling };
+        return false;
+    }
+    return hold(state, optionFault(occurrence), option.global);
+}
+/** The failure a faulted occurrence of a declared option reports. */
+function optionFault(occurrence) {
+    const { spelling } = occurrence;
+    if (occurrence.kind === 'unexpected') {
+        return new UnexpectedValueError(spelling, occurrence.value, occurrence.option.type);
+    }
+    return occurrence.kind === 'repeated'
+        ? new RepeatedOptionError(spelling)
+        : new MissingValueError(spelling, 'attached');
+}
+/** Applies a word's occurrences in order, up to the first that faults. A faulted one supplies nothing. */
+function apply(state, reading) {
+    for (const occurrence of reading.occurrences) {
+        stamp(state);
+        const held = !state.routed && isOwnOccurrence(occurrence);
+        if (held) {
+            state.pending.push({ at: state.at, occurrence });
+        }
+        if (held ? occurrence.kind !== 'value' : !applyOccurrence(state, occurrence)) {
+            return;
+        }
+    }
+}
+/**
+ * The occurrence routing read against a parent's own option, bound to the routed Command's
+ * declaration of the same spelling. A Command without it reports the spelling as it reports any its
+ * table lacks, and a declaration of another value class is misplaced, because the parent's
+ * declaration already decided whether the next word was the value, and the words are never read
+ * again. A declaration of the same class keeps the fault the parent's declaration found, if any.
+ */
+function rebound(state, pending) {
+    const { spelling } = pending;
+    const option = state.command.table.get(spelling);
+    if (!option) {
+        return { kind: 'unknown', spelling };
+    }
+    if (option.valueClass !== pending.option.valueClass) {
+        return { kind: 'misplaced', spelling };
+    }
+    return pending.kind === 'value'
+        ? boundValue(state, pending, option)
+        : boundFault(pending, option);
+}
+/**
+ * A fault routing held back, bound to the routed Command's declaration of the same class, which
+ * keeps it. A value after a spelling that takes none reaches here only with a Boolean or counted
+ * option, because a class mismatch is misplaced before this binds; the string branch exists only so
+ * the bound occurrence stays typed, and no invocation reaches it.
+ */
+function boundFault(pending, option) {
+    if (pending.kind !== 'unexpected') {
+        return { ...pending, option };
+    }
+    return option.type === 'string'
+        ? { kind: 'misplaced', spelling: pending.spelling }
+        : { ...pending, option };
+}
+/** A value routing held back, bound to the routed Command's declaration of the same class. */
+function boundValue(state, pending, option) {
+    const { spelling } = pending;
+    if (repeats({ table: state.command.table, values: state.values }, option)) {
+        return { kind: 'repeated', option, spelling };
+    }
+    // The bound declaration decides what a spelling with nothing attached supplies.
+    // That is a Boolean's own value, one occurrence of a count, or its own implied value.
+    // A value in the next word or attached is the word the parent's declaration read.
+    const bare = pending.lead === undefined ? bareValue(option, spelling) : undefined;
+    return { ...pending, option, value: bare?.value ?? pending.value };
+}
+/** Binds each occurrence routing read against a parent's own option to the Command it reached. */
+function bindPending(state) {
+    for (const { at, occurrence } of state.pending) {
+        state.at = at;
+        applyOccurrence(state, rebound(state, occurrence));
+    }
+    state.pending = [];
+}
+/**
+ * The names a routing failure offers: the canonical names of the visible, current children, in
+ * authoring order. A candidate list is a listing, so a hidden or a deprecated child is absent from
+ * it, as completion leaves them out, and a parent whose children are all hidden or deprecated
+ * offers none. A deprecated child typed in full still routes.
+ */
+function candidatesOf(command) {
+    return [...command.children]
+        .filter(([, child]) => !child.hidden && child.deprecated === undefined)
+        .map(([name]) => name);
+}
+/**
+ * The slot the positional at one index fills: the slot at that index, else a variadic last slot,
+ * which accepts every later positional, else none. Binding and `locate` read positions through it.
+ */
+function argumentSlot(slots, position) {
+    const last = slots.at(-1);
+    return slots[position] ?? (last?.variadic ? last : undefined);
+}
+/**
+ * Whether routing reads a Command's own options: it has an action and children. A Command with
+ * children takes no arguments, so a plain word after its own option can only name a child, and its
+ * own declaration says whether the next word is that option's value.
+ */
+function readsOwnOptions(command) {
+    return command.dispatch !== undefined && command.children.size > 0;
+}
+/**
+ * An option word under routing, read against the global options, and at a Command with an action
+ * and children against its whole table, whose own options bind once routing ends. A walk that meets
+ * a spelling those options do not declare ends routing at the Command reached, which reads the word
+ * again against its own table. Answers how many words it read, and `0` where routing ends.
+ */
+function routeOption(routing, state, index) {
+    const { graph, words } = routing;
+    const { command } = state;
+    const table = readsOwnOptions(command) ? command.table : graph.globals.table;
+    const context = { table, values: state.values };
+    const reading = readOptionWord(context, words[index] ?? '', words[index + 1]);
+    if (reading.occurrences.some((occurrence) => occurrence.kind === 'unknown')) {
+        return 0;
+    }
+    apply(state, reading);
+    return reading.takesNext ? 2 : 1;
+}
+/**
+ * A plain word under routing names a child or an alias and descends, and an unknown child is the
+ * one fault raised here. Under a Command with no children it ends routing as that Command's first
+ * argument. `walked` hears the path as each name routes, so an unknown Command leaves its caller
+ * holding the partial path.
+ */
+function descend(routing, state, word) {
+    const { command } = state;
+    if (command.children.size === 0) {
+        return 0;
+    }
+    const child = command.routes.get(word);
+    if (!child) {
+        throw new UnknownCommandError(word, candidatesOf(command));
+    }
+    // An alias routes like the canonical name, and the path it walks reports that name alone.
+    state.command = child.command;
+    state.path.push(child.name);
+    routing.walked?.(Object.freeze([...state.path]));
+    return 1;
+}
+/** One word routing reads: how many words it took, or `0` where routing ends. */
+function routeWord(routing, state, index) {
+    const word = routing.words[index];
+    if (word === undefined || word === '--') {
+        return 0;
+    }
+    return isOptionWord(word) ? routeOption(routing, state, index) : descend(routing, state, word);
+}
+/**
+ * Routing: the words before the first bare `--`, read from the root against the global options
+ * alone. Answers the index of the first word it did not read.
+ */
+function route(routing, state) {
+    let index = 0;
+    for (let read = routeWord(routing, state, index); read > 0; read = routeWord(routing, state, index)) {
+        index += read;
+    }
+    return index;
+}
+/** One plain word after routing: the routed Command's next positional, even one that names a child. */
+function positional(state, word) {
+    stamp(state);
+    state.positionals.push(word);
+    const position = state.positionals.length - 1;
+    if (!argumentSlot(state.command.arguments, position)) {
+        keep(state, { at: state.at, extra: position });
+    }
+}
+/** One word of the routed Command, read against its table. Answers how many later words it took. */
+function readCommandWord(state, word, next) {
+    if (!isOptionWord(word)) {
+        positional(state, word);
+        return 0;
+    }
+    const reading = readOptionWord({ table: state.command.table, values: state.values }, word, next);
+    apply(state, reading);
+    return reading.takesNext ? 1 : 0;
+}
+/** The routed Command's words from where routing ended, up to the first bare `--`. */
+function readCommandWords(routing, state, start) {
+    const { words } = routing;
+    for (let index = start; index < words.length; index += 1) {
+        const word = words[index] ?? '';
+        if (word === '--') {
+            return { delimited: true, passthrough: words.slice(index + 1) };
+        }
+        index += readCommandWord(state, word, words[index + 1]);
+    }
+    return { delimited: false, passthrough: [] };
+}
+/**
+ * Whether routing ended where the words did: they stopped it, the list is complete, no later word
+ * can continue routing, or a parent's own option already faulted, which binding reports wherever
+ * routing ends.
+ */
+function routingEnded(state, start, read) {
+    return (start < read.words.length ||
+        read.partial !== true ||
+        state.command.children.size === 0 ||
+        state.pending.some(({ occurrence }) => occurrence.kind !== 'value'));
+}
+/**
+ * Reads a word list through routing, against the global options and the own options of each
+ * Command with an action and children it passes through, binds those own options to the Command
+ * routing reached once routing has ended, and then reads that Command's own words, up to the first
+ * bare `--`, against the one table it holds.
+ * Parsing continues past a fault, so every global option is found wherever it sits, and only the
+ * first fault in word order is held. Only an unknown Command throws.
+ */
+function readWords(graph, words, options = {}) {
+    const { partial, walked } = options;
+    const routing = { graph, walked, words };
+    const state = {
+        at: 0,
+        awaiting: undefined,
+        command: graph.root,
+        fault: undefined,
+        globalFault: false,
+        path: [],
+        pending: [],
+        positionals: [],
+        read: 0,
+        routed: false,
+        supplied: [],
+        values: { globals: emptyValues(), locals: emptyValues() },
+    };
+    const start = route(routing, state);
+    if (routingEnded(state, start, { partial, words })) {
+        state.routed = true;
+        bindPending(state);
+    }
+    else {
+        noteHeld(state);
+    }
+    const tail = readCommandWords(routing, state, start);
+    return {
+        ...state,
+        ...tail,
+        committed: start < words.length && words[start] !== '--',
+        supplied: state.supplied.map(({ name }) => name),
+    };
+}
+/** The failure a held fault reports once every word is read. */
+function heldFailure(read, fault) {
+    return 'error' in fault
+        ? fault.error
+        : new UnexpectedArgumentError(read.path, read.command.arguments.length, read.positionals.slice(fault.extra));
+}
+/**
+ * Parses a complete invocation, where a string option still waiting for its value at the end of
+ * the words is a missing value.
+ */
+function parseInvocation(graph, argv, walked) {
+    const read = readWords(graph, argv, { walked });
+    const { awaiting, command, passthrough, path, positionals, values } = read;
+    const missing = awaiting && { at: read.read, error: new MissingValueError(awaiting.spelling) };
+    const fault = read.fault ?? missing;
+    return {
+        command,
+        fault: fault && heldFailure(read, fault),
+        globalFault: read.globalFault || awaiting?.global === true,
+        passthrough,
+        path,
+        positionals,
+        values,
+    };
+}
+export { argumentSlot, candidatesOf, isOptionWord, parseInvocation, readOptionWord, readWords, refusesValue, };

package/dist/plain.d.ts

@@ -1,6 +1,56 @@
+/**
+ * Runs one declaring call with verdicts of its own, dropped when it returns or throws. A call made
+ * inside another, such as a `plugin()` a getter makes, is part of the outer read and shares them.
+ */
+declare function declaring<Result>(call: () => Result): Result;
 /**
  * A structural value core reads as plain data: an object literal, and never a declaration that
  * carries state of its own. The options slots read it to reject a value that is not an options
- * object, and inspection reads it to copy a declared value faithfully.
+ * object, and `snapshot` reads it to copy a declared value faithfully. A value a declaring call
+ * already judged answers with that verdict.
+ */
+declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Whether a declaring call reads one part of a declaration as plain data, decided once: the first
+ * verdict is recorded, and `isPlainObject` answers with it for the same value from then on.
+ */
+declare function decidePlain(value: unknown): value is Record<string, unknown>;
+/**
+ * A snapshot of one value. Arrays and plain objects are copied and frozen to any depth, so a
+ * consumer cannot reach the source through the copy. A value that holds itself is copied with the
+ * same cycle, because each source object is judged and copied once and every path to it reaches
+ * that copy. Primitives and library objects, such as a class instance or a `Date` a schema
+ * produced, are reported as they are, because core cannot copy them meaningfully. Build reads it
+ * for a converter's schema, and the chain for the request one middleware holds.
+ */
+declare function snapshot(value: unknown): unknown;
+/** The snapshot of one plain object, under the record type the caller already established. */
+declare function snapshotRecord(value: Record<string, unknown>): Readonly<Record<string, unknown>>;
+/**
+ * The snapshot `snapshot` takes, of a value whose paths may hold at most `levels` arrays and plain
+ * objects, the value itself included. Every path through a container the value holds twice counts
+ * it, and a value that holds itself has a path without end. Either kind of path past `levels`
+ * throws `NestedTooDeepError` before the walk goes deeper than `levels`, so neither the walk nor
+ * any later reader of the copy goes deeper either. A declaring call reads it for a declared default.
+ */
+declare function boundedSnapshot(value: unknown, levels: number): unknown;
+/** What `boundedSnapshot` throws for a value with a path longer than its limit. */
+declare class NestedTooDeepError extends Error {
+    name: string;
+}
+/**
+ * A copy of every own string key of one object, enumerable or not, each described once and read
+ * once, in the order the object lists its keys. `entering` hears each key before it is read, so a
+ * read that throws can name it. A symbol key is not copied, because no declaration declares one.
+ */
+declare function copyOwnKeys(declared: object, entering?: (key: string) => void): Record<string, unknown>;
+/**
+ * The copy of one part of a declaration that `decidePlain` judges plain, by `copyOwnKeys`. Any other
+ * value is answered as it is, so the rule for its slot reports it.
  */
-export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+declare function shallowRecord(value: unknown): unknown;
+/** A copy of one list's entries by `fillList`. Each entry is what its factory built, so it is kept. */
+declare function copyList<Entry>(list: readonly Entry[]): Entry[];
+/** The copy of a value that is a list, by `copyList`. Any other value is answered as it is. */
+declare function shallowList(value: unknown): unknown;
+export { boundedSnapshot, copyList, copyOwnKeys, decidePlain, declaring, isPlainObject, NestedTooDeepError, shallowList, shallowRecord, snapshot, snapshotRecord, };