@ztimson/utils 0.23.1 → 0.23.3

package/dist/arg-parser.d.ts

@@ -0,0 +1,52 @@
+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[];
+    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,119 @@
 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);
 
+  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}
+
+`;
+    }
+  }
   function clean(obj, undefinedOnly = false) {
     if (obj == null) throw new Error("Cannot clean a NULL value");
     if (Array.isArray(obj)) {
@@ -110,6 +223,10 @@ var __publicField = (obj, key, value2) => __defNormalProp(obj, typeof key !== "s
       return json;
     }
   }
+  function JSONSerialize(obj) {
+    if (typeof obj == "object" && obj != null) return JSONSanitize(obj);
+    return obj;
+  }
   function JSONSanitize(obj, space) {
     return JSON.stringify(obj, (key, value2) => {
       return value2;
@@ -1537,6 +1654,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;
@@ -1551,6 +1669,7 @@ var __publicField = (obj, key, value2) => __defNormalProp(obj, typeof key !== "s
   exports.InternalServerError = InternalServerError;
   exports.JSONAttemptParse = JSONAttemptParse;
   exports.JSONSanitize = JSONSanitize;
+  exports.JSONSerialize = JSONSerialize;
   exports.LETTER_LIST = LETTER_LIST;
   exports.LOG_LEVEL = LOG_LEVEL;
   exports.Logger = Logger;