@optique/core 1.0.0-dev.509 → 1.0.0-dev.513

package/dist/constructs.d.cts

@@ -838,6 +838,9 @@ type LongestMatchArityGuard<TParsers extends readonly unknown[]> = IsTuple<TPars
  * Creates a parser that selects the successful branch that consumed
  * the most input tokens.
  *
+ * The resulting parser tries every given parser and returns the
+ * successful result that consumed more input than the others.
+ *
  * @param parsers Parsers to evaluate and compare by consumed input.
  * @returns A parser that yields the best successful branch result.
  * Type inference is precise for tuple calls up to 15 parser arguments.
@@ -848,6 +851,9 @@ declare function longestMatch<const TParsers extends readonly Parser<"sync", unk
  * Creates a parser that selects the successful branch that consumed
  * the most input tokens.
  *
+ * The resulting parser tries every given parser and returns the
+ * successful result that consumed more input than the others.
+ *
  * @param parsers Parsers to evaluate and compare by consumed input.
  * @returns A parser that yields the best successful branch result.
  * Type inference is precise for tuple calls up to 15 parser arguments.
@@ -858,6 +864,9 @@ declare function longestMatch<const TParsers extends readonly Parser<Mode, unkno
  * Creates a parser that selects the successful branch that consumed
  * the most input tokens, with custom error options.
  *
+ * The resulting parser tries every given parser and returns the
+ * successful result that consumed more input than the others.
+ *
  * @param rest Parsers to compare, followed by error customization options.
  * @returns A parser that yields the best successful branch result.
  * Type inference is precise for tuple calls up to 15 parser arguments.
@@ -1085,11 +1094,15 @@ type MergeTailOptions = MergeOptions & {
 type MergeArityGuard<TParsers extends readonly unknown[]> = IsTuple<TParsers> extends true ? TParsers["length"] extends MergeParserArity ? unknown : MergeArityLimitError : unknown;
 type MergeParsers = readonly Parser<Mode, unknown, unknown>[];
 type EnsureMergeParsers<TParsers extends MergeParsers> = { readonly [K in keyof TParsers]: ExtractObjectTypes<TParsers[K]> extends never ? never : TParsers[K] };
-type MergeValues<TParsers extends MergeParsers> = TParsers extends readonly [infer THead extends Parser<Mode, unknown, unknown>, ...infer TRest extends MergeParsers] ? ExtractObjectTypes<THead> & MergeValues<TRest> : Record<string | symbol, unknown>;
+type IntersectMergeValues<TParsers extends MergeParsers> = TParsers extends readonly [infer THead extends Parser<Mode, unknown, unknown>, ...infer TRest extends MergeParsers] ? ExtractObjectTypes<THead> & IntersectMergeValues<TRest> : unknown;
+type MergeValues<TParsers extends MergeParsers> = IsTuple<TParsers> extends true ? IntersectMergeValues<TParsers> : Record<string | symbol, unknown>;
 type MergeReturnType<TParsers extends MergeParsers> = Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, MergeValues<TParsers>, Record<string | symbol, unknown>>;
 /**
  * Merges multiple object-like parsers into one parser.
  *
+ * This is useful for combining separate object parsers into one
+ * unified parser while keeping fields grouped by parser boundaries.
+ *
  * @param parsers Parsers to merge in declaration order.
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
@@ -1099,6 +1112,9 @@ declare function merge<const TParsers extends MergeParsers>(...parsers: EnsureMe
 /**
  * Merges multiple object-like parsers into one parser, with options.
  *
+ * This is useful for combining separate object parsers into one
+ * unified parser while keeping fields grouped by parser boundaries.
+ *
  * @param rest Parsers to merge, followed by merge options.
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
@@ -1108,6 +1124,9 @@ declare function merge<const TParsers extends MergeParsers>(...rest: [...parsers
 /**
  * Merges multiple object-like parsers into one labeled parser.
  *
+ * This is useful for combining separate object parsers into one
+ * unified parser while keeping fields grouped by parser boundaries.
+ *
  * @param label Label used in documentation output.
  * @param parsers Parsers to merge in declaration order.
  * @returns A parser that merges parsed object fields from all parsers.
@@ -1115,6 +1134,19 @@ declare function merge<const TParsers extends MergeParsers>(...rest: [...parsers
  * @since 0.4.0
  */
 declare function merge<const TParsers extends MergeParsers>(label: string, ...parsers: EnsureMergeParsers<TParsers> & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
+/**
+ * Merges multiple object-like parsers into one labeled parser, with options.
+ *
+ * This is useful for combining separate object parsers into one
+ * unified parser while keeping fields grouped by parser boundaries.
+ *
+ * @param label Label used in documentation output.
+ * @param rest Parsers to merge, followed by merge options.
+ * @returns A parser that merges parsed object fields from all parsers.
+ * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @since 0.7.0
+ */
+declare function merge<const TParsers extends MergeParsers>(label: string, ...rest: [...parsers: EnsureMergeParsers<TParsers>, options: MergeTailOptions] & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
 type ConcatParserArity = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15;
 type ConcatArityLimitError = {
   readonly __optiqueConcatArityLimit: "concat() requires between 1 and 15 parser arguments. Nest concat() to combine more.";
@@ -1127,6 +1159,15 @@ type ConcatValues<TParsers extends ConcatParsers> = IsTuple<TParsers> extends tr
 /**
  * Concatenates tuple parsers into one parser with a flattened tuple value.
  *
+ * Unlike {@link merge}, which combines object fields, this combines tuple
+ * entries in order into one flattened tuple value.
+ *
+ * @example
+ * ```typescript
+ * const parser = concat(tuple([string()]), tuple([number()]));
+ * // parser value: [string, number]
+ * ```
+ *
  * @param parsers Tuple parsers to concatenate.
  * @returns A parser with flattened tuple values from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.

package/dist/constructs.d.ts

@@ -838,6 +838,9 @@ type LongestMatchArityGuard<TParsers extends readonly unknown[]> = IsTuple<TPars
  * Creates a parser that selects the successful branch that consumed
  * the most input tokens.
  *
+ * The resulting parser tries every given parser and returns the
+ * successful result that consumed more input than the others.
+ *
  * @param parsers Parsers to evaluate and compare by consumed input.
  * @returns A parser that yields the best successful branch result.
  * Type inference is precise for tuple calls up to 15 parser arguments.
@@ -848,6 +851,9 @@ declare function longestMatch<const TParsers extends readonly Parser<"sync", unk
  * Creates a parser that selects the successful branch that consumed
  * the most input tokens.
  *
+ * The resulting parser tries every given parser and returns the
+ * successful result that consumed more input than the others.
+ *
  * @param parsers Parsers to evaluate and compare by consumed input.
  * @returns A parser that yields the best successful branch result.
  * Type inference is precise for tuple calls up to 15 parser arguments.
@@ -858,6 +864,9 @@ declare function longestMatch<const TParsers extends readonly Parser<Mode, unkno
  * Creates a parser that selects the successful branch that consumed
  * the most input tokens, with custom error options.
  *
+ * The resulting parser tries every given parser and returns the
+ * successful result that consumed more input than the others.
+ *
  * @param rest Parsers to compare, followed by error customization options.
  * @returns A parser that yields the best successful branch result.
  * Type inference is precise for tuple calls up to 15 parser arguments.
@@ -1085,11 +1094,15 @@ type MergeTailOptions = MergeOptions & {
 type MergeArityGuard<TParsers extends readonly unknown[]> = IsTuple<TParsers> extends true ? TParsers["length"] extends MergeParserArity ? unknown : MergeArityLimitError : unknown;
 type MergeParsers = readonly Parser<Mode, unknown, unknown>[];
 type EnsureMergeParsers<TParsers extends MergeParsers> = { readonly [K in keyof TParsers]: ExtractObjectTypes<TParsers[K]> extends never ? never : TParsers[K] };
-type MergeValues<TParsers extends MergeParsers> = TParsers extends readonly [infer THead extends Parser<Mode, unknown, unknown>, ...infer TRest extends MergeParsers] ? ExtractObjectTypes<THead> & MergeValues<TRest> : Record<string | symbol, unknown>;
+type IntersectMergeValues<TParsers extends MergeParsers> = TParsers extends readonly [infer THead extends Parser<Mode, unknown, unknown>, ...infer TRest extends MergeParsers] ? ExtractObjectTypes<THead> & IntersectMergeValues<TRest> : unknown;
+type MergeValues<TParsers extends MergeParsers> = IsTuple<TParsers> extends true ? IntersectMergeValues<TParsers> : Record<string | symbol, unknown>;
 type MergeReturnType<TParsers extends MergeParsers> = Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, MergeValues<TParsers>, Record<string | symbol, unknown>>;
 /**
  * Merges multiple object-like parsers into one parser.
  *
+ * This is useful for combining separate object parsers into one
+ * unified parser while keeping fields grouped by parser boundaries.
+ *
  * @param parsers Parsers to merge in declaration order.
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
@@ -1099,6 +1112,9 @@ declare function merge<const TParsers extends MergeParsers>(...parsers: EnsureMe
 /**
  * Merges multiple object-like parsers into one parser, with options.
  *
+ * This is useful for combining separate object parsers into one
+ * unified parser while keeping fields grouped by parser boundaries.
+ *
  * @param rest Parsers to merge, followed by merge options.
  * @returns A parser that merges parsed object fields from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.
@@ -1108,6 +1124,9 @@ declare function merge<const TParsers extends MergeParsers>(...rest: [...parsers
 /**
  * Merges multiple object-like parsers into one labeled parser.
  *
+ * This is useful for combining separate object parsers into one
+ * unified parser while keeping fields grouped by parser boundaries.
+ *
  * @param label Label used in documentation output.
  * @param parsers Parsers to merge in declaration order.
  * @returns A parser that merges parsed object fields from all parsers.
@@ -1115,6 +1134,19 @@ declare function merge<const TParsers extends MergeParsers>(...rest: [...parsers
  * @since 0.4.0
  */
 declare function merge<const TParsers extends MergeParsers>(label: string, ...parsers: EnsureMergeParsers<TParsers> & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
+/**
+ * Merges multiple object-like parsers into one labeled parser, with options.
+ *
+ * This is useful for combining separate object parsers into one
+ * unified parser while keeping fields grouped by parser boundaries.
+ *
+ * @param label Label used in documentation output.
+ * @param rest Parsers to merge, followed by merge options.
+ * @returns A parser that merges parsed object fields from all parsers.
+ * Type inference is precise for tuple calls up to 15 parser arguments.
+ * @since 0.7.0
+ */
+declare function merge<const TParsers extends MergeParsers>(label: string, ...rest: [...parsers: EnsureMergeParsers<TParsers>, options: MergeTailOptions] & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
 type ConcatParserArity = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15;
 type ConcatArityLimitError = {
   readonly __optiqueConcatArityLimit: "concat() requires between 1 and 15 parser arguments. Nest concat() to combine more.";
@@ -1127,6 +1159,15 @@ type ConcatValues<TParsers extends ConcatParsers> = IsTuple<TParsers> extends tr
 /**
  * Concatenates tuple parsers into one parser with a flattened tuple value.
  *
+ * Unlike {@link merge}, which combines object fields, this combines tuple
+ * entries in order into one flattened tuple value.
+ *
+ * @example
+ * ```typescript
+ * const parser = concat(tuple([string()]), tuple([number()]));
+ * // parser value: [string, number]
+ * ```
+ *
  * @param parsers Tuple parsers to concatenate.
  * @returns A parser with flattened tuple values from all parsers.
  * Type inference is precise for tuple calls up to 15 parser arguments.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.509+52b4f7b6",
+  "version": "1.0.0-dev.513+486612c6",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",