@optique/core 0.4.0-dev.52 → 0.4.0-dev.54

package/dist/parser.cjs

@@ -1492,6 +1492,81 @@ function parse(parser, args) {
 	};
 }
 /**
+* Wraps a parser with a group label for documentation purposes.
+*
+* The `group()` function is a documentation-only wrapper that applies a label
+* to any parser for help text organization. This allows you to use clean code
+* structure with combinators like {@link merge} while maintaining well-organized
+* help text through group labeling.
+*
+* The wrapped parser has identical parsing behavior but generates documentation
+* fragments wrapped in a labeled section. This is particularly useful when
+* combining parsers using {@link merge}—you can wrap the merged result with
+* `group()` to add a section header in help output.
+*
+* @example
+* ```typescript
+* const apiOptions = merge(
+*   object({ endpoint: option("--endpoint", string()) }),
+*   object({ timeout: option("--timeout", integer()) })
+* );
+*
+* const groupedApiOptions = group("API Options", apiOptions);
+* // Now produces a labeled "API Options" section in help text
+* ```
+*
+* @example
+* ```typescript
+* // Can be used with any parser, not just merge()
+* const verboseGroup = group("Verbosity", object({
+*   verbose: option("-v", "--verbose"),
+*   quiet: option("-q", "--quiet")
+* }));
+* ```
+*
+* @template TValue The value type of the wrapped parser.
+* @template TState The state type of the wrapped parser.
+* @param label A descriptive label for this parser group, used for
+*              documentation and help text organization.
+* @param parser The parser to wrap with a group label.
+* @returns A new parser that behaves identically to the input parser
+*          but generates documentation within a labeled section.
+* @since 0.4.0
+*/
+function group(label, parser) {
+	return {
+		$valueType: parser.$valueType,
+		$stateType: parser.$stateType,
+		priority: parser.priority,
+		usage: parser.usage,
+		initialState: parser.initialState,
+		parse: (context) => parser.parse(context),
+		complete: (state) => parser.complete(state),
+		getDocFragments: (state, defaultValue) => {
+			const { description, fragments } = parser.getDocFragments(state, defaultValue);
+			const allEntries = [];
+			const titledSections = [];
+			for (const fragment of fragments) if (fragment.type === "entry") allEntries.push(fragment);
+			else if (fragment.type === "section") if (fragment.title) titledSections.push(fragment);
+			else allEntries.push(...fragment.entries);
+			const labeledSection = {
+				title: label,
+				entries: allEntries
+			};
+			return {
+				description,
+				fragments: [...titledSections.map((s) => ({
+					...s,
+					type: "section"
+				})), {
+					type: "section",
+					...labeledSection
+				}]
+			};
+		}
+	};
+}
+/**
 * Generates a documentation page for a parser based on its current state after
 * attempting to parse the provided arguments. This function is useful for
 * creating help documentation that reflects the current parsing context.
@@ -1576,6 +1651,7 @@ exports.concat = concat;
 exports.constant = constant;
 exports.flag = flag;
 exports.getDocPage = getDocPage;
+exports.group = group;
 exports.longestMatch = longestMatch;
 exports.map = map;
 exports.merge = merge;

package/dist/parser.d.cts

@@ -400,7 +400,7 @@ declare function object<T extends {
  *          as the input array, where each element is the result of the
  *          corresponding parser.
  */
-declare function tuple<T extends readonly Parser<unknown, unknown>[]>(parsers: T): Parser<{ readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, { readonly [K in keyof T]: T[K]["$stateType"][number] extends (infer U2) ? U2 : never }>;
+declare function tuple<const T extends readonly Parser<unknown, unknown>[]>(parsers: T): Parser<{ readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, { readonly [K in keyof T]: T[K]["$stateType"][number] extends (infer U2) ? U2 : never }>;
 /**
  * Creates a labeled parser that combines multiple parsers into a sequential
  * tuple parser with an associated label for documentation or error reporting.
@@ -413,7 +413,7 @@ declare function tuple<T extends readonly Parser<unknown, unknown>[]>(parsers: T
  *          as the input array, where each element is the result of the
  *          corresponding parser.
  */
-declare function tuple<T extends readonly Parser<unknown, unknown>[]>(label: string, parsers: T): Parser<{ readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, { readonly [K in keyof T]: T[K]["$stateType"][number] extends (infer U2) ? U2 : never }>;
+declare function tuple<const T extends readonly Parser<unknown, unknown>[]>(label: string, parsers: T): Parser<{ readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, { readonly [K in keyof T]: T[K]["$stateType"][number] extends (infer U2) ? U2 : never }>;
 /**
  * Creates a parser that combines two mutually exclusive parsers into one.
  * The resulting parser will try each of the provided parsers in order,
@@ -739,7 +739,7 @@ declare function longestMatch<TA, TB, TC, TD, TE, TStateA, TStateB, TStateC, TSt
  * Helper type to check if all members of a union are object-like.
  * This allows merge() to work with parsers like withDefault() that produce union types.
  */
-type AllObjectLike<T> = T extends Record<string | symbol, unknown> ? T : never;
+type AllObjectLike<T> = T extends readonly unknown[] ? never : T extends Record<string | symbol, unknown> ? T : never;
 /**
  * Helper type to extract object-like types from parser value types,
  * including union types where all members are objects.
@@ -758,7 +758,7 @@ type ExtractObjectTypes<P> = P extends Parser<infer V, unknown> ? [AllObjectLike
  * @return A new {@link object} parser that combines the values and states
  *         of the two parsers into a single object.
  */
-declare function merge<TA extends Parser<unknown, unknown>, TB extends Parser<unknown, unknown>>(a: TA, b: TB): ExtractObjectTypes<TA> extends never ? never : ExtractObjectTypes<TB> extends never ? never : Parser<ExtractObjectTypes<TA> & ExtractObjectTypes<TB>, Record<string | symbol, unknown>>;
+declare function merge<TA extends Parser<unknown, unknown>, TB extends Parser<unknown, unknown>>(a: ExtractObjectTypes<TA> extends never ? never : TA, b: ExtractObjectTypes<TB> extends never ? never : TB): Parser<ExtractObjectTypes<TA> & ExtractObjectTypes<TB>, Record<string | symbol, unknown>>;
 /**
  * Merges multiple {@link object} parsers into a single {@link object} parser
  * with a label for documentation and help text organization.
@@ -775,7 +775,7 @@ declare function merge<TA extends Parser<unknown, unknown>, TB extends Parser<un
  * @return A new {@link object} parser that combines the values and states
  *         of the two parsers into a single object.
  */
-declare function merge<TA extends Parser<unknown, unknown>, TB extends Parser<unknown, unknown>>(label: string, a: TA, b: TB): ExtractObjectTypes<TA> extends never ? never : ExtractObjectTypes<TB> extends never ? never : Parser<ExtractObjectTypes<TA> & ExtractObjectTypes<TB>, Record<string | symbol, unknown>>;
+declare function merge<TA extends Parser<unknown, unknown>, TB extends Parser<unknown, unknown>>(label: string, a: ExtractObjectTypes<TA> extends never ? never : TA, b: ExtractObjectTypes<TB> extends never ? never : TB): Parser<ExtractObjectTypes<TA> & ExtractObjectTypes<TB>, Record<string | symbol, unknown>>;
 /**
  * Merges multiple {@link object} parsers into a single {@link object} parser.
  * It is useful for combining multiple {@link object} parsers so that
@@ -791,7 +791,7 @@ declare function merge<TA extends Parser<unknown, unknown>, TB extends Parser<un
  * @return A new {@link object} parser that combines the values and states
  *         of the two parsers into a single object.
  */
-declare function merge<TA extends Parser<unknown, unknown>, TB extends Parser<unknown, unknown>, TC extends Parser<unknown, unknown>>(a: TA, b: TB, c: TC): ExtractObjectTypes<TA> extends never ? never : ExtractObjectTypes<TB> extends never ? never : ExtractObjectTypes<TC> extends never ? never : Parser<ExtractObjectTypes<TA> & ExtractObjectTypes<TB> & ExtractObjectTypes<TC>, Record<string | symbol, unknown>>;
+declare function merge<TA extends Parser<unknown, unknown>, TB extends Parser<unknown, unknown>, TC extends Parser<unknown, unknown>>(a: ExtractObjectTypes<TA> extends never ? never : TA, b: ExtractObjectTypes<TB> extends never ? never : TB, c: ExtractObjectTypes<TC> extends never ? never : TC): Parser<ExtractObjectTypes<TA> & ExtractObjectTypes<TB> & ExtractObjectTypes<TC>, Record<string | symbol, unknown>>;
 /**
  * Merges multiple {@link object} parsers into a single {@link object} parser
  * with a label for documentation and help text organization.
@@ -869,7 +869,7 @@ declare function merge<TA extends Parser<unknown, unknown>, TB extends Parser<un
  * @return A new {@link object} parser that combines the values and states
  *         of the two parsers into a single object.
  */
-declare function merge<TA extends Parser<unknown, unknown>, TB extends Parser<unknown, unknown>, TC extends Parser<unknown, unknown>, TD extends Parser<unknown, unknown>, TE extends Parser<unknown, unknown>>(a: TA, b: TB, c: TC, d: TD, e: TE): ExtractObjectTypes<TA> extends never ? never : ExtractObjectTypes<TB> extends never ? never : ExtractObjectTypes<TC> extends never ? never : ExtractObjectTypes<TD> extends never ? never : ExtractObjectTypes<TE> extends never ? never : Parser<ExtractObjectTypes<TA> & ExtractObjectTypes<TB> & ExtractObjectTypes<TC> & ExtractObjectTypes<TD> & ExtractObjectTypes<TE>, Record<string | symbol, unknown>>;
+declare function merge<TA extends Parser<unknown, unknown>, TB extends Parser<unknown, unknown>, TC extends Parser<unknown, unknown>, TD extends Parser<unknown, unknown>, TE extends Parser<unknown, unknown>>(a: ExtractObjectTypes<TA> extends never ? never : TA, b: ExtractObjectTypes<TB> extends never ? never : TB, c: ExtractObjectTypes<TC> extends never ? never : TC, d: ExtractObjectTypes<TD> extends never ? never : TD, e: ExtractObjectTypes<TE> extends never ? never : TE): Parser<ExtractObjectTypes<TA> & ExtractObjectTypes<TB> & ExtractObjectTypes<TC> & ExtractObjectTypes<TD> & ExtractObjectTypes<TE>, Record<string | symbol, unknown>>;
 /**
  * Merges multiple {@link object} parsers into a single {@link object} parser
  * with a label for documentation and help text organization.
@@ -1353,6 +1353,49 @@ type Result<T> = {
  *          failure.
  */
 declare function parse<T>(parser: Parser<T, unknown>, args: readonly string[]): Result<T>;
+/**
+ * Wraps a parser with a group label for documentation purposes.
+ *
+ * The `group()` function is a documentation-only wrapper that applies a label
+ * to any parser for help text organization. This allows you to use clean code
+ * structure with combinators like {@link merge} while maintaining well-organized
+ * help text through group labeling.
+ *
+ * The wrapped parser has identical parsing behavior but generates documentation
+ * fragments wrapped in a labeled section. This is particularly useful when
+ * combining parsers using {@link merge}—you can wrap the merged result with
+ * `group()` to add a section header in help output.
+ *
+ * @example
+ * ```typescript
+ * const apiOptions = merge(
+ *   object({ endpoint: option("--endpoint", string()) }),
+ *   object({ timeout: option("--timeout", integer()) })
+ * );
+ *
+ * const groupedApiOptions = group("API Options", apiOptions);
+ * // Now produces a labeled "API Options" section in help text
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Can be used with any parser, not just merge()
+ * const verboseGroup = group("Verbosity", object({
+ *   verbose: option("-v", "--verbose"),
+ *   quiet: option("-q", "--quiet")
+ * }));
+ * ```
+ *
+ * @template TValue The value type of the wrapped parser.
+ * @template TState The state type of the wrapped parser.
+ * @param label A descriptive label for this parser group, used for
+ *              documentation and help text organization.
+ * @param parser The parser to wrap with a group label.
+ * @returns A new parser that behaves identically to the input parser
+ *          but generates documentation within a labeled section.
+ * @since 0.4.0
+ */
+declare function group<TValue, TState>(label: string, parser: Parser<TValue, TState>): Parser<TValue, TState>;
 /**
  * Generates a documentation page for a parser based on its current state after
  * attempting to parse the provided arguments. This function is useful for
@@ -1388,4 +1431,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, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, concat, constant, flag, getDocPage, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };
+export { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };

package/dist/parser.d.ts

@@ -400,7 +400,7 @@ declare function object<T extends {
  *          as the input array, where each element is the result of the
  *          corresponding parser.
  */
-declare function tuple<T extends readonly Parser<unknown, unknown>[]>(parsers: T): Parser<{ readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, { readonly [K in keyof T]: T[K]["$stateType"][number] extends (infer U2) ? U2 : never }>;
+declare function tuple<const T extends readonly Parser<unknown, unknown>[]>(parsers: T): Parser<{ readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, { readonly [K in keyof T]: T[K]["$stateType"][number] extends (infer U2) ? U2 : never }>;
 /**
  * Creates a labeled parser that combines multiple parsers into a sequential
  * tuple parser with an associated label for documentation or error reporting.
@@ -413,7 +413,7 @@ declare function tuple<T extends readonly Parser<unknown, unknown>[]>(parsers: T
  *          as the input array, where each element is the result of the
  *          corresponding parser.
  */
-declare function tuple<T extends readonly Parser<unknown, unknown>[]>(label: string, parsers: T): Parser<{ readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, { readonly [K in keyof T]: T[K]["$stateType"][number] extends (infer U2) ? U2 : never }>;
+declare function tuple<const T extends readonly Parser<unknown, unknown>[]>(label: string, parsers: T): Parser<{ readonly [K in keyof T]: T[K]["$valueType"][number] extends (infer U) ? U : never }, { readonly [K in keyof T]: T[K]["$stateType"][number] extends (infer U2) ? U2 : never }>;
 /**
  * Creates a parser that combines two mutually exclusive parsers into one.
  * The resulting parser will try each of the provided parsers in order,
@@ -739,7 +739,7 @@ declare function longestMatch<TA, TB, TC, TD, TE, TStateA, TStateB, TStateC, TSt
  * Helper type to check if all members of a union are object-like.
  * This allows merge() to work with parsers like withDefault() that produce union types.
  */
-type AllObjectLike<T> = T extends Record<string | symbol, unknown> ? T : never;
+type AllObjectLike<T> = T extends readonly unknown[] ? never : T extends Record<string | symbol, unknown> ? T : never;
 /**
  * Helper type to extract object-like types from parser value types,
  * including union types where all members are objects.
@@ -758,7 +758,7 @@ type ExtractObjectTypes<P> = P extends Parser<infer V, unknown> ? [AllObjectLike
  * @return A new {@link object} parser that combines the values and states
  *         of the two parsers into a single object.
  */
-declare function merge<TA extends Parser<unknown, unknown>, TB extends Parser<unknown, unknown>>(a: TA, b: TB): ExtractObjectTypes<TA> extends never ? never : ExtractObjectTypes<TB> extends never ? never : Parser<ExtractObjectTypes<TA> & ExtractObjectTypes<TB>, Record<string | symbol, unknown>>;
+declare function merge<TA extends Parser<unknown, unknown>, TB extends Parser<unknown, unknown>>(a: ExtractObjectTypes<TA> extends never ? never : TA, b: ExtractObjectTypes<TB> extends never ? never : TB): Parser<ExtractObjectTypes<TA> & ExtractObjectTypes<TB>, Record<string | symbol, unknown>>;
 /**
  * Merges multiple {@link object} parsers into a single {@link object} parser
  * with a label for documentation and help text organization.
@@ -775,7 +775,7 @@ declare function merge<TA extends Parser<unknown, unknown>, TB extends Parser<un
  * @return A new {@link object} parser that combines the values and states
  *         of the two parsers into a single object.
  */
-declare function merge<TA extends Parser<unknown, unknown>, TB extends Parser<unknown, unknown>>(label: string, a: TA, b: TB): ExtractObjectTypes<TA> extends never ? never : ExtractObjectTypes<TB> extends never ? never : Parser<ExtractObjectTypes<TA> & ExtractObjectTypes<TB>, Record<string | symbol, unknown>>;
+declare function merge<TA extends Parser<unknown, unknown>, TB extends Parser<unknown, unknown>>(label: string, a: ExtractObjectTypes<TA> extends never ? never : TA, b: ExtractObjectTypes<TB> extends never ? never : TB): Parser<ExtractObjectTypes<TA> & ExtractObjectTypes<TB>, Record<string | symbol, unknown>>;
 /**
  * Merges multiple {@link object} parsers into a single {@link object} parser.
  * It is useful for combining multiple {@link object} parsers so that
@@ -791,7 +791,7 @@ declare function merge<TA extends Parser<unknown, unknown>, TB extends Parser<un
  * @return A new {@link object} parser that combines the values and states
  *         of the two parsers into a single object.
  */
-declare function merge<TA extends Parser<unknown, unknown>, TB extends Parser<unknown, unknown>, TC extends Parser<unknown, unknown>>(a: TA, b: TB, c: TC): ExtractObjectTypes<TA> extends never ? never : ExtractObjectTypes<TB> extends never ? never : ExtractObjectTypes<TC> extends never ? never : Parser<ExtractObjectTypes<TA> & ExtractObjectTypes<TB> & ExtractObjectTypes<TC>, Record<string | symbol, unknown>>;
+declare function merge<TA extends Parser<unknown, unknown>, TB extends Parser<unknown, unknown>, TC extends Parser<unknown, unknown>>(a: ExtractObjectTypes<TA> extends never ? never : TA, b: ExtractObjectTypes<TB> extends never ? never : TB, c: ExtractObjectTypes<TC> extends never ? never : TC): Parser<ExtractObjectTypes<TA> & ExtractObjectTypes<TB> & ExtractObjectTypes<TC>, Record<string | symbol, unknown>>;
 /**
  * Merges multiple {@link object} parsers into a single {@link object} parser
  * with a label for documentation and help text organization.
@@ -869,7 +869,7 @@ declare function merge<TA extends Parser<unknown, unknown>, TB extends Parser<un
  * @return A new {@link object} parser that combines the values and states
  *         of the two parsers into a single object.
  */
-declare function merge<TA extends Parser<unknown, unknown>, TB extends Parser<unknown, unknown>, TC extends Parser<unknown, unknown>, TD extends Parser<unknown, unknown>, TE extends Parser<unknown, unknown>>(a: TA, b: TB, c: TC, d: TD, e: TE): ExtractObjectTypes<TA> extends never ? never : ExtractObjectTypes<TB> extends never ? never : ExtractObjectTypes<TC> extends never ? never : ExtractObjectTypes<TD> extends never ? never : ExtractObjectTypes<TE> extends never ? never : Parser<ExtractObjectTypes<TA> & ExtractObjectTypes<TB> & ExtractObjectTypes<TC> & ExtractObjectTypes<TD> & ExtractObjectTypes<TE>, Record<string | symbol, unknown>>;
+declare function merge<TA extends Parser<unknown, unknown>, TB extends Parser<unknown, unknown>, TC extends Parser<unknown, unknown>, TD extends Parser<unknown, unknown>, TE extends Parser<unknown, unknown>>(a: ExtractObjectTypes<TA> extends never ? never : TA, b: ExtractObjectTypes<TB> extends never ? never : TB, c: ExtractObjectTypes<TC> extends never ? never : TC, d: ExtractObjectTypes<TD> extends never ? never : TD, e: ExtractObjectTypes<TE> extends never ? never : TE): Parser<ExtractObjectTypes<TA> & ExtractObjectTypes<TB> & ExtractObjectTypes<TC> & ExtractObjectTypes<TD> & ExtractObjectTypes<TE>, Record<string | symbol, unknown>>;
 /**
  * Merges multiple {@link object} parsers into a single {@link object} parser
  * with a label for documentation and help text organization.
@@ -1353,6 +1353,49 @@ type Result<T> = {
  *          failure.
  */
 declare function parse<T>(parser: Parser<T, unknown>, args: readonly string[]): Result<T>;
+/**
+ * Wraps a parser with a group label for documentation purposes.
+ *
+ * The `group()` function is a documentation-only wrapper that applies a label
+ * to any parser for help text organization. This allows you to use clean code
+ * structure with combinators like {@link merge} while maintaining well-organized
+ * help text through group labeling.
+ *
+ * The wrapped parser has identical parsing behavior but generates documentation
+ * fragments wrapped in a labeled section. This is particularly useful when
+ * combining parsers using {@link merge}—you can wrap the merged result with
+ * `group()` to add a section header in help output.
+ *
+ * @example
+ * ```typescript
+ * const apiOptions = merge(
+ *   object({ endpoint: option("--endpoint", string()) }),
+ *   object({ timeout: option("--timeout", integer()) })
+ * );
+ *
+ * const groupedApiOptions = group("API Options", apiOptions);
+ * // Now produces a labeled "API Options" section in help text
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Can be used with any parser, not just merge()
+ * const verboseGroup = group("Verbosity", object({
+ *   verbose: option("-v", "--verbose"),
+ *   quiet: option("-q", "--quiet")
+ * }));
+ * ```
+ *
+ * @template TValue The value type of the wrapped parser.
+ * @template TState The state type of the wrapped parser.
+ * @param label A descriptive label for this parser group, used for
+ *              documentation and help text organization.
+ * @param parser The parser to wrap with a group label.
+ * @returns A new parser that behaves identically to the input parser
+ *          but generates documentation within a labeled section.
+ * @since 0.4.0
+ */
+declare function group<TValue, TState>(label: string, parser: Parser<TValue, TState>): Parser<TValue, TState>;
 /**
  * Generates a documentation page for a parser based on its current state after
  * attempting to parse the provided arguments. This function is useful for
@@ -1388,4 +1431,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, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, concat, constant, flag, getDocPage, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };
+export { ArgumentOptions, CommandOptions, DocState, FlagOptions, InferValue, MultipleOptions, OptionOptions, Parser, ParserContext, ParserResult, Result, argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };

package/dist/parser.js

@@ -1492,6 +1492,81 @@ function parse(parser, args) {
 	};
 }
 /**
+* Wraps a parser with a group label for documentation purposes.
+*
+* The `group()` function is a documentation-only wrapper that applies a label
+* to any parser for help text organization. This allows you to use clean code
+* structure with combinators like {@link merge} while maintaining well-organized
+* help text through group labeling.
+*
+* The wrapped parser has identical parsing behavior but generates documentation
+* fragments wrapped in a labeled section. This is particularly useful when
+* combining parsers using {@link merge}—you can wrap the merged result with
+* `group()` to add a section header in help output.
+*
+* @example
+* ```typescript
+* const apiOptions = merge(
+*   object({ endpoint: option("--endpoint", string()) }),
+*   object({ timeout: option("--timeout", integer()) })
+* );
+*
+* const groupedApiOptions = group("API Options", apiOptions);
+* // Now produces a labeled "API Options" section in help text
+* ```
+*
+* @example
+* ```typescript
+* // Can be used with any parser, not just merge()
+* const verboseGroup = group("Verbosity", object({
+*   verbose: option("-v", "--verbose"),
+*   quiet: option("-q", "--quiet")
+* }));
+* ```
+*
+* @template TValue The value type of the wrapped parser.
+* @template TState The state type of the wrapped parser.
+* @param label A descriptive label for this parser group, used for
+*              documentation and help text organization.
+* @param parser The parser to wrap with a group label.
+* @returns A new parser that behaves identically to the input parser
+*          but generates documentation within a labeled section.
+* @since 0.4.0
+*/
+function group(label, parser) {
+	return {
+		$valueType: parser.$valueType,
+		$stateType: parser.$stateType,
+		priority: parser.priority,
+		usage: parser.usage,
+		initialState: parser.initialState,
+		parse: (context) => parser.parse(context),
+		complete: (state) => parser.complete(state),
+		getDocFragments: (state, defaultValue) => {
+			const { description, fragments } = parser.getDocFragments(state, defaultValue);
+			const allEntries = [];
+			const titledSections = [];
+			for (const fragment of fragments) if (fragment.type === "entry") allEntries.push(fragment);
+			else if (fragment.type === "section") if (fragment.title) titledSections.push(fragment);
+			else allEntries.push(...fragment.entries);
+			const labeledSection = {
+				title: label,
+				entries: allEntries
+			};
+			return {
+				description,
+				fragments: [...titledSections.map((s) => ({
+					...s,
+					type: "section"
+				})), {
+					type: "section",
+					...labeledSection
+				}]
+			};
+		}
+	};
+}
+/**
 * Generates a documentation page for a parser based on its current state after
 * attempting to parse the provided arguments. This function is useful for
 * creating help documentation that reflects the current parsing context.
@@ -1570,4 +1645,4 @@ function getDocPage(parser, args = []) {
 }
 
 //#endregion
-export { argument, command, concat, constant, flag, getDocPage, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };
+export { argument, command, concat, constant, flag, getDocPage, group, longestMatch, map, merge, multiple, object, option, optional, or, parse, tuple, withDefault };

package/dist/valueparser.cjs

@@ -84,7 +84,7 @@ function string(options = {}) {
 * @example
 * ```typescript
 * // Create a parser for regular integers
-* const portParser = integer({ min: 1, max: 65535 });
+* const portParser = integer({ min: 1, max: 0xffff });
 *
 * // Create a parser for BigInt values
 * const bigIntParser = integer({ type: "bigint", min: 0n });

package/dist/valueparser.js

@@ -84,7 +84,7 @@ function string(options = {}) {
 * @example
 * ```typescript
 * // Create a parser for regular integers
-* const portParser = integer({ min: 1, max: 65535 });
+* const portParser = integer({ min: 1, max: 0xffff });
 *
 * // Create a parser for BigInt values
 * const bigIntParser = integer({ type: "bigint", min: 0n });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "0.4.0-dev.52+12ee9e92",
+  "version": "0.4.0-dev.54+e30f3e5c",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",