@optique/core 1.0.0-dev.1313 → 1.0.0-dev.1323

package/dist/constructs.cjs

@@ -304,6 +304,7 @@ function or(...args) {
 		parsers = args;
 		options = void 0;
 	}
+	if (parsers.length < 1) throw new TypeError("or() requires at least one parser argument.");
 	const noMatchContext = analyzeNoMatchContext(parsers);
 	const combinedMode = parsers.some((p) => p.$mode === "async") ? "async" : "sync";
 	const syncParsers = parsers;
@@ -505,6 +506,7 @@ function longestMatch(...args) {
 		parsers = args;
 		options = void 0;
 	}
+	if (parsers.length < 1) throw new TypeError("longestMatch() requires at least one parser argument.");
 	const noMatchContext = analyzeNoMatchContext(parsers);
 	const combinedMode = parsers.some((p) => p.$mode === "async") ? "async" : "sync";
 	const syncParsers = parsers;
@@ -1656,6 +1658,7 @@ function merge(...args) {
 	const startIndex = typeof args[0] === "string" ? 1 : 0;
 	const endIndex = hasOptions ? args.length - 1 : args.length;
 	const rawParsers = args.slice(startIndex, endIndex);
+	if (rawParsers.length < 1) throw new TypeError("merge() requires at least one parser argument.");
 	const combinedMode = rawParsers.some((p) => p.$mode === "async") ? "async" : "sync";
 	const isAsync = combinedMode === "async";
 	const syncRawParsers = rawParsers;
@@ -2098,6 +2101,7 @@ function tryParseSuggestList(context, stateArray, parsers, matchedParsers, remai
 	return null;
 }
 function concat(...parsers) {
+	if (parsers.length < 1) throw new TypeError("concat() requires at least one parser argument.");
 	const combinedMode = parsers.some((p) => p.$mode === "async") ? "async" : "sync";
 	const isAsync = combinedMode === "async";
 	const syncParsers = parsers;

package/dist/constructs.d.cts

@@ -730,6 +730,7 @@ declare function or<MA extends Mode, MB extends Mode, MC extends Mode, MD extend
  * @param options Custom error message options.
  * @return A {@link Parser} that tries to parse using the provided parsers
  *         in order, returning the result of the first successful parser.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<MA extends Mode, MB extends Mode, TA, TB, TStateA, TStateB>(a: Parser<MA, TA, TStateA>, b: Parser<MB, TB, TStateB>, options: OrOptions): Parser<CombineModes<readonly [MA, MB]>, TA | TB, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>]>;
@@ -751,6 +752,7 @@ declare function or<MA extends Mode, MB extends Mode, TA, TB, TStateA, TStateB>(
  * @param options Custom error message options.
  * @return A {@link Parser} that tries to parse using the provided parsers
  *         in order, returning the result of the first successful parser.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<MA extends Mode, MB extends Mode, MC extends Mode, TA, TB, TC, TStateA, TStateB, TStateC>(a: Parser<MA, TA, TStateA>, b: Parser<MB, TB, TStateB>, c: Parser<MC, TC, TStateC>, options: OrOptions): Parser<CombineModes<readonly [MA, MB, MC]>, TA | TB | TC, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>] | [2, ParserResult<TStateC>]>;
@@ -760,6 +762,7 @@ declare function or<MA extends Mode, MB extends Mode, MC extends Mode, TA, TB, T
  * @param rest Parsers to try, followed by {@link OrOptions} for error
  *             customization.
  * @returns A parser that succeeds if any of the input parsers succeed.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<const TParsers extends readonly Parser<Mode, unknown, unknown>[]>(...rest: [...parsers: TParsers, options: OrTailOptions] & OrArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, InferValue<TParsers[number]>, undefined | [number, ParserResult<unknown>]>;
@@ -767,6 +770,7 @@ declare function or<const TParsers extends readonly Parser<Mode, unknown, unknow
  * Creates a parser that tries each parser in sequence until one succeeds.
  * @param parsers Parsers to try in order.
  * @returns A parser that succeeds if any of the input parsers succeed.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<const TParsers extends readonly Parser<Mode, unknown, unknown>[]>(...parsers: TParsers & OrArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, InferValue<TParsers[number]>, undefined | [number, ParserResult<unknown>]>;
@@ -860,6 +864,7 @@ declare function longestMatch<const TParsers extends readonly Parser<"sync", unk
  * @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.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function longestMatch<const TParsers extends readonly Parser<"sync", unknown, unknown>[]>(...rest: [...parsers: TParsers, options: LongestMatchTailOptions] & LongestMatchArityGuard<TParsers>): Parser<"sync", InferValue<TParsers[number]>, LongestMatchState<TParsers>>;
@@ -870,6 +875,7 @@ declare function longestMatch<const TParsers extends readonly Parser<"sync", unk
  * @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.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function longestMatch<const TParsers extends readonly Parser<Mode, unknown, unknown>[]>(...rest: [...parsers: TParsers, options: LongestMatchTailOptions] & LongestMatchArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, InferValue<TParsers[number]>, LongestMatchState<TParsers>>;
@@ -1131,6 +1137,7 @@ type MergeReturnType<TParsers extends MergeParsers> = Parser<CombineModes<{ read
  * @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.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.7.0
  */
 declare function merge<const TParsers extends MergeParsers>(...rest: [...parsers: EnsureMergeParsers<TParsers>, options: MergeTailOptions] & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1144,6 +1151,7 @@ declare function merge<const TParsers extends MergeParsers>(...rest: [...parsers
  * @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.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.4.0
  */
 declare function merge<const TParsers extends MergeParsers>(label: string, ...parsers: EnsureMergeParsers<TParsers> & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1157,6 +1165,7 @@ declare function merge<const TParsers extends MergeParsers>(label: string, ...pa
  * @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.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.7.0
  */
 declare function merge<const TParsers extends MergeParsers>(label: string, ...rest: [...parsers: EnsureMergeParsers<TParsers>, options: MergeTailOptions] & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1169,6 +1178,7 @@ declare function merge<const TParsers extends MergeParsers>(label: string, ...re
  * @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.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.1.0
  */
 declare function merge<const TParsers extends MergeParsers>(...parsers: EnsureMergeParsers<TParsers> & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1216,6 +1226,7 @@ type ConcatValues<TParsers extends ConcatParsers> = IsTuple<TParsers> extends tr
  * @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.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.2.0
  */
 declare function concat<const TParsers extends ConcatParsers>(...parsers: TParsers & ConcatArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, ConcatValues<TParsers>, ConcatStates<TParsers>>;

package/dist/constructs.d.ts

@@ -730,6 +730,7 @@ declare function or<MA extends Mode, MB extends Mode, MC extends Mode, MD extend
  * @param options Custom error message options.
  * @return A {@link Parser} that tries to parse using the provided parsers
  *         in order, returning the result of the first successful parser.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<MA extends Mode, MB extends Mode, TA, TB, TStateA, TStateB>(a: Parser<MA, TA, TStateA>, b: Parser<MB, TB, TStateB>, options: OrOptions): Parser<CombineModes<readonly [MA, MB]>, TA | TB, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>]>;
@@ -751,6 +752,7 @@ declare function or<MA extends Mode, MB extends Mode, TA, TB, TStateA, TStateB>(
  * @param options Custom error message options.
  * @return A {@link Parser} that tries to parse using the provided parsers
  *         in order, returning the result of the first successful parser.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<MA extends Mode, MB extends Mode, MC extends Mode, TA, TB, TC, TStateA, TStateB, TStateC>(a: Parser<MA, TA, TStateA>, b: Parser<MB, TB, TStateB>, c: Parser<MC, TC, TStateC>, options: OrOptions): Parser<CombineModes<readonly [MA, MB, MC]>, TA | TB | TC, undefined | [0, ParserResult<TStateA>] | [1, ParserResult<TStateB>] | [2, ParserResult<TStateC>]>;
@@ -760,6 +762,7 @@ declare function or<MA extends Mode, MB extends Mode, MC extends Mode, TA, TB, T
  * @param rest Parsers to try, followed by {@link OrOptions} for error
  *             customization.
  * @returns A parser that succeeds if any of the input parsers succeed.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<const TParsers extends readonly Parser<Mode, unknown, unknown>[]>(...rest: [...parsers: TParsers, options: OrTailOptions] & OrArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, InferValue<TParsers[number]>, undefined | [number, ParserResult<unknown>]>;
@@ -767,6 +770,7 @@ declare function or<const TParsers extends readonly Parser<Mode, unknown, unknow
  * Creates a parser that tries each parser in sequence until one succeeds.
  * @param parsers Parsers to try in order.
  * @returns A parser that succeeds if any of the input parsers succeed.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function or<const TParsers extends readonly Parser<Mode, unknown, unknown>[]>(...parsers: TParsers & OrArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, InferValue<TParsers[number]>, undefined | [number, ParserResult<unknown>]>;
@@ -860,6 +864,7 @@ declare function longestMatch<const TParsers extends readonly Parser<"sync", unk
  * @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.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function longestMatch<const TParsers extends readonly Parser<"sync", unknown, unknown>[]>(...rest: [...parsers: TParsers, options: LongestMatchTailOptions] & LongestMatchArityGuard<TParsers>): Parser<"sync", InferValue<TParsers[number]>, LongestMatchState<TParsers>>;
@@ -870,6 +875,7 @@ declare function longestMatch<const TParsers extends readonly Parser<"sync", unk
  * @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.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.5.0
  */
 declare function longestMatch<const TParsers extends readonly Parser<Mode, unknown, unknown>[]>(...rest: [...parsers: TParsers, options: LongestMatchTailOptions] & LongestMatchArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, InferValue<TParsers[number]>, LongestMatchState<TParsers>>;
@@ -1131,6 +1137,7 @@ type MergeReturnType<TParsers extends MergeParsers> = Parser<CombineModes<{ read
  * @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.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.7.0
  */
 declare function merge<const TParsers extends MergeParsers>(...rest: [...parsers: EnsureMergeParsers<TParsers>, options: MergeTailOptions] & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1144,6 +1151,7 @@ declare function merge<const TParsers extends MergeParsers>(...rest: [...parsers
  * @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.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.4.0
  */
 declare function merge<const TParsers extends MergeParsers>(label: string, ...parsers: EnsureMergeParsers<TParsers> & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1157,6 +1165,7 @@ declare function merge<const TParsers extends MergeParsers>(label: string, ...pa
  * @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.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.7.0
  */
 declare function merge<const TParsers extends MergeParsers>(label: string, ...rest: [...parsers: EnsureMergeParsers<TParsers>, options: MergeTailOptions] & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1169,6 +1178,7 @@ declare function merge<const TParsers extends MergeParsers>(label: string, ...re
  * @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.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.1.0
  */
 declare function merge<const TParsers extends MergeParsers>(...parsers: EnsureMergeParsers<TParsers> & MergeArityGuard<TParsers>): MergeReturnType<TParsers>;
@@ -1216,6 +1226,7 @@ type ConcatValues<TParsers extends ConcatParsers> = IsTuple<TParsers> extends tr
  * @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.
+ * @throws {TypeError} If no parser arguments are provided.
  * @since 0.2.0
  */
 declare function concat<const TParsers extends ConcatParsers>(...parsers: TParsers & ConcatArityGuard<TParsers>): Parser<CombineModes<{ readonly [K in keyof TParsers]: ExtractMode<TParsers[K]> }>, ConcatValues<TParsers>, ConcatStates<TParsers>>;

package/dist/constructs.js

@@ -304,6 +304,7 @@ function or(...args) {
 		parsers = args;
 		options = void 0;
 	}
+	if (parsers.length < 1) throw new TypeError("or() requires at least one parser argument.");
 	const noMatchContext = analyzeNoMatchContext(parsers);
 	const combinedMode = parsers.some((p) => p.$mode === "async") ? "async" : "sync";
 	const syncParsers = parsers;
@@ -505,6 +506,7 @@ function longestMatch(...args) {
 		parsers = args;
 		options = void 0;
 	}
+	if (parsers.length < 1) throw new TypeError("longestMatch() requires at least one parser argument.");
 	const noMatchContext = analyzeNoMatchContext(parsers);
 	const combinedMode = parsers.some((p) => p.$mode === "async") ? "async" : "sync";
 	const syncParsers = parsers;
@@ -1656,6 +1658,7 @@ function merge(...args) {
 	const startIndex = typeof args[0] === "string" ? 1 : 0;
 	const endIndex = hasOptions ? args.length - 1 : args.length;
 	const rawParsers = args.slice(startIndex, endIndex);
+	if (rawParsers.length < 1) throw new TypeError("merge() requires at least one parser argument.");
 	const combinedMode = rawParsers.some((p) => p.$mode === "async") ? "async" : "sync";
 	const isAsync = combinedMode === "async";
 	const syncRawParsers = rawParsers;
@@ -2098,6 +2101,7 @@ function tryParseSuggestList(context, stateArray, parsers, matchedParsers, remai
 	return null;
 }
 function concat(...parsers) {
+	if (parsers.length < 1) throw new TypeError("concat() requires at least one parser argument.");
 	const combinedMode = parsers.some((p) => p.$mode === "async") ? "async" : "sync";
 	const isAsync = combinedMode === "async";
 	const syncParsers = parsers;

package/dist/doc.cjs

@@ -51,7 +51,8 @@ function defaultSectionOrder(a, b) {
 * any non-empty section's title is empty, whitespace-only, or contains a CR
 * or LF character, or if `maxWidth` is not a finite integer.
 * @throws {RangeError} If any entry needs a description column and `maxWidth`
-* is too small to fit the minimum layout (less than `termIndent + 4`).
+* is too small to fit the minimum layout (less than `termIndent + 4`), or if
+* `showChoices.maxItems` is less than `1`.
 *
 * @example
 * ```typescript
@@ -87,6 +88,10 @@ function formatDocPage(programName, page, options = {}) {
 		...page,
 		sections: filteredSections
 	};
+	if (typeof options.showChoices === "object" && options.showChoices.maxItems != null) {
+		const maxItems = options.showChoices.maxItems;
+		if (maxItems < 1) throw new RangeError(`showChoices.maxItems must be at least 1, but got ${maxItems}.`);
+	}
 	const hasContent = (msg) => Array.isArray(msg) && msg.length > 0;
 	if (options.maxWidth != null) {
 		const hasEntries = page.sections.some((s) => s.entries.length > 0);

package/dist/doc.d.cts

@@ -148,9 +148,10 @@ interface ShowChoicesOptions {
   readonly label?: string;
   /**
    * Maximum number of choice values to display before truncating with
-   * `...`.  Set to `Infinity` to show all choices.
+   * `...`.  Must be at least `1`.  Set to `Infinity` to show all choices.
    *
    * @default `8`
+   * @throws {RangeError} If the value is less than `1`.
    */
   readonly maxItems?: number;
 }
@@ -267,7 +268,8 @@ interface DocPageFormatOptions {
  * any non-empty section's title is empty, whitespace-only, or contains a CR
  * or LF character, or if `maxWidth` is not a finite integer.
  * @throws {RangeError} If any entry needs a description column and `maxWidth`
- * is too small to fit the minimum layout (less than `termIndent + 4`).
+ * is too small to fit the minimum layout (less than `termIndent + 4`), or if
+ * `showChoices.maxItems` is less than `1`.
  *
  * @example
  * ```typescript

package/dist/doc.d.ts

@@ -148,9 +148,10 @@ interface ShowChoicesOptions {
   readonly label?: string;
   /**
    * Maximum number of choice values to display before truncating with
-   * `...`.  Set to `Infinity` to show all choices.
+   * `...`.  Must be at least `1`.  Set to `Infinity` to show all choices.
    *
    * @default `8`
+   * @throws {RangeError} If the value is less than `1`.
    */
   readonly maxItems?: number;
 }
@@ -267,7 +268,8 @@ interface DocPageFormatOptions {
  * any non-empty section's title is empty, whitespace-only, or contains a CR
  * or LF character, or if `maxWidth` is not a finite integer.
  * @throws {RangeError} If any entry needs a description column and `maxWidth`
- * is too small to fit the minimum layout (less than `termIndent + 4`).
+ * is too small to fit the minimum layout (less than `termIndent + 4`), or if
+ * `showChoices.maxItems` is less than `1`.
  *
  * @example
  * ```typescript

package/dist/doc.js

@@ -51,7 +51,8 @@ function defaultSectionOrder(a, b) {
 * any non-empty section's title is empty, whitespace-only, or contains a CR
 * or LF character, or if `maxWidth` is not a finite integer.
 * @throws {RangeError} If any entry needs a description column and `maxWidth`
-* is too small to fit the minimum layout (less than `termIndent + 4`).
+* is too small to fit the minimum layout (less than `termIndent + 4`), or if
+* `showChoices.maxItems` is less than `1`.
 *
 * @example
 * ```typescript
@@ -87,6 +88,10 @@ function formatDocPage(programName, page, options = {}) {
 		...page,
 		sections: filteredSections
 	};
+	if (typeof options.showChoices === "object" && options.showChoices.maxItems != null) {
+		const maxItems = options.showChoices.maxItems;
+		if (maxItems < 1) throw new RangeError(`showChoices.maxItems must be at least 1, but got ${maxItems}.`);
+	}
 	const hasContent = (msg) => Array.isArray(msg) && msg.length > 0;
 	if (options.maxWidth != null) {
 		const hasEntries = page.sections.some((s) => s.entries.length > 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1313+758f4e24",
+  "version": "1.0.0-dev.1323+0653ad71",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",