cli-kiss 0.2.6 → 0.2.8

package/src/lib/Type.ts

@@ -1,4 +1,5 @@
 import { statSync } from "fs";
+import { suggestTextPushMessage } from "./Suggest";
 import {
   TypoError,
   TypoString,
@@ -19,15 +20,15 @@ import {
  */
 export 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;
+  content: string; // TODO - add an enforcement mechanism for casing ?
   /**
    * Decodes a raw CLI string into `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;
 };
@@ -50,20 +51,19 @@ export function typeBoolean(name?: string): Type<boolean> {
   return {
     content: name ?? "boolean",
     decoder(input: string) {
-      const lower = input.toLowerCase();
-      if (typeBooleanValuesTrue.has(lower)) {
+      const lowerInput = input.toLowerCase();
+      if (typeBooleanValuesTrue.has(lowerInput)) {
         return true;
       }
-      if (typeBooleanValuesFalse.has(lower)) {
+      if (typeBooleanValuesFalse.has(lowerInput)) {
         return false;
       }
       throwInvalidValue("a boolean", input);
     },
   };
 }
-
-export const typeBooleanValuesTrue = new Set(["true", "yes", "on", "y"]);
-export const typeBooleanValuesFalse = new Set(["false", "no", "off", "n"]);
+const typeBooleanValuesTrue = new Set(["true", "yes", "on", "y"]);
+const typeBooleanValuesFalse = new Set(["false", "no", "off", "n"]);
 
 /**
  * Parses a date/time string via `Date.parse`.
@@ -94,7 +94,7 @@ export 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
@@ -122,7 +122,7 @@ export 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
@@ -146,7 +146,7 @@ export function typeInteger(name?: string): Type<bigint> {
 
 /**
  * Parses an absolute URL string to a `URL` object.
- * Relative or malformed URLs throw {@link TypoError}.
+ * Relative or malformed URLs throws.
  *
  * @example
  * ```ts
@@ -315,7 +315,6 @@ export function typePath(
 
 /**
  * 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.
@@ -325,53 +324,50 @@ export function typePath(
  * ```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")
+ * typeEnv.decoder("unknown") // throws
  * ```
  */
 export function typeChoice<const Value extends string>(
   name: string,
   values: Array<Value>,
-  caseSensitive: boolean = false,
+  caseSensitive: boolean = true,
 ): Type<Value> {
+  if (values.length === 0) {
+    throw new Error("At least one value is required");
+  }
   const normalize = caseSensitive
-    ? (s: string) => s
-    : (s: string) => s.toLowerCase();
-  const valueMap = new Map(values.map((value) => [normalize(value), value]));
+    ? (input: string) => input
+    : (input: string) => input.toLowerCase();
+  const valueByNormalized = new Map(
+    values.map((value) => [normalize(value), value]),
+  );
   return {
     content: name,
     decoder(input: string) {
-      const normalized = normalize(input);
-      const original = valueMap.get(normalized);
-      if (original !== undefined) {
-        return original;
+      const value = valueByNormalized.get(normalize(input));
+      if (value !== undefined) {
+        return value;
       }
-      const valuesPreview = [];
-      for (const value of values) {
-        if (valuesPreview.length >= 5) {
-          valuesPreview.push(new TypoString(`...`));
-          break;
-        }
-        if (valuesPreview.length > 0) {
-          valuesPreview.push(new TypoString(` | `));
-        }
-        valuesPreview.push(new TypoString(`"${value}"`, typoStyleQuote));
-      }
-      throw new TypoError(
-        new TypoText(
-          new TypoString(`Invalid value: `),
-          new TypoString(`"${input}"`, typoStyleQuote),
-          new TypoString(` (expected one of: `),
-          ...valuesPreview,
-          new TypoString(`)`),
-        ),
+      const errorText = new TypoText();
+      errorText.push(new TypoString(`Unknown value: `));
+      errorText.push(new TypoString(`"${input}"`, typoStyleQuote));
+      errorText.push(new TypoString(`.`));
+      suggestTextPushMessage(
+        errorText,
+        input,
+        values.map((value) => ({
+          reference: value,
+          hint: new TypoString(`"${value}"`, typoStyleQuote),
+        })),
       );
+      throw new TypoError(errorText);
     },
   };
 }
 
 /**
  * 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`).
  *
@@ -383,8 +379,9 @@ export function typeChoice<const Value extends string>(
  * ```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
  * ```
  */
 export function typeTuple<const Elements extends Array<any>>(
@@ -403,6 +400,7 @@ export function typeTuple<const Elements extends Array<any>>(
             new TypoString(`Found ${splits.length} splits: `),
             new TypoString(`Expected ${elementTypes.length} splits from: `),
             new TypoString(`"${input}"`, typoStyleQuote),
+            new TypoString(`.`),
           ),
         );
       }
@@ -423,7 +421,7 @@ export function typeTuple<const Elements extends Array<any>>(
 
 /**
  * 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`.
@@ -434,10 +432,9 @@ export function typeTuple<const Elements extends Array<any>>(
  *
  * @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"]
  * ```
@@ -469,6 +466,7 @@ function throwInvalidValue(kind: string, input: string): never {
     new TypoText(
       new TypoString(`Not ${kind}: `),
       new TypoString(`"${input}"`, typoStyleQuote),
+      new TypoString(`.`),
     ),
   );
 }

package/src/lib/Typo.ts

@@ -1,5 +1,3 @@
-import { typeBooleanValuesFalse } from "./Type";
-
 /**
  * Color names for terminal styling, used by {@link TypoStyle}.
  * `dark*` = standard ANSI (30–37); `bright*` = high-intensity (90–97).
@@ -125,14 +123,14 @@ export const typoStyleRegularWeaker: TypoStyle = {
  */
 export class TypoString {
   #value: string;
-  #typoStyle: TypoStyle;
+  #style: TypoStyle | undefined;
   /**
    * @param value - Raw text content.
-   * @param typoStyle - Style to apply when rendering. Defaults to `{}` (no style).
+   * @param style - Style to apply when rendering.
    */
-  constructor(value: string, typoStyle: TypoStyle = {}) {
+  constructor(value: string, style?: TypoStyle) {
     this.#value = value;
-    this.#typoStyle = typoStyle;
+    this.#style = style;
   }
   /**
    * Returns the text styled by `typoSupport`.
@@ -140,48 +138,75 @@ export class TypoString {
    * @param typoSupport - Rendering mode.
    */
   computeStyledString(typoSupport: TypoSupport): string {
-    return typoSupport.computeStyledString(this.#value, this.#typoStyle);
+    return typoSupport.computeStyledString(this.#value, this.#style);
   }
   /**
    * Returns the raw text.
    */
   getRawString(): string {
+    // TODO - should there be a global config or smthg instead of passing support everywhere?
     return this.#value;
   }
+  /**
+   * Predefined ellipsis segment with subtle styling.
+   */
+  static elipsis = new TypoString("...", typoStyleRegularWeaker);
 }
 
+/**
+ * A segment of styled text, a string, or an array of segments.
+ */
+export type TypoSegment = TypoText | TypoString | Array<TypoSegment>;
+
 /**
  * Mutable sequence of {@link TypoString} segments.
  */
 export class TypoText {
-  #typoStrings: Array<TypoString>;
+  #strings: Array<TypoString>;
   /**
    * @param segments - Initial text segments
    */
-  constructor(
-    ...segments: Array<TypoText | Array<TypoString> | TypoString | string>
-  ) {
-    this.#typoStrings = [];
-    for (const typoPart of segments) {
-      this.push(typoPart);
+  constructor(...segments: Array<TypoSegment>) {
+    this.#strings = [];
+    for (const segment of segments) {
+      this.push(segment);
     }
   }
   /**
    * Appends new text segment(s).
-   *
-   * @param segment - Text segment(s) to append.
    */
-  push(segment: TypoText | Array<TypoString> | TypoString | string) {
-    if (typeof segment === "string") {
-      this.#typoStrings.push(new TypoString(segment));
-    } else if (segment instanceof TypoText) {
-      this.#typoStrings.push(...segment.#typoStrings);
-    } else if (Array.isArray(segment)) {
-      for (const typoString of segment) {
-        this.#typoStrings.push(typoString);
+  push(...segments: Array<TypoSegment>): void {
+    for (const segment of segments) {
+      if (typeof segment === "string") {
+        this.#strings.push(new TypoString(segment));
+      } else if (segment instanceof TypoString) {
+        this.#strings.push(segment);
+      } else if (segment instanceof TypoText) {
+        this.#strings.push(...segment.#strings);
+      } else if (Array.isArray(segment)) {
+        for (const part of segment) {
+          this.push(part);
+        }
       }
-    } else {
-      this.#typoStrings.push(segment);
+    }
+  }
+  /**
+   * Appends separated segments, optionally truncating with an ellipsis.
+   */
+  pushJoined(
+    segments: Array<TypoSegment>,
+    separator: TypoSegment,
+    ellipsisLimit: number,
+  ): void {
+    for (let index = 0; index < segments.length; index++) {
+      if (index > 0) {
+        this.push(separator);
+      }
+      if (ellipsisLimit !== undefined && index >= ellipsisLimit) {
+        this.push(TypoString.elipsis);
+        break;
+      }
+      this.push(segments[index]!);
     }
   }
   /**
@@ -191,7 +216,7 @@ export class TypoText {
    * @returns Concatenated styled string.
    */
   computeStyledString(typoSupport: TypoSupport): string {
-    return this.#typoStrings
+    return this.#strings
       .map((t) => t.computeStyledString(typoSupport))
       .join("");
   }
@@ -199,14 +224,14 @@ export class TypoText {
    * Returns the concatenated raw text.
    */
   computeRawString(): string {
-    return this.#typoStrings.map((t) => t.getRawString()).join("");
+    return this.#strings.map((t) => t.getRawString()).join("");
   }
   /**
    * Returns the total raw character count.
    */
   computeRawLength(): number {
     let length = 0;
-    for (const typoString of this.#typoStrings) {
+    for (const typoString of this.#strings) {
       length += typoString.getRawString().length;
     }
     return length;
@@ -334,8 +359,8 @@ export class TypoError extends Error {
  * Controls ANSI terminal styling. Create via the static factory methods.
  */
 export class TypoSupport {
-  #kind: "none" | "tty" | "mock";
-  private constructor(kind: "none" | "tty" | "mock") {
+  #kind: TypoSupportKind;
+  private constructor(kind: TypoSupportKind) {
     this.#kind = kind;
   }
   /**
@@ -360,15 +385,6 @@ export class TypoSupport {
    * Auto-detects styling mode from the process environment on best-effort basis.
    */
   static inferFromEnv(): TypoSupport {
-    /*
-    console.warn({
-      no: readEnvVar("NO_COLOR"),
-      force: readEnvVar("FORCE_COLOR"),
-      mock: readEnvVar("MOCK_COLOR"),
-      term: readEnvVar("TERM"),
-      tty: process.stdout.isTTY,
-    });
-    */
     if (!process || !process.env || !process.stdout) {
       return TypoSupport.none();
     }
@@ -379,13 +395,17 @@ export class TypoSupport {
     if (envForceColor === "0") {
       return TypoSupport.none();
     }
-    if (envForceColor !== undefined) {
-      if (!typeBooleanValuesFalse.has(envForceColor.toLowerCase())) {
-        return TypoSupport.tty();
-      }
+    if (envForceColor === "1") {
+      return TypoSupport.tty();
     }
-    if (readEnvVar("MOCK_COLOR")) {
-      return TypoSupport.mock();
+    if (envForceColor === "2") {
+      return TypoSupport.tty();
+    }
+    if (envForceColor === "3") {
+      return TypoSupport.tty(); // TODO - should there be fancy colors possible?
+    }
+    if (envForceColor) {
+      return TypoSupport.tty();
     }
     if (!process.stdout.isTTY) {
       return TypoSupport.none();
@@ -402,7 +422,10 @@ export class TypoSupport {
    * @param typoStyle - Style to apply.
    * @returns Styled string.
    */
-  computeStyledString(value: string, typoStyle: TypoStyle): string {
+  computeStyledString(value: string, typoStyle: TypoStyle | undefined): string {
+    if (typoStyle === undefined) {
+      return value;
+    }
     let styledValue = value;
     if (typoStyle.case === "upper") {
       styledValue = styledValue.toUpperCase();
@@ -516,3 +539,5 @@ function readEnvVar(name: string) {
   }
   return process.env[name];
 }
+
+type TypoSupportKind = "none" | "tty" | "mock";

package/src/lib/Usage.ts

@@ -93,7 +93,7 @@ export type UsageOption = {
   /**
    * Extra annotation appended to the option label in help.
    */
-  annotation?: string | undefined;
+  annotation?: string | undefined; // TODO - maybe prefix/postfix would be more useful
   /**
    * Help text.
    */
@@ -175,7 +175,7 @@ export function usageToStyledLines(params: {
   lines.push("");
   const introText = new TypoText();
   introText.push(textUsageText(usage.information.description));
-  if (usage.information.hint) {
+  if (usage.information.hint !== undefined) {
     introText.push(textDelimiter(" "));
     introText.push(textSubtleInfo(`(${usage.information.hint})`));
   }
@@ -221,7 +221,7 @@ export function usageToStyledLines(params: {
     for (const optionUsage of usage.options) {
       const typoGridRow = new Array<TypoText>();
       typoGridRow.push(new TypoText(textDelimiter("  ")));
-      if (optionUsage.short) {
+      if (optionUsage.short !== undefined) {
         typoGridRow.push(
           new TypoText(
             textConstants(`-${optionUsage.short}`),
@@ -234,11 +234,11 @@ export function usageToStyledLines(params: {
       const longOptionText = new TypoText(
         textConstants(`--${optionUsage.long}`),
       );
-      if (optionUsage.label) {
+      if (optionUsage.label !== undefined) {
         longOptionText.push(textDelimiter(" "));
         longOptionText.push(textUserInput(optionUsage.label));
       }
-      if (optionUsage.annotation) {
+      if (optionUsage.annotation !== undefined) {
         longOptionText.push(textSubtleInfo(optionUsage.annotation));
       }
       typoGridRow.push(longOptionText);
@@ -248,21 +248,21 @@ export function usageToStyledLines(params: {
     lines.push(...typoGrid.computeStyledLines(typoSupport));
   }
 
-  if (usage.information.examples) {
+  if (usage.information.examples !== undefined) {
     lines.push("");
     lines.push(textBlockTitle("Examples:").computeStyledString(typoSupport));
     for (const example of usage.information.examples) {
-      const exampleExplanationText = new TypoText();
-      exampleExplanationText.push(textDelimiter(" "));
-      exampleExplanationText.push(textSubtleInfo(`# ${example.explanation}`));
-      lines.push(exampleExplanationText.computeStyledString(typoSupport));
+      const explanationText = new TypoText();
+      explanationText.push(textDelimiter(" "));
+      explanationText.push(textSubtleInfo(`# ${example.explanation}`));
+      lines.push(explanationText.computeStyledString(typoSupport));
       const commandLineText = new TypoText();
       commandLineText.push(textDelimiter(" "));
       commandLineText.push(textConstants(cliName));
       for (const commandArg of example.commandArgs) {
         commandLineText.push(textDelimiter(" "));
         if (typeof commandArg === "string") {
-          commandLineText.push(commandArg);
+          commandLineText.push(new TypoString(commandArg));
         } else if ("positional" in commandArg) {
           commandLineText.push(textUserInput(commandArg.positional));
         } else if ("subcommand" in commandArg) {
@@ -299,11 +299,11 @@ function createInformationals(usage: {
   hint?: string | undefined;
 }): Array<TypoText> {
   const informationals = [];
-  if (usage.description) {
+  if (usage.description !== undefined) {
     informationals.push(textDelimiter(" "));
     informationals.push(textUsefulInfo(usage.description));
   }
-  if (usage.hint) {
+  if (usage.hint !== undefined) {
     informationals.push(textDelimiter(" "));
     informationals.push(textSubtleInfo(`(${usage.hint})`));
   }