cli-kiss 0.0.1

package/src/lib/Usage.ts

@@ -0,0 +1,104 @@
+import { CommandUsage } from "./Command";
+
+export function usageFormatter(
+  cliName: string,
+  commandUsage: CommandUsage,
+): string {
+  const lines = new Array<string>();
+  if (commandUsage.description) {
+    lines.push("");
+    lines.push(commandUsage.description);
+  }
+  lines.push("");
+  lines.push(`Usage: ${cliName} ${commandUsage.breadcrumbs.join(" ")}`);
+  if (commandUsage.arguments.length > 0) {
+    lines.push("");
+    lines.push("Arguments:");
+    lines.push("");
+    const rows = new Array<Array<string>>();
+    for (const argumentUsage of commandUsage.arguments) {
+      const columns = new Array<string>();
+      columns.push("");
+      columns.push(argumentUsage.label);
+      columns.push("");
+      if (argumentUsage.description) {
+        columns.push(argumentUsage.description);
+      }
+      rows.push(columns);
+    }
+    pushGrid(lines, rows);
+  }
+  if (commandUsage.options.length > 0) {
+    lines.push("");
+    lines.push("Options:");
+    lines.push("");
+    const rows = new Array<Array<string>>();
+    for (const optionUsage of commandUsage.options) {
+      const columns = new Array<string>();
+      columns.push("");
+      if (optionUsage.short) {
+        columns.push(`-${optionUsage.short},`);
+      } else {
+        columns.push("");
+      }
+      if (optionUsage.label) {
+        columns.push(`--${optionUsage.long} ${optionUsage.label}`);
+      } else {
+        columns.push(`--${optionUsage.long}`);
+      }
+      columns.push("");
+      if (optionUsage.description) {
+        columns.push(optionUsage.description);
+      }
+      rows.push(columns);
+    }
+    pushGrid(lines, rows);
+  }
+  if (commandUsage.subcommands.length > 0) {
+    lines.push("");
+    lines.push("Subcommands:");
+    lines.push("");
+    const rows = new Array<Array<string>>();
+    for (const subcommand of commandUsage.subcommands) {
+      const columns = new Array<string>();
+      columns.push("");
+      columns.push(subcommand.name);
+      columns.push("");
+      if (subcommand.description) {
+        columns.push(subcommand.description);
+      }
+      rows.push(columns);
+    }
+    pushGrid(lines, rows);
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+
+function pushGrid(lines: Array<string>, rows: Array<Array<string>>) {
+  const widths = new Array<number>();
+  for (const row of rows) {
+    for (let columnIndex = 0; columnIndex < row.length; columnIndex++) {
+      const cell = row[columnIndex]!;
+      if (
+        widths[columnIndex] === undefined ||
+        cell.length > widths[columnIndex]!
+      ) {
+        widths[columnIndex] = cell.length;
+      }
+    }
+  }
+  for (const row of rows) {
+    const cells = new Array<string>();
+    for (let columnIndex = 0; columnIndex < row.length; columnIndex++) {
+      const cell = row[columnIndex]!;
+      if (columnIndex < row.length - 1) {
+        const padding = " ".repeat(widths[columnIndex]! - cell.length);
+        cells.push(cell + padding);
+      } else {
+        cells.push(cell);
+      }
+    }
+    lines.push(cells.join(" "));
+  }
+}

package/tests/unit.Reader.aliases.ts

@@ -0,0 +1,46 @@
+import { expect, it } from "@jest/globals";
+import { ReaderTokenizer } from "../src";
+
+it("run", async () => {
+  const readerTokenizer = new ReaderTokenizer([
+    "--option=1.1",
+    "--option-alias1=1.2",
+    "--option-alias2",
+    "1.3",
+    "-pts=1.4",
+    "-o",
+    "1.5",
+    "--flag-alias",
+    "-fa2",
+  ]);
+
+  readerTokenizer.registerOption({
+    key: "option",
+    longs: ["option", "option-alias1", "option-alias2"],
+    shorts: ["pts", "o"],
+  });
+
+  readerTokenizer.registerFlag({
+    key: "flag1",
+    longs: ["flag1", "flag-alias"],
+    shorts: [],
+  });
+  readerTokenizer.registerFlag({
+    key: "flag2",
+    longs: ["flag2"],
+    shorts: ["fa2"],
+  });
+
+  expect(readerTokenizer.consumePositional()).toStrictEqual(undefined);
+
+  expect(readerTokenizer.consumeOption("option")).toStrictEqual([
+    "1.1",
+    "1.2",
+    "1.3",
+    "1.4",
+    "1.5",
+  ]);
+
+  expect(readerTokenizer.consumeFlag("flag1")).toStrictEqual(true);
+  expect(readerTokenizer.consumeFlag("flag2")).toStrictEqual(true);
+});

package/tests/unit.Reader.commons.ts

@@ -0,0 +1,124 @@
+import { expect, it } from "@jest/globals";
+import { ReaderTokenizer } from "../src";
+
+it("run", async () => {
+  const stream = new ReaderTokenizer([
+    "positional-0",
+    "--flag-normal",
+    "--flag-positive=true",
+    "--flag-negative=false",
+    "positional-1",
+    "--option-split",
+    "1.1",
+    "--option-split",
+    "1.2",
+    "--option-join=2",
+    "-ab",
+    "3.1",
+    "-cd=4.1",
+    "-ef5.1",
+    "positional-2",
+    "-gh=false",
+    "-ij=true",
+    "-b",
+    "3.2",
+    "-d=4.2",
+    "-f5.2",
+    "positional-3",
+    "--",
+    "--not-a-flag",
+    "-mn",
+    "--",
+    "positional-4",
+  ]);
+
+  expect(stream.consumePositional()).toStrictEqual("positional-0");
+
+  stream.registerFlag({
+    key: "flag-normal",
+    longs: ["flag-normal"],
+    shorts: [],
+  });
+  stream.registerFlag({
+    key: "flag-positive",
+    longs: ["flag-positive"],
+    shorts: [],
+  });
+  stream.registerFlag({
+    key: "flag-negative",
+    longs: ["flag-negative"],
+    shorts: [],
+  });
+  stream.registerFlag({
+    key: "flag-unset",
+    longs: ["flag-unset"],
+    shorts: [],
+  });
+
+  expect(stream.consumePositional()).toStrictEqual("positional-1");
+
+  stream.registerOption({
+    key: "option-split",
+    longs: ["option-split"],
+    shorts: [],
+  });
+  stream.registerOption({
+    key: "option-join",
+    longs: ["option-join"],
+    shorts: [],
+  });
+  stream.registerOption({
+    key: "option-unset",
+    longs: ["option-unset"],
+    shorts: [],
+  });
+
+  stream.registerFlag({ key: "a", longs: [], shorts: ["a"] });
+  stream.registerOption({ key: "b", longs: [], shorts: ["b"] });
+
+  stream.registerFlag({ key: "c", longs: [], shorts: ["c"] });
+  stream.registerOption({ key: "d", longs: [], shorts: ["d"] });
+
+  stream.registerFlag({ key: "e", longs: [], shorts: ["e"] });
+  stream.registerOption({ key: "f", longs: [], shorts: ["f"] });
+
+  expect(stream.consumePositional()).toStrictEqual("positional-2");
+
+  stream.registerFlag({ key: "g", longs: [], shorts: ["g"] });
+  stream.registerFlag({ key: "h", longs: [], shorts: ["h"] });
+
+  stream.registerFlag({ key: "i", longs: [], shorts: ["i"] });
+  stream.registerFlag({ key: "j", longs: [], shorts: ["j"] });
+
+  expect(stream.consumePositional()).toStrictEqual("positional-3");
+
+  expect(stream.consumePositional()).toStrictEqual("--not-a-flag");
+  expect(stream.consumePositional()).toStrictEqual("-mn");
+  expect(stream.consumePositional()).toStrictEqual("--");
+  expect(stream.consumePositional()).toStrictEqual("positional-4");
+  expect(stream.consumePositional()).toStrictEqual(undefined);
+
+  expect(stream.consumeFlag("flag-normal")).toStrictEqual(true);
+  expect(stream.consumeFlag("flag-positive")).toStrictEqual(true);
+  expect(stream.consumeFlag("flag-negative")).toStrictEqual(false);
+  expect(stream.consumeFlag("flag-unset")).toStrictEqual(undefined);
+
+  expect(stream.consumeOption("option-unset")).toStrictEqual([]);
+  expect(stream.consumeOption("option-split")).toStrictEqual(["1.1", "1.2"]);
+  expect(stream.consumeOption("option-join")).toStrictEqual(["2"]);
+
+  expect(stream.consumeFlag("a")).toStrictEqual(true);
+  expect(stream.consumeOption("b")).toStrictEqual(["3.1", "3.2"]);
+
+  expect(stream.consumeFlag("c")).toStrictEqual(true);
+  expect(stream.consumeOption("d")).toStrictEqual(["4.1", "4.2"]);
+
+  expect(stream.consumeFlag("e")).toStrictEqual(true);
+  expect(stream.consumeOption("f")).toStrictEqual(["5.1", "5.2"]);
+
+  expect(stream.consumeFlag("g")).toStrictEqual(true);
+  expect(stream.consumeFlag("h")).toStrictEqual(false);
+
+  expect(stream.consumeFlag("i")).toStrictEqual(true);
+  expect(stream.consumeFlag("j")).toStrictEqual(true);
+});

package/tests/unit.Reader.shortBig.ts

@@ -0,0 +1,86 @@
+import { expect, it } from "@jest/globals";
+import { ReaderTokenizer } from "../src";
+
+it("run", async () => {
+  const stream = new ReaderTokenizer([
+    "positional-0",
+    "-aasof-normal",
+    "-bbsof-positive=true",
+    "-ccsof-negative=false",
+    "positional-1",
+    "-ddsov-split",
+    "1.1",
+    "-eesov-split",
+    "1.2",
+    "-ffsov-join=2",
+    "positional-2",
+  ]);
+
+  expect(stream.consumePositional()).toStrictEqual("positional-0");
+
+  stream.registerFlag({
+    key: "sof-normal",
+    shorts: ["sof-normal"],
+    longs: [],
+  });
+  stream.registerFlag({
+    key: "sof-positive",
+    longs: [],
+    shorts: ["sof-positive"],
+  });
+  stream.registerFlag({
+    key: "sof-negative",
+    longs: [],
+    shorts: ["sof-negative"],
+  });
+  stream.registerFlag({
+    key: "sof-unset",
+    longs: [],
+    shorts: ["sof-unset"],
+  });
+
+  stream.registerFlag({ key: "aa", longs: [], shorts: ["aa"] });
+  stream.registerFlag({ key: "bb", longs: [], shorts: ["bb"] });
+  stream.registerFlag({ key: "cc", longs: [], shorts: ["cc"] });
+
+  expect(stream.consumePositional()).toStrictEqual("positional-1");
+
+  stream.registerOption({
+    key: "sov-split",
+    longs: [],
+    shorts: ["sov-split"],
+  });
+  stream.registerOption({
+    key: "sov-join",
+    longs: [],
+    shorts: ["sov-join"],
+  });
+  stream.registerOption({
+    key: "sov-unset",
+    longs: [],
+    shorts: ["sov-unset"],
+  });
+
+  stream.registerFlag({ key: "dd", longs: [], shorts: ["dd"] });
+  stream.registerFlag({ key: "ee", longs: [], shorts: ["ee"] });
+  stream.registerFlag({ key: "ff", longs: [], shorts: ["ff"] });
+
+  expect(stream.consumePositional()).toStrictEqual("positional-2");
+
+  expect(stream.consumeFlag("sof-normal")).toStrictEqual(true);
+  expect(stream.consumeFlag("sof-positive")).toStrictEqual(true);
+  expect(stream.consumeFlag("sof-negative")).toStrictEqual(false);
+  expect(stream.consumeFlag("sof-unset")).toStrictEqual(undefined);
+
+  expect(stream.consumeFlag("aa")).toStrictEqual(true);
+  expect(stream.consumeFlag("bb")).toStrictEqual(true);
+  expect(stream.consumeFlag("cc")).toStrictEqual(true);
+
+  expect(stream.consumeOption("sov-unset")).toStrictEqual([]);
+  expect(stream.consumeOption("sov-split")).toStrictEqual(["1.1", "1.2"]);
+  expect(stream.consumeOption("sov-join")).toStrictEqual(["2"]);
+
+  expect(stream.consumeFlag("dd")).toStrictEqual(true);
+  expect(stream.consumeFlag("ee")).toStrictEqual(true);
+  expect(stream.consumeFlag("ff")).toStrictEqual(true);
+});

package/tests/unit.command.run.ts

@@ -0,0 +1,139 @@
+import { expect, it } from "@jest/globals";
+import {
+  argumentOptional,
+  argumentRequired,
+  argumentVariadics,
+  command,
+  commandWithSubcommands,
+  optionFlag,
+  optionRepeatable,
+  optionSingleValue,
+  processor,
+  runWithArgv,
+  typeNumber,
+  typeString,
+} from "../src";
+
+const cmd = commandWithSubcommands<string, any, any>(
+  "Root command description",
+  processor(
+    {
+      options: {
+        booleanFlag: optionFlag({ long: "boolean-flag", default: () => false }),
+        stringOption: optionSingleValue({
+          long: "string-option",
+          type: typeString,
+          default: () => undefined,
+        }),
+        numberOption: optionRepeatable({
+          long: "number-option",
+          type: typeNumber,
+        }),
+      },
+      arguments: [
+        argumentRequired({ type: typeNumber }),
+        argumentRequired({ type: typeNumber }),
+      ],
+    },
+    async (context, inputs) => {
+      return { at: "root", context, inputs };
+    },
+  ),
+  {
+    sub1: command(
+      "Subcommand 1 description",
+      processor(
+        {
+          options: {},
+          arguments: [argumentRequired({ type: typeString })],
+        },
+        async (context, inputs) => {
+          return { at: "sub1", context, inputs };
+        },
+      ),
+    ),
+    sub2: command(
+      "Subcommand 2 description",
+      processor(
+        {
+          options: {},
+          arguments: [
+            argumentRequired({ type: typeNumber }),
+            argumentOptional({ type: typeString, default: () => "42" }),
+            argumentVariadics({ type: typeString }),
+          ],
+        },
+        async (context, inputs) => {
+          return { at: "sub2", context, inputs };
+        },
+      ),
+    ),
+  },
+);
+
+it("run", async () => {
+  const res1 = await runWithArgv(
+    ["node", "script", "50", "51", "sub1", "final"],
+    "Run Context Input",
+    cmd,
+  );
+  expect(res1).toStrictEqual({
+    context: {
+      context: "Run Context Input",
+      inputs: {
+        options: {
+          booleanFlag: false,
+          stringOption: undefined,
+          numberOption: [],
+        },
+        arguments: [50, 51],
+      },
+      at: "root",
+    },
+    inputs: {
+      options: {},
+      arguments: ["final"],
+    },
+    at: "sub1",
+  });
+
+  const res2 = await runWithArgv(
+    [
+      "node",
+      "script",
+      "40",
+      "41",
+      "sub2",
+      "--string-option=hello",
+      "--number-option",
+      "123",
+      "--number-option",
+      "1234",
+      "88.88",
+      "a,b",
+      "final",
+      "--boolean-flag",
+    ],
+    "Run Context Input",
+    cmd,
+  );
+  expect(res2).toStrictEqual({
+    context: {
+      context: "Run Context Input",
+      inputs: {
+        options: {
+          booleanFlag: true,
+          stringOption: "hello",
+          numberOption: [123, 1234],
+        },
+        arguments: [40, 41],
+      },
+      at: "root",
+    },
+    inputs: {
+      options: {},
+      arguments: [88.88, "a,b", ["final"]],
+    },
+    at: "sub2",
+  });
+});

package/tests/unit.command.usage.ts

@@ -0,0 +1,153 @@
+import { it } from "@jest/globals";
+import {
+  argumentOptional,
+  argumentRequired,
+  argumentVariadics,
+  Command,
+  command,
+  commandWithSubcommands,
+  optionFlag,
+  optionRepeatable,
+  optionSingleValue,
+  processor,
+  ReaderTokenizer,
+  typeNumber,
+  typeString,
+} from "../src";
+import { usageFormatter } from "../src/lib/Usage";
+
+const cmd = commandWithSubcommands<string, any, any>(
+  "Root command description",
+  processor(
+    {
+      options: {
+        booleanFlag: optionFlag({
+          short: "b",
+          long: "boolean-flag",
+          description: "Root boolean-flag description",
+        }),
+        stringOption: optionSingleValue({
+          short: "s",
+          long: "string-option",
+          type: typeString,
+          default: () => undefined,
+          label: "COOL_STUFF",
+          description: "Root string-option description",
+        }),
+        numberOption: optionRepeatable({
+          short: "n",
+          long: "number-option",
+          type: typeNumber,
+          description: "Root number-option description",
+        }),
+      },
+      arguments: [
+        argumentRequired({
+          label: "POSITIONAL-1",
+          description: "First positional argument",
+          type: typeNumber,
+        }),
+        argumentRequired({
+          label: "POSITIONAL-2",
+          description: "Second positional argument",
+          type: typeNumber,
+        }),
+      ],
+    },
+    async (context, inputs) => {
+      return { at: "root", context, inputs };
+    },
+  ),
+  {
+    sub1: command(
+      "Subcommand 1 description",
+      processor(
+        {
+          options: {},
+          arguments: [
+            argumentRequired({
+              label: "POS-STRING",
+              description: "Positional string argument",
+              type: typeString,
+            }),
+          ],
+        },
+        async (context, inputs) => {
+          return { at: "sub1", context, inputs };
+        },
+      ),
+    ),
+    sub2: command(
+      "Subcommand 2 description",
+      processor(
+        {
+          options: {
+            duduValue: optionSingleValue({
+              long: "dudu",
+              type: typeString,
+              default: () => "duduDefault",
+              description: "Dudu option description",
+            }),
+          },
+          arguments: [
+            argumentRequired({
+              label: "POS-NUMBER",
+              description: "Positional number argument",
+              type: typeNumber,
+            }),
+            argumentOptional({
+              label: "OPT-POSITIONAL",
+              description: "Optional positional argument",
+              type: typeString,
+              default: () => "42",
+            }),
+            argumentVariadics({
+              label: "VARIADIC-POSITIONALS",
+              description: "Variadic positional arguments",
+              type: typeString,
+            }),
+          ],
+        },
+        async (context, inputs) => {
+          return { at: "sub2", context, inputs };
+        },
+      ),
+    ),
+  },
+);
+
+it("run", async () => {
+  const res0 = getUsage([], cmd);
+  console.log(res0);
+
+  const res1 = getUsage(["50", "51", "sub1", "final"], cmd);
+  console.log(res1);
+  //expect(res1).toStrictEqual({});
+
+  const res2 = getUsage(
+    [
+      "40",
+      "41",
+      "sub2",
+      "--string-option=hello",
+      "--number-option",
+      "123",
+      "--number-option",
+      "1234",
+      "88.88",
+      "a,b",
+      "final",
+      "--boolean-flag",
+    ],
+    cmd,
+  );
+  console.log(res2);
+});
+
+function getUsage<Context, Result>(
+  argv: Array<string>,
+  command: Command<Context, Result>,
+) {
+  const commandRunner = command.prepareRunner(new ReaderTokenizer(argv));
+  return usageFormatter("my-cli", commandRunner.computeUsage());
+}

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "outDir": "dist",
+    "declaration": true,
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "strict": true,
+    "alwaysStrict": true,
+    "noImplicitOverride": true,
+    "noImplicitAny": true,
+    "noImplicitThis": true,
+    "noImplicitReturns": true,
+    "noPropertyAccessFromIndexSignature": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "useUnknownInCatchVariables": true,
+    "erasableSyntaxOnly": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src", "tests"]
+}