cli-kiss 0.2.3 → 0.2.5

package/src/lib/Type.ts

@@ -1,3 +1,4 @@
+import { statSync } from "fs";
 import {
   TypoError,
   TypoString,
@@ -8,21 +9,21 @@ 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 error messages (e.g. `"String"`, `"Number"`).
+   * Human-readable name shown in help and errors (e.g. `"name"`, `"number"`).
    */
   content: string;
   /**
-   * Converts a raw CLI string into `Value`.
+   * Decodes a raw CLI string into `Value`.
    *
    * @param input - Raw string from the command line.
    * @returns The decoded value.
@@ -32,200 +33,211 @@ export type Type<Value> = {
 };
 
 /**
- * Decodes `"true"` / `"yes"` → `true` and `"false"` / `"no"` → `false` (case-insensitive).
- * Used internally by {@link optionFlag} for the `--flag=<value>` syntax.
+ * Decodes a string to `boolean` (case-insensitive).
+ * Used by {@link optionFlag} for `--flag=<value>`.
  *
  * @example
  * ```ts
- * typeBoolean.decoder("yes")   // → true
- * typeBoolean.decoder("false") // → false
- * typeBoolean.decoder("1")     // throws TypoError
+ * 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 (lower === "true" || lower === "yes") {
-      return true;
-    }
-    if (lower === "false" || lower === "no") {
-      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"]);
 
 /**
- * Parses a date/time string via `Date.parse` into a `Date` object.
+ * Parses a date/time string via `Date.parse`.
  * Accepts any format supported by `Date.parse`, including ISO 8601.
  *
  * @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 into a `number` via `Number()`.
- * Accepts integers, floats, and scientific notation; `NaN` throws a {@link TypoError}.
+ * 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 into a `bigint` via `BigInt()`.
- * Floats and non-numeric strings throw a {@link TypoError}.
+ * Parses an integer string to `bigint` via `BigInt()`.
+ * Floats and non-numeric strings throw {@link TypoError}.
  *
  * @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 into a `URL` object.
- * Relative or malformed URLs throw a {@link TypoError}.
+ * Parses an absolute URL string to a `URL` object.
+ * Relative or malformed URLs throw {@link TypoError}.
  *
  * @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,
+  };
+}
 
 /**
- * Creates a {@link Type} by chaining `before`'s decoder with an `after` transformation.
+ * Chains `before`'s decoder with an `after` transformation.
  * `before` errors are prefixed with `"from: <content>"` for traceability.
  *
  * @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),
           () =>
@@ -240,31 +252,109 @@ export function typeMapped<Before, After>(
 }
 
 /**
- * Creates a {@link Type}`<string>` accepting only a fixed set of string values.
- * Out-of-set inputs throw a {@link TypoError} listing up to 5 valid options.
+ * Adds a name to a {@link Type} for clearer error messages and help text.
  *
- * @param content - Name shown in help and errors (e.g. `"Environment"`).
+ * @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 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) {
@@ -291,7 +381,7 @@ export function typeOneOf<const Value extends string>(
 }
 
 /**
- * Splits a delimited string into a fixed-length typed tuple.
+ * 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}.
  *
  * @typeParam Elements - Tuple of decoded value types (inferred from `elementTypes`).
@@ -302,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"
@@ -316,14 +406,14 @@ export function typeTuple<const Elements extends Array<any>>(
     content: elementTypes
       .map((elementType) => elementType.content)
       .join(separator),
-    decoder(value: string) {
-      const splits = value.split(separator, elementTypes.length);
+    decoder(input: string) {
+      const splits = input.split(separator, elementTypes.length);
       if (splits.length !== elementTypes.length) {
         throw new TypoError(
           new TypoText(
             new TypoString(`Found ${splits.length} splits: `),
             new TypoString(`Expected ${elementTypes.length} splits from: `),
-            new TypoString(`"${value}"`, typoStyleQuote),
+            new TypoString(`"${input}"`, typoStyleQuote),
           ),
         );
       }
@@ -343,7 +433,7 @@ export function typeTuple<const Elements extends Array<any>>(
 }
 
 /**
- * Splits a delimited string into a variable-length typed array.
+ * Splits a delimited string into a typed array.
  * Each part is decoded by `elementType`; failed decodes throw {@link TypoError}.
  * Note: splitting an empty string yields one empty element — prefer {@link optionRepeatable} for a zero-default.
  *
@@ -359,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"]
  * ```
  */