cli-kiss 0.2.7 → 0.2.9

package/dist/index.d.ts

@@ -1,47 +1,37 @@
 /**
- * Opaque key returned by {@link ReaderArgs.registerOption}.
+ * Represents the parsing specification for a long option
  */
-type ReaderOptionKey = (string | {
-    __brand: "ReaderOptionKey";
-}) & {
-    __brand: "ReaderOptionKey";
+type ReaderOptionLongSpec = {
+    key: string;
+    nextGuard: ReaderOptionNextGuard;
 };
 /**
- * Parsing behaviour for a registered option, passed to {@link ReaderArgs.registerOption}.
+ * Represents the parsing specification for a short option
  */
-type ReaderOptionParsing = {
-    consumeShortGroup: boolean;
-    consumeNextArg: (inlined: string | null, separated: Array<string>, nextArg: string | undefined) => boolean;
+type ReaderOptionShortSpec = ReaderOptionLongSpec & {
+    consumeGroupRestAsValue: boolean;
 };
 /**
- * Result of parsing an option, including its inlined value and any following separated values.
+ * Determines whether the next token is valid for a given option.
+ */
+type ReaderOptionNextGuard = (value: ReaderOptionValue, next: string | undefined) => boolean;
+/**
+ * Represents the values parsed for an option.
  */
 type ReaderOptionValue = {
     inlined: string | null;
-    separated: Array<string>;
+    separated: ReadonlyArray<string>;
 };
+/**
+ * Returns the parsed values for a registered option.
+ */
+type ReaderOptionGetter = () => ReadonlyArray<ReaderOptionValue>;
 /**
  * Option registration/query interface. Subset of {@link ReaderArgs}.
  */
 type ReaderOptions = {
-    /**
-     * Registers an option; all `longs` and `shorts` share the same key.
-     *
-     * @param definition.longs - Long-form names (without `--`).
-     * @param definition.shorts - Short-form names (without `-`).
-     * @param definition.parsing - Parsing behaviour.
-     * @returns A {@link ReaderOptionKey} for later retrieval.
-     * @throws `Error` if a name is already registered or short names overlap.
-     */
-    registerOption(definition: {
-        longs: Array<string>;
-        shorts: Array<string>;
-        parsing: ReaderOptionParsing;
-    }): ReaderOptionKey;
-    /**
-     * Returns all values collected for `key`.
-     */
-    getOptionValues(key: ReaderOptionKey): Array<ReaderOptionValue>;
+    registerOptionLong(longSpec: ReaderOptionLongSpec): ReaderOptionGetter;
+    registerOptionShort(shortSpec: ReaderOptionShortSpec): ReaderOptionGetter;
 };
 /**
  * Positional consumption interface. Subset of {@link ReaderArgs}.
@@ -51,7 +41,7 @@ type ReaderPositionals = {
      * Returns the next positional token, parsing intervening options as side-effects.
      *
      * @returns The next positional, or `undefined` when exhausted.
-     * @throws {@link TypoError} on an unrecognised option.
+     * @throws on an unrecognised option.
      */
     consumePositional(): string | undefined;
 };
@@ -67,38 +57,23 @@ type ReaderPositionals = {
 declare class ReaderArgs {
     #private;
     /**
-     * @param args - Raw CLI tokens (e.g. `process.argv.slice(2)`). Not mutated.
+     * @param tokens - Raw CLI tokens (e.g. `process.argv.slice(2)`).
      */
-    constructor(args: ReadonlyArray<string>);
+    constructor(tokens: ReadonlyArray<string>);
     /**
-     * Registers an option; all `longs` and `shorts` share the same key.
-     * Short names must not be prefixes of one another.
-     *
-     * @param definition.longs - Long-form names (without `--`).
-     * @param definition.shorts - Short-form names (without `-`).
-     * @param definition.parsing - Parsing behaviour.
-     * @returns A {@link ReaderOptionKey} for {@link ReaderArgs.getOptionValues}.
-     * @throws `Error` if any name is already registered or short names overlap.
-     */
-    registerOption(definition: {
-        longs: Array<string>;
-        shorts: Array<string>;
-        parsing: ReaderOptionParsing;
-    }): ReaderOptionKey;
-    /**
-     * Returns all values collected for `key`.
-     *
-     * @param key - Key from {@link ReaderArgs.registerOption}.
-     * @returns One entry per occurrence.
-     * @throws `Error` if `key` was not registered.
+     * Registers a long option and returns a getter for its parsed values.
+     */
+    registerOptionLong(longSpec: ReaderOptionLongSpec): ReaderOptionGetter;
+    /**
+     * Registers a short option and returns a getter for its parsed values.
      */
-    getOptionValues(key: ReaderOptionKey): Array<ReaderOptionValue>;
+    registerOptionShort(shortSpec: ReaderOptionShortSpec): ReaderOptionGetter;
     /**
      * Returns the next positional token; parses intervening options as a side-effect.
      * All tokens after `--` are treated as positionals.
      *
      * @returns The next positional, or `undefined` when exhausted.
-     * @throws {@link TypoError} on an unrecognised option.
+     * @throws on an unrecognised option.
      */
     consumePositional(): string | undefined;
 }
@@ -107,15 +82,26 @@ declare class ReaderArgs {
  * Decodes a raw CLI string into a typed value.
  * A pair of a human-readable `content` name and a `decoder` function.
  *
- * Built-in: {@link type}, {@link typeBoolean}, {@link typeNumber},
- * {@link typeInteger}, {@link typeDatetime}, {@link typeUrl}.
- * Composite: {@link typeChoice}, {@link typeConverted}, {@link typeTuple}, {@link typeList}.
+ * Primitive Types:
+ * - {@link typeString}
+ * - {@link typeBoolean}
+ * - {@link typeNumber},
+ * - {@link typeInteger}
+ * - {@link typeDatetime}
+ * - {@link typeUrl}
+ * - {@link typePath}
+ * - {@link typeChoice}
+ *
+ * Composed Types:
+ * - {@link typeMapped}
+ * - {@link typeTuple}
+ * - {@link typeList}
  *
  * @typeParam Value - Type produced by the decoder.
  */
 type Type<Value> = {
     /**
-     * Human-readable name shown in help and errors (e.g. `"name"`, `"number"`).
+     * Human-readable name shown in help and errors (e.g. `"name"`, `"context"`).
      */
     content: string;
     /**
@@ -123,10 +109,20 @@ type Type<Value> = {
      *
      * @param input - Raw string from the command line.
      * @returns The decoded value.
-     * @throws {@link TypoError} on invalid input.
+     * @throws on invalid input.
      */
     decoder(input: string): Value;
 };
+/**
+ * A named type that accepts any string as input.
+ * @param name - Name shown in help and errors (e.g. `"my-value"`).
+ * @example
+ * ```ts
+ * typeString("greeting").decoder("hello") // → "hello"
+ * typeString("greeting").decoder("")      // → ""
+ * ```
+ */
+declare function typeString(name?: string): Type<string>;
 /**
  * Decodes a string to `boolean` (case-insensitive).
  * Used by {@link optionFlag} for `--flag=<value>`.
@@ -135,29 +131,16 @@ type Type<Value> = {
  * ```ts
  * typeBoolean("flag").decoder("true")  // → true
  * typeBoolean("flag").decoder("yes")   // → true
- * typeBoolean("flag").decoder("y")     // → true
- * typeBoolean("flag").decoder("false") // → false
- * typeBoolean("flag").decoder("no")    // → false
+ * typeBoolean("flag").decoder("Y")     // → true
+ * typeBoolean("flag").decoder("FALSE") // → false
+ * typeBoolean("flag").decoder("NO")    // → false
  * typeBoolean("flag").decoder("n")     // → false
+ * typeBoolean("flag").decoder("maybe") // throws
  * ```
  */
 declare function typeBoolean(name?: string): Type<boolean>;
-declare const typeBooleanValuesTrue: Set<string>;
-declare const typeBooleanValuesFalse: Set<string>;
-/**
- * Parses a date/time string via `Date.parse`.
- * Accepts any format supported by `Date.parse`, including ISO 8601.
- *
- * @example
- * ```ts
- * typeDatetime("my-datetime").decoder("2024-01-15") // → Date object for 2024-01-15
- * typeDatetime("my-datetime").decoder("2024-01-15T13:45:30Z") // → Date object for 2024-01-15 13:45:30 UTC
- * typeDatetime("my-datetime").decoder("not a date") // throws TypoError
- * ```
- */
-declare function typeDatetime(name?: string): Type<Date>;
 /**
- * Parses a string to `number` via `Number()`; `NaN` throws {@link TypoError}.
+ * Parses a string to `number` via `Number()`; `NaN` throws.
  *
  * @example
  * ```ts
@@ -169,7 +152,7 @@ declare function typeDatetime(name?: string): Type<Date>;
 declare function typeNumber(name?: string): Type<number>;
 /**
  * Parses an integer string to `bigint` via `BigInt()`.
- * Floats and non-numeric strings throw {@link TypoError}.
+ * Floats and non-numeric strings throws.
  *
  * @example
  * ```ts
@@ -179,9 +162,21 @@ declare function typeNumber(name?: string): Type<number>;
  * ```
  */
 declare function typeInteger(name?: string): Type<bigint>;
+/**
+ * Parses a date/time string via `Date.parse`.
+ * Accepts any format supported by `Date.parse`, including ISO 8601.
+ *
+ * @example
+ * ```ts
+ * typeDatetime("start").decoder("2024-01-15") // → Date object for 2024-01-15
+ * typeDatetime("start").decoder("2024-01-15T13:45:30Z") // → Date object for 2024-01-15 13:45:30 UTC
+ * typeDatetime("start").decoder("not a date") // throws
+ * ```
+ */
+declare function typeDatetime(name?: string): Type<Date>;
 /**
  * Parses an absolute URL string to a `URL` object.
- * Relative or malformed URLs throw {@link TypoError}.
+ * Relative or malformed URLs throws.
  *
  * @example
  * ```ts
@@ -191,15 +186,36 @@ declare function typeInteger(name?: string): Type<bigint>;
  */
 declare function typeUrl(name?: string): Type<URL>;
 /**
- * A named type that accepts any string as input.
- * @param name - Name shown in help and errors (e.g. `"my-value"`).
+ * Creates a {@link Type} for filesystem paths with optional existence checks.
+ *
+ * @param checks - Optional checks for path existence and type (file/directory).
+ * @returns A {@link Type}`<string>` representing the path.
+ *
+ * @example
+ * ```ts
+ * const typeInputFile = typePath("input-file", { checkSyncExistAs: "file" });
+ * typeInputFile.decoder("data.txt"); // → "data.txt" if it exists and is a file, otherwise throws
+ * typeInputFile.decoder("somedir");  // throws if "somedir" exists and is a directory
+ * ```
+ */
+declare function typePath(name?: string, checks?: {
+    checkSyncExistAs?: "file" | "directory" | "anything";
+}): Type<string>;
+/**
+ * Creates a {@link Type}`<string>` that only accepts a fixed set of values.
+ *
+ * @param name - Name shown in help and errors.
+ * @param values - Ordered list of accepted values.
+ * @returns A {@link Type}`<string>`.
+ *
  * @example
  * ```ts
- * type("greeting").decoder("hello") // → "hello"
- * type("greeting").decoder("")      // → ""
+ * const typeEnv = typeChoice("environment", ["dev", "staging", "prod"]);
+ * typeEnv.decoder("prod")    // → "prod"
+ * typeEnv.decoder("unknown") // throws
  * ```
  */
-declare function type(name?: string): Type<string>;
+declare function typeChoice<const Value extends string>(name: string, values: Array<Value>, caseSensitive?: boolean): Type<Value>;
 /**
  * Chains `before`'s decoder with an `after` transformation.
  * `before` errors are prefixed with `"from: <content>"` for traceability.
@@ -214,15 +230,17 @@ declare function type(name?: string): Type<string>;
  *
  * @example
  * ```ts
- * const typePort = typeConverted("port", typeNumber(), (n) => {
- *   if (n < 1 || n > 65535) throw new Error("Out of range");
+ * const typePort = typeMapped("port", typeNumber(), (n) => {
+ *   if (n < 1 || n > 65535) {
+ *     throw new Error("Out of range");
+ *   }
  *   return n;
  * });
- * // "--port 8080"   →  8080
- * // "--port 99999"  →  TypoError: --port: <PORT>: Port: Out of range
+ * typePort.decoder("8080");  // → 8080
+ * typePort.decoder("70000"); // throws
  * ```
  */
-declare function typeConverted<Before, After>(name: string, before: Type<Before>, mapper: (value: Before) => After): Type<After>;
+declare function typeMapped<Before, After>(name: string, before: Type<Before>, mapper: (value: Before) => After): Type<After>;
 /**
  * Adds a name to a {@link Type} for clearer error messages and help text.
  *
@@ -231,33 +249,9 @@ declare function typeConverted<Before, After>(name: string, before: Type<Before>
  * @returns A {@link Type} with the given name.
  */
 declare function typeRenamed<Value>(type: Type<Value>, name: string): Type<Value>;
-/**
- * Creates a {@link Type} for filesystem paths with optional existence checks.
- * @param checks - Optional checks for path existence and type (file/directory).
- * @returns A {@link Type}`<string>` representing the path.
- */
-declare function typePath(name?: string, checks?: {
-    checkSyncExistAs?: "file" | "directory" | "anything";
-}): Type<string>;
-/**
- * Creates a {@link Type}`<string>` that only accepts a fixed set of values.
- * Out-of-set inputs throw {@link TypoError} listing up to 5 valid options.
- *
- * @param name - Name shown in help and errors.
- * @param values - Ordered list of accepted values.
- * @returns A {@link Type}`<string>`.
- *
- * @example
- * ```ts
- * const typeEnv = typeChoice("environment", ["dev", "staging", "prod"]);
- * typeEnv.decoder("prod")    // → "prod"
- * typeEnv.decoder("unknown") // throws TypoError: Invalid value: "unknown" (expected one of: "dev" | "staging" | "prod")
- * ```
- */
-declare function typeChoice<const Value extends string>(name: string, values: Array<Value>, caseSensitive?: boolean): Type<Value>;
 /**
  * Splits a delimited string into a typed tuple.
- * Each part is decoded by the corresponding element type; wrong count or decode failure throws {@link TypoError}.
+ * Each part is decoded by the corresponding element type; wrong count or decode failure throws.
  *
  * @typeParam Elements - Tuple of decoded value types (inferred from `elementTypes`).
  *
@@ -269,8 +263,9 @@ declare function typeChoice<const Value extends string>(name: string, values: Ar
  * ```ts
  * const typePoint = typeTuple([typeNumber("x"), typeNumber("y")]);
  * typePoint.decoder("3.14,2.71") // → [3.14, 2.71]
- * typePoint.decoder("1,2,3")     // → [1, 2]
- * typePoint.decoder("x,2")       // throws TypoError: at 0: Number: Unable to parse: "x"
+ * typePoint.decoder("1")         // throws
+ * typePoint.decoder("1,2,3")     // throws
+ * typePoint.decoder("x,2")       // throws
  * ```
  */
 declare function typeTuple<const Elements extends Array<any>>(elementTypes: {
@@ -278,7 +273,7 @@ declare function typeTuple<const Elements extends Array<any>>(elementTypes: {
 }, separator?: string): Type<Elements>;
 /**
  * Splits a delimited string into a typed array.
- * Each part is decoded by `elementType`; failed decodes throw {@link TypoError}.
+ * Each part is decoded by `elementType`; failed decodes throws.
  * Note: splitting an empty string yields one empty element — prefer {@link optionRepeatable} for a zero-default.
  *
  * @typeParam Value - Element type produced by `elementType.decoder`.
@@ -289,12 +284,13 @@ declare function typeTuple<const Elements extends Array<any>>(elementTypes: {
  *
  * @example
  * ```ts
- * const typeNumbers = typeList(typeNumber);
+ * const typeNumbers = typeList(typeNumber("v"));
  * typeNumbers.decoder("1,2,3")  // → [1, 2, 3]
- * typeNumbers.decoder("1,x,3")  // throws TypoError: at 1: Number: Unable to parse: "x"
- *
+ * typeNumbers.decoder("1,x,3")  // throws
  * const typePaths = typeList(typePath(), ":");
- * typePaths.decoder("/usr/bin:/usr/local/bin") // → ["/usr/bin", "/usr/local/bin"]
+ * typePaths.decoder("/bin:/usr") // → ["/bin", "/usr"]
+ * typePaths.decoder("/usr/bin")  // → ["/usr/bin"]
+ * typePaths.decoder("")          // → throws
  * ```
  */
 declare function typeList<Value>(elementType: Type<Value>, separator?: string): Type<Array<Value>>;
@@ -381,9 +377,9 @@ declare class TypoString {
     #private;
     /**
      * @param value - Raw text content.
-     * @param typoStyle - Style to apply when rendering. Defaults to `undefined` (no style).
+     * @param style - Style to apply when rendering.
      */
-    constructor(value: string, typoStyle?: TypoStyle);
+    constructor(value: string, style?: TypoStyle);
     /**
      * Returns the text styled by `typoSupport`.
      *
@@ -394,11 +390,15 @@ declare class TypoString {
      * Returns the raw text.
      */
     getRawString(): string;
+    /**
+     * Predefined ellipsis segment with subtle styling.
+     */
+    static elipsis: TypoString;
 }
 /**
  * A segment of styled text, a string, or an array of segments.
  */
-type TypoSegment = TypoText | TypoString | string | Array<TypoSegment>;
+type TypoSegment = TypoText | TypoString | Array<TypoSegment>;
 /**
  * Mutable sequence of {@link TypoString} segments.
  */
@@ -407,13 +407,15 @@ declare class TypoText {
     /**
      * @param segments - Initial text segments
      */
-    constructor(...segments: TypoSegment[]);
+    constructor(...segments: Array<TypoSegment>);
     /**
      * Appends new text segment(s).
-     *
-     * @param segment - Text segment(s) to append.
      */
-    push(segment: TypoSegment): void;
+    push(...segments: Array<TypoSegment>): void;
+    /**
+     * Appends separated segments, optionally truncating with an ellipsis.
+     */
+    pushJoined(segments: Array<TypoSegment>, separator: TypoSegment, ellipsisLimit: number): void;
     /**
      * Renders all segments into a single styled string.
      *
@@ -429,11 +431,6 @@ declare class TypoText {
      * Returns the total raw character count.
      */
     computeRawLength(): number;
-    /**
-     * Joins multiple segments with a separator.
-     * @returns A new {@link TypoText} containing the joined segments.
-     */
-    static join(segments: Array<TypoSegment>, separator: TypoSegment): TypoText;
 }
 /**
  * Column-aligned grid of {@link TypoText} cells.
@@ -680,7 +677,7 @@ type Option<Value> = {
     /**
      * Registers the option on `readerOptions` and returns an {@link OptionDecoder}.
      */
-    registerAndMakeDecoder(readerOptions: ReaderArgs): OptionDecoder<Value>;
+    registerAndMakeDecoder(readerOptions: ReaderOptions): OptionDecoder<Value>;
 };
 /**
  * Produced by {@link Option.registerAndMakeDecoder}.
@@ -691,15 +688,19 @@ type OptionDecoder<Value> = {
     /**
      * Returns the decoded option value.
      *
-     * @throws {@link TypoError} if decoding failed.
+     * @throws if decoding failed.
      */
     getAndDecodeValue(): Value;
 };
 /**
  * Creates a boolean flag option (`--verbose`, optionally `--flag=no`).
  *
- * Parsing: absent → default value; `--flag` / `--flag=yes` → `true`; `--flag=no` → `false`;
- * specified more than once → throws {@link TypoError}.
+ * Syntax: `--long`, `--long=no`, `-s`, `-s=no`.
+ * Parsing logic:
+ * - absent → default value
+ * - `--flag` / `--flag=yes` → `true`
+ * - `--flag=no` → `false`
+ * - specified more than once → throws.
  *
  * @param definition.long - Long-form name (without `--`).
  * @param definition.short - Short-form name (without `-`).
@@ -716,11 +717,6 @@ type OptionDecoder<Value> = {
  *   short: "v",
  *   description: "Enable verbose output",
  * });
- * // Usage:
- * //   my-cli  →  false
- * //   my-cli --verbose  →  true
- * //   my-cli --verbose=yes  →  true
- * //   my-cli -v=no  →  false
  * ```
  */
 declare function optionFlag(definition: {
@@ -737,8 +733,13 @@ declare function optionFlag(definition: {
 /**
  * Creates an option that accepts exactly one value (e.g. `--output dist/`).
  *
- * Parsing: absent → `defaultValue()`; once → decoded with `type`; more than once → {@link TypoError}.
- * Value syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
+ * Syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
+ * Parsing logic:
+ * - absent → `fallbackValueIfAbsent()`
+ * - `--long value` → decoded with `type.decoder("value")`
+ * - more than once → throws
+ * - if `impliedValueIfNotInlined` is not provided, then: `--long` / `-s` without a value → throws
+ * - if `impliedValueIfNotInlined` is provided, then: `--long` / `-s` without an inline value → `impliedValueIfNotInlined()`
  *
  * @typeParam Value - Type produced by the decoder.
  *
@@ -748,8 +749,8 @@ declare function optionFlag(definition: {
  * @param definition.hint - Short note shown in parentheses.
  * @param definition.aliases - Additional names.
  * @param definition.type - Decoder for the raw string value.
- * @param definition.defaultIfNotSpecified - Default value when the option is not specified at all.
- * @param definition.valueIfNothingInlined - Default value when the option is specified without an inline value (e.g. `--option` or `-o`).
+ * @param definition.fallbackValueIfAbsent - Default value when the option is not specified at all.
+ * @param definition.impliedValueIfNotInlined - Default value when the option is specified without an inline value (e.g. `--option` or `-o`).
  * @returns An {@link Option}`<Value>`.
  *
  * @example
@@ -759,12 +760,8 @@ declare function optionFlag(definition: {
  *   short: "o",
  *   type: typePath(),
  *   description: "Output directory",
- *   defaultIfNotSpecified: () => "dist",
+ *   fallbackValueIfAbsent: () => "dist",
  * });
- * // Usage:
- * //   my-cli  →  "dist"
- * //   my-cli --output folder  →  "folder"
- * //   my-cli -o folder  →  "folder"
  * ```
  */
 declare function optionSingleValue<Value>(definition: {
@@ -777,14 +774,16 @@ declare function optionSingleValue<Value>(definition: {
         shorts?: Array<string>;
     };
     type: Type<Value>;
-    defaultIfNotSpecified: () => Value;
-    valueIfNothingInlined?: () => Value;
+    fallbackValueIfAbsent?: () => Value;
+    impliedValueIfNotInlined?: () => Value;
 }): Option<Value>;
 /**
  * Creates an option that collects every occurrence into an array (e.g. `--file a.ts --file b.ts`).
  *
- * Parsing: absent → `[]`; N occurrences → array of N decoded values in order.
- * Value syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
+ * Syntax: `--long value`, `--long=value`, `-s value`, `-s=value`, `-svalue`.
+ * Parsing logic:
+ * - absent → `[]`
+ * - N occurrences → array of N decoded values in order.
  *
  * @typeParam Value - Type produced by the decoder for each occurrence.
  *
@@ -805,7 +804,6 @@ declare function optionSingleValue<Value>(definition: {
  *   label: "PATH",
  *   description: "Input file (may be repeated)",
  * });
- * // Usage: my-cli --file a.ts --file b.ts  →  ["a.ts", "b.ts"]
  * ```
  */
 declare function optionRepeatable<Value>(definition: {
@@ -846,18 +844,24 @@ type PositionalDecoder<Value> = {
     /**
      * Returns the decoded positional value.
      *
-     * @throws {@link TypoError} if decoding failed.
+     * @throws if decoding failed.
      */
     decodeValue(): Value;
 };
 /**
- * Creates a required positional — missing token throws {@link TypoError}.
+ * Creates a required positional — missing token throws.
+ *
+ * Syntax: `<type>`, e.g. `<NAME>`.
+ * Parsing logic:
+ * - "token" → decoded with `type.decoder("token")`
+ * - token missing → throws
  *
  * @typeParam Value - Type produced by the decoder.
  *
  * @param definition.description - Help text.
  * @param definition.hint - Short note shown in parentheses.
  * @param definition.type - Decoder for the raw token.
+ * @param definition.missing - Message shown when the token is missing.
  * @returns A {@link Positional}`<Value>`.
  *
  * @example
@@ -866,8 +870,6 @@ type PositionalDecoder<Value> = {
  *   type: type("name"),
  *   description: "The name to greet",
  * });
- * // Usage:
- * //   my-cli Alice  →  "Alice"
  * ```
  */
 declare function positionalRequired<Value>(definition: {
@@ -878,6 +880,11 @@ declare function positionalRequired<Value>(definition: {
 /**
  * Creates an optional positional — absent token falls back to `default()`.
  *
+ * Syntax: `[type]`, e.g. `[NAME]`.
+ * Parsing logic:
+ * - "token" → decoded with `type.decoder("token")`
+ * - token missing → `default()`
+ *
  * @typeParam Value - Type produced by the decoder (or the default).
  *
  * @param definition.description - Help text.
@@ -894,9 +901,6 @@ declare function positionalRequired<Value>(definition: {
  *   hint: "Defaults to \"world\"",
  *   default: () => "world",
  * });
- * // Usage:
- * //   my-cli  →  "world"
- * //   my-cli Alice  →  "Alice"
  * ```
  */
 declare function positionalOptional<Value>(definition: {
@@ -909,6 +913,12 @@ declare function positionalOptional<Value>(definition: {
  * Creates a variadic positional that collects zero or more remaining tokens into an array.
  * Optionally stops at `endDelimiter` (consumed, not included).
  *
+ * Syntax: `[type]...`, e.g. `[NAME]...`.
+ * Parsing logic:
+ * - "a b ..." → decoded with `[type.decoder("a")`, `type.decoder("b"), ...]``
+ * - token missing → stops collection
+ * - endDelimiter encountered → stops collection
+ *
  * @typeParam Value - Type produced by the decoder for each token.
  *
  * @param definition.endDelimiter - Sentinel token that stops collection (consumed, not included).
@@ -923,9 +933,6 @@ declare function positionalOptional<Value>(definition: {
  *   type: typePath(),
  *   description: "Files to process",
  * });
- * // Usage:
- * //   my-cli  →  []
- * //   my-cli a.ts b.ts c.ts  →  ["a.ts", "b.ts", "c.ts"]
  * ```
  */
 declare function positionalVariadics<Value>(definition: {
@@ -944,7 +951,7 @@ declare function positionalVariadics<Value>(definition: {
  * @typeParam Context - Injected at execution; forwarded to handlers.
  * @typeParam Result - Value produced on execution; typically `void`.
  */
-type Operation<Context, Result> = {
+type Operation<Context, Result = void> = {
     /**
      * Returns usage metadata without consuming any arguments.
      */
@@ -973,7 +980,7 @@ type OperationDecoder<Context, Result> = {
     /**
      * Creates a ready-to-execute {@link OperationInterpreter}.
      *
-     * @throws {@link TypoError} if parsing or decoding failed.
+     * @throws if parsing or decoding failed.
      */
     decodeAndMakeInterpreter(): OperationInterpreter<Context, Result>;
 };
@@ -1023,18 +1030,22 @@ type OperationInterpreter<Context, Result> = {
  * );
  * ```
  */
-declare function operation<Context, Result, Options extends {
+declare function operation<Context, Result, const Options extends {
     [option: string]: any;
-}, const Positionals extends Array<any>>(inputs: {
-    options: {
+} = {}, const Positionals extends Array<any> = []>(inputs: {
+    options?: {
         [K in keyof Options]: Option<Options[K]>;
     };
-    positionals: {
+    positionals?: {
         [K in keyof Positionals]: Positional<Positionals[K]>;
     };
 }, handler: (context: Context, inputs: {
-    options: Options;
-    positionals: Positionals;
+    options: {
+        [K in keyof Options]: Options[K];
+    };
+    positionals: {
+        [K in keyof Positionals]: Positionals[K];
+    };
 }) => Promise<Result>): Operation<Context, Result>;
 
 /**
@@ -1043,7 +1054,7 @@ declare function operation<Context, Result, Options extends {
  * @typeParam Context - Injected at execution; forwarded to handlers.
  * @typeParam Result - Produced on execution; typically `void`.
  */
-type Command<Context, Result> = {
+type Command<Context, Result = void> = {
     /**
      * Returns static metadata.
      */
@@ -1067,7 +1078,7 @@ type CommandDecoder<Context, Result> = {
     /**
      * Creates a ready-to-execute {@link CommandInterpreter}.
      *
-     * @throws {@link TypoError} if parsing or decoding failed.
+     * @throws if parsing or decoding failed.
      */
     decodeAndMakeInterpreter(): CommandInterpreter<Context, Result>;
 };
@@ -1142,15 +1153,16 @@ type CommandInformation = {
  * const greet = command(
  *   { description: "Greet a user" },
  *   operation(
- *     { options: {}, positionals: [positionalRequired({ type: type("name") })] },
+ *     { positionals: [positionalRequired({ type: type("name") })] },
  *     async (_ctx, { positionals: [name] }) => console.log(`Hello, ${name}!`),
  *   ),
  * );
  * ```
  */
-declare function command<Context, Result>(information: CommandInformation, operation: Operation<Context, Result>): Command<Context, Result>;
+declare function command<Context, Result = void>(information: CommandInformation, operation: Operation<Context, Result>): Command<Context, Result>;
 /**
- * Creates a command that runs `operation` first, then dispatches to a named subcommand.
+ * Creates a command that runs `operation` first,
+ * then dispatches result to a named subcommand.
  *
  * @typeParam Context - Context accepted by `operation`.
  * @typeParam Payload - Output of `operation`; becomes the subcommand's context.
@@ -1173,12 +1185,12 @@ declare function command<Context, Result>(information: CommandInformation, opera
  * );
  * ```
  */
-declare function commandWithSubcommands<Context, Payload, Result>(information: CommandInformation, operation: Operation<Context, Payload>, subcommands: {
+declare function commandWithSubcommands<Context, Payload, Result = void>(information: CommandInformation, operation: Operation<Context, Payload>, subcommands: {
     [subcommand: string]: Command<Payload, Result>;
 }): Command<Context, Result>;
 /**
- * Chains an {@link Operation} and a {@link Command}: `operation` runs first, its
- * output becomes `subcommand`'s context. No token is consumed for routing.
+ * Chains an {@link Operation} and a {@link Command}: `operation` runs first,
+ * its output becomes `subcommand`'s context. No token is consumed for routing.
  *
  * @typeParam Context - Context accepted by `operation`.
  * @typeParam Payload - Output of `operation`; becomes `subcommand`'s context.
@@ -1189,7 +1201,7 @@ declare function commandWithSubcommands<Context, Payload, Result>(information: C
  * @param subcommand - Runs after `operation`.
  * @returns A {@link Command} composing both stages.
  */
-declare function commandChained<Context, Payload, Result>(information: CommandInformation, operation: Operation<Context, Payload>, subcommand: Command<Payload, Result>): Command<Context, Result>;
+declare function commandChained<Context, Payload, Result = void>(information: CommandInformation, operation: Operation<Context, Payload>, subcommand: Command<Payload, Result>): Command<Context, Result>;
 
 /**
  * Color selection modes availables
@@ -1246,11 +1258,9 @@ declare function runAndExit<Context>(cliName: string, cliArgs: ReadonlyArray<str
     onExit?: ((code: number) => never) | undefined;
 }): Promise<never>;
 
-declare function similaritySort<Value>(reference: string, candidates: {
-    [key: string]: Value;
-} | Array<{
-    key: string;
-    value: Value;
-}>): Array<Value>;
+declare function suggestTextPushMessage(text: TypoText, query: string, candidates: Array<{
+    reference: string;
+    hint: TypoSegment;
+}>): void;
 
-export { type Command, type CommandDecoder, type CommandInformation, type CommandInterpreter, type Operation, type OperationDecoder, type OperationInterpreter, type Option, type OptionDecoder, type Positional, type PositionalDecoder, ReaderArgs, type ReaderOptionKey, type ReaderOptionParsing, type ReaderOptionValue, type ReaderOptions, type ReaderPositionals, type RunColorMode, type Type, type TypoColor, TypoError, TypoGrid, type TypoSegment, TypoString, type TypoStyle, TypoSupport, TypoText, type UsageCommand, type UsageOption, type UsagePositional, type UsageSubcommand, command, commandChained, commandWithSubcommands, operation, optionFlag, optionRepeatable, optionSingleValue, positionalOptional, positionalRequired, positionalVariadics, runAndExit, similaritySort, type, typeBoolean, typeBooleanValuesFalse, typeBooleanValuesTrue, typeChoice, typeConverted, typeDatetime, typeInteger, typeList, typeNumber, typePath, typeRenamed, typeTuple, typeUrl, typoStyleConstants, typoStyleFailure, typoStyleLogic, typoStyleQuote, typoStyleRegularStrong, typoStyleRegularWeaker, typoStyleTitle, typoStyleUserInput, usageToStyledLines };
+export { type Command, type CommandDecoder, type CommandInformation, type CommandInterpreter, type Operation, type OperationDecoder, type OperationInterpreter, type Option, type OptionDecoder, type Positional, type PositionalDecoder, ReaderArgs, type ReaderOptionGetter, type ReaderOptionLongSpec, type ReaderOptionNextGuard, type ReaderOptionShortSpec, type ReaderOptionValue, type ReaderOptions, type ReaderPositionals, type RunColorMode, type Type, type TypoColor, TypoError, TypoGrid, type TypoSegment, TypoString, type TypoStyle, TypoSupport, TypoText, type UsageCommand, type UsageOption, type UsagePositional, type UsageSubcommand, command, commandChained, commandWithSubcommands, operation, optionFlag, optionRepeatable, optionSingleValue, positionalOptional, positionalRequired, positionalVariadics, runAndExit, suggestTextPushMessage, typeBoolean, typeChoice, typeDatetime, typeInteger, typeList, typeMapped, typeNumber, typePath, typeRenamed, typeString, typeTuple, typeUrl, typoStyleConstants, typoStyleFailure, typoStyleLogic, typoStyleQuote, typoStyleRegularStrong, typoStyleRegularWeaker, typoStyleTitle, typoStyleUserInput, usageToStyledLines };