@optique/core 1.0.0-dev.1315 → 1.0.0-dev.1326

package/dist/constructs.cjs

@@ -304,6 +304,7 @@ function or(...args) {
 		parsers = args;
 		options = void 0;
 	}
+	if (parsers.length < 1) throw new TypeError("or() requires at least one parser argument.");
 	const noMatchContext = analyzeNoMatchContext(parsers);
 	const combinedMode = parsers.some((p) => p.$mode === "async") ? "async" : "sync";
 	const syncParsers = parsers;
@@ -505,6 +506,7 @@ function longestMatch(...args) {
 		parsers = args;
 		options = void 0;
 	}
+	if (parsers.length < 1) throw new TypeError("longestMatch() requires at least one parser argument.");
 	const noMatchContext = analyzeNoMatchContext(parsers);
 	const combinedMode = parsers.some((p) => p.$mode === "async") ? "async" : "sync";
 	const syncParsers = parsers;
@@ -1656,6 +1658,7 @@ function merge(...args) {
 	const startIndex = typeof args[0] === "string" ? 1 : 0;
 	const endIndex = hasOptions ? args.length - 1 : args.length;
 	const rawParsers = args.slice(startIndex, endIndex);
+	if (rawParsers.length < 1) throw new TypeError("merge() requires at least one parser argument.");
 	const combinedMode = rawParsers.some((p) => p.$mode === "async") ? "async" : "sync";
 	const isAsync = combinedMode === "async";
 	const syncRawParsers = rawParsers;
@@ -2098,6 +2101,7 @@ function tryParseSuggestList(context, stateArray, parsers, matchedParsers, remai
 	return null;
 }
 function concat(...parsers) {
+	if (parsers.length < 1) throw new TypeError("concat() requires at least one parser argument.");
 	const combinedMode = parsers.some((p) => p.$mode === "async") ? "async" : "sync";
 	const isAsync = combinedMode === "async";
 	const syncParsers = parsers;

package/dist/constructs.d.cts

@@ -730,6 +730,7 @@ declare function or<MA extends Mode, MB extends Mode, MC extends Mode, MD extend
  * @param options Custom error message options.
  * @return A {@link Parser} that tries to parse using the provided parsers
  *         in order, returning the result of the first successful parser.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<MA extends Mode, MB extends Mode, TA, TB, TStateA, TStateB>(a: Parser<MA, TA, TStateA>, b: Parser<MB, TB, TStateB>, options: OrOptions): Parser<CombineModes<readonly [MA, MB]>, TA | TB, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>]>;
@@ -751,6 +752,7 @@ declare function or<MA extends Mode, MB extends Mode, TA, TB, TStateA, TStateB>(
  * @param options Custom error message options.
  * @return A {@link Parser} that tries to parse using the provided parsers
  *         in order, returning the result of the first successful parser.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<MA extends Mode, MB extends Mode, MC extends Mode, TA, TB, TC, TStateA, TStateB, TStateC>(a: Parser<MA, TA, TStateA>, b: Parser<MB, TB, TStateB>, c: Parser<MC, TC, TStateC>, options: OrOptions): Parser<CombineModes<readonly [MA, MB, MC]>, TA | TB | TC, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>] | [2, ParserResult<TStateC>]>;
@@ -760,6 +762,7 @@ declare function or<MA extends Mode, MB extends Mode, MC extends Mode, TA, TB, T
  * @param rest Parsers to try, followed by {@link OrOptions} for error
  *             customization.
  * @returns A parser that succeeds if any of the input parsers succeed.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<const TParsers extends readonly Parser<Mode, unknown, unknown>[]>(...rest: [...parsers: TParsers, options: OrTailOptions] & OrArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, InferValue<TParsers[number]>, undefined | [number, ParserResult<unknown>]>;
@@ -767,6 +770,7 @@ declare function or<const TParsers extends readonly Parser<Mode, unknown, unknow
  * Creates a parser that tries each parser in sequence until one succeeds.
  * @param parsers Parsers to try in order.
  * @returns A parser that succeeds if any of the input parsers succeed.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<const TParsers extends readonly Parser<Mode, unknown, unknown>[]>(...parsers: TParsers & OrArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, InferValue<TParsers[number]>, undefined | [number, ParserResult<unknown>]>;
@@ -860,6 +864,7 @@ declare function longestMatch<const TParsers extends readonly Parser<"sync", unk
  * @param rest Parsers to compare, followed by error customization options.
  * @returns A parser that yields the best successful branch result.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function longestMatch<const TParsers extends readonly Parser<"sync", unknown, unknown>[]>(...rest: [...parsers: TParsers, options: LongestMatchTailOptions] & LongestMatchArityGuard<TParsers>): Parser<"sync", InferValue<TParsers[number]>, LongestMatchState<TParsers>>;
@@ -870,6 +875,7 @@ declare function longestMatch<const TParsers extends readonly Parser<"sync", unk
  * @param rest Parsers to compare, followed by error customization options.
  * @returns A parser that yields the best successful branch result.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function longestMatch<const TParsers extends readonly Parser<Mode, unknown, unknown>[]>(...rest: [...parsers: TParsers, options: LongestMatchTailOptions] & LongestMatchArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, InferValue<TParsers[number]>, LongestMatchState<TParsers>>;
@@ -1131,6 +1137,7 @@ type MergeReturnType<TParsers extends MergeParsers> = Parser<CombineModes<{ read
  * @param rest Parsers to merge, followed by merge options.
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.7.0
  */
 declare function merge<const TParsers extends MergeParsers>(...rest: [...parsers: EnsureMergeParsers<TParsers>, options: MergeTailOptions] & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1144,6 +1151,7 @@ declare function merge<const TParsers extends MergeParsers>(...rest: [...parsers
  * @param parsers Parsers to merge in declaration order.
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.4.0
  */
 declare function merge<const TParsers extends MergeParsers>(label: string, ...parsers: EnsureMergeParsers<TParsers> & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1157,6 +1165,7 @@ declare function merge<const TParsers extends MergeParsers>(label: string, ...pa
  * @param rest Parsers to merge, followed by merge options.
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.7.0
  */
 declare function merge<const TParsers extends MergeParsers>(label: string, ...rest: [...parsers: EnsureMergeParsers<TParsers>, options: MergeTailOptions] & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1169,6 +1178,7 @@ declare function merge<const TParsers extends MergeParsers>(label: string, ...re
  * @param parsers Parsers to merge in declaration order.
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.1.0
  */
 declare function merge<const TParsers extends MergeParsers>(...parsers: EnsureMergeParsers<TParsers> & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1216,6 +1226,7 @@ type ConcatValues<TParsers extends ConcatParsers> = IsTuple<TParsers> extends tr
  * @param parsers Tuple parsers to concatenate.
  * @returns A parser with flattened tuple values from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.2.0
  */
 declare function concat<const TParsers extends ConcatParsers>(...parsers: TParsers & ConcatArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, ConcatValues<TParsers>, ConcatStates<TParsers>>;

package/dist/constructs.d.ts

@@ -730,6 +730,7 @@ declare function or<MA extends Mode, MB extends Mode, MC extends Mode, MD extend
  * @param options Custom error message options.
  * @return A {@link Parser} that tries to parse using the provided parsers
  *         in order, returning the result of the first successful parser.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<MA extends Mode, MB extends Mode, TA, TB, TStateA, TStateB>(a: Parser<MA, TA, TStateA>, b: Parser<MB, TB, TStateB>, options: OrOptions): Parser<CombineModes<readonly [MA, MB]>, TA | TB, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>]>;
@@ -751,6 +752,7 @@ declare function or<MA extends Mode, MB extends Mode, TA, TB, TStateA, TStateB>(
  * @param options Custom error message options.
  * @return A {@link Parser} that tries to parse using the provided parsers
  *         in order, returning the result of the first successful parser.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<MA extends Mode, MB extends Mode, MC extends Mode, TA, TB, TC, TStateA, TStateB, TStateC>(a: Parser<MA, TA, TStateA>, b: Parser<MB, TB, TStateB>, c: Parser<MC, TC, TStateC>, options: OrOptions): Parser<CombineModes<readonly [MA, MB, MC]>, TA | TB | TC, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>] | [2, ParserResult<TStateC>]>;
@@ -760,6 +762,7 @@ declare function or<MA extends Mode, MB extends Mode, MC extends Mode, TA, TB, T
  * @param rest Parsers to try, followed by {@link OrOptions} for error
  *             customization.
  * @returns A parser that succeeds if any of the input parsers succeed.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<const TParsers extends readonly Parser<Mode, unknown, unknown>[]>(...rest: [...parsers: TParsers, options: OrTailOptions] & OrArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, InferValue<TParsers[number]>, undefined | [number, ParserResult<unknown>]>;
@@ -767,6 +770,7 @@ declare function or<const TParsers extends readonly Parser<Mode, unknown, unknow
  * Creates a parser that tries each parser in sequence until one succeeds.
  * @param parsers Parsers to try in order.
  * @returns A parser that succeeds if any of the input parsers succeed.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<const TParsers extends readonly Parser<Mode, unknown, unknown>[]>(...parsers: TParsers & OrArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, InferValue<TParsers[number]>, undefined | [number, ParserResult<unknown>]>;
@@ -860,6 +864,7 @@ declare function longestMatch<const TParsers extends readonly Parser<"sync", unk
  * @param rest Parsers to compare, followed by error customization options.
  * @returns A parser that yields the best successful branch result.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function longestMatch<const TParsers extends readonly Parser<"sync", unknown, unknown>[]>(...rest: [...parsers: TParsers, options: LongestMatchTailOptions] & LongestMatchArityGuard<TParsers>): Parser<"sync", InferValue<TParsers[number]>, LongestMatchState<TParsers>>;
@@ -870,6 +875,7 @@ declare function longestMatch<const TParsers extends readonly Parser<"sync", unk
  * @param rest Parsers to compare, followed by error customization options.
  * @returns A parser that yields the best successful branch result.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function longestMatch<const TParsers extends readonly Parser<Mode, unknown, unknown>[]>(...rest: [...parsers: TParsers, options: LongestMatchTailOptions] & LongestMatchArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, InferValue<TParsers[number]>, LongestMatchState<TParsers>>;
@@ -1131,6 +1137,7 @@ type MergeReturnType<TParsers extends MergeParsers> = Parser<CombineModes<{ read
  * @param rest Parsers to merge, followed by merge options.
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.7.0
  */
 declare function merge<const TParsers extends MergeParsers>(...rest: [...parsers: EnsureMergeParsers<TParsers>, options: MergeTailOptions] & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1144,6 +1151,7 @@ declare function merge<const TParsers extends MergeParsers>(...rest: [...parsers
  * @param parsers Parsers to merge in declaration order.
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.4.0
  */
 declare function merge<const TParsers extends MergeParsers>(label: string, ...parsers: EnsureMergeParsers<TParsers> & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1157,6 +1165,7 @@ declare function merge<const TParsers extends MergeParsers>(label: string, ...pa
  * @param rest Parsers to merge, followed by merge options.
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.7.0
  */
 declare function merge<const TParsers extends MergeParsers>(label: string, ...rest: [...parsers: EnsureMergeParsers<TParsers>, options: MergeTailOptions] & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1169,6 +1178,7 @@ declare function merge<const TParsers extends MergeParsers>(label: string, ...re
  * @param parsers Parsers to merge in declaration order.
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.1.0
  */
 declare function merge<const TParsers extends MergeParsers>(...parsers: EnsureMergeParsers<TParsers> & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1216,6 +1226,7 @@ type ConcatValues<TParsers extends ConcatParsers> = IsTuple<TParsers> extends tr
  * @param parsers Tuple parsers to concatenate.
  * @returns A parser with flattened tuple values from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.2.0
  */
 declare function concat<const TParsers extends ConcatParsers>(...parsers: TParsers & ConcatArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, ConcatValues<TParsers>, ConcatStates<TParsers>>;

package/dist/constructs.js

@@ -304,6 +304,7 @@ function or(...args) {
 		parsers = args;
 		options = void 0;
 	}
+	if (parsers.length < 1) throw new TypeError("or() requires at least one parser argument.");
 	const noMatchContext = analyzeNoMatchContext(parsers);
 	const combinedMode = parsers.some((p) => p.$mode === "async") ? "async" : "sync";
 	const syncParsers = parsers;
@@ -505,6 +506,7 @@ function longestMatch(...args) {
 		parsers = args;
 		options = void 0;
 	}
+	if (parsers.length < 1) throw new TypeError("longestMatch() requires at least one parser argument.");
 	const noMatchContext = analyzeNoMatchContext(parsers);
 	const combinedMode = parsers.some((p) => p.$mode === "async") ? "async" : "sync";
 	const syncParsers = parsers;
@@ -1656,6 +1658,7 @@ function merge(...args) {
 	const startIndex = typeof args[0] === "string" ? 1 : 0;
 	const endIndex = hasOptions ? args.length - 1 : args.length;
 	const rawParsers = args.slice(startIndex, endIndex);
+	if (rawParsers.length < 1) throw new TypeError("merge() requires at least one parser argument.");
 	const combinedMode = rawParsers.some((p) => p.$mode === "async") ? "async" : "sync";
 	const isAsync = combinedMode === "async";
 	const syncRawParsers = rawParsers;
@@ -2098,6 +2101,7 @@ function tryParseSuggestList(context, stateArray, parsers, matchedParsers, remai
 	return null;
 }
 function concat(...parsers) {
+	if (parsers.length < 1) throw new TypeError("concat() requires at least one parser argument.");
 	const combinedMode = parsers.some((p) => p.$mode === "async") ? "async" : "sync";
 	const isAsync = combinedMode === "async";
 	const syncParsers = parsers;

package/dist/doc.cjs

@@ -3,6 +3,23 @@ const require_usage = require('./usage.cjs');
 
 //#region src/doc.ts
 /**
+* Creates a deep clone of a {@link DocEntry}.  The `term` is cloned via
+* {@link cloneUsageTerm}, and `description`, `default`, and `choices`
+* messages are cloned via {@link cloneMessage}.
+*
+* @param entry The documentation entry to clone.
+* @returns A structurally equal but referentially distinct copy.
+* @since 1.0.0
+*/
+function cloneDocEntry(entry) {
+	return {
+		term: require_usage.cloneUsageTerm(entry.term),
+		...entry.description != null && { description: require_message.cloneMessage(entry.description) },
+		...entry.default != null && { default: require_message.cloneMessage(entry.default) },
+		...entry.choices != null && { choices: require_message.cloneMessage(entry.choices) }
+	};
+}
+/**
 * Classifies a {@link DocSection} by its content type for use in the
 * default smart sort.
 *
@@ -327,4 +344,5 @@ function lastLineVisibleLength(text$1) {
 }
 
 //#endregion
+exports.cloneDocEntry = cloneDocEntry;
 exports.formatDocPage = formatDocPage;

package/dist/doc.d.cts

@@ -103,6 +103,16 @@ interface DocFragments {
    */
   readonly footer?: Message;
 }
+/**
+ * Creates a deep clone of a {@link DocEntry}.  The `term` is cloned via
+ * {@link cloneUsageTerm}, and `description`, `default`, and `choices`
+ * messages are cloned via {@link cloneMessage}.
+ *
+ * @param entry The documentation entry to clone.
+ * @returns A structurally equal but referentially distinct copy.
+ * @since 1.0.0
+ */
+declare function cloneDocEntry(entry: DocEntry): DocEntry;
 /**
  * Configuration for customizing default value display formatting.
  *
@@ -291,4 +301,4 @@ interface DocPageFormatOptions {
  */
 declare function formatDocPage(programName: string, page: DocPage, options?: DocPageFormatOptions): string;
 //#endregion
-export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, formatDocPage };
+export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, formatDocPage };

package/dist/doc.d.ts

@@ -103,6 +103,16 @@ interface DocFragments {
    */
   readonly footer?: Message;
 }
+/**
+ * Creates a deep clone of a {@link DocEntry}.  The `term` is cloned via
+ * {@link cloneUsageTerm}, and `description`, `default`, and `choices`
+ * messages are cloned via {@link cloneMessage}.
+ *
+ * @param entry The documentation entry to clone.
+ * @returns A structurally equal but referentially distinct copy.
+ * @since 1.0.0
+ */
+declare function cloneDocEntry(entry: DocEntry): DocEntry;
 /**
  * Configuration for customizing default value display formatting.
  *
@@ -291,4 +301,4 @@ interface DocPageFormatOptions {
  */
 declare function formatDocPage(programName: string, page: DocPage, options?: DocPageFormatOptions): string;
 //#endregion
-export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, formatDocPage };
+export { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, formatDocPage };

package/dist/doc.js

@@ -1,8 +1,25 @@
-import { formatMessage, text } from "./message.js";
-import { formatUsage, formatUsageTerm } from "./usage.js";
+import { cloneMessage, formatMessage, text } from "./message.js";
+import { cloneUsageTerm, formatUsage, formatUsageTerm } from "./usage.js";
 
 //#region src/doc.ts
 /**
+* Creates a deep clone of a {@link DocEntry}.  The `term` is cloned via
+* {@link cloneUsageTerm}, and `description`, `default`, and `choices`
+* messages are cloned via {@link cloneMessage}.
+*
+* @param entry The documentation entry to clone.
+* @returns A structurally equal but referentially distinct copy.
+* @since 1.0.0
+*/
+function cloneDocEntry(entry) {
+	return {
+		term: cloneUsageTerm(entry.term),
+		...entry.description != null && { description: cloneMessage(entry.description) },
+		...entry.default != null && { default: cloneMessage(entry.default) },
+		...entry.choices != null && { choices: cloneMessage(entry.choices) }
+	};
+}
+/**
 * Classifies a {@link DocSection} by its content type for use in the
 * default smart sort.
 *
@@ -327,4 +344,4 @@ function lastLineVisibleLength(text$1) {
 }
 
 //#endregion
-export { formatDocPage };
+export { cloneDocEntry, formatDocPage };

package/dist/index.cjs

@@ -23,6 +23,9 @@ exports.checkBooleanOption = require_valueparser.checkBooleanOption;
 exports.checkEnumOption = require_valueparser.checkEnumOption;
 exports.choice = require_valueparser.choice;
 exports.cidr = require_valueparser.cidr;
+exports.cloneDocEntry = require_doc.cloneDocEntry;
+exports.cloneUsage = require_usage.cloneUsage;
+exports.cloneUsageTerm = require_usage.cloneUsageTerm;
 exports.command = require_primitives.command;
 exports.commandLine = require_message.commandLine;
 exports.concat = require_constructs.concat;

package/dist/index.d.cts

@@ -1,8 +1,8 @@
 import { Annotations, ParseOptions, annotationKey, getAnnotations } from "./annotations.cjs";
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.cjs";
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.cjs";
-import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.cjs";
-import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, formatDocPage } from "./doc.cjs";
+import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.cjs";
+import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, formatDocPage } from "./doc.cjs";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.cjs";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.cjs";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
@@ -12,4 +12,4 @@ import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, Mode
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { ParserValuePlaceholder, SourceContext } from "./context.cjs";
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { Annotations, ParseOptions, annotationKey, getAnnotations } from "./annotations.js";
 import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
-import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
-import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, formatDocPage } from "./doc.js";
+import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
+import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, formatDocPage } from "./doc.js";
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, DomainOptions, EmailOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.js";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
@@ -12,4 +12,4 @@ import { CombineModes, DocState, InferMode, InferValue, Mode, ModeIterable, Mode
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { ParserValuePlaceholder, SourceContext } from "./context.js";
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredParseState, DependencyError, DependencyMode, DependencyRegistry, DependencySource, DependencySourceState, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExtractRequiredOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PendingDependencySourceState, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, ResolvedDependency, Result, RunOptions, RunParserError, RunWithOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/index.js

@@ -2,9 +2,9 @@ import { annotationKey, getAnnotations } from "./annotations.js";
 import { commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { DependencyRegistry, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, formatDependencyError, getDefaultValuesFunction, getDependencyIds, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isPendingDependencySourceState, isWrappedDependencySource, parseWithDependency, pendingDependencySourceStateMarker, suggestWithDependency, transformsDependencyValue, transformsDependencyValueMarker, wrappedDependencySourceMarker } from "./dependency.js";
-import { extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
+import { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
-import { formatDocPage } from "./doc.js";
+import { cloneDocEntry, formatDocPage } from "./doc.js";
 import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 import { checkBooleanOption, checkEnumOption, choice, cidr, domain, email, float, hostname, integer, ip, ipv4, ipv6, isValueParser, locale, macAddress, port, portRange, socketAddress, string, url, uuid } from "./valueparser.js";
@@ -12,4 +12,4 @@ import { argument, command, constant, fail, flag, option, passThrough } from "./
 import { getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./parser.js";
 import { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 
-export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };
+export { DependencyRegistry, DuplicateOptionError, RunParserError, WithDefaultError, annotationKey, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, command, commandLine, concat, conditional, constant, createDeferredParseState, createDependencySourceState, createPendingDependencySourceState, defaultValues, deferredParseMarker, dependency, dependencyId, dependencyIds, dependencySourceMarker, dependencySourceStateMarker, deriveFrom, deriveFromAsync, deriveFromSync, derivedValueParserMarker, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractOptionNames, fail, fish, flag, float, formatDependencyError, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDefaultValuesFunction, getDependencyIds, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDeferredParseState, isDependencySource, isDependencySourceState, isDerivedValueParser, isDocHidden, isNonEmptyString, isPendingDependencySourceState, isSuggestionHidden, isUsageHidden, isValueParser, isWrappedDependencySource, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, parseWithDependency, passThrough, pendingDependencySourceStateMarker, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, socketAddress, string, suggest, suggestAsync, suggestSync, suggestWithDependency, text, transformsDependencyValue, transformsDependencyValueMarker, tuple, url, uuid, value, valueSet, values, withDefault, wrappedDependencySourceMarker, zsh };

package/dist/message.cjs

@@ -1,6 +1,44 @@
 
 //#region src/message.ts
 /**
+* Creates a deep clone of a {@link MessageTerm}.  Most variants contain only
+* primitive fields and are cloned via object spread.  The `url` variant
+* receives a new `URL` object (since `structuredClone` cannot handle `URL`
+* on Node.js), and array-valued fields (`optionNames`, `values`) are
+* shallow-copied.
+*
+* @param term The message term to clone.
+* @returns A structurally equal but referentially distinct copy.
+* @since 1.0.0
+*/
+function cloneMessageTerm(term) {
+	switch (term.type) {
+		case "optionNames": return {
+			...term,
+			optionNames: [...term.optionNames]
+		};
+		case "values": return {
+			...term,
+			values: [...term.values]
+		};
+		case "url": return {
+			type: "url",
+			url: new URL(term.url.href)
+		};
+		default: return { ...term };
+	}
+}
+/**
+* Creates a deep clone of a {@link Message} array and all of its terms.
+*
+* @param msg The message to clone.
+* @returns A structurally equal but referentially distinct copy.
+* @since 1.0.0
+*/
+function cloneMessage(msg) {
+	return msg.map(cloneMessageTerm);
+}
+/**
 * Creates a structured message with template strings and values.
 *
 * This function allows creating messages where specific values can be
@@ -386,6 +424,8 @@ function formatMessage(msg, options = {}) {
 }
 
 //#endregion
+exports.cloneMessage = cloneMessage;
+exports.cloneMessageTerm = cloneMessageTerm;
 exports.commandLine = commandLine;
 exports.envVar = envVar;
 exports.formatMessage = formatMessage;

package/dist/message.d.cts

@@ -151,6 +151,26 @@ type MessageTerm =
  * displayed to the user with specific formatting.
  */
 type Message = readonly MessageTerm[];
+/**
+ * Creates a deep clone of a {@link MessageTerm}.  Most variants contain only
+ * primitive fields and are cloned via object spread.  The `url` variant
+ * receives a new `URL` object (since `structuredClone` cannot handle `URL`
+ * on Node.js), and array-valued fields (`optionNames`, `values`) are
+ * shallow-copied.
+ *
+ * @param term The message term to clone.
+ * @returns A structurally equal but referentially distinct copy.
+ * @since 1.0.0
+ */
+declare function cloneMessageTerm(term: MessageTerm): MessageTerm;
+/**
+ * Creates a deep clone of a {@link Message} array and all of its terms.
+ *
+ * @param msg The message to clone.
+ * @returns A structurally equal but referentially distinct copy.
+ * @since 1.0.0
+ */
+declare function cloneMessage(msg: Message): Message;
 /**
  * Creates a structured message with template strings and values.
  *
@@ -380,4 +400,4 @@ interface MessageFormatOptions {
  */
 declare function formatMessage(msg: Message, options?: MessageFormatOptions): string;
 //#endregion
-export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };
+export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, cloneMessage, cloneMessageTerm, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };

package/dist/message.d.ts

@@ -151,6 +151,26 @@ type MessageTerm =
  * displayed to the user with specific formatting.
  */
 type Message = readonly MessageTerm[];
+/**
+ * Creates a deep clone of a {@link MessageTerm}.  Most variants contain only
+ * primitive fields and are cloned via object spread.  The `url` variant
+ * receives a new `URL` object (since `structuredClone` cannot handle `URL`
+ * on Node.js), and array-valued fields (`optionNames`, `values`) are
+ * shallow-copied.
+ *
+ * @param term The message term to clone.
+ * @returns A structurally equal but referentially distinct copy.
+ * @since 1.0.0
+ */
+declare function cloneMessageTerm(term: MessageTerm): MessageTerm;
+/**
+ * Creates a deep clone of a {@link Message} array and all of its terms.
+ *
+ * @param msg The message to clone.
+ * @returns A structurally equal but referentially distinct copy.
+ * @since 1.0.0
+ */
+declare function cloneMessage(msg: Message): Message;
 /**
  * Creates a structured message with template strings and values.
  *
@@ -380,4 +400,4 @@ interface MessageFormatOptions {
  */
 declare function formatMessage(msg: Message, options?: MessageFormatOptions): string;
 //#endregion
-export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };
+export { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, cloneMessage, cloneMessageTerm, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };

package/dist/message.js

@@ -1,5 +1,43 @@
 //#region src/message.ts
 /**
+* Creates a deep clone of a {@link MessageTerm}.  Most variants contain only
+* primitive fields and are cloned via object spread.  The `url` variant
+* receives a new `URL` object (since `structuredClone` cannot handle `URL`
+* on Node.js), and array-valued fields (`optionNames`, `values`) are
+* shallow-copied.
+*
+* @param term The message term to clone.
+* @returns A structurally equal but referentially distinct copy.
+* @since 1.0.0
+*/
+function cloneMessageTerm(term) {
+	switch (term.type) {
+		case "optionNames": return {
+			...term,
+			optionNames: [...term.optionNames]
+		};
+		case "values": return {
+			...term,
+			values: [...term.values]
+		};
+		case "url": return {
+			type: "url",
+			url: new URL(term.url.href)
+		};
+		default: return { ...term };
+	}
+}
+/**
+* Creates a deep clone of a {@link Message} array and all of its terms.
+*
+* @param msg The message to clone.
+* @returns A structurally equal but referentially distinct copy.
+* @since 1.0.0
+*/
+function cloneMessage(msg) {
+	return msg.map(cloneMessageTerm);
+}
+/**
 * Creates a structured message with template strings and values.
 *
 * This function allows creating messages where specific values can be
@@ -385,4 +423,4 @@ function formatMessage(msg, options = {}) {
 }
 
 //#endregion
-export { commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };
+export { cloneMessage, cloneMessageTerm, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, url, value, valueSet, values };

package/dist/parser.cjs

@@ -3,6 +3,7 @@ const require_message = require('./message.cjs');
 const require_mode_dispatch = require('./mode-dispatch.cjs');
 const require_usage = require('./usage.cjs');
 const require_constructs = require('./constructs.cjs');
+const require_doc = require('./doc.cjs');
 const require_modifiers = require('./modifiers.cjs');
 const require_primitives = require('./primitives.cjs');
 
@@ -388,13 +389,13 @@ function buildDocPage(parser, context, args) {
 			untitledSection = { entries: [] };
 			buildingSections.push(untitledSection);
 		}
-		untitledSection.entries.push(fragment);
+		untitledSection.entries.push(require_doc.cloneDocEntry(fragment));
 	} else if (fragment.type === "section") if (fragment.title == null) {
 		if (untitledSection == null) {
 			untitledSection = { entries: [] };
 			buildingSections.push(untitledSection);
 		}
-		untitledSection.entries.push(...fragment.entries);
+		untitledSection.entries.push(...fragment.entries.map(require_doc.cloneDocEntry));
 	} else {
 		let section = titledSectionMap.get(fragment.title);
 		if (section == null) {
@@ -405,15 +406,15 @@ function buildDocPage(parser, context, args) {
 			titledSectionMap.set(fragment.title, section);
 			buildingSections.push(section);
 		}
-		section.entries.push(...fragment.entries);
+		section.entries.push(...fragment.entries.map(require_doc.cloneDocEntry));
 	}
 	const sections = buildingSections;
-	const usage = [...require_usage.normalizeUsage(parser.usage)];
+	const usage = require_usage.cloneUsage(require_usage.normalizeUsage(parser.usage));
 	const maybeApplyCommandUsageLine = (term, arg, isLastArg, usageIndex) => {
 		if (term?.type !== "command" || term.name !== arg || !isLastArg || term.usageLine == null) return;
-		const defaultUsageLine = usage.slice(usageIndex + 1);
+		const defaultUsageLine = require_usage.cloneUsage(usage.slice(usageIndex + 1));
 		const customUsageLine = typeof term.usageLine === "function" ? term.usageLine(defaultUsageLine) : term.usageLine;
-		const normalizedCustomUsageLine = require_usage.normalizeUsage(customUsageLine);
+		const normalizedCustomUsageLine = require_usage.cloneUsage(require_usage.normalizeUsage(customUsageLine));
 		usage.splice(usageIndex + 1, usage.length - (usageIndex + 1), ...normalizedCustomUsageLine);
 	};
 	let i = 0;
@@ -434,17 +435,18 @@ function buildDocPage(parser, context, args) {
 	if (effectiveArgs.length === 0 && usage.length > 0) {
 		const first = usage[0];
 		if (first.type === "command" && first.usageLine != null) {
-			const defaultUsageLine = usage.slice(1);
+			const defaultUsageLine = require_usage.cloneUsage(usage.slice(1));
 			const customUsageLine = typeof first.usageLine === "function" ? first.usageLine(defaultUsageLine) : first.usageLine;
-			usage.splice(1, usage.length - 1, ...require_usage.normalizeUsage(customUsageLine));
+			const normalizedCustomUsageLine = require_usage.cloneUsage(require_usage.normalizeUsage(customUsageLine));
+			usage.splice(1, usage.length - 1, ...normalizedCustomUsageLine);
 		}
 	}
 	return {
 		usage,
 		sections,
-		...brief != null && { brief },
-		...description != null && { description },
-		...footer != null && { footer }
+		...brief != null && { brief: require_message.cloneMessage(brief) },
+		...description != null && { description: require_message.cloneMessage(description) },
+		...footer != null && { footer: require_message.cloneMessage(footer) }
 	};
 }
 

package/dist/parser.js

@@ -1,8 +1,9 @@
 import { injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./annotations.js";
-import { message } from "./message.js";
+import { cloneMessage, message } from "./message.js";
 import { dispatchByMode } from "./mode-dispatch.js";
-import { normalizeUsage } from "./usage.js";
+import { cloneUsage, normalizeUsage } from "./usage.js";
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, tuple } from "./constructs.js";
+import { cloneDocEntry } from "./doc.js";
 import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { argument, command, constant, fail, flag, option, passThrough } from "./primitives.js";
 
@@ -388,13 +389,13 @@ function buildDocPage(parser, context, args) {
 			untitledSection = { entries: [] };
 			buildingSections.push(untitledSection);
 		}
-		untitledSection.entries.push(fragment);
+		untitledSection.entries.push(cloneDocEntry(fragment));
 	} else if (fragment.type === "section") if (fragment.title == null) {
 		if (untitledSection == null) {
 			untitledSection = { entries: [] };
 			buildingSections.push(untitledSection);
 		}
-		untitledSection.entries.push(...fragment.entries);
+		untitledSection.entries.push(...fragment.entries.map(cloneDocEntry));
 	} else {
 		let section = titledSectionMap.get(fragment.title);
 		if (section == null) {
@@ -405,15 +406,15 @@ function buildDocPage(parser, context, args) {
 			titledSectionMap.set(fragment.title, section);
 			buildingSections.push(section);
 		}
-		section.entries.push(...fragment.entries);
+		section.entries.push(...fragment.entries.map(cloneDocEntry));
 	}
 	const sections = buildingSections;
-	const usage = [...normalizeUsage(parser.usage)];
+	const usage = cloneUsage(normalizeUsage(parser.usage));
 	const maybeApplyCommandUsageLine = (term, arg, isLastArg, usageIndex) => {
 		if (term?.type !== "command" || term.name !== arg || !isLastArg || term.usageLine == null) return;
-		const defaultUsageLine = usage.slice(usageIndex + 1);
+		const defaultUsageLine = cloneUsage(usage.slice(usageIndex + 1));
 		const customUsageLine = typeof term.usageLine === "function" ? term.usageLine(defaultUsageLine) : term.usageLine;
-		const normalizedCustomUsageLine = normalizeUsage(customUsageLine);
+		const normalizedCustomUsageLine = cloneUsage(normalizeUsage(customUsageLine));
 		usage.splice(usageIndex + 1, usage.length - (usageIndex + 1), ...normalizedCustomUsageLine);
 	};
 	let i = 0;
@@ -434,17 +435,18 @@ function buildDocPage(parser, context, args) {
 	if (effectiveArgs.length === 0 && usage.length > 0) {
 		const first = usage[0];
 		if (first.type === "command" && first.usageLine != null) {
-			const defaultUsageLine = usage.slice(1);
+			const defaultUsageLine = cloneUsage(usage.slice(1));
 			const customUsageLine = typeof first.usageLine === "function" ? first.usageLine(defaultUsageLine) : first.usageLine;
-			usage.splice(1, usage.length - 1, ...normalizeUsage(customUsageLine));
+			const normalizedCustomUsageLine = cloneUsage(normalizeUsage(customUsageLine));
+			usage.splice(1, usage.length - 1, ...normalizedCustomUsageLine);
 		}
 	}
 	return {
 		usage,
 		sections,
-		...brief != null && { brief },
-		...description != null && { description },
-		...footer != null && { footer }
+		...brief != null && { brief: cloneMessage(brief) },
+		...description != null && { description: cloneMessage(description) },
+		...footer != null && { footer: cloneMessage(footer) }
 	};
 }
 

package/dist/usage.cjs

@@ -237,6 +237,59 @@ function normalizeUsageTerm(term) {
 		};
 	} else return term;
 }
+/**
+* Creates a deep clone of a single {@link UsageTerm}.  Recursive term
+* variants (`optional`, `multiple`, `exclusive`) are cloned recursively.
+* For `command` terms, a function-valued `usageLine` is preserved by
+* reference (functions are stateless callbacks), while an array-valued
+* `usageLine` is deep-cloned.
+*
+* @param term The usage term to clone.
+* @returns A structurally equal but referentially distinct copy.
+* @since 1.0.0
+*/
+function cloneUsageTerm(term) {
+	switch (term.type) {
+		case "argument": return { ...term };
+		case "option": return {
+			...term,
+			names: [...term.names]
+		};
+		case "command": {
+			if (term.usageLine == null || typeof term.usageLine === "function") return { ...term };
+			return {
+				...term,
+				usageLine: term.usageLine.map(cloneUsageTerm)
+			};
+		}
+		case "optional": return {
+			type: "optional",
+			terms: term.terms.map(cloneUsageTerm)
+		};
+		case "multiple": return {
+			type: "multiple",
+			terms: term.terms.map(cloneUsageTerm),
+			min: term.min
+		};
+		case "exclusive": return {
+			type: "exclusive",
+			terms: term.terms.map((u) => u.map(cloneUsageTerm))
+		};
+		case "literal":
+		case "passthrough":
+		case "ellipsis": return { ...term };
+	}
+}
+/**
+* Creates a deep clone of a {@link Usage} array and all of its terms.
+*
+* @param usage The usage array to clone.
+* @returns A mutable array of deeply cloned usage terms.
+* @since 1.0.0
+*/
+function cloneUsage(usage) {
+	return usage.map(cloneUsageTerm);
+}
 function filterUsageForDisplay(usage, isHidden = isUsageHidden) {
 	const terms = [];
 	for (const term of usage) {
@@ -433,6 +486,8 @@ function* formatUsageTermInternal(term, options) {
 }
 
 //#endregion
+exports.cloneUsage = cloneUsage;
+exports.cloneUsageTerm = cloneUsageTerm;
 exports.extractArgumentMetavars = extractArgumentMetavars;
 exports.extractCommandNames = extractCommandNames;
 exports.extractOptionNames = extractOptionNames;

package/dist/usage.d.cts

@@ -347,6 +347,26 @@ declare function formatUsage(programName: string, usage: Usage, options?: UsageF
  *          and terms sorted for optimal readability.
  */
 declare function normalizeUsage(usage: Usage): Usage;
+/**
+ * Creates a deep clone of a single {@link UsageTerm}.  Recursive term
+ * variants (`optional`, `multiple`, `exclusive`) are cloned recursively.
+ * For `command` terms, a function-valued `usageLine` is preserved by
+ * reference (functions are stateless callbacks), while an array-valued
+ * `usageLine` is deep-cloned.
+ *
+ * @param term The usage term to clone.
+ * @returns A structurally equal but referentially distinct copy.
+ * @since 1.0.0
+ */
+declare function cloneUsageTerm(term: UsageTerm): UsageTerm;
+/**
+ * Creates a deep clone of a {@link Usage} array and all of its terms.
+ *
+ * @param usage The usage array to clone.
+ * @returns A mutable array of deeply cloned usage terms.
+ * @since 1.0.0
+ */
+declare function cloneUsage(usage: Usage): UsageTerm[];
 /**
  * Options for formatting a single {@link UsageTerm}.
  */
@@ -378,4 +398,4 @@ interface UsageTermFormatOptions extends UsageFormatOptions {
  */
 declare function formatUsageTerm(term: UsageTerm, options?: UsageTermFormatOptions): string;
 //#endregion
-export { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };
+export { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };

package/dist/usage.d.ts

@@ -347,6 +347,26 @@ declare function formatUsage(programName: string, usage: Usage, options?: UsageF
  *          and terms sorted for optimal readability.
  */
 declare function normalizeUsage(usage: Usage): Usage;
+/**
+ * Creates a deep clone of a single {@link UsageTerm}.  Recursive term
+ * variants (`optional`, `multiple`, `exclusive`) are cloned recursively.
+ * For `command` terms, a function-valued `usageLine` is preserved by
+ * reference (functions are stateless callbacks), while an array-valued
+ * `usageLine` is deep-cloned.
+ *
+ * @param term The usage term to clone.
+ * @returns A structurally equal but referentially distinct copy.
+ * @since 1.0.0
+ */
+declare function cloneUsageTerm(term: UsageTerm): UsageTerm;
+/**
+ * Creates a deep clone of a {@link Usage} array and all of its terms.
+ *
+ * @param usage The usage array to clone.
+ * @returns A mutable array of deeply cloned usage terms.
+ * @since 1.0.0
+ */
+declare function cloneUsage(usage: Usage): UsageTerm[];
 /**
  * Options for formatting a single {@link UsageTerm}.
  */
@@ -378,4 +398,4 @@ interface UsageTermFormatOptions extends UsageFormatOptions {
  */
 declare function formatUsageTerm(term: UsageTerm, options?: UsageTermFormatOptions): string;
 //#endregion
-export { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };
+export { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };

package/dist/usage.js

@@ -236,6 +236,59 @@ function normalizeUsageTerm(term) {
 		};
 	} else return term;
 }
+/**
+* Creates a deep clone of a single {@link UsageTerm}.  Recursive term
+* variants (`optional`, `multiple`, `exclusive`) are cloned recursively.
+* For `command` terms, a function-valued `usageLine` is preserved by
+* reference (functions are stateless callbacks), while an array-valued
+* `usageLine` is deep-cloned.
+*
+* @param term The usage term to clone.
+* @returns A structurally equal but referentially distinct copy.
+* @since 1.0.0
+*/
+function cloneUsageTerm(term) {
+	switch (term.type) {
+		case "argument": return { ...term };
+		case "option": return {
+			...term,
+			names: [...term.names]
+		};
+		case "command": {
+			if (term.usageLine == null || typeof term.usageLine === "function") return { ...term };
+			return {
+				...term,
+				usageLine: term.usageLine.map(cloneUsageTerm)
+			};
+		}
+		case "optional": return {
+			type: "optional",
+			terms: term.terms.map(cloneUsageTerm)
+		};
+		case "multiple": return {
+			type: "multiple",
+			terms: term.terms.map(cloneUsageTerm),
+			min: term.min
+		};
+		case "exclusive": return {
+			type: "exclusive",
+			terms: term.terms.map((u) => u.map(cloneUsageTerm))
+		};
+		case "literal":
+		case "passthrough":
+		case "ellipsis": return { ...term };
+	}
+}
+/**
+* Creates a deep clone of a {@link Usage} array and all of its terms.
+*
+* @param usage The usage array to clone.
+* @returns A mutable array of deeply cloned usage terms.
+* @since 1.0.0
+*/
+function cloneUsage(usage) {
+	return usage.map(cloneUsageTerm);
+}
 function filterUsageForDisplay(usage, isHidden = isUsageHidden) {
 	const terms = [];
 	for (const term of usage) {
@@ -432,4 +485,4 @@ function* formatUsageTermInternal(term, options) {
 }
 
 //#endregion
-export { extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };
+export { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1315+171b6980",
+  "version": "1.0.0-dev.1326+40fd572e",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",