cli-kiss 0.2.4 → 0.2.6

package/docs/guide/05_types.md

@@ -1,132 +0,0 @@
-# Types
-
-A `Type<Value>` converts a raw CLI string into a typed value: a `content` label paired with a `decoder`.
-
-## Built-in types
-
-| Export        | TypeScript type | Accepts                                                    |
-| ------------- | --------------- | ---------------------------------------------------------- |
-| `typeString`  | `string`        | Any string                                                 |
-| `typeBoolean` | `boolean`       | `true/yes/on/1/y/t` → true, `false/no/off/0/n/f` → false (case-insensitive) |
-| `typeNumber`  | `number`        | Integers, floats, scientific notation                      |
-| `typeInteger` | `bigint`        | Integer strings only                                       |
-| `typeDate`    | `Date`          | Any format accepted by `Date.parse` (ISO 8601 recommended) |
-| `typeUrl`     | `URL`           | Absolute URLs                                              |
-
-```ts
-import {
-  typeBoolean,
-  typeDate,
-  typeInteger,
-  typeNumber,
-  typeString,
-  typeUrl,
-} from "cli-kiss";
-
-typeString.decoder("hello"); // → "hello"
-typeBoolean.decoder("yes"); // → true
-typeNumber.decoder("3.14"); // → 3.14
-typeInteger.decoder("9007199254740993"); // → 9007199254740993n
-typeDate.decoder("2024-01-15"); // → Date object
-typeUrl.decoder("https://example.com/path"); // → URL object
-```
-
-## `typeOneOf` — string enum
-
-Accepts only a fixed set of strings:
-
-```ts
-import { typeOneOf } from "cli-kiss";
-
-const typeEnv = typeOneOf("Environment", ["dev", "staging", "prod"]);
-
-typeEnv.decoder("prod"); // → "prod"
-typeEnv.decoder("unknown");
-// Error: Invalid value: "unknown" (expected one of: "dev" | "staging" | "prod")
-```
-
-## `typeMapped` — transform an existing type
-
-Chain a `before` type with an `after` transformation:
-
-```ts
-import { typeMapped, typeNumber } from "cli-kiss";
-
-const typePort = typeMapped(typeNumber, {
-  content: "Port",
-  decoder: (n) => {
-    if (n < 1 || n > 65535) throw new Error("Out of range");
-    return n;
-  },
-});
-// "--port 8080"   →  8080
-// "--port 99999"  →  Error: --port: <PORT>: Port: Out of range
-```
-
-Errors from the `before` decoder are prefixed with `from: <content>`.
-
-## `typeTuple` — fixed-length delimited value
-
-Splits a string into a fixed-length typed tuple:
-
-```ts
-import { typeTuple, typeNumber } from "cli-kiss";
-
-const typePoint = typeTuple([typeNumber, typeNumber]);
-
-typePoint.decoder("3.14,2.71"); // → [3.14, 2.71]
-typePoint.decoder("x,2"); // → Error: at 0: Number: Unable to parse: "x"
-```
-
-The default separator is `","`. Pass a second argument to change it:
-
-```ts
-typeTuple([typeString, typeNumber], ":");
-// "foo:42"  →  ["foo", 42]
-```
-
-## `typeList` — variable-length delimited value
-
-Splits a string into an array of typed values:
-
-```ts
-import { typeList, typeNumber } from "cli-kiss";
-
-const typeNumbers = typeList(typeNumber);
-
-typeNumbers.decoder("1,2,3"); // → [1, 2, 3]
-typeNumbers.decoder("1,x,3"); // → Error: at 1: Number: Unable to parse: "x"
-```
-
-Custom separator:
-
-```ts
-const typePaths = typeList(typeString, ":");
-typePaths.decoder("/usr/bin:/usr/local/bin"); // → ["/usr/bin", "/usr/local/bin"]
-```
-
-::: tip Prefer
-[`optionRepeatable`](/guide/03_options#optionrepeatable-collect-multiple-values)
-over `typeList` when users should pass multiple values as separate flags
-(`--file a --file b` rather than `--files a,b`).
-
-:::
-
-## Custom types
-
-Implement the `Type<Value>` interface directly:
-
-```ts
-import type { Type } from "cli-kiss";
-
-const typeHexColor: Type<string> = {
-  content: "HexColor",
-  decoder(value) {
-    if (/^#[0-9a-fA-F]{6}$/.test(value)) return value;
-    throw new Error(`Not a valid value: "${value}"`);
-  },
-};
-
-// "--color #ff0000"  →  "#ff0000"
-// "--color red"      →  Error: --color: <HEXCOLOR>: HexColor: Not a valid value: "red"
-```

package/docs/guide/06_run.md

@@ -1,160 +0,0 @@
-# Running your CLI
-
-## `runAndExit`
-
-`runAndExit` parses arguments, runs the matched command, and exits.
-
-```ts
-await runAndExit(cliName, cliArgs, context, command, options?);
-```
-
-| Parameter | Type                               | Description                                       |
-| --------- | ---------------------------------- | ------------------------------------------------- |
-| `cliName` | `Lowercase<string>`                | Program name used in help and `--version` output  |
-| `cliArgs` | `ReadonlyArray<string>`            | Raw arguments — typically `process.argv.slice(2)` |
-| `context` | `Context`                          | Value forwarded to every command handler          |
-| `command` | `Command<Context, void>`           | The root command                                  |
-| `options` | `object?`                          | See below                                         |
-
-### Options
-
-| Option         | Type                       | Default        | Description                                                 |
-| -------------- | -------------------------- | -------------- | ----------------------------------------------------------- |
-| `buildVersion` | `string?`                  | —              | Enables `--version` flag; prints `<cliName> <buildVersion>` |
-| `usageOnHelp`  | `boolean?`                 | `true`         | Enables `--help` flag                                       |
-| `usageOnError` | `boolean?`                 | `true`         | Prints usage to stderr when parsing fails                   |
-| `useTtyColors` | `boolean \| "mock"?`       | auto           | Controls ANSI color output                                  |
-| `onError`      | `(error: unknown) => void` | —              | Custom handler for parse and execution errors               |
-| `onExit`       | `(code: number) => never`  | `process.exit` | Override for testing                                        |
-
-### Exit codes
-
-| Code | Reason                                  |
-| ---- | --------------------------------------- |
-| `0`  | Success, `--help`, or `--version`       |
-| `1`  | Parse error or uncaught execution error |
-
-## Full example
-
-```ts
-import {
-  command,
-  commandWithSubcommands,
-  operation,
-  optionFlag,
-  optionSingleValue,
-  positionalRequired,
-  runAndExit,
-  typeString,
-  typeUrl,
-} from "cli-kiss";
-
-type Ctx = { db: string };
-
-const deployCmd = command(
-  { description: "Deploy to production" },
-  operation(
-    {
-      options: {
-        dryRun: optionFlag({ long: "dry-run", description: "Simulate only" }),
-      },
-      positionals: [],
-    },
-    async ({ db }, { options: { dryRun } }) => {
-      if (dryRun) {
-        console.log(`[dry-run] would deploy with DB: ${db}`);
-      } else {
-        console.log(`Deploying with DB: ${db}`);
-      }
-    },
-  ),
-);
-
-const rootCmd = commandWithSubcommands(
-  { description: "My deployment CLI" },
-  operation(
-    {
-      options: {
-        dbUrl: optionSingleValue({
-          long: "db",
-          type: typeUrl,
-          description: "Database URL",
-          default: () => new URL("postgres://localhost/mydb"),
-        }),
-      },
-      positionals: [],
-    },
-    async (_ctx, { options: { dbUrl } }): Promise<Ctx> => ({
-      db: dbUrl.toString(),
-    }),
-  ),
-  { deploy: deployCmd },
-);
-
-await runAndExit("my-cli", process.argv.slice(2), undefined, rootCmd, {
-  buildVersion: "2.0.0",
-});
-```
-
-Check it
-
-```sh
-my-cli --help
-```
-
-```text
-Usage: my-cli <SUBCOMMAND>
-
-My deployment CLI
-
-Subcommands:
-  deploy  Deploy to production
-
-Options:
-  --db <URL>  Database URL
-```
-
-Try it
-
-```sh
-my-cli deploy --dry-run
-```
-
-```text
-[dry-run] would deploy with DB: postgres://localhost/mydb
-```
-
-## Color control
-
-Colors are auto-detected. Override:
-
-```ts
-// Force colors on
-await runAndExit("my-cli", args, ctx, cmd, { useTtyColors: true });
-
-// Force colors off (useful in CI)
-await runAndExit("my-cli", args, ctx, cmd, { useTtyColors: false });
-
-// Deterministic mock output (useful in snapshot tests)
-await runAndExit("my-cli", args, ctx, cmd, { useTtyColors: "mock" });
-```
-
-## Testing your CLI
-
-Override `onExit` to prevent process exit during tests:
-
-```ts
-import { runAndExit } from "cli-kiss";
-
-const exitCodes: number[] = [];
-
-await runAndExit("my-cli", ["--help"], undefined, myCommand, {
-  useTtyColors: false,
-  onExit: (code) => {
-    exitCodes.push(code);
-    return undefined as never;
-  },
-});
-
-console.assert(exitCodes[0] === 0, "expected exit 0 for --help");
-```