@optique/core 1.0.0-dev.511 → 1.0.0-dev.515

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.
@@ -1091,6 +1100,9 @@ type MergeReturnType<TParsers extends MergeParsers> = Parser<CombineModes<{ read
 /**
  * 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.
@@ -1100,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.
@@ -1109,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.
@@ -1119,6 +1137,9 @@ declare function merge<const TParsers extends MergeParsers>(label: string, ...pa
 /**
  * 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.
@@ -1138,6 +1159,35 @@ 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
+ * import { parse } from "@optique/core/parser";
+ * import { option } from "@optique/core/primitives";
+ * import { integer, string } from "@optique/core/valueparser";
+ *
+ * const basicTuple = tuple([
+ *   option("-v", "--verbose"),
+ *   option("-p", "--port", integer()),
+ * ]);
+ *
+ * const serverTuple = tuple([
+ *   option("-h", "--host", string()),
+ *   option("-d", "--debug"),
+ * ]);
+ *
+ * const combined = concat(basicTuple, serverTuple);
+ * // Inferred type: Parser<..., [boolean, number, string, boolean], ...>
+ *
+ * const result = parse(
+ *   combined,
+ *   ["-v", "-p", "8080", "-h", "localhost", "-d"],
+ * );
+ * // result.value: [true, 8080, "localhost", true]
+ * ```
+ *
  * @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.
@@ -1091,6 +1100,9 @@ type MergeReturnType<TParsers extends MergeParsers> = Parser<CombineModes<{ read
 /**
  * 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.
@@ -1100,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.
@@ -1109,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.
@@ -1119,6 +1137,9 @@ declare function merge<const TParsers extends MergeParsers>(label: string, ...pa
 /**
  * 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.
@@ -1138,6 +1159,35 @@ 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
+ * import { parse } from "@optique/core/parser";
+ * import { option } from "@optique/core/primitives";
+ * import { integer, string } from "@optique/core/valueparser";
+ *
+ * const basicTuple = tuple([
+ *   option("-v", "--verbose"),
+ *   option("-p", "--port", integer()),
+ * ]);
+ *
+ * const serverTuple = tuple([
+ *   option("-h", "--host", string()),
+ *   option("-d", "--debug"),
+ * ]);
+ *
+ * const combined = concat(basicTuple, serverTuple);
+ * // Inferred type: Parser<..., [boolean, number, string, boolean], ...>
+ *
+ * const result = parse(
+ *   combined,
+ *   ["-v", "-p", "8080", "-h", "localhost", "-d"],
+ * );
+ * // result.value: [true, 8080, "localhost", true]
+ * ```
+ *
  * @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.511+2a5e3e40",
+  "version": "1.0.0-dev.515+abdd200c",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",