@optique/core 1.2.0-dev.2180 → 1.2.0-dev.2187

package/dist/index.d.ts

@@ -6,10 +6,10 @@ import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, Doc
 import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid } from "./valueparser.js";
 import { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
+import { FluentParser, MultipleErrorOptions, MultipleOptions, ParserModifiers, WithDefaultError, WithDefaultOptions, fluent, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, SeqOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, seq, tuple } from "./constructs.js";
 import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./context.js";
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
-import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, FluentParser, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.js

@@ -5,11 +5,11 @@ import { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDo
 import { dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
 import { createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
 import { bash, fish, nu, pwsh, zsh } from "./completion.js";
+import { WithDefaultError, fluent, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, seq, tuple } from "./constructs.js";
-import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
 import { checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, keyValue, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid } from "./valueparser.js";
 import { argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.js";
 import { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 
-export { DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, fluent, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, keyValue, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/modifiers.cjs

@@ -422,7 +422,7 @@ function optional(parser) {
 	}
 	require_internal_parser.defineInheritedAnnotationParser(optionalParser);
 	require_internal_parser.defineSourceBindingOnlyAnnotationCompletionParser(optionalParser);
-	return optionalParser;
+	return fluent(optionalParser);
 }
 /**
 * Error type for structured error messages in {@link withDefault} default value callbacks.
@@ -656,7 +656,7 @@ function withDefault(parser, defaultValue, options) {
 	}
 	require_internal_parser.defineInheritedAnnotationParser(withDefaultParser);
 	require_internal_parser.defineSourceBindingOnlyAnnotationCompletionParser(withDefaultParser);
-	return withDefaultParser;
+	return fluent(withDefaultParser);
 }
 /**
 * Creates a parser that transforms the result value of another parser using
@@ -843,7 +843,7 @@ function map(parser, transform) {
 		}
 		if (composed != null) mappedParser.dependencyMetadata = composed;
 	}
-	return mappedParser;
+	return fluent(mappedParser);
 }
 /**
 * Creates a parser that allows multiple occurrences of a given parser.
@@ -1467,7 +1467,7 @@ function multiple(parser, options = {}) {
 			enumerable: false
 		});
 	}
-	return resultParser;
+	return fluent(resultParser);
 }
 /**
 * Creates a parser that requires the wrapped parser to consume at least one
@@ -1585,11 +1585,72 @@ function nonEmpty(parser) {
 		configurable: true,
 		enumerable: false
 	});
-	return nonEmptyParser;
+	return fluent(nonEmptyParser);
+}
+const fluentParserMarker = Symbol.for("@optique/core/fluent");
+/**
+* Decorates a parser with fluent modifier methods.
+*
+* The parser object is returned unchanged when it already has fluent methods.
+* Otherwise, the methods are defined as non-enumerable properties so object
+* spread and structural parser cloning continue to copy only parser data.
+*
+* @param parser The parser to decorate.
+* @returns The same parser object with fluent modifier methods.
+* @throws {TypeError} If the parser object is frozen and cannot be decorated.
+* @since 1.2.0
+*/
+function fluent(parser) {
+	const fluentParser = parser;
+	if (fluentParserMarker in fluentParser) return fluentParser;
+	Object.defineProperties(fluentParser, {
+		[fluentParserMarker]: {
+			value: true,
+			configurable: true,
+			enumerable: false
+		},
+		map: {
+			value(transform) {
+				return map(parser, transform);
+			},
+			configurable: true,
+			enumerable: false
+		},
+		optional: {
+			value() {
+				return optional(parser);
+			},
+			configurable: true,
+			enumerable: false
+		},
+		withDefault: {
+			value(defaultValue, options) {
+				return withDefault(parser, defaultValue, options);
+			},
+			configurable: true,
+			enumerable: false
+		},
+		multiple: {
+			value(options) {
+				return multiple(parser, options);
+			},
+			configurable: true,
+			enumerable: false
+		},
+		nonEmpty: {
+			value() {
+				return nonEmpty(parser);
+			},
+			configurable: true,
+			enumerable: false
+		}
+	});
+	return fluentParser;
 }
 
 //#endregion
 exports.WithDefaultError = WithDefaultError;
+exports.fluent = fluent;
 exports.map = map;
 exports.multiple = multiple;
 exports.nonEmpty = nonEmpty;

package/dist/modifiers.d.cts

@@ -15,7 +15,7 @@ import { Mode, Parser } from "./internal/parser.cjs";
  * @returns A {@link Parser} that produces either the result of the wrapped parser
  *          or `undefined` if the wrapped parser fails to match.
  */
-declare function optional<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>): Parser<M, TValue | undefined, [TState] | undefined>;
+declare function optional<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>): FluentParser<M, TValue | undefined, [TState] | undefined>;
 /**
  * Options for the {@link withDefault} parser.
  */
@@ -83,7 +83,7 @@ declare class WithDefaultError extends Error {
  *          or the default value if the wrapped parser fails to match
  *          (union type {@link TValue} | {@link TDefault}).
  */
-declare function withDefault<M extends Mode, TValue, TState, const TDefault = TValue>(parser: Parser<M, TValue, TState>, defaultValue: TDefault | (() => TDefault)): Parser<M, TValue | TDefault, [TState] | undefined>;
+declare function withDefault<M extends Mode, TValue, TState, const TDefault = TValue>(parser: Parser<M, TValue, TState>, defaultValue: TDefault | (() => TDefault)): FluentParser<M, TValue | TDefault, [TState] | undefined>;
 /**
  * Creates a parser that makes another parser use a default value when it fails
  * to match or consume input. This is similar to {@link optional}, but instead
@@ -103,7 +103,7 @@ declare function withDefault<M extends Mode, TValue, TState, const TDefault = TV
  *          (union type {@link TValue} | {@link TDefault}).
  * @since 0.5.0
  */
-declare function withDefault<M extends Mode, TValue, TState, const TDefault = TValue>(parser: Parser<M, TValue, TState>, defaultValue: TDefault | (() => TDefault), options?: WithDefaultOptions): Parser<M, TValue | TDefault, [TState] | undefined>;
+declare function withDefault<M extends Mode, TValue, TState, const TDefault = TValue>(parser: Parser<M, TValue, TState>, defaultValue: TDefault | (() => TDefault), options?: WithDefaultOptions): FluentParser<M, TValue | TDefault, [TState] | undefined>;
 /**
  * Creates a parser that transforms the result value of another parser using
  * a mapping function. This enables value transformation while preserving
@@ -179,7 +179,7 @@ declare function withDefault<M extends Mode, TValue, TState, const TDefault = TV
  * const prefixedParser = map(option("-n", integer()), n => `value: ${n}`);
  * ```
  */
-declare function map<M extends Mode, T, U, TState>(parser: Parser<M, T, TState>, transform: (value: T) => U): Parser<M, U, TState>;
+declare function map<M extends Mode, T, U, TState>(parser: Parser<M, T, TState>, transform: (value: T) => U): FluentParser<M, U, TState>;
 /**
  * Options for the {@link multiple} parser.
  */
@@ -233,7 +233,7 @@ interface MultipleErrorOptions {
  *          of type {@link TValue} and an array of states
  *          of type {@link TState}.
  */
-declare function multiple<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, options?: MultipleOptions): Parser<M, readonly TValue[], readonly TState[]>;
+declare function multiple<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, options?: MultipleOptions): FluentParser<M, readonly TValue[], readonly TState[]>;
 /**
  * Creates a parser that requires the wrapped parser to consume at least one
  * input token to succeed. If the wrapped parser succeeds without consuming
@@ -271,6 +271,76 @@ declare function multiple<M extends Mode, TValue, TState>(parser: Parser<M, TVal
  *
  * @since 0.10.0
  */
-declare function nonEmpty<M extends Mode, T, TState>(parser: Parser<M, T, TState>): Parser<M, T, TState>;
+declare function nonEmpty<M extends Mode, T, TState>(parser: Parser<M, T, TState>): FluentParser<M, T, TState>;
+/**
+ * Method-style parser modifiers.
+ *
+ * These methods are a convenience layer over the standalone modifier
+ * functions.  They are intentionally separate from {@link Parser} so custom
+ * parser authors can keep implementing the smaller base parser contract.
+ *
+ * @template M The execution mode of the parser.
+ * @template TValue The parser result value.
+ * @template TState The parser state.
+ * @since 1.2.0
+ */
+interface ParserModifiers<M extends Mode = "sync", TValue = unknown, TState = unknown> {
+  /**
+   * Transforms the parsed value.
+   *
+   * @param transform Function that maps the parser value.
+   * @returns A parser that produces the mapped value.
+   */
+  map<U>(transform: (value: TValue) => U): FluentParser<M, U, TState>;
+  /**
+   * Makes this parser optional.
+   *
+   * @returns A parser that produces this parser's value or `undefined`.
+   */
+  optional(): FluentParser<M, TValue | undefined, [TState] | undefined>;
+  /**
+   * Supplies a default value when this parser does not match.
+   *
+   * @param defaultValue Value or factory used as the default.
+   * @param options Optional default display configuration.
+   * @returns A parser that produces this parser's value or the default value.
+   */
+  withDefault<const TDefault = TValue>(defaultValue: TDefault | (() => TDefault), options?: WithDefaultOptions): FluentParser<M, TValue | TDefault, [TState] | undefined>;
+  /**
+   * Allows this parser to match multiple times.
+   *
+   * @param options Optional occurrence constraints.
+   * @returns A parser that produces all matched values.
+   */
+  multiple(options?: MultipleOptions): FluentParser<M, readonly TValue[], readonly TState[]>;
+  /**
+   * Requires this parser to consume at least one token.
+   *
+   * @returns A parser with the same value and state types.
+   */
+  nonEmpty(): FluentParser<M, TValue, TState>;
+}
+/**
+ * A parser decorated with method-style modifier helpers.
+ *
+ * @template M The execution mode of the parser.
+ * @template TValue The parser result value.
+ * @template TState The parser state.
+ * @since 1.2.0
+ */
+type FluentParser<M extends Mode = "sync", TValue = unknown, TState = unknown> = Parser<M, TValue, TState> & ParserModifiers<M, TValue, TState>;
+/**
+ * Decorates a parser with fluent modifier methods.
+ *
+ * The parser object is returned unchanged when it already has fluent methods.
+ * Otherwise, the methods are defined as non-enumerable properties so object
+ * spread and structural parser cloning continue to copy only parser data.
+ *
+ * @param parser The parser to decorate.
+ * @returns The same parser object with fluent modifier methods.
+ * @throws {TypeError} If the parser object is frozen and cannot be decorated.
+ * @since 1.2.0
+ */
+declare function fluent<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>): FluentParser<M, TValue, TState>;
 //#endregion
-export { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault };
+export { FluentParser, MultipleErrorOptions, MultipleOptions, ParserModifiers, WithDefaultError, WithDefaultOptions, fluent, map, multiple, nonEmpty, optional, withDefault };

package/dist/modifiers.d.ts

@@ -15,7 +15,7 @@ import { Mode, Parser } from "./internal/parser.js";
  * @returns A {@link Parser} that produces either the result of the wrapped parser
  *          or `undefined` if the wrapped parser fails to match.
  */
-declare function optional<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>): Parser<M, TValue | undefined, [TState] | undefined>;
+declare function optional<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>): FluentParser<M, TValue | undefined, [TState] | undefined>;
 /**
  * Options for the {@link withDefault} parser.
  */
@@ -83,7 +83,7 @@ declare class WithDefaultError extends Error {
  *          or the default value if the wrapped parser fails to match
  *          (union type {@link TValue} | {@link TDefault}).
  */
-declare function withDefault<M extends Mode, TValue, TState, const TDefault = TValue>(parser: Parser<M, TValue, TState>, defaultValue: TDefault | (() => TDefault)): Parser<M, TValue | TDefault, [TState] | undefined>;
+declare function withDefault<M extends Mode, TValue, TState, const TDefault = TValue>(parser: Parser<M, TValue, TState>, defaultValue: TDefault | (() => TDefault)): FluentParser<M, TValue | TDefault, [TState] | undefined>;
 /**
  * Creates a parser that makes another parser use a default value when it fails
  * to match or consume input. This is similar to {@link optional}, but instead
@@ -103,7 +103,7 @@ declare function withDefault<M extends Mode, TValue, TState, const TDefault = TV
  *          (union type {@link TValue} | {@link TDefault}).
  * @since 0.5.0
  */
-declare function withDefault<M extends Mode, TValue, TState, const TDefault = TValue>(parser: Parser<M, TValue, TState>, defaultValue: TDefault | (() => TDefault), options?: WithDefaultOptions): Parser<M, TValue | TDefault, [TState] | undefined>;
+declare function withDefault<M extends Mode, TValue, TState, const TDefault = TValue>(parser: Parser<M, TValue, TState>, defaultValue: TDefault | (() => TDefault), options?: WithDefaultOptions): FluentParser<M, TValue | TDefault, [TState] | undefined>;
 /**
  * Creates a parser that transforms the result value of another parser using
  * a mapping function. This enables value transformation while preserving
@@ -179,7 +179,7 @@ declare function withDefault<M extends Mode, TValue, TState, const TDefault = TV
  * const prefixedParser = map(option("-n", integer()), n => `value: ${n}`);
  * ```
  */
-declare function map<M extends Mode, T, U, TState>(parser: Parser<M, T, TState>, transform: (value: T) => U): Parser<M, U, TState>;
+declare function map<M extends Mode, T, U, TState>(parser: Parser<M, T, TState>, transform: (value: T) => U): FluentParser<M, U, TState>;
 /**
  * Options for the {@link multiple} parser.
  */
@@ -233,7 +233,7 @@ interface MultipleErrorOptions {
  *          of type {@link TValue} and an array of states
  *          of type {@link TState}.
  */
-declare function multiple<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, options?: MultipleOptions): Parser<M, readonly TValue[], readonly TState[]>;
+declare function multiple<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, options?: MultipleOptions): FluentParser<M, readonly TValue[], readonly TState[]>;
 /**
  * Creates a parser that requires the wrapped parser to consume at least one
  * input token to succeed. If the wrapped parser succeeds without consuming
@@ -271,6 +271,76 @@ declare function multiple<M extends Mode, TValue, TState>(parser: Parser<M, TVal
  *
  * @since 0.10.0
  */
-declare function nonEmpty<M extends Mode, T, TState>(parser: Parser<M, T, TState>): Parser<M, T, TState>;
+declare function nonEmpty<M extends Mode, T, TState>(parser: Parser<M, T, TState>): FluentParser<M, T, TState>;
+/**
+ * Method-style parser modifiers.
+ *
+ * These methods are a convenience layer over the standalone modifier
+ * functions.  They are intentionally separate from {@link Parser} so custom
+ * parser authors can keep implementing the smaller base parser contract.
+ *
+ * @template M The execution mode of the parser.
+ * @template TValue The parser result value.
+ * @template TState The parser state.
+ * @since 1.2.0
+ */
+interface ParserModifiers<M extends Mode = "sync", TValue = unknown, TState = unknown> {
+  /**
+   * Transforms the parsed value.
+   *
+   * @param transform Function that maps the parser value.
+   * @returns A parser that produces the mapped value.
+   */
+  map<U>(transform: (value: TValue) => U): FluentParser<M, U, TState>;
+  /**
+   * Makes this parser optional.
+   *
+   * @returns A parser that produces this parser's value or `undefined`.
+   */
+  optional(): FluentParser<M, TValue | undefined, [TState] | undefined>;
+  /**
+   * Supplies a default value when this parser does not match.
+   *
+   * @param defaultValue Value or factory used as the default.
+   * @param options Optional default display configuration.
+   * @returns A parser that produces this parser's value or the default value.
+   */
+  withDefault<const TDefault = TValue>(defaultValue: TDefault | (() => TDefault), options?: WithDefaultOptions): FluentParser<M, TValue | TDefault, [TState] | undefined>;
+  /**
+   * Allows this parser to match multiple times.
+   *
+   * @param options Optional occurrence constraints.
+   * @returns A parser that produces all matched values.
+   */
+  multiple(options?: MultipleOptions): FluentParser<M, readonly TValue[], readonly TState[]>;
+  /**
+   * Requires this parser to consume at least one token.
+   *
+   * @returns A parser with the same value and state types.
+   */
+  nonEmpty(): FluentParser<M, TValue, TState>;
+}
+/**
+ * A parser decorated with method-style modifier helpers.
+ *
+ * @template M The execution mode of the parser.
+ * @template TValue The parser result value.
+ * @template TState The parser state.
+ * @since 1.2.0
+ */
+type FluentParser<M extends Mode = "sync", TValue = unknown, TState = unknown> = Parser<M, TValue, TState> & ParserModifiers<M, TValue, TState>;
+/**
+ * Decorates a parser with fluent modifier methods.
+ *
+ * The parser object is returned unchanged when it already has fluent methods.
+ * Otherwise, the methods are defined as non-enumerable properties so object
+ * spread and structural parser cloning continue to copy only parser data.
+ *
+ * @param parser The parser to decorate.
+ * @returns The same parser object with fluent modifier methods.
+ * @throws {TypeError} If the parser object is frozen and cannot be decorated.
+ * @since 1.2.0
+ */
+declare function fluent<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>): FluentParser<M, TValue, TState>;
 //#endregion
-export { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault };
+export { FluentParser, MultipleErrorOptions, MultipleOptions, ParserModifiers, WithDefaultError, WithDefaultOptions, fluent, map, multiple, nonEmpty, optional, withDefault };

package/dist/modifiers.js

@@ -422,7 +422,7 @@ function optional(parser) {
 	}
 	defineInheritedAnnotationParser(optionalParser);
 	defineSourceBindingOnlyAnnotationCompletionParser(optionalParser);
-	return optionalParser;
+	return fluent(optionalParser);
 }
 /**
 * Error type for structured error messages in {@link withDefault} default value callbacks.
@@ -656,7 +656,7 @@ function withDefault(parser, defaultValue, options) {
 	}
 	defineInheritedAnnotationParser(withDefaultParser);
 	defineSourceBindingOnlyAnnotationCompletionParser(withDefaultParser);
-	return withDefaultParser;
+	return fluent(withDefaultParser);
 }
 /**
 * Creates a parser that transforms the result value of another parser using
@@ -843,7 +843,7 @@ function map(parser, transform) {
 		}
 		if (composed != null) mappedParser.dependencyMetadata = composed;
 	}
-	return mappedParser;
+	return fluent(mappedParser);
 }
 /**
 * Creates a parser that allows multiple occurrences of a given parser.
@@ -1467,7 +1467,7 @@ function multiple(parser, options = {}) {
 			enumerable: false
 		});
 	}
-	return resultParser;
+	return fluent(resultParser);
 }
 /**
 * Creates a parser that requires the wrapped parser to consume at least one
@@ -1585,8 +1585,68 @@ function nonEmpty(parser) {
 		configurable: true,
 		enumerable: false
 	});
-	return nonEmptyParser;
+	return fluent(nonEmptyParser);
+}
+const fluentParserMarker = Symbol.for("@optique/core/fluent");
+/**
+* Decorates a parser with fluent modifier methods.
+*
+* The parser object is returned unchanged when it already has fluent methods.
+* Otherwise, the methods are defined as non-enumerable properties so object
+* spread and structural parser cloning continue to copy only parser data.
+*
+* @param parser The parser to decorate.
+* @returns The same parser object with fluent modifier methods.
+* @throws {TypeError} If the parser object is frozen and cannot be decorated.
+* @since 1.2.0
+*/
+function fluent(parser) {
+	const fluentParser = parser;
+	if (fluentParserMarker in fluentParser) return fluentParser;
+	Object.defineProperties(fluentParser, {
+		[fluentParserMarker]: {
+			value: true,
+			configurable: true,
+			enumerable: false
+		},
+		map: {
+			value(transform) {
+				return map(parser, transform);
+			},
+			configurable: true,
+			enumerable: false
+		},
+		optional: {
+			value() {
+				return optional(parser);
+			},
+			configurable: true,
+			enumerable: false
+		},
+		withDefault: {
+			value(defaultValue, options) {
+				return withDefault(parser, defaultValue, options);
+			},
+			configurable: true,
+			enumerable: false
+		},
+		multiple: {
+			value(options) {
+				return multiple(parser, options);
+			},
+			configurable: true,
+			enumerable: false
+		},
+		nonEmpty: {
+			value() {
+				return nonEmpty(parser);
+			},
+			configurable: true,
+			enumerable: false
+		}
+	});
+	return fluentParser;
 }
 
 //#endregion
-export { WithDefaultError, map, multiple, nonEmpty, optional, withDefault };
+export { WithDefaultError, fluent, map, multiple, nonEmpty, optional, withDefault };

package/dist/primitives.cjs

@@ -9,9 +9,10 @@ const require_annotation_state = require('./annotation-state.cjs');
 const require_command_alias = require('./internal/command-alias.cjs');
 const require_execution_context = require('./execution-context.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
+const require_dependency_metadata = require('./dependency-metadata.cjs');
+const require_modifiers = require('./modifiers.cjs');
 const require_suggestion = require('./suggestion.cjs');
 const require_usage_internals = require('./usage-internals.cjs');
-const require_dependency_metadata = require('./dependency-metadata.cjs');
 const require_valueparser = require('./valueparser.cjs');
 
 //#region src/primitives.ts
@@ -150,7 +151,7 @@ function constant(value) {
 		enumerable: false,
 		writable: false
 	});
-	return result;
+	return require_modifiers.fluent(result);
 }
 /**
 * Creates a parser that always fails without consuming any input.
@@ -172,7 +173,7 @@ function constant(value) {
 * @since 1.0.0
 */
 function fail() {
-	return {
+	return require_modifiers.fluent({
 		$valueType: [],
 		$stateType: [],
 		mode: "sync",
@@ -203,7 +204,7 @@ function fail() {
 		getDocFragments(_state, _defaultValue) {
 			return { fragments: [] };
 		}
-	};
+	});
 }
 /**
 * Internal helper to get suggestions from a value parser, using dependency values
@@ -741,7 +742,7 @@ function option(...args) {
 		configurable: true,
 		enumerable: false
 	});
-	return result;
+	return require_modifiers.fluent(result);
 }
 /**
 * Creates a parser for command-line flags that must be explicitly provided.
@@ -944,7 +945,7 @@ function flag(...args) {
 		enumerable: false,
 		writable: false
 	});
-	return result;
+	return require_modifiers.fluent(result);
 }
 function normalizeNegatableFlagNameList(names) {
 	return typeof names === "string" ? [names] : names;
@@ -1162,7 +1163,7 @@ function negatableFlag(names, options = {}) {
 		enumerable: false,
 		writable: false
 	});
-	return result;
+	return require_modifiers.fluent(result);
 }
 /**
 * Creates a parser that expects a single argument value.
@@ -1371,7 +1372,7 @@ function argument(valueParser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
-	return result;
+	return require_modifiers.fluent(result);
 }
 function normalizeCommandState(state) {
 	return require_annotation_state.normalizeInjectedAnnotationState(state);
@@ -1700,7 +1701,7 @@ function command(name, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
-	return result;
+	return require_modifiers.fluent(result);
 }
 /**
 * Creates a parser that collects unrecognized options and passes them through.
@@ -1752,7 +1753,7 @@ function passThrough(options = {}) {
 	const format = options.format ?? "equalsOnly";
 	const optionPattern = /^-[a-z0-9-]|^--[a-z0-9-]+/i;
 	const equalsOptionPattern = /^--[a-z0-9-]+=/i;
-	return {
+	const result = {
 		$valueType: [],
 		$stateType: [],
 		mode: "sync",
@@ -1884,6 +1885,7 @@ function passThrough(options = {}) {
 			return `passThrough(${format})`;
 		}
 	};
+	return require_modifiers.fluent(result);
 }
 
 //#endregion