@ztimson/utils 0.23.2 → 0.23.4

package/dist/arg-parser.d.ts

@@ -0,0 +1,53 @@
+export type Arg<T = any> = {
+    /** Argument/property name */
+    name: string;
+    /** Argument description for help page */
+    desc: string;
+    /** Available shorthands */
+    flags?: string[];
+    /** Argument is not required */
+    optional?: boolean;
+    /** Default value if argument is not used */
+    default?: T;
+    /** Collects any unmatched arguments */
+    extras?: boolean;
+};
+export declare class ArgParser {
+    readonly name: string;
+    readonly desc: string;
+    readonly argList: (ArgParser | Arg)[];
+    readonly examples: string[];
+    static readonly helpArg: Arg;
+    commands: ArgParser[];
+    args: Arg[];
+    flags: Arg[];
+    defaults: {
+        [key: string]: any;
+    };
+    /**
+     * Create a unix-like argument parser to extract flags from the argument list. Can also create help messages.
+     *
+     * @param {string} name Script name
+     * @param {string} desc Help description
+     * @param {(ArgParser | Arg[]} argList Array of CLI arguments
+     * @param {string[]} examples Additional examples to display
+     */
+    constructor(name: string, desc: string, argList?: (ArgParser | Arg)[], examples?: string[]);
+    /**
+     * Parse an array into an arguments dictionary using the configuration.
+     *
+     * @param {string[]} args Array of arguments to be parsed
+     * @returns {object} Dictionary of arguments with defaults applied
+     */
+    parse(args: string[]): any;
+    /**
+     * Create help message from the provided description & argument list.
+     *
+     * @returns {string} Help message
+     * @param opts Help options: command - display a commands help, message - override help description
+     */
+    help(opts?: {
+        command?: string;
+        message?: string;
+    }): string;
+}

package/dist/index.cjs

@@ -5,6 +5,121 @@
 var __defNormalProp = (obj, key, value2) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value: value2 }) : obj[key] = value2;
 var __publicField = (obj, key, value2) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value2);
 
+  const _ArgParser = class _ArgParser {
+    /**
+     * Create a unix-like argument parser to extract flags from the argument list. Can also create help messages.
+     *
+     * @param {string} name Script name
+     * @param {string} desc Help description
+     * @param {(ArgParser | Arg[]} argList Array of CLI arguments
+     * @param {string[]} examples Additional examples to display
+     */
+    constructor(name, desc, argList = [], examples = []) {
+      __publicField(this, "commands", []);
+      __publicField(this, "args", []);
+      __publicField(this, "flags", []);
+      __publicField(this, "defaults");
+      this.name = name;
+      this.desc = desc;
+      this.argList = argList;
+      this.examples = examples;
+      this.commands = argList.filter((arg) => arg instanceof _ArgParser);
+      this.args = argList.filter((arg) => {
+        var _a;
+        return !(arg instanceof _ArgParser) && !((_a = arg.flags) == null ? void 0 : _a.length);
+      });
+      this.flags = [...argList.filter((arg) => !(arg instanceof _ArgParser) && arg.flags && arg.flags.length), ...this.flags];
+      this.defaults = argList.reduce((acc, arg) => ({ ...acc, [arg.name]: arg["extras"] ? [] : arg.default ?? null }), {});
+      this.examples = [
+        ...examples,
+        `[OPTIONS] ${this.args.map((arg) => (arg.optional ? `[${arg.name.toUpperCase()}]` : arg.name.toUpperCase()) + (arg.extras ? "..." : "")).join(" ")}`,
+        this.commands.length ? `[OPTIONS] COMMAND` : null,
+        `--help ${this.commands.length ? "[COMMAND]" : ""}`
+      ].filter((e) => !!e);
+    }
+    /**
+     * Parse an array into an arguments dictionary using the configuration.
+     *
+     * @param {string[]} args Array of arguments to be parsed
+     * @returns {object} Dictionary of arguments with defaults applied
+     */
+    parse(args) {
+      var _a;
+      let extras = [], parsed = { ...this.defaults, "_error": [] }, queue = [...args];
+      while (queue.length) {
+        let arg = queue.splice(0, 1)[0];
+        if (arg[0] == "-") {
+          if (arg[1] != "-" && arg.length > 2) {
+            queue = [...arg.substring(2).split("").map((a2) => `-${a2}`), ...queue];
+            arg = `-${arg[1]}`;
+          }
+          const combined = arg.split("=");
+          const argDef = this.flags.find((flag) => {
+            var _a2;
+            return (_a2 = flag.flags) == null ? void 0 : _a2.includes(combined[0] || arg);
+          });
+          if (argDef == null) {
+            extras.push(arg);
+            continue;
+          }
+          const value2 = argDef.default === false ? true : argDef.default === true ? false : queue.splice(queue.findIndex((q) => q[0] != "-"), 1)[0] || argDef.default;
+          if (value2 == null) parsed["_error"].push(`Option missing value: ${argDef.name || combined[0]}`);
+          parsed[argDef.name] = value2;
+        } else {
+          const c = this.commands.find((command) => command.name == arg);
+          if (!!c) {
+            const parsedCommand = c.parse(queue.splice(0, queue.length));
+            Object.keys(parsedCommand).forEach((key) => {
+              if (parsed[key] != parsedCommand[key] && parsedCommand[key] == c.defaults[key])
+                delete parsedCommand[key];
+            });
+            parsed = {
+              ...parsed,
+              ...parsedCommand,
+              _command: c.name
+            };
+          } else extras.push(arg);
+        }
+      }
+      this.args.filter((arg) => !arg.extras).forEach((arg) => {
+        if (!arg.optional && !extras.length) parsed["_error"].push(`Argument missing: ${arg.name.toUpperCase()}`);
+        if (extras.length) parsed[arg.name] = extras.splice(0, 1)[0];
+      });
+      const extraKey = ((_a = this.args.find((arg) => arg.extras)) == null ? void 0 : _a.name) || "_extra";
+      parsed[extraKey] = extras;
+      return parsed;
+    }
+    /**
+     * Create help message from the provided description & argument list.
+     *
+     * @returns {string} Help message
+     * @param opts Help options: command - display a commands help, message - override help description
+     */
+    help(opts = {}) {
+      const spacer = (text) => Array(24 - text.length || 1).fill(" ").join("");
+      if (opts.command) {
+        const argParser = this.commands.find((parser) => parser.name == opts.command);
+        if (!argParser) throw new Error(`${opts.command.toUpperCase()} is not a command`);
+        return argParser.help({ ...opts, command: void 0 });
+      }
+      let msg = `
+
+${opts.message || this.desc}`;
+      msg += "\n\nUsage:	" + this.examples.map((ex) => `run ${this.name} ${ex}`).join("\n		");
+      if (this.args.length) msg += "\n\n		" + this.args.map((arg) => `${arg.name.toUpperCase()}${spacer(arg.name)}${arg.desc}`).join("\n		");
+      msg += "\n\nOptions:\n		" + this.flags.map((flag) => {
+        var _a;
+        const flags = ((_a = flag.flags) == null ? void 0 : _a.join(", ")) || "";
+        return `${flags}${spacer(flags)}${flag.desc}`;
+      }).join("\n		");
+      if (this.commands.length) msg += "\n\nCommands:\n		" + this.commands.map((command) => `${command.name}${spacer(command.name)}${command.desc}`).join("\n		");
+      return `${msg}
+
+`;
+    }
+  };
+  __publicField(_ArgParser, "helpArg", { name: "help", desc: "Display command's help message", flags: ["-h", "--help"], default: false });
+  let ArgParser = _ArgParser;
   function clean(obj, undefinedOnly = false) {
     if (obj == null) throw new Error("Cannot clean a NULL value");
     if (Array.isArray(obj)) {
@@ -1541,6 +1656,7 @@ var __publicField = (obj, key, value2) => __defNormalProp(obj, typeof key !== "s
     return Object.keys({});
   }
   exports.ASet = ASet;
+  exports.ArgParser = ArgParser;
   exports.BadGatewayError = BadGatewayError;
   exports.BadRequestError = BadRequestError;
   exports.CHAR_LIST = CHAR_LIST;