cli-kiss 0.0.1

package/src/lib/Option.ts

@@ -0,0 +1,140 @@
+import { ReaderTokenizer } from "./Reader";
+import { Type } from "./Type";
+
+export type Option<Value> = {
+  generateUsage(): OptionUsage;
+  prepareConsumer(readerTokenizer: ReaderTokenizer): OptionConsumer<Value>;
+};
+
+export type OptionUsage = {
+  description: string | undefined;
+  long: Lowercase<string>; // TODO - better type for long option names ?
+  short: string | undefined;
+  label: Uppercase<string> | undefined;
+};
+
+export type OptionConsumer<Value> = () => Value;
+
+export function optionFlag(definition: {
+  description?: string;
+  long: Lowercase<string>;
+  short?: string;
+  aliases?: { longs?: Array<Lowercase<string>>; shorts?: Array<string> };
+  default?: () => boolean;
+}): Option<boolean> {
+  return {
+    generateUsage() {
+      return {
+        description: definition.description,
+        long: definition.long,
+        short: definition.short,
+        label: undefined,
+      };
+    },
+    prepareConsumer(readerTokenizer: ReaderTokenizer) {
+      const key = definition.long;
+      const longs = [definition.long];
+      if (definition.aliases?.longs) {
+        longs.push(...definition.aliases?.longs);
+      }
+      const shorts = definition.short ? [definition.short] : [];
+      if (definition.aliases?.shorts) {
+        shorts.push(...definition.aliases?.shorts);
+      }
+      readerTokenizer.registerFlag({ key, longs, shorts });
+      return () => {
+        const value = readerTokenizer.consumeFlag(key);
+        if (value === undefined) {
+          return definition.default ? definition.default() : false;
+        }
+        return value;
+      };
+    },
+  };
+}
+
+// TODO - option with comma-separated values, e.g. --names=alice,bob,charlie
+
+export function optionRepeatable<Value>(definition: {
+  description?: string;
+  type: Type<Value>;
+  long: Lowercase<string>;
+  short?: string;
+  aliases?: { longs?: Array<Lowercase<string>>; shorts?: Array<string> };
+  label?: Uppercase<string>;
+}): Option<Array<Value>> {
+  return {
+    generateUsage() {
+      return {
+        description: definition.description,
+        long: definition.long,
+        short: definition.short,
+        label:
+          `<${definition.label ?? definition.type.label}>` as Uppercase<string>,
+      };
+    },
+    prepareConsumer(readerTokenizer: ReaderTokenizer) {
+      const key = definition.long;
+      const longs = definition.long ? [definition.long] : [];
+      if (definition.aliases?.longs) {
+        longs.push(...definition.aliases?.longs);
+      }
+      const shorts = definition.short ? [definition.short] : [];
+      if (definition.aliases?.shorts) {
+        shorts.push(...definition.aliases?.shorts);
+      }
+      readerTokenizer.registerOption({ key, longs, shorts });
+      return () => {
+        return readerTokenizer.consumeOption(key).map(definition.type.decoder);
+      };
+    },
+  };
+}
+
+export function optionSingleValue<Value>(definition: {
+  description?: string;
+  type: Type<Value>;
+  long: Lowercase<string>;
+  short?: string;
+  aliases?: { longs?: Array<Lowercase<string>>; shorts?: Array<string> };
+  label?: Uppercase<string>;
+  default: () => Value;
+}): Option<Value> {
+  return {
+    generateUsage() {
+      return {
+        description: definition.description,
+        long: definition.long,
+        short: definition.short,
+        label:
+          `<${definition.label ?? definition.type.label}>` as Uppercase<string>,
+      };
+    },
+    prepareConsumer(readerTokenizer: ReaderTokenizer) {
+      const key = definition.long;
+      const longs = [definition.long];
+      if (definition.aliases?.longs) {
+        longs.push(...definition.aliases?.longs);
+      }
+      const shorts = definition.short ? [definition.short] : [];
+      if (definition.aliases?.shorts) {
+        shorts.push(...definition.aliases?.shorts);
+      }
+      readerTokenizer.registerOption({ key, longs, shorts });
+      return () => {
+        // TODO - error handling
+        const values = readerTokenizer.consumeOption(definition.long);
+        if (values.length > 1) {
+          throw new Error(
+            `Multiple values provided for option: ${definition.long}`,
+          );
+        }
+        const firstValue = values[0];
+        if (firstValue === undefined) {
+          return definition.default();
+        }
+        return definition.type.decoder(firstValue);
+      };
+    },
+  };
+}

package/src/lib/Processor.ts

@@ -0,0 +1,87 @@
+import { Argument, ArgumentUsage } from "./Argument";
+import { Option, OptionUsage } from "./Option";
+import { ReaderTokenizer } from "./Reader";
+
+export type Processor<Context, Result> = {
+  computeUsage(): ProcessorUsage;
+  prepareResolver(
+    readerTokenizer: ReaderTokenizer,
+  ): ProcessorResolver<Context, Result>;
+};
+
+export type ProcessorResolver<Context, Result> = () => ProcessorRunner<
+  Context,
+  Result
+>;
+
+export type ProcessorRunner<Context, Result> = {
+  execute(context: Context): Promise<Result>;
+};
+
+export type ProcessorUsage = {
+  options: Array<OptionUsage>;
+  arguments: Array<ArgumentUsage>;
+};
+
+export function processor<
+  Context,
+  Result,
+  Options extends { [option: string]: Option<any> },
+  const Arguments extends Array<Argument<any>>,
+>(
+  inputs: { options: Options; arguments: Arguments },
+  handler: (
+    context: Context,
+    inputs: {
+      options: {
+        [K in keyof Options]: ReturnType<
+          ReturnType<Options[K]["prepareConsumer"]>
+        >;
+      };
+      arguments: {
+        [K in keyof Arguments]: ReturnType<Arguments[K]["consumeValue"]>;
+      };
+    },
+  ) => Promise<Result>,
+): Processor<Context, Result> {
+  return {
+    computeUsage() {
+      const optionsUsage = new Array<OptionUsage>();
+      for (const optionKey in inputs.options) {
+        const optionInput = inputs.options[optionKey]!;
+        optionsUsage.push(optionInput.generateUsage());
+      }
+      const argumentsUsage = new Array<ArgumentUsage>();
+      for (const argumentInput of inputs.arguments) {
+        argumentsUsage.push(argumentInput.generateUsage());
+      }
+      return { options: optionsUsage, arguments: argumentsUsage };
+    },
+    prepareResolver(readerTokenizer: ReaderTokenizer) {
+      const optionsConsumers: any = {};
+      for (const optionKey in inputs.options) {
+        const optionInput = inputs.options[optionKey]!;
+        optionsConsumers[optionKey] =
+          optionInput.prepareConsumer(readerTokenizer);
+      }
+      const argumentsValues: any = [];
+      for (const argumentInput of inputs.arguments) {
+        argumentsValues.push(argumentInput.consumeValue(readerTokenizer));
+      }
+      return () => {
+        const optionsValues: any = {};
+        for (const optionKey in optionsConsumers) {
+          optionsValues[optionKey] = optionsConsumers[optionKey]!();
+        }
+        return {
+          async execute(context: Context) {
+            return await handler(context, {
+              options: optionsValues,
+              arguments: argumentsValues,
+            });
+          },
+        };
+      };
+    },
+  };
+}

package/src/lib/Reader.ts

@@ -0,0 +1,285 @@
+export type ReaderPositionals = {
+  consumePositional(): string | undefined;
+};
+
+export class ReaderTokenizer {
+  #parsedArgv: Array<string>;
+  #parsedIndex: number;
+  #parsedDouble: boolean;
+
+  #flagKeyByShort: Map<string, string>;
+  #flagKeyByLong: Map<string, string>;
+  #flagInfoByKey: Map<string, {}>;
+  #flagResultByKey: Map<string, boolean | null>;
+
+  #optionKeyByShort: Map<string, string>;
+  #optionKeyByLong: Map<string, string>;
+  #optionInfoByKey: Map<string, {}>; // TODO - what dis for
+  #optionResultByKey: Map<string, Array<string> | null>;
+
+  constructor(argv: Array<string>) {
+    this.#parsedArgv = argv;
+    this.#parsedIndex = 0;
+    this.#parsedDouble = false;
+
+    // TODO - this seems like a good candidate for abstraction
+    this.#flagKeyByShort = new Map();
+    this.#flagKeyByLong = new Map();
+    this.#flagInfoByKey = new Map();
+    this.#flagResultByKey = new Map();
+
+    this.#optionKeyByShort = new Map();
+    this.#optionKeyByLong = new Map();
+    this.#optionInfoByKey = new Map();
+    this.#optionResultByKey = new Map();
+  }
+
+  registerFlag(definition: {
+    key: string;
+    shorts: Array<string>;
+    longs: Array<string>;
+  }) {
+    this.#ensureUniqueKey(definition.key);
+    this.#flagInfoByKey.set(definition.key, {});
+    for (const short of definition.shorts) {
+      this.#ensureUniqueName(short);
+      this.#flagKeyByShort.set(short, definition.key);
+    }
+    for (const long of definition.longs) {
+      this.#ensureUniqueName(long);
+      this.#flagKeyByLong.set(long, definition.key);
+    }
+  }
+
+  registerOption(definition: {
+    key: string;
+    shorts: Array<string>;
+    longs: Array<string>;
+  }) {
+    this.#ensureUniqueKey(definition.key);
+    this.#optionInfoByKey.set(definition.key, {});
+    for (const short of definition.shorts) {
+      this.#ensureUniqueName(short);
+      this.#optionKeyByShort.set(short, definition.key);
+    }
+    for (const long of definition.longs) {
+      this.#ensureUniqueName(long);
+      this.#optionKeyByLong.set(long, definition.key);
+    }
+  }
+
+  consumeFlag(key: string): boolean | undefined {
+    const flagInfo = this.#flagInfoByKey.get(key);
+    if (flagInfo === undefined) {
+      throw new Error(`Option flag not registered: ${key}`);
+    }
+    const result = this.#flagResultByKey.get(key);
+    if (result === undefined) {
+      this.#flagResultByKey.set(key, null);
+      return undefined;
+    }
+    if (result === null) {
+      throw new Error(`Option flag already consumed: ${key}`);
+    }
+    this.#flagResultByKey.set(key, null);
+    return result;
+  }
+
+  consumeOption(key: string): Array<string> {
+    const optionInfo = this.#optionInfoByKey.get(key);
+    if (optionInfo === undefined) {
+      throw new Error(`Option values not registered: ${key}`);
+    }
+    const result = this.#optionResultByKey.get(key);
+    if (result === undefined) {
+      this.#optionResultByKey.set(key, null);
+      return new Array<string>();
+    }
+    if (result === null) {
+      throw new Error(`Option values already consumed: ${key}`);
+    }
+    this.#optionResultByKey.set(key, null);
+    return result;
+  }
+
+  consumePositional(): string | undefined {
+    while (true) {
+      const arg = this.#consumeArg();
+      if (arg === null) {
+        return undefined;
+      }
+      const positional = this.#parseAsPositional(arg);
+      if (positional !== null) {
+        return positional;
+      }
+    }
+  }
+
+  #consumeArg(): string | null {
+    const arg = this.#parsedArgv[this.#parsedIndex];
+    if (arg === undefined) {
+      return null;
+    }
+    this.#parsedIndex++;
+    if (!this.#parsedDouble) {
+      if (arg === "--") {
+        this.#parsedDouble = true;
+        return this.#consumeArg();
+      }
+    }
+    return arg;
+  }
+
+  #consumeOptionValue(name: string) {
+    const arg = this.#consumeArg();
+    if (arg === null) {
+      throw new Error(`Option ${name} requires a value`);
+    }
+    if (this.#parsedDouble) {
+      throw new Error(`Option ${name} requires a value before --`);
+    }
+    // TODO - is that weird, could a valid value start with dash ?
+    if (arg.startsWith("-")) {
+      throw new Error(`Option ${name} requires a value, got: ${arg}`);
+    }
+    return arg;
+  }
+
+  #parseAsPositional(arg: string): string | null {
+    if (this.#parsedDouble) {
+      return arg;
+    }
+    if (arg.startsWith("--")) {
+      const valueIndexStart = arg.indexOf("=");
+      if (valueIndexStart === -1) {
+        this.#consumeOptionLong(arg.slice(2), null);
+      } else {
+        this.#consumeOptionLong(
+          arg.slice(2, valueIndexStart),
+          arg.slice(valueIndexStart + 1),
+        );
+      }
+      return null;
+    }
+    if (arg.startsWith("-")) {
+      let shortIndexStart = 1;
+      let shortIndexEnd = 2;
+      while (shortIndexEnd <= arg.length) {
+        const short = arg.slice(shortIndexStart, shortIndexEnd);
+        const rest = arg.slice(shortIndexEnd);
+        const result = this.#tryConsumeOptionShort(short, rest);
+        if (result === true) {
+          return null;
+        }
+        if (result === false) {
+          shortIndexStart = shortIndexEnd;
+        }
+        shortIndexEnd++;
+      }
+      throw new Error(
+        `Unknown short flags or options: ${arg.slice(shortIndexStart)}`,
+      );
+    }
+    return arg;
+  }
+
+  #consumeOptionLong(long: string, direct: string | null): void {
+    const flagKey = this.#flagKeyByLong.get(long);
+    if (flagKey !== undefined) {
+      if (direct !== null) {
+        if (direct === "true") {
+          return this.#acknowledgeFlag(flagKey, true);
+        }
+        if (direct === "false") {
+          return this.#acknowledgeFlag(flagKey, false);
+        }
+        throw new Error(
+          `Invalid parameter for long flag: ${flagKey}, value: ${direct}`,
+        );
+      }
+      return this.#acknowledgeFlag(flagKey, true);
+    }
+    const optionKey = this.#optionKeyByLong.get(long);
+    if (optionKey !== undefined) {
+      if (direct !== null) {
+        return this.#acknowledgeOption(optionKey, direct);
+      }
+      return this.#acknowledgeOption(optionKey, this.#consumeOptionValue(long));
+    }
+    throw new Error(`Unknown long flag or option: ${long}`);
+  }
+
+  #tryConsumeOptionShort(short: string, rest: string): boolean | null {
+    const flagKey = this.#flagKeyByShort.get(short);
+    if (flagKey !== undefined) {
+      if (rest.startsWith("=")) {
+        if (rest === "=true") {
+          this.#acknowledgeFlag(flagKey, true);
+          return true;
+        }
+        if (rest === "=false") {
+          this.#acknowledgeFlag(flagKey, false);
+          return true;
+        }
+        throw new Error(
+          `Invalid parameter for short flag: ${short}, value: ${rest}`,
+        );
+      }
+      this.#acknowledgeFlag(flagKey, true);
+      return rest === "";
+    }
+    const optionKey = this.#optionKeyByShort.get(short);
+    if (optionKey !== undefined) {
+      if (rest === "") {
+        this.#acknowledgeOption(optionKey, this.#consumeOptionValue(short));
+        return true;
+      }
+      if (rest.startsWith("=")) {
+        this.#acknowledgeOption(optionKey, rest.slice(1));
+      } else {
+        this.#acknowledgeOption(optionKey, rest);
+      }
+      return true;
+    }
+    return null;
+  }
+
+  #acknowledgeFlag(key: string, value: boolean) {
+    if (this.#flagResultByKey.has(key)) {
+      throw new Error(`Flag already set: ${key}`);
+    }
+    this.#flagResultByKey.set(key, value);
+  }
+
+  #acknowledgeOption(key: string, value: string) {
+    const values = this.#optionResultByKey.get(key) ?? new Array<string>();
+    values.push(value);
+    this.#optionResultByKey.set(key, values);
+  }
+
+  #ensureUniqueKey(key: string) {
+    if (this.#flagInfoByKey.has(key)) {
+      throw new Error(`Option already registered: ${key}`);
+    }
+    if (this.#optionInfoByKey.has(key)) {
+      throw new Error(`Option already registered: ${key}`);
+    }
+  }
+
+  #ensureUniqueName(nameShortOrLong: string) {
+    // TODO - overall better error handling
+    // TODO - short flag overlap might be annoying here
+    if (this.#flagKeyByShort.has(nameShortOrLong)) {
+      throw new Error(`Option already registered: ${nameShortOrLong}`);
+    }
+    if (this.#flagKeyByLong.has(nameShortOrLong)) {
+      throw new Error(`Option already registered: ${nameShortOrLong}`);
+    }
+    if (this.#optionKeyByShort.has(nameShortOrLong)) {
+      throw new Error(`Option already registered: ${nameShortOrLong}`);
+    }
+    if (this.#optionKeyByLong.has(nameShortOrLong)) {
+      throw new Error(`Option already registered: ${nameShortOrLong}`);
+    }
+  }
+}

package/src/lib/Run.ts

@@ -0,0 +1,58 @@
+import { Command } from "./Command";
+import { ReaderTokenizer } from "./Reader";
+import { usageFormatter } from "./Usage";
+
+export async function runWithArgv<Context, Result>(
+  argv: string[],
+  context: Context,
+  command: Command<Context, Result>,
+  cliInfo?: { name?: string; version?: string; helpOnError?: boolean },
+): Promise<Result> {
+  const cliName = cliInfo?.name ?? argv[1]!;
+  const readerTokenizer = new ReaderTokenizer(argv.slice(2));
+  readerTokenizer.registerFlag({
+    key: "help",
+    shorts: [],
+    longs: ["help"],
+  });
+  if (cliInfo?.version) {
+    readerTokenizer.registerFlag({
+      key: "version",
+      shorts: [],
+      longs: ["version"],
+    });
+  }
+  /*
+  // TODO - handle completions ?
+  readerTokenizer.registerFlag({
+    key: "completion",
+    shorts: [],
+    longs: ["completion"],
+  });
+  */
+  try {
+    const commandRunner = command.prepareRunner(readerTokenizer);
+    if (cliInfo?.version) {
+      if (readerTokenizer.consumeFlag("version")) {
+        console.log(cliName, cliInfo.version);
+        process.exit(0);
+      }
+    }
+    if (readerTokenizer.consumeFlag("help")) {
+      console.log(usageFormatter(cliName, commandRunner.computeUsage()));
+      process.exit(0);
+    }
+    try {
+      return await commandRunner.execute(context);
+    } catch (error) {
+      if (cliInfo?.helpOnError ?? true) {
+        console.log(usageFormatter(cliName, commandRunner.computeUsage()));
+      }
+      console.error(error);
+      process.exit(1);
+    }
+  } catch (error) {
+    console.error(error);
+    process.exit(1);
+  }
+}

package/src/lib/Type.ts

@@ -0,0 +1,59 @@
+export type Type<Value> = {
+  label: Uppercase<string>; // TODO - is there a better way to enforce uppercase labels?
+  decoder(value: string): Value;
+};
+
+export const typeBoolean: Type<boolean> = {
+  label: "BOOLEAN",
+  decoder(value: string) {
+    if (value === "true") {
+      return true;
+    }
+    if (value === "false") {
+      return false;
+    }
+    throw new Error(`Invalid boolean value: ${value}`);
+  },
+};
+
+export const typeDate: Type<Date> = {
+  label: "DATE",
+  decoder(value: string) {
+    const timestamp = Date.parse(value);
+    if (isNaN(timestamp)) {
+      throw new Error(`Invalid date value: ${value}`);
+    }
+    return new Date(timestamp);
+  },
+};
+
+export const typeString: Type<string> = {
+  label: "STRING",
+  decoder(value: string) {
+    return value;
+  },
+};
+
+export const typeNumber: Type<number> = {
+  label: "NUMBER",
+  decoder(value: string) {
+    return Number(value);
+  },
+};
+
+export const typeBigInt: Type<bigint> = {
+  label: "BIGINT",
+  decoder(value: string) {
+    return BigInt(value);
+  },
+};
+
+export function typeCommaArray(elementType: Type<any>): Type<Array<any>> {
+  return {
+    label:
+      `${elementType.label}[${elementType.label},...]` as Uppercase<string>,
+    decoder(value: string) {
+      return value.split(",").map(elementType.decoder);
+    },
+  };
+}