cli-kiss 0.2.4 → 0.2.5

package/src/lib/Type.ts

@@ -1,3 +1,4 @@
+import { statSync } from "fs";
 import {
   TypoError,
   TypoString,
@@ -8,17 +9,17 @@ import {
 
 /**
  * Decodes a raw CLI string into a typed value.
- * A pair of a human-readable `content` name (e.g. `"Number"`) and a `decoder` function.
+ * A pair of a human-readable `content` name and a `decoder` function.
  *
- * Built-in: {@link typeString}, {@link typeBoolean}, {@link typeNumber},
- * {@link typeInteger}, {@link typeDate}, {@link typeUrl}.
- * Composite: {@link typeOneOf}, {@link typeMapped}, {@link typeTuple}, {@link typeList}.
+ * Built-in: {@link type}, {@link typeBoolean}, {@link typeNumber},
+ * {@link typeInteger}, {@link typeDatetime}, {@link typeUrl}.
+ * Composite: {@link typeChoice}, {@link typeConverted}, {@link typeTuple}, {@link typeList}.
  *
  * @typeParam Value - Type produced by the decoder.
  */
 export type Type<Value> = {
   /**
-   * Human-readable name shown in help and errors (e.g. `"String"`, `"Number"`).
+   * Human-readable name shown in help and errors (e.g. `"name"`, `"number"`).
    */
   content: string;
   /**
@@ -37,32 +38,34 @@ export type Type<Value> = {
  *
  * @example
  * ```ts
- * typeBoolean.decoder("true")  // → true
- * typeBoolean.decoder("yes")   // → true
- * typeBoolean.decoder("y")     // → true
- * typeBoolean.decoder("false") // → false
- * typeBoolean.decoder("no")    // → false
- * typeBoolean.decoder("n")     // → false
+ * 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("n")     // → false
  * ```
  */
-export const typeBoolean: Type<boolean> = {
-  content: "Boolean",
-  decoder(input: string) {
-    const lower = input.toLowerCase();
-    if (booleanValuesTrue.has(lower)) {
-      return true;
-    }
-    if (booleanValuesFalse.has(lower)) {
-      return false;
-    }
-    throw new TypoError(
-      new TypoText(
-        new TypoString(`Invalid value: `),
-        new TypoString(`"${input}"`, typoStyleQuote),
-      ),
-    );
-  },
-};
+export function typeBoolean(name?: string): Type<boolean> {
+  return {
+    content: name ?? "boolean",
+    decoder(input: string) {
+      const lower = input.toLowerCase();
+      if (booleanValuesTrue.has(lower)) {
+        return true;
+      }
+      if (booleanValuesFalse.has(lower)) {
+        return false;
+      }
+      throw new TypoError(
+        new TypoText(
+          new TypoString(`Not a boolean: `),
+          new TypoString(`"${input}"`, typoStyleQuote),
+        ),
+      );
+    },
+  };
+}
 const booleanValuesTrue = new Set(["true", "yes", "on", "1", "y", "t"]);
 const booleanValuesFalse = new Set(["false", "no", "off", "0", "n", "f"]);
 
@@ -72,60 +75,64 @@ const booleanValuesFalse = new Set(["false", "no", "off", "0", "n", "f"]);
  *
  * @example
  * ```ts
- * typeDate.decoder("2024-01-15") // → Date object for 2024-01-15
- * typeDate.decoder("2024-01-15T13:45:30Z") // → Date object for 2024-01-15 13:45:30 UTC
- * typeDate.decoder("not a date") // throws TypoError
+ * 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
  * ```
  */
-export const typeDate: Type<Date> = {
-  content: "Date",
-  decoder(input: string) {
-    try {
-      const timestampMs = Date.parse(input);
-      if (isNaN(timestampMs)) {
-        throw new Error();
+export function typeDatetime(name?: string): Type<Date> {
+  return {
+    content: name ?? "datetime",
+    decoder(input: string) {
+      try {
+        const timestampMs = Date.parse(input);
+        if (isNaN(timestampMs)) {
+          throw new Error();
+        }
+        return new Date(timestampMs);
+      } catch {
+        throw new TypoError(
+          new TypoText(
+            new TypoString(`Not a valid ISO_8601 datetime: `),
+            new TypoString(`"${input}"`, typoStyleQuote),
+          ),
+        );
       }
-      return new Date(timestampMs);
-    } catch {
-      throw new TypoError(
-        new TypoText(
-          new TypoString(`Not a valid ISO_8601: `),
-          new TypoString(`"${input}"`, typoStyleQuote),
-        ),
-      );
-    }
-  },
-};
+    },
+  };
+}
 
 /**
  * Parses a string to `number` via `Number()`; `NaN` throws {@link TypoError}.
  *
  * @example
  * ```ts
- * typeNumber.decoder("3.14")  // → 3.14
- * typeNumber.decoder("-1")    // → -1
- * typeNumber.decoder("hello") // throws TypoError
+ * typeNumber("my-number").decoder("3.14")  // → 3.14
+ * typeNumber("my-number").decoder("-1")    // → -1
+ * typeNumber("my-number").decoder("hello") // throws TypoError
  * ```
  */
-export const typeNumber: Type<number> = {
-  content: "Number",
-  decoder(input: string) {
-    try {
-      const parsed = Number(input);
-      if (isNaN(parsed)) {
-        throw new Error();
+export function typeNumber(name?: string): Type<number> {
+  return {
+    content: name ?? "number",
+    decoder(input: string) {
+      try {
+        const parsed = Number(input);
+        if (isNaN(parsed)) {
+          throw new Error();
+        }
+        return parsed;
+      } catch {
+        throw new TypoError(
+          new TypoText(
+            new TypoString(`Not a number: `),
+            new TypoString(`"${input}"`, typoStyleQuote),
+          ),
+        );
       }
-      return parsed;
-    } catch {
-      throw new TypoError(
-        new TypoText(
-          new TypoString(`Unable to parse: `),
-          new TypoString(`"${input}"`, typoStyleQuote),
-        ),
-      );
-    }
-  },
-};
+    },
+  };
+}
 
 /**
  * Parses an integer string to `bigint` via `BigInt()`.
@@ -133,26 +140,28 @@ export const typeNumber: Type<number> = {
  *
  * @example
  * ```ts
- * typeInteger.decoder("42")   // → 42n
- * typeInteger.decoder("3.14") // throws TypoError
- * typeInteger.decoder("abc")  // throws TypoError
+ * typeInteger("my-integer").decoder("42")   // → 42n
+ * typeInteger("my-integer").decoder("3.14") // throws TypoError
+ * typeInteger("my-integer").decoder("abc")  // throws TypoError
  * ```
  */
-export const typeInteger: Type<bigint> = {
-  content: "Integer",
-  decoder(input: string) {
-    try {
-      return BigInt(input);
-    } catch {
-      throw new TypoError(
-        new TypoText(
-          new TypoString(`Unable to parse: `),
-          new TypoString(`"${input}"`, typoStyleQuote),
-        ),
-      );
-    }
-  },
-};
+export function typeInteger(name?: string): Type<bigint> {
+  return {
+    content: name ?? "integer",
+    decoder(input: string) {
+      try {
+        return BigInt(input);
+      } catch {
+        throw new TypoError(
+          new TypoText(
+            new TypoString(`Not an integer: `),
+            new TypoString(`"${input}"`, typoStyleQuote),
+          ),
+        );
+      }
+    },
+  };
+}
 
 /**
  * Parses an absolute URL string to a `URL` object.
@@ -160,41 +169,43 @@ export const typeInteger: Type<bigint> = {
  *
  * @example
  * ```ts
- * typeUrl.decoder("https://example.com") // → URL { href: "https://example.com/", ... }
- * typeUrl.decoder("not-a-url")           // throws TypoError
+ * typeUrl("my-url").decoder("https://example.com") // → URL { href: "https://example.com/", ... }
+ * typeUrl("my-url").decoder("not-a-url")           // throws TypoError
  * ```
  */
-export const typeUrl: Type<URL> = {
-  content: "Url",
-  decoder(input: string) {
-    try {
-      return new URL(input);
-    } catch {
-      throw new TypoError(
-        new TypoText(
-          new TypoString(`Unable to parse: `),
-          new TypoString(`"${input}"`, typoStyleQuote),
-        ),
-      );
-    }
-  },
-};
+export function typeUrl(name?: string): Type<URL> {
+  return {
+    content: name ?? "url",
+    decoder(input: string) {
+      try {
+        return new URL(input);
+      } catch {
+        throw new TypoError(
+          new TypoText(
+            new TypoString(`Not an URL: `),
+            new TypoString(`"${input}"`, typoStyleQuote),
+          ),
+        );
+      }
+    },
+  };
+}
 
 /**
- * Identity decoder — passes the raw string through unchanged.
- *
+ * A named type that accepts any string as input.
+ * @param name - Name shown in help and errors (e.g. `"my-value"`).
  * @example
  * ```ts
- * typeString.decoder("hello") // → "hello"
- * typeString.decoder("")      // → ""
+ * type("greeting").decoder("hello") // → "hello"
+ * type("greeting").decoder("")      // → ""
  * ```
  */
-export const typeString: Type<string> = {
-  content: "String",
-  decoder(input: string) {
-    return input;
-  },
-};
+export function type(name?: string): Type<string> {
+  return {
+    content: name ?? "string",
+    decoder: (input: string) => input,
+  };
+}
 
 /**
  * Chains `before`'s decoder with an `after` transformation.
@@ -203,33 +214,30 @@ export const typeString: Type<string> = {
  * @typeParam Before - Intermediate type from `before.decoder`.
  * @typeParam After - Final type from `after.decoder`.
  *
- * @param before - Base decoder for the raw string.
- * @param after - Transformation applied to the decoded value.
- * @param after.content - Name for the resulting type (shown in errors).
- * @param after.decoder - Converts a `Before` value to `After`.
+ * @param name - Name shown in help and errors (e.g. `"my-value"`).
+ * @param before - Base type to decode the raw string.
+ * @param mapper - Transforms `before`'s output to the final value; errors are wrapped with context.
  * @returns A {@link Type}`<After>`.
  *
  * @example
  * ```ts
- * const typePort = typeMapped(typeNumber, {
- *   content: "Port",
- *   decoder: (n) => {
- *     if (n < 1 || n > 65535) throw new Error("Out of range");
- *     return n;
- *   },
+ * const typePort = typeConverted("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
  * ```
  */
-export function typeMapped<Before, After>(
+export function typeConverted<Before, After>(
+  name: string,
   before: Type<Before>,
-  after: { content: string; decoder: (value: Before) => After },
+  mapper: (value: Before) => After,
 ): Type<After> {
   return {
-    content: after.content,
+    content: name,
     decoder: (input: string) => {
-      return after.decoder(
+      return mapper(
         TypoError.tryWithContext(
           () => before.decoder(input),
           () =>
@@ -243,32 +251,110 @@ export function typeMapped<Before, After>(
   };
 }
 
+/**
+ * Adds a name to a {@link Type} for clearer error messages and help text.
+ *
+ * @param name - Name to use for the type.
+ * @param type - Base type to name.
+ * @returns A {@link Type} with the given name.
+ */
+export function typeRenamed<Value>(
+  type: Type<Value>,
+  name: string,
+): Type<Value> {
+  return {
+    content: name,
+    decoder: (input: string) => {
+      return TypoError.tryWithContext(
+        () => type.decoder(input),
+        () =>
+          new TypoText(
+            new TypoString("from: "),
+            new TypoString(type.content, typoStyleLogic),
+          ),
+      );
+    },
+  };
+}
+
+/**
+ * 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.
+ */
+export function typePath(
+  name?: string,
+  checks?: { checkSyncExistAs?: "file" | "directory" | "anything" },
+): Type<string> {
+  return {
+    content: name ?? "path",
+    decoder(input: string) {
+      if (input.length === 0) {
+        throw new Error(`Path cannot be empty`);
+      }
+      if (input.includes("\0")) {
+        throw new Error(`Path cannot contain null characters`);
+      }
+      if (checks?.checkSyncExistAs !== undefined) {
+        const stats = statSync(input);
+        const preview = stats.isDirectory()
+          ? "directory"
+          : stats.isFile()
+            ? "file"
+            : "unknown";
+        if (checks.checkSyncExistAs === "file" && !stats.isFile()) {
+          throw new TypoError(
+            new TypoText(
+              new TypoString(`Expected a 'file' but found '${preview}': `),
+              new TypoString(`"${input}"`, typoStyleQuote),
+            ),
+          );
+        }
+        if (checks.checkSyncExistAs === "directory" && !stats.isDirectory()) {
+          throw new TypoError(
+            new TypoText(
+              new TypoString(`Expected a 'directory' but found '${preview}': `),
+              new TypoString(`"${input}"`, typoStyleQuote),
+            ),
+          );
+        }
+      }
+      return input;
+    },
+  };
+}
+
 /**
  * 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 content - Name shown in help and errors (e.g. `"Environment"`).
+ * @param name - Name shown in help and errors.
  * @param values - Ordered list of accepted values.
  * @returns A {@link Type}`<string>`.
  *
  * @example
  * ```ts
- * const typeEnv = typeOneOf("Environment", ["dev", "staging", "prod"]);
+ * 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")
  * ```
  */
-export function typeOneOf<const Value extends string>(
-  content: string,
+export function typeChoice<const Value extends string>(
+  name: string,
   values: Array<Value>,
+  caseSensitive: boolean = false,
 ): Type<Value> {
+  const normalize = caseSensitive
+    ? (s: string) => s
+    : (s: string) => s.toLowerCase();
+  const valueMap = new Map(values.map((value) => [normalize(value), value]));
   return {
-    content: content,
+    content: name,
     decoder(input: string) {
-      for (const value of values) {
-        if (input === value) {
-          return value;
-        }
+      const normalized = normalize(input);
+      const original = valueMap.get(normalized);
+      if (original !== undefined) {
+        return original;
       }
       const valuesPreview = [];
       for (const value of values) {
@@ -306,7 +392,7 @@ export function typeOneOf<const Value extends string>(
  *
  * @example
  * ```ts
- * const typePoint = typeTuple([typeNumber, typeNumber]);
+ * 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"
@@ -363,7 +449,7 @@ export function typeTuple<const Elements extends Array<any>>(
  * typeNumbers.decoder("1,2,3")  // → [1, 2, 3]
  * typeNumbers.decoder("1,x,3")  // throws TypoError: at 1: Number: Unable to parse: "x"
  *
- * const typePaths = typeList(typeString, ":");
+ * const typePaths = typeList(typePath(), ":");
  * typePaths.decoder("/usr/bin:/usr/local/bin") // → ["/usr/bin", "/usr/local/bin"]
  * ```
  */

package/src/lib/Typo.ts

@@ -25,6 +25,10 @@ export type TypoColor =
  * All fields are optional; ignored entirely in `"none"` mode.
  */
 export type TypoStyle = {
+  /**
+   * Letter case.
+   */
+  case?: "upper" | "lower";
   /**
    * Foreground (text) color.
    */
@@ -228,7 +232,7 @@ export class TypoGrid {
    * Renders as an array of styled, column-padded strings.
    *
    * @param typoSupport - Rendering mode.
-   * @returns 2-D array of styled strings.
+   * @returns Array of styled strings.
    */
   computeStyledLines(typoSupport: TypoSupport): Array<string> {
     const widths = new Array<number>();
@@ -346,36 +350,37 @@ export class TypoSupport {
   }
   /**
    * Deterministic textual styling for snapshot tests.
-   * Style flags appear as suffixes: `{text}@color`, `{text}+` (bold), `{text}-` (dim),
-   * `{text}*` (italic), `{text}_` (underline), `{text}~` (strikethrough).
    */
   static mock(): TypoSupport {
     return new TypoSupport("mock");
   }
   /**
-   * Auto-detects styling mode from the process environment.
-   * `FORCE_COLOR=0` / `NO_COLOR` → none; `FORCE_COLOR` (truthy) / `isTTY` → tty; else → none.
-   * Falls back to none if `process` is unavailable.
+   * Auto-detects styling mode from the process environment on best-effort basis.
    */
-  static inferFromProcess(): TypoSupport {
-    if (!process) {
+  static inferFromEnv(): TypoSupport {
+    if (!process || !process.env) {
       return TypoSupport.none();
     }
-    if (process.env) {
-      if (process.env["FORCE_COLOR"] === "0") {
-        return TypoSupport.none();
-      }
-      if (process.env["FORCE_COLOR"]) {
-        return TypoSupport.tty();
-      }
-      if ("NO_COLOR" in process.env) {
-        return TypoSupport.none();
+    function readEnvVar(name: string) {
+      if (!(name in process.env)) {
+        return undefined;
       }
+      return process.env[name];
+    }
+    const envForceColor = readEnvVar("FORCE_COLOR");
+    if (envForceColor === "0") {
+      return TypoSupport.none();
     }
-    if (process.stdout && process.stdout.isTTY) {
-      return TypoSupport.tty();
+    if (envForceColor !== undefined) {
+      TypoSupport.tty();
     }
-    return TypoSupport.none();
+    if (readEnvVar("NO_COLOR") !== undefined) {
+      return TypoSupport.none();
+    }
+    if (readEnvVar("MOCK_COLOR") !== undefined) {
+      return TypoSupport.mock();
+    }
+    return TypoSupport.tty();
   }
   /**
    * Applies `typoStyle` to `value` according to the current mode.
@@ -385,8 +390,15 @@ export class TypoSupport {
    * @returns Styled string.
    */
   computeStyledString(value: string, typoStyle: TypoStyle): string {
+    let styledValue = value;
+    if (typoStyle.case === "upper") {
+      styledValue = styledValue.toUpperCase();
+    }
+    if (typoStyle.case === "lower") {
+      styledValue = styledValue.toLowerCase();
+    }
     if (this.#kind === "none") {
-      return value;
+      return styledValue;
     }
     if (this.#kind === "tty") {
       const fgColorCode = typoStyle.fgColor
@@ -402,12 +414,12 @@ export class TypoSupport {
       const strikethroughCode = typoStyle.strikethrough
         ? ttyCodeStrikethrough
         : "";
-      return `${fgColorCode}${bgColorCode}${boldCode}${dimCode}${italicCode}${underlineCode}${strikethroughCode}${value}${ttyCodeReset}`;
+      return `${fgColorCode}${bgColorCode}${boldCode}${dimCode}${italicCode}${underlineCode}${strikethroughCode}${styledValue}${ttyCodeReset}`;
     }
     if (this.#kind === "mock") {
       const fgColorPart = typoStyle.fgColor
-        ? `{${value}}@${typoStyle.fgColor}`
-        : value;
+        ? `{${styledValue}}@${typoStyle.fgColor}`
+        : styledValue;
       const bgColorPart = typoStyle.bgColor
         ? `{${fgColorPart}}#${typoStyle.bgColor}`
         : fgColorPart;