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

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.1323+0653ad71",
+  "version": "1.0.0-dev.1326+40fd572e",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",