@optique/core 0.1.0-dev.1 → 0.1.0-dev.2

package/README.md

@@ -46,10 +46,12 @@ Optique is built around several key concepts:
      -  `option()` for command-line flags and their arguments
      -  `argument()` for positional arguments
      -  `command()` for subcommands
+     -  `constant()` for literal values (essential for discriminated unions)
 
  -   *Modifying combinators* transform and combine parsers:
      -  `optional()` makes parsers optional
      -  `withDefault()` provides default values for optional parsers
+     -  `map()` transforms parsed values using mapping functions
      -  `multiple()` allows repetition
      -  `or()` creates alternatives
      -  `merge()` combines object parsers
@@ -189,6 +191,13 @@ Optique provides several types of parsers and combinators for building sophistic
     command("add", object({ file: argument(string()) }))
     ~~~~
 
+ -  **`constant()`**: Produces a constant value without consuming input, essential for discriminated unions
+
+    ~~~~ typescript
+    constant("add")  // Always returns "add"
+    constant(42)     // Always returns 42
+    ~~~~
+
 ### Modifying combinators
 
  -  **`optional()`**: Makes any parser optional, returning `undefined` if not
@@ -212,6 +221,20 @@ Optique provides several types of parsers and combinators for building sophistic
     });
     ~~~~
 
+ -  **`map()`**: Transforms the parsed value using a mapping function while
+    preserving the original parsing logic
+
+    ~~~~ typescript
+    const parser = object({
+      // Transform boolean flag to its inverse
+      disallow: map(option("--allow"), b => !b),
+      // Transform string to uppercase
+      upperName: map(option("-n", "--name", string()), s => s.toUpperCase()),
+      // Transform number to formatted string
+      portDesc: map(option("-p", "--port", integer()), n => `port: ${n}`),
+    });
+    ~~~~
+
  -  **`multiple()`**: Allows repeating a parser multiple times with constraints
 
     ~~~~ typescript
@@ -421,11 +444,16 @@ This example demonstrates:
  -  *Subcommand routing*: `command("show", ...)` matches the first argument
     and applies the inner parser to remaining arguments
  -  *Type discrimination*: Using `constant()` with unique values enables
-    TypeScript to discriminate between subcommand types
+    TypeScript to discriminate between subcommand types in the result union
  -  *Per-subcommand options*: Each subcommand can have its own unique set
     of options and arguments
  -  *Complex arguments*: The `delete` command shows multiple required arguments
 
+The `constant()` parser is crucial here—it adds a literal value to each
+subcommand's result object without consuming any input.  This creates
+a discriminated union type that TypeScript can use for type narrowing in
+`switch` statements or type guards.
+
 Example usage:
 
 ~~~~ bash

package/dist/index.cjs

@@ -19,6 +19,7 @@ exports.getDocPage = require_parser.getDocPage;
 exports.integer = require_valueparser.integer;
 exports.isValueParser = require_valueparser.isValueParser;
 exports.locale = require_valueparser.locale;
+exports.map = require_parser.map;
 exports.merge = require_parser.merge;
 exports.message = require_message.message;
 exports.metavar = require_message.metavar;

package/dist/index.d.cts

@@ -2,6 +2,6 @@ import { Message, MessageFormatOptions, MessageTerm, formatMessage, message, met
 import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.cjs";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, formatDocPage } from "./doc.cjs";
 import { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.cjs";
-import { ArgumentOptions, CommandOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, constant, getDocPage, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.cjs";
+import { ArgumentOptions, CommandOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, constant, getDocPage, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.cjs";
 import { RunError, RunOptions, run } from "./facade.cjs";
-export { ArgumentOptions, ChoiceOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, Message, MessageFormatOptions, MessageTerm, MultipleOptions, OptionName, OptionOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, argument, choice, command, constant, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, integer, isValueParser, locale, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };
+export { ArgumentOptions, ChoiceOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, Message, MessageFormatOptions, MessageTerm, MultipleOptions, OptionName, OptionOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, argument, choice, command, constant, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, integer, isValueParser, locale, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };

package/dist/index.d.ts

@@ -2,6 +2,6 @@ import { Message, MessageFormatOptions, MessageTerm, formatMessage, message, met
 import { OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, formatDocPage } from "./doc.js";
 import { ChoiceOptions, FloatOptions, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.js";
-import { ArgumentOptions, CommandOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, constant, getDocPage, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.js";
+import { ArgumentOptions, CommandOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, constant, getDocPage, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.js";
 import { RunError, RunOptions, run } from "./facade.js";
-export { ArgumentOptions, ChoiceOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, Message, MessageFormatOptions, MessageTerm, MultipleOptions, OptionName, OptionOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, argument, choice, command, constant, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, integer, isValueParser, locale, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };
+export { ArgumentOptions, ChoiceOptions, CommandOptions, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, FloatOptions, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, LocaleOptions, Message, MessageFormatOptions, MessageTerm, MultipleOptions, OptionName, OptionOptions, Parser, ParserContext, ParserResult, Result, RunError, RunOptions, StringOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, argument, choice, command, constant, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, integer, isValueParser, locale, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };

package/dist/index.js

@@ -2,7 +2,7 @@ import { formatMessage, message, metavar, optionName, optionNames, text, value,
 import { formatUsage, formatUsageTerm, normalizeUsage } from "./usage.js";
 import { formatDocPage } from "./doc.js";
 import { choice, float, integer, isValueParser, locale, string, url, uuid } from "./valueparser.js";
-import { argument, command, constant, getDocPage, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.js";
+import { argument, command, constant, getDocPage, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault } from "./parser.js";
 import { RunError, run } from "./facade.js";
 
-export { RunError, argument, choice, command, constant, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, integer, isValueParser, locale, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };
+export { RunError, argument, choice, command, constant, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getDocPage, integer, isValueParser, locale, map, merge, message, metavar, multiple, normalizeUsage, object, option, optionName, optionNames, optional, or, parse, run, string, text, tuple, url, uuid, value, values, withDefault };

package/dist/parser.cjs

@@ -413,6 +413,60 @@ function withDefault(parser, defaultValue) {
 	};
 }
 /**
+* Creates a parser that transforms the result value of another parser using
+* a mapping function. This enables value transformation while preserving
+* the original parser's parsing logic and state management.
+*
+* The `map()` function is useful for:
+* - Converting parsed values to different types
+* - Applying transformations like string formatting or boolean inversion
+* - Computing derived values from parsed input
+* - Creating reusable transformations that can be applied to any parser
+*
+* @template T The type of the value produced by the original parser.
+* @template U The type of the value produced by the mapping function.
+* @template TState The type of the state used by the original parser.
+* @param parser The {@link Parser} whose result will be transformed.
+* @param transform A function that transforms the parsed value from type T to type U.
+* @returns A {@link Parser} that produces the transformed value of type U
+*          while preserving the original parser's state type and parsing behavior.
+*
+* @example
+* ```typescript
+* // Transform boolean flag to its inverse
+* const parser = object({
+*   disallow: map(option("--allow"), b => !b)
+* });
+*
+* // Transform string to uppercase
+* const upperParser = map(argument(string()), s => s.toUpperCase());
+*
+* // Transform number to formatted string
+* const prefixedParser = map(option("-n", integer()), n => `value: ${n}`);
+* ```
+*/
+function map(parser, transform) {
+	return {
+		$valueType: [],
+		$stateType: parser.$stateType,
+		priority: parser.priority,
+		usage: parser.usage,
+		initialState: parser.initialState,
+		parse: parser.parse.bind(parser),
+		complete(state) {
+			const result = parser.complete(state);
+			if (result.success) return {
+				success: true,
+				value: transform(result.value)
+			};
+			return result;
+		},
+		getDocFragments(state, _defaultValue) {
+			return parser.getDocFragments(state, void 0);
+		}
+	};
+}
+/**
 * Creates a parser that allows multiple occurrences of a given parser.
 * This parser can be used to parse multiple values of the same type,
 * such as multiple command-line arguments or options.
@@ -1054,6 +1108,7 @@ exports.argument = argument;
 exports.command = command;
 exports.constant = constant;
 exports.getDocPage = getDocPage;
+exports.map = map;
 exports.merge = merge;
 exports.multiple = multiple;
 exports.object = object;

package/dist/parser.d.cts

@@ -238,6 +238,40 @@ declare function optional<TValue, TState>(parser: Parser<TValue, TState>): Parse
  *          or the default value if the wrapped parser fails to match.
  */
 declare function withDefault<TValue, TState>(parser: Parser<TValue, TState>, defaultValue: TValue | (() => TValue)): Parser<TValue, [TState] | undefined>;
+/**
+ * Creates a parser that transforms the result value of another parser using
+ * a mapping function. This enables value transformation while preserving
+ * the original parser's parsing logic and state management.
+ *
+ * The `map()` function is useful for:
+ * - Converting parsed values to different types
+ * - Applying transformations like string formatting or boolean inversion
+ * - Computing derived values from parsed input
+ * - Creating reusable transformations that can be applied to any parser
+ *
+ * @template T The type of the value produced by the original parser.
+ * @template U The type of the value produced by the mapping function.
+ * @template TState The type of the state used by the original parser.
+ * @param parser The {@link Parser} whose result will be transformed.
+ * @param transform A function that transforms the parsed value from type T to type U.
+ * @returns A {@link Parser} that produces the transformed value of type U
+ *          while preserving the original parser's state type and parsing behavior.
+ *
+ * @example
+ * ```typescript
+ * // Transform boolean flag to its inverse
+ * const parser = object({
+ *   disallow: map(option("--allow"), b => !b)
+ * });
+ *
+ * // Transform string to uppercase
+ * const upperParser = map(argument(string()), s => s.toUpperCase());
+ *
+ * // Transform number to formatted string
+ * const prefixedParser = map(option("-n", integer()), n => `value: ${n}`);
+ * ```
+ */
+declare function map<T, U, TState>(parser: Parser<T, TState>, transform: (value: T) => U): Parser<U, TState>;
 /**
  * Options for the {@link multiple} parser.
  */
@@ -577,4 +611,4 @@ declare function parse<T>(parser: Parser<T, unknown>, args: readonly string[]):
  */
 declare function getDocPage(parser: Parser<unknown, unknown>, args?: readonly string[]): DocPage | undefined;
 //#endregion
-export { ArgumentOptions, CommandOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, constant, getDocPage, merge, multiple, object, option, optional, or, parse, tuple, withDefault };
+export { ArgumentOptions, CommandOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, constant, getDocPage, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };

package/dist/parser.d.ts

@@ -238,6 +238,40 @@ declare function optional<TValue, TState>(parser: Parser<TValue, TState>): Parse
  *          or the default value if the wrapped parser fails to match.
  */
 declare function withDefault<TValue, TState>(parser: Parser<TValue, TState>, defaultValue: TValue | (() => TValue)): Parser<TValue, [TState] | undefined>;
+/**
+ * Creates a parser that transforms the result value of another parser using
+ * a mapping function. This enables value transformation while preserving
+ * the original parser's parsing logic and state management.
+ *
+ * The `map()` function is useful for:
+ * - Converting parsed values to different types
+ * - Applying transformations like string formatting or boolean inversion
+ * - Computing derived values from parsed input
+ * - Creating reusable transformations that can be applied to any parser
+ *
+ * @template T The type of the value produced by the original parser.
+ * @template U The type of the value produced by the mapping function.
+ * @template TState The type of the state used by the original parser.
+ * @param parser The {@link Parser} whose result will be transformed.
+ * @param transform A function that transforms the parsed value from type T to type U.
+ * @returns A {@link Parser} that produces the transformed value of type U
+ *          while preserving the original parser's state type and parsing behavior.
+ *
+ * @example
+ * ```typescript
+ * // Transform boolean flag to its inverse
+ * const parser = object({
+ *   disallow: map(option("--allow"), b => !b)
+ * });
+ *
+ * // Transform string to uppercase
+ * const upperParser = map(argument(string()), s => s.toUpperCase());
+ *
+ * // Transform number to formatted string
+ * const prefixedParser = map(option("-n", integer()), n => `value: ${n}`);
+ * ```
+ */
+declare function map<T, U, TState>(parser: Parser<T, TState>, transform: (value: T) => U): Parser<U, TState>;
 /**
  * Options for the {@link multiple} parser.
  */
@@ -577,4 +611,4 @@ declare function parse<T>(parser: Parser<T, unknown>, args: readonly string[]):
  */
 declare function getDocPage(parser: Parser<unknown, unknown>, args?: readonly string[]): DocPage | undefined;
 //#endregion
-export { ArgumentOptions, CommandOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, constant, getDocPage, merge, multiple, object, option, optional, or, parse, tuple, withDefault };
+export { ArgumentOptions, CommandOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, constant, getDocPage, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };

package/dist/parser.js

@@ -413,6 +413,60 @@ function withDefault(parser, defaultValue) {
 	};
 }
 /**
+* Creates a parser that transforms the result value of another parser using
+* a mapping function. This enables value transformation while preserving
+* the original parser's parsing logic and state management.
+*
+* The `map()` function is useful for:
+* - Converting parsed values to different types
+* - Applying transformations like string formatting or boolean inversion
+* - Computing derived values from parsed input
+* - Creating reusable transformations that can be applied to any parser
+*
+* @template T The type of the value produced by the original parser.
+* @template U The type of the value produced by the mapping function.
+* @template TState The type of the state used by the original parser.
+* @param parser The {@link Parser} whose result will be transformed.
+* @param transform A function that transforms the parsed value from type T to type U.
+* @returns A {@link Parser} that produces the transformed value of type U
+*          while preserving the original parser's state type and parsing behavior.
+*
+* @example
+* ```typescript
+* // Transform boolean flag to its inverse
+* const parser = object({
+*   disallow: map(option("--allow"), b => !b)
+* });
+*
+* // Transform string to uppercase
+* const upperParser = map(argument(string()), s => s.toUpperCase());
+*
+* // Transform number to formatted string
+* const prefixedParser = map(option("-n", integer()), n => `value: ${n}`);
+* ```
+*/
+function map(parser, transform) {
+	return {
+		$valueType: [],
+		$stateType: parser.$stateType,
+		priority: parser.priority,
+		usage: parser.usage,
+		initialState: parser.initialState,
+		parse: parser.parse.bind(parser),
+		complete(state) {
+			const result = parser.complete(state);
+			if (result.success) return {
+				success: true,
+				value: transform(result.value)
+			};
+			return result;
+		},
+		getDocFragments(state, _defaultValue) {
+			return parser.getDocFragments(state, void 0);
+		}
+	};
+}
+/**
 * Creates a parser that allows multiple occurrences of a given parser.
 * This parser can be used to parse multiple values of the same type,
 * such as multiple command-line arguments or options.
@@ -1050,4 +1104,4 @@ function getDocPage(parser, args = []) {
 }
 
 //#endregion
-export { argument, command, constant, getDocPage, merge, multiple, object, option, optional, or, parse, tuple, withDefault };
+export { argument, command, constant, getDocPage, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.1.0-dev.1+4d43eddd",
+  "version": "0.1.0-dev.2+f542cb87",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",