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

package/dist/primitives.d.cts

@@ -2,6 +2,7 @@ import { Message } from "./message.cjs";
 import { HiddenVisibility, OptionName, Usage } from "./usage.cjs";
 import { ValueParser, ValueParserResult } from "./valueparser.cjs";
 import { Mode, Parser } from "./internal/parser.cjs";
+import { FluentParser } from "./modifiers.cjs";
 
 //#region src/primitives.d.ts
 /** @internal */
@@ -11,7 +12,7 @@ type OptionState<T> = ValueParserResult<T> | undefined;
  * produces a constant value of the type {@link T}.
  * @template T The type of the constant value produced by the parser.
  */
-declare function constant<const T>(value: T): Parser<"sync", T, T>;
+declare function constant<const T>(value: T): FluentParser<"sync", T, T>;
 /**
  * Creates a parser that always fails without consuming any input.
  *
@@ -31,7 +32,7 @@ declare function constant<const T>(value: T): Parser<"sync", T, T>;
  *          complete time.
  * @since 1.0.0
  */
-declare function fail<T>(): Parser<"sync", T, undefined>;
+declare function fail<T>(): FluentParser<"sync", T, undefined>;
 /**
  * Options for the {@link option} parser.
  */
@@ -113,7 +114,7 @@ interface OptionErrorOptions {
  * @returns A {@link Parser} that can parse the specified options and their
  *          values.
  */
-declare function option<M extends Mode, T>(...args: readonly [OptionName, ...readonly OptionName[], ValueParser<M, T>]): Parser<M, T, ValueParserResult<T> | undefined>;
+declare function option<M extends Mode, T>(...args: readonly [OptionName, ...readonly OptionName[], ValueParser<M, T>]): FluentParser<M, T, ValueParserResult<T> | undefined>;
 /**
  * Creates a parser for various styles of command-line options that take an
  * argument value, such as `--option=value`, `-option=value`, `-o value`,
@@ -127,7 +128,7 @@ declare function option<M extends Mode, T>(...args: readonly [OptionName, ...rea
  * @returns A {@link Parser} that can parse the specified options and their
  *          values.
  */
-declare function option<M extends Mode, T>(...args: readonly [OptionName, ...readonly OptionName[], ValueParser<M, T>, OptionOptions]): Parser<M, T, ValueParserResult<T> | undefined>;
+declare function option<M extends Mode, T>(...args: readonly [OptionName, ...readonly OptionName[], ValueParser<M, T>, OptionOptions]): FluentParser<M, T, ValueParserResult<T> | undefined>;
 /**
  * Creates a parser for various styles of command-line options that do not
  * take an argument value, such as `--option`, `-o`, or `/option`.
@@ -135,7 +136,7 @@ declare function option<M extends Mode, T>(...args: readonly [OptionName, ...rea
  * @return A {@link Parser} that can parse the specified options as Boolean
  *         flags, producing `true` if the option is present.
  */
-declare function option(...optionNames: readonly [OptionName, ...readonly OptionName[]]): Parser<"sync", boolean, ValueParserResult<boolean> | undefined>;
+declare function option(...optionNames: readonly [OptionName, ...readonly OptionName[]]): FluentParser<"sync", boolean, ValueParserResult<boolean> | undefined>;
 /**
  * Creates a parser for various styles of command-line options that take an
  * argument value, such as `--option=value`, `-option=value`, `-o value`,
@@ -146,7 +147,7 @@ declare function option(...optionNames: readonly [OptionName, ...readonly Option
  * @returns A {@link Parser} that can parse the specified options and their
  *          values.
  */
-declare function option(...args: readonly [OptionName, ...readonly OptionName[], OptionOptions]): Parser<"sync", boolean, ValueParserResult<boolean> | undefined>;
+declare function option(...args: readonly [OptionName, ...readonly OptionName[], OptionOptions]): FluentParser<"sync", boolean, ValueParserResult<boolean> | undefined>;
 /**
  * Options for the {@link flag} parser.
  */
@@ -236,7 +237,7 @@ interface FlagErrorOptions {
  * });
  * ```
  */
-declare function flag(...args: readonly [OptionName, ...readonly OptionName[], FlagOptions] | readonly [OptionName, ...readonly OptionName[]]): Parser<"sync", true, ValueParserResult<true> | undefined>;
+declare function flag(...args: readonly [OptionName, ...readonly OptionName[], FlagOptions] | readonly [OptionName, ...readonly OptionName[]]): FluentParser<"sync", true, ValueParserResult<true> | undefined>;
 /**
  * A non-empty list of option names, or a single option name.
  * @since 1.1.0
@@ -340,7 +341,7 @@ interface NegatableFlagState {
  *         side, or shared by the positive and negative sides.
  * @since 1.1.0
  */
-declare function negatableFlag(names: NegatableFlagNames, options?: NegatableFlagOptions): Parser<"sync", boolean, NegatableFlagState | undefined>;
+declare function negatableFlag(names: NegatableFlagNames, options?: NegatableFlagOptions): FluentParser<"sync", boolean, NegatableFlagState | undefined>;
 /**
  * Options for the {@link argument} parser.
  */
@@ -399,7 +400,7 @@ interface ArgumentErrorOptions {
  * @returns A {@link Parser} that expects a single argument value and produces
  *          the parsed value of type {@link T}.
  */
-declare function argument<M extends Mode, T>(valueParser: ValueParser<M, T>, options?: ArgumentOptions): Parser<M, T, ValueParserResult<T> | undefined>;
+declare function argument<M extends Mode, T>(valueParser: ValueParser<M, T>, options?: ArgumentOptions): FluentParser<M, T, ValueParserResult<T> | undefined>;
 /**
  * Options for the {@link command} parser.
  * @since 0.5.0
@@ -507,7 +508,7 @@ type CommandState<TState> = undefined | ["matched", string] | ["parsing", TState
  * @throws {TypeError} If `name` is empty, whitespace-only, contains
  *         embedded whitespace, or contains control characters.
  */
-declare function command<M extends Mode, T, TState>(name: string, parser: Parser<M, T, TState>, options?: CommandOptions): Parser<M, T, CommandState<TState>>;
+declare function command<M extends Mode, T, TState>(name: string, parser: Parser<M, T, TState>, options?: CommandOptions): FluentParser<M, T, CommandState<TState>>;
 /**
  * Format options for how {@link passThrough} captures options.
  * @since 0.8.0
@@ -595,6 +596,6 @@ interface PassThroughOptions {
  *
  * @since 0.8.0
  */
-declare function passThrough(options?: PassThroughOptions): Parser<"sync", readonly string[], readonly string[]>;
+declare function passThrough(options?: PassThroughOptions): FluentParser<"sync", readonly string[], readonly string[]>;
 //#endregion
 export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough };

package/dist/primitives.d.ts

@@ -2,6 +2,7 @@ import { Message } from "./message.js";
 import { HiddenVisibility, OptionName, Usage } from "./usage.js";
 import { ValueParser, ValueParserResult } from "./valueparser.js";
 import { Mode, Parser } from "./internal/parser.js";
+import { FluentParser } from "./modifiers.js";
 
 //#region src/primitives.d.ts
 /** @internal */
@@ -11,7 +12,7 @@ type OptionState<T> = ValueParserResult<T> | undefined;
  * produces a constant value of the type {@link T}.
  * @template T The type of the constant value produced by the parser.
  */
-declare function constant<const T>(value: T): Parser<"sync", T, T>;
+declare function constant<const T>(value: T): FluentParser<"sync", T, T>;
 /**
  * Creates a parser that always fails without consuming any input.
  *
@@ -31,7 +32,7 @@ declare function constant<const T>(value: T): Parser<"sync", T, T>;
  *          complete time.
  * @since 1.0.0
  */
-declare function fail<T>(): Parser<"sync", T, undefined>;
+declare function fail<T>(): FluentParser<"sync", T, undefined>;
 /**
  * Options for the {@link option} parser.
  */
@@ -113,7 +114,7 @@ interface OptionErrorOptions {
  * @returns A {@link Parser} that can parse the specified options and their
  *          values.
  */
-declare function option<M extends Mode, T>(...args: readonly [OptionName, ...readonly OptionName[], ValueParser<M, T>]): Parser<M, T, ValueParserResult<T> | undefined>;
+declare function option<M extends Mode, T>(...args: readonly [OptionName, ...readonly OptionName[], ValueParser<M, T>]): FluentParser<M, T, ValueParserResult<T> | undefined>;
 /**
  * Creates a parser for various styles of command-line options that take an
  * argument value, such as `--option=value`, `-option=value`, `-o value`,
@@ -127,7 +128,7 @@ declare function option<M extends Mode, T>(...args: readonly [OptionName, ...rea
  * @returns A {@link Parser} that can parse the specified options and their
  *          values.
  */
-declare function option<M extends Mode, T>(...args: readonly [OptionName, ...readonly OptionName[], ValueParser<M, T>, OptionOptions]): Parser<M, T, ValueParserResult<T> | undefined>;
+declare function option<M extends Mode, T>(...args: readonly [OptionName, ...readonly OptionName[], ValueParser<M, T>, OptionOptions]): FluentParser<M, T, ValueParserResult<T> | undefined>;
 /**
  * Creates a parser for various styles of command-line options that do not
  * take an argument value, such as `--option`, `-o`, or `/option`.
@@ -135,7 +136,7 @@ declare function option<M extends Mode, T>(...args: readonly [OptionName, ...rea
  * @return A {@link Parser} that can parse the specified options as Boolean
  *         flags, producing `true` if the option is present.
  */
-declare function option(...optionNames: readonly [OptionName, ...readonly OptionName[]]): Parser<"sync", boolean, ValueParserResult<boolean> | undefined>;
+declare function option(...optionNames: readonly [OptionName, ...readonly OptionName[]]): FluentParser<"sync", boolean, ValueParserResult<boolean> | undefined>;
 /**
  * Creates a parser for various styles of command-line options that take an
  * argument value, such as `--option=value`, `-option=value`, `-o value`,
@@ -146,7 +147,7 @@ declare function option(...optionNames: readonly [OptionName, ...readonly Option
  * @returns A {@link Parser} that can parse the specified options and their
  *          values.
  */
-declare function option(...args: readonly [OptionName, ...readonly OptionName[], OptionOptions]): Parser<"sync", boolean, ValueParserResult<boolean> | undefined>;
+declare function option(...args: readonly [OptionName, ...readonly OptionName[], OptionOptions]): FluentParser<"sync", boolean, ValueParserResult<boolean> | undefined>;
 /**
  * Options for the {@link flag} parser.
  */
@@ -236,7 +237,7 @@ interface FlagErrorOptions {
  * });
  * ```
  */
-declare function flag(...args: readonly [OptionName, ...readonly OptionName[], FlagOptions] | readonly [OptionName, ...readonly OptionName[]]): Parser<"sync", true, ValueParserResult<true> | undefined>;
+declare function flag(...args: readonly [OptionName, ...readonly OptionName[], FlagOptions] | readonly [OptionName, ...readonly OptionName[]]): FluentParser<"sync", true, ValueParserResult<true> | undefined>;
 /**
  * A non-empty list of option names, or a single option name.
  * @since 1.1.0
@@ -340,7 +341,7 @@ interface NegatableFlagState {
  *         side, or shared by the positive and negative sides.
  * @since 1.1.0
  */
-declare function negatableFlag(names: NegatableFlagNames, options?: NegatableFlagOptions): Parser<"sync", boolean, NegatableFlagState | undefined>;
+declare function negatableFlag(names: NegatableFlagNames, options?: NegatableFlagOptions): FluentParser<"sync", boolean, NegatableFlagState | undefined>;
 /**
  * Options for the {@link argument} parser.
  */
@@ -399,7 +400,7 @@ interface ArgumentErrorOptions {
  * @returns A {@link Parser} that expects a single argument value and produces
  *          the parsed value of type {@link T}.
  */
-declare function argument<M extends Mode, T>(valueParser: ValueParser<M, T>, options?: ArgumentOptions): Parser<M, T, ValueParserResult<T> | undefined>;
+declare function argument<M extends Mode, T>(valueParser: ValueParser<M, T>, options?: ArgumentOptions): FluentParser<M, T, ValueParserResult<T> | undefined>;
 /**
  * Options for the {@link command} parser.
  * @since 0.5.0
@@ -507,7 +508,7 @@ type CommandState<TState> = undefined | ["matched", string] | ["parsing", TState
  * @throws {TypeError} If `name` is empty, whitespace-only, contains
  *         embedded whitespace, or contains control characters.
  */
-declare function command<M extends Mode, T, TState>(name: string, parser: Parser<M, T, TState>, options?: CommandOptions): Parser<M, T, CommandState<TState>>;
+declare function command<M extends Mode, T, TState>(name: string, parser: Parser<M, T, TState>, options?: CommandOptions): FluentParser<M, T, CommandState<TState>>;
 /**
  * Format options for how {@link passThrough} captures options.
  * @since 0.8.0
@@ -595,6 +596,6 @@ interface PassThroughOptions {
  *
  * @since 0.8.0
  */
-declare function passThrough(options?: PassThroughOptions): Parser<"sync", readonly string[], readonly string[]>;
+declare function passThrough(options?: PassThroughOptions): FluentParser<"sync", readonly string[], readonly string[]>;
 //#endregion
 export { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough };

package/dist/primitives.js

@@ -9,9 +9,10 @@ import { getWrappedChildParseState, getWrappedChildState, isAnnotationWrappedIni
 import { hiddenCommandAliasesKey } from "./internal/command-alias.js";
 import { mergeChildExec, withChildContext, withChildExecPath } from "./execution-context.js";
 import { completeOrExtractPhase2Seed, extractPhase2SeedKey } from "./phase2-seed.js";
+import { extractDependencyMetadata } from "./dependency-metadata.js";
+import { fluent } from "./modifiers.js";
 import { DEFAULT_FIND_SIMILAR_OPTIONS, createErrorWithSuggestions, createSuggestionMessage, expandCommandAliasSuggestions, findSimilar } from "./suggestion.js";
 import { extractLeadingCommandNames } from "./usage-internals.js";
-import { extractDependencyMetadata } from "./dependency-metadata.js";
 import { isValueParser } from "./valueparser.js";
 
 //#region src/primitives.ts
@@ -150,7 +151,7 @@ function constant(value) {
 		enumerable: false,
 		writable: false
 	});
-	return result;
+	return 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 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 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 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 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 fluent(result);
 }
 function normalizeCommandState(state) {
 	return normalizeInjectedAnnotationState(state);
@@ -1700,7 +1701,7 @@ function command(name, parser, options = {}) {
 		configurable: true,
 		enumerable: false
 	});
-	return result;
+	return 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 fluent(result);
 }
 
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.2.0-dev.2179",
+  "version": "1.2.0-dev.2187",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -123,6 +123,14 @@
       "import": "./dist/facade.js",
       "require": "./dist/facade.cjs"
     },
+    "./fluent": {
+      "types": {
+        "import": "./dist/fluent.d.ts",
+        "require": "./dist/fluent.d.cts"
+      },
+      "import": "./dist/fluent.js",
+      "require": "./dist/fluent.cjs"
+    },
     "./message": {
       "types": {
         "import": "./dist/message.d.ts",
@@ -200,7 +208,7 @@
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",
     "typescript": "^5.8.3",
-    "@optique/env": "1.2.0-dev.2179+919d5ae8"
+    "@optique/env": "1.2.0-dev.2187+6112b083"
   },
   "scripts": {
     "build": "tsdown",