@ztimson/utils 0.23.1 → 0.23.3

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+export * from './arg-parser';
 export * from './array';
 export * from './aset';
 export * from './cache';

package/dist/index.mjs

@@ -1,6 +1,119 @@
 var __defProp = Object.defineProperty;
 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)) {
@@ -106,6 +219,10 @@ function JSONAttemptParse(json) {
     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;
@@ -1534,6 +1651,7 @@ function typeKeys() {
 }
 export {
   ASet,
+  ArgParser,
   BadGatewayError,
   BadRequestError,
   CHAR_LIST,
@@ -1548,6 +1666,7 @@ export {
   InternalServerError,
   JSONAttemptParse,
   JSONSanitize,
+  JSONSerialize,
   LETTER_LIST,
   LOG_LEVEL,
   Logger,