@jakubmazanec/args 1.0.0-de51f16

package/dist/types.d.ts

@@ -0,0 +1,17 @@
+export * from './types/Arguments.js';
+export * from './types/ArgumentsCommand.js';
+export * from './types/ArgumentsOptions.js';
+export * from './types/ArgumentsParameters.js';
+export * from './types/ArgumentsUnknownOptions.js';
+export * from './types/Argv.js';
+export * from './types/CommandConfig.js';
+export * from './types/CommandsConfig.js';
+export * from './types/LongOptionName.js';
+export * from './types/NormalizedCommandConfig.js';
+export * from './types/NormalizedCommandsConfig.js';
+export * from './types/OptionConfig.js';
+export * from './types/OptionsConfig.js';
+export * from './types/ParameterConfig.js';
+export * from './types/ParametersConfig.js';
+export * from './types/ParserConfig.js';
+export * from './types/ShortOptionName.js';

package/dist/types.js

@@ -0,0 +1,19 @@
+export * from './types/Arguments.js';
+export * from './types/ArgumentsCommand.js';
+export * from './types/ArgumentsOptions.js';
+export * from './types/ArgumentsParameters.js';
+export * from './types/ArgumentsUnknownOptions.js';
+export * from './types/Argv.js';
+export * from './types/CommandConfig.js';
+export * from './types/CommandsConfig.js';
+export * from './types/LongOptionName.js';
+export * from './types/NormalizedCommandConfig.js';
+export * from './types/NormalizedCommandsConfig.js';
+export * from './types/OptionConfig.js';
+export * from './types/OptionsConfig.js';
+export * from './types/ParameterConfig.js';
+export * from './types/ParametersConfig.js';
+export * from './types/ParserConfig.js';
+export * from './types/ShortOptionName.js';
+
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["export * from './types/Arguments.js';\nexport * from './types/ArgumentsCommand.js';\nexport * from './types/ArgumentsOptions.js';\nexport * from './types/ArgumentsParameters.js';\nexport * from './types/ArgumentsUnknownOptions.js';\nexport * from './types/Argv.js';\nexport * from './types/CommandConfig.js';\nexport * from './types/CommandsConfig.js';\nexport * from './types/LongOptionName.js';\nexport * from './types/NormalizedCommandConfig.js';\nexport * from './types/NormalizedCommandsConfig.js';\nexport * from './types/OptionConfig.js';\nexport * from './types/OptionsConfig.js';\nexport * from './types/ParameterConfig.js';\nexport * from './types/ParametersConfig.js';\nexport * from './types/ParserConfig.js';\nexport * from './types/ShortOptionName.js';\n"],"names":[],"mappings":"AAAA,cAAc,uBAAuB;AACrC,cAAc,8BAA8B;AAC5C,cAAc,8BAA8B;AAC5C,cAAc,iCAAiC;AAC/C,cAAc,qCAAqC;AACnD,cAAc,kBAAkB;AAChC,cAAc,2BAA2B;AACzC,cAAc,4BAA4B;AAC1C,cAAc,4BAA4B;AAC1C,cAAc,qCAAqC;AACnD,cAAc,sCAAsC;AACpD,cAAc,0BAA0B;AACxC,cAAc,2BAA2B;AACzC,cAAc,6BAA6B;AAC3C,cAAc,8BAA8B;AAC5C,cAAc,0BAA0B;AACxC,cAAc,6BAA6B"}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@jakubmazanec/args",
+  "version": "1.0.0-de51f16",
+  "description": "TypeScript-first library for parsing command line arguments.",
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:jakubmazanec/js-tools.git",
+    "directory": "packages/args"
+  },
+  "license": "LGPL-3.0-only",
+  "author": "Jakub Mazanec <jakub@mazanec.dev>",
+  "sideEffects": false,
+  "type": "module",
+  "exports": "./dist/main.js",
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "swc src -d dist && tsc",
+    "clean": "del-cli dist *.tsbuildinfo",
+    "document": "typedoc --options typedoc.config.cjs",
+    "format": "prettier . --write --ignore-unknown --ignore-path ../../.prettierignore",
+    "lint": "eslint .",
+    "test": "cross-env NODE_OPTIONS=--experimental-vm-modules jest --passWithNoTests",
+    "typecheck": "tsc --project tsconfig.typecheck.json"
+  },
+  "dependencies": {
+    "@jakubmazanec/error": "^2.0.0",
+    "@jakubmazanec/ts-utils": "^2.0.0",
+    "lodash.camelcase": "^4.3.0"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.5.0",
+    "@types/lodash.camelcase": "^4.3.7",
+    "@types/node": "^16.18.3"
+  },
+  "packageManager": "npm@8.19.4",
+  "engines": {
+    "node": ">=16.20.0"
+  }
+}

package/src/ParsingError.ts

@@ -0,0 +1,11 @@
+import {createCustomError} from '@jakubmazanec/error';
+
+/**
+ * A subclass of `Error` that indicates a parsing failure.
+ */
+export const ParsingError = createCustomError('ParsingError', {
+  INVALID_PARAMETER: 'Invalid value "{0}" found. Allowed values for parameter "{1}" are: {2}.',
+  UNKNOWN_PARAMETER: 'Unknown parameter "{0}" found. Unknown parameters are not allowed.',
+  INVALID_OPTION: 'Invalid value "{0}" found. Allowed values for option "{1}" are: {2}.',
+  UNKNOWN_OPTION: 'Unknown option "{0}" found. Unknown options are not allowed.',
+});

package/src/ValidationError.ts

@@ -0,0 +1,22 @@
+import {createCustomError} from '@jakubmazanec/error';
+
+/**
+ * A subclass of `Error` that indicates a validation issue.
+ */
+export const ValidationError = createCustomError('ValidationError', {
+  INVALID_COMMAND:
+    'Command "{0}" has invalid format. Only words consisting of letters, numbers or dashes separated by single space are allowed.',
+  MISSING_PARAMETER: 'Parameter "{0}" is required but its value is undefined.',
+  INVALID_PARAMETER_DEFAULT_AND_CHOICES:
+    'Parameter "{0}" has invalid default value "{1}". Default value must be one of the `choices` elements.',
+  INVALID_PARAMETER_ORDER:
+    'Optional parameter "{0}" found before required parameter "{1}". Required parameter must be first.',
+  MISSING_OPTION: 'Option "{0}" is required but its value is undefined.',
+  INVALID_OPTION_DEFAULT_AND_CHOICES:
+    'Option "{0}" has invalid default value "{1}". Default value must be one of the `choices` elements.',
+  INVALID_OPTION_NAME:
+    'Option "{0}" has invalid name. Only names consisting of letters, numbers or dashes are allowed.',
+  REPEATED_OPTION_NAME:
+    'Option "{0}" has invalid short name "{1}". Short option names must be unique.',
+  INVALID_OPTION_ARITY: 'Option "{0}" has invalid number of values. Found "{1}", require "{2}".',
+});

package/src/internals/Checker.ts

@@ -0,0 +1,145 @@
+import {type CommandsConfig, type OptionsConfig, type ParametersConfig} from '../types.js';
+import {ValidationError} from '../ValidationError.js';
+import {isCommand} from './isCommand.js';
+import {isLongOption} from './isLongOption.js';
+
+/**
+ * `Checker` is used for handling various check before, during, and after parsing of the arguments.
+ */
+export class Checker {
+  errors: Error[] = [];
+
+  checkCommandsConfig(commandsConfig: CommandsConfig) {
+    for (let commandConfig of commandsConfig) {
+      if (!isCommand(commandConfig)) {
+        this.addError(new ValidationError('INVALID_COMMAND', {messageParameters: [commandConfig]}));
+      }
+    }
+  }
+
+  checkParametersConfig(parametersConfig: ParametersConfig | []) {
+    for (let [i, parameterConfig] of parametersConfig.entries()) {
+      // types of choices must be correct
+      if (
+        parameterConfig.type !== 'boolean' &&
+        parameterConfig.choices && // default values and chocies do not contradict each other
+        typeof parameterConfig.defaultValue !== 'undefined' &&
+        !parameterConfig.choices.includes(parameterConfig.defaultValue as never)
+      ) {
+        this.addError(
+          new ValidationError('INVALID_PARAMETER_DEFAULT_AND_CHOICES', {
+            messageParameters: [parameterConfig.label ?? i, parameterConfig.defaultValue],
+          }),
+        );
+      }
+
+      // if parameter is required, all parameters before must be required too
+      if (
+        i >= 1 &&
+        parameterConfig.required === true &&
+        parametersConfig[i - 1]?.required !== true
+      ) {
+        this.addError(
+          new ValidationError('INVALID_PARAMETER_ORDER', {
+            messageParameters: [
+              parametersConfig[i - 1]?.label ?? i - 1,
+              parameterConfig.label ?? i,
+            ],
+          }),
+        );
+      }
+    }
+  }
+
+  checkOptionsConfig(optionsConfig: OptionsConfig) {
+    let usedShortOptionNames: Set<string> = new Set([]);
+
+    for (let [optionName, optionConfig] of Object.entries(optionsConfig)) {
+      // option names must be in correct format
+      if (!isLongOption(`--${optionName}`)) {
+        this.addError(
+          new ValidationError('INVALID_OPTION_NAME', {
+            messageParameters: [optionName],
+          }),
+        );
+      }
+
+      // option short names must be unique
+      if (optionConfig.shortName && usedShortOptionNames.has(optionConfig.shortName)) {
+        this.addError(
+          new ValidationError('REPEATED_OPTION_NAME', {
+            messageParameters: [optionName, optionConfig.shortName],
+          }),
+        );
+      } else if (optionConfig.shortName) {
+        usedShortOptionNames.add(optionConfig.shortName);
+      }
+
+      // default values and chocies do not contradict each other
+      if (
+        (optionConfig.type === 'string' ||
+          (optionConfig.type === 'number' && !optionConfig.count)) &&
+        optionConfig.choices &&
+        typeof optionConfig.defaultValue !== 'undefined' &&
+        !optionConfig.choices.includes(optionConfig.defaultValue as never)
+      ) {
+        this.addError(
+          new ValidationError('INVALID_OPTION_DEFAULT_AND_CHOICES', {
+            messageParameters: [optionName, optionConfig.defaultValue],
+          }),
+        );
+      }
+    }
+  }
+
+  checkParsedParameters(parametersConfig: ParametersConfig | [], parsedParameters: unknown[]) {
+    for (let [i, parameterConfig] of parametersConfig.entries()) {
+      let parsedParameter = parsedParameters[i];
+
+      // required parameters must have value
+      if (parameterConfig.required === true && typeof parsedParameter === 'undefined') {
+        this.addError(
+          new ValidationError('MISSING_PARAMETER', {
+            messageParameters: [parameterConfig.label ?? i],
+          }),
+        );
+      }
+    }
+  }
+
+  checkParsedOptions(optionsConfig: OptionsConfig, parsedOptions: Record<string, unknown>) {
+    for (let [optionName, optionConfig] of Object.entries(optionsConfig)) {
+      let parsedOption = parsedOptions[optionName];
+
+      // check required
+      if (optionConfig.required && typeof parsedOption === 'undefined') {
+        this.addError(
+          new ValidationError('MISSING_OPTION', {
+            messageParameters: [optionName],
+          }),
+        );
+      }
+
+      // check arity
+      if (
+        typeof parsedOption !== 'undefined' &&
+        ((optionConfig.type === 'string' && optionConfig.multiple) ||
+          (optionConfig.type === 'number' && optionConfig.multiple)) &&
+        typeof optionConfig.arity === 'number' &&
+        Array.isArray(parsedOption) &&
+        (parsedOption as unknown[]).length > 0 &&
+        (parsedOption as unknown[]).length !== optionConfig.arity
+      ) {
+        this.addError(
+          new ValidationError('INVALID_OPTION_ARITY', {
+            messageParameters: [optionName, (parsedOption as unknown[]).length, optionConfig.arity],
+          }),
+        );
+      }
+    }
+  }
+
+  addError(error: Error) {
+    this.errors.push(error);
+  }
+}

package/src/internals/CommandScope.ts

@@ -0,0 +1,61 @@
+import {type NormalizedCommandConfig, type NormalizedCommandsConfig} from '../types.js';
+
+/**
+ * `CommandScope` handles storing information about parsing of a command.
+ */
+export class CommandScope {
+  private readonly args: string[];
+  readonly config: NormalizedCommandConfig;
+
+  constructor(arg: string, normalizedCommandsConfig: NormalizedCommandsConfig) {
+    let normalizedArgument = arg.toLowerCase();
+    let commandConfig = normalizedCommandsConfig.find(
+      (commandConfig) => commandConfig.args[0] === normalizedArgument,
+    );
+
+    this.config = commandConfig ?? ([] as unknown as NormalizedCommandConfig);
+    this.args = [normalizedArgument];
+  }
+
+  captureArg(arg: string) {
+    this.args.push(arg.toLowerCase());
+
+    return this;
+  }
+
+  isComplete() {
+    let isComplete = true;
+
+    for (let [i, arg] of this.config.args.entries()) {
+      if (this.args[i] !== arg) {
+        isComplete = false;
+
+        break;
+      }
+    }
+
+    return isComplete;
+  }
+
+  isDone() {
+    let isDone = false;
+
+    for (let [i, arg] of this.config.args.entries()) {
+      if (this.args[i] !== arg) {
+        isDone = true;
+
+        break;
+      }
+    }
+
+    return isDone;
+  }
+
+  getValue() {
+    return this.config.command;
+  }
+
+  getArgs() {
+    return [...this.args];
+  }
+}

package/src/internals/OptionScope.ts

@@ -0,0 +1,101 @@
+import camelCase from 'lodash.camelcase';
+
+import {ParsingError} from '../ParsingError.js';
+import {type OptionConfig, type OptionsConfig} from '../types.js';
+import {castValue} from './castValue.js';
+
+/**
+ * `CommandScope` handles storing information about parsing of an option..
+ */
+export class OptionScope {
+  name: string;
+
+  values: unknown[] = [];
+  previousParsedValue?: unknown[] | unknown;
+  readonly config: OptionConfig;
+
+  constructor(optionName: string, optionsConfig: OptionsConfig, allowUnknownOptions = false) {
+    this.name = optionName;
+
+    // Convert option to camel case
+    if (this.name.includes('-')) {
+      this.name = camelCase(this.name);
+    }
+
+    let optionConfig = optionsConfig[this.name];
+
+    if (!optionConfig) {
+      if (!allowUnknownOptions) {
+        throw new ParsingError('UNKNOWN_OPTION', {messageParameters: [this.name]});
+      }
+
+      optionConfig = {
+        type: 'string',
+      };
+    }
+
+    this.config = optionConfig;
+  }
+
+  captureArg(arg: string) {
+    let value = castValue(arg, this.config.type);
+
+    if (
+      ((this.config.type === 'number' && !this.config.count) || this.config.type === 'string') &&
+      typeof this.config.choices !== 'undefined' &&
+      !this.config.choices.includes(value as never)
+    ) {
+      throw new ParsingError('INVALID_OPTION', {
+        messageParameters: [
+          value,
+          this.name,
+          this.config.choices.map((choice) => `"${choice}"`).join(', '),
+        ],
+      });
+    }
+
+    if (this.config.multiple) {
+      this.values.push(value);
+    } else {
+      this.values = [value];
+    }
+  }
+
+  isComplete() {
+    if (!this.config.multiple && this.values.length === 1) {
+      return true;
+    }
+
+    if (
+      this.config.multiple &&
+      typeof this.config.arity === 'number' &&
+      this.values.length + ((this.previousParsedValue as unknown[] | undefined) ?? []).length ===
+        this.config.arity
+    ) {
+      return true;
+    }
+
+    return false;
+  }
+
+  getValue() {
+    let {config, previousParsedValue} = this;
+    let {values} = this;
+
+    if (config.type === 'boolean' && !config.multiple && !values.length) {
+      values = [true];
+    } else if (config.type === 'number' && config.count && !values.length) {
+      values = [1];
+    }
+
+    if (config.multiple && previousParsedValue) {
+      values = [...(previousParsedValue as unknown[]), ...values];
+    }
+
+    if (config.type === 'number' && config.count && previousParsedValue) {
+      values = [(values[0] as number) + (previousParsedValue as number)];
+    }
+
+    return config.multiple ? values : values[0];
+  }
+}

package/src/internals/castValue.ts

@@ -0,0 +1,36 @@
+import {isFalseString} from './isFalseString.js';
+
+/**
+ * A function that casts string value to a specified type.
+ *
+ * @param value The value to be converted.
+ * @param type The type to convert the value into.
+ * */
+export function castValue<T extends 'boolean' | 'number' | 'string'>(
+  value: string,
+  type?: T,
+): T extends 'boolean' ? boolean : T extends 'number' ? number : string {
+  switch (type) {
+    case 'boolean': {
+      let booleanString = String(value).toLowerCase();
+
+      return !(isFalseString(booleanString) || booleanString === '') as T extends 'boolean'
+        ? boolean
+        : T extends 'number'
+        ? number
+        : string;
+    }
+
+    case 'number': {
+      return Number.parseFloat(value) as T extends 'boolean'
+        ? boolean
+        : T extends 'number'
+        ? number
+        : string;
+    }
+
+    default: {
+      return String(value) as T extends 'boolean' ? boolean : T extends 'number' ? number : string;
+    }
+  }
+}

package/src/internals/commandToArguments.ts

@@ -0,0 +1,22 @@
+/**
+ * A function that converts a string representing a command into the arguments, i.e. array of strings.
+ *
+ * @param value The value to convert.
+ * @return Arguments.
+ */
+export function commandToArguments(value: string): string[] {
+  let rawArgs = value.split(' ');
+  let args: string[] = [];
+
+  for (let [, rawValue] of rawArgs.entries()) {
+    if (typeof rawValue !== 'undefined') {
+      if (rawValue === '' && args.at(-1)) {
+        args[args.length - 1] += ' ';
+      } else {
+        args.push(rawValue);
+      }
+    }
+  }
+
+  return args;
+}

package/src/internals/createOptionShortNameMap.ts

@@ -0,0 +1,13 @@
+import {type OptionsConfig} from '../types.js';
+
+export function createOptionShortNameMap(optionsConfig: OptionsConfig) {
+  let map: Record<string, string> = {};
+
+  for (let [optionName, optionConfig] of Object.entries(optionsConfig)) {
+    if (typeof optionConfig.shortName === 'string') {
+      map[optionConfig.shortName] = optionName;
+    }
+  }
+
+  return map;
+}

package/src/internals/expandArguments.ts

@@ -0,0 +1,22 @@
+import {type Argv} from '../types.js';
+import {isShortOptionsGroup} from './isShortOptionsGroup.js';
+
+/**
+ * A function that converts any argument that is a short options group into separate short options.
+ *
+ * @param argv Arguments.
+ * @return Arguments that contain no short options group
+ */
+export function expandArguments(argv: Argv): Argv {
+  let expandedArguments = [];
+
+  for (let arg of argv) {
+    if (isShortOptionsGroup(arg)) {
+      expandedArguments.push(...[...arg].slice(1).map((value) => `-${value}`));
+    } else {
+      expandedArguments.push(arg);
+    }
+  }
+
+  return expandedArguments;
+}

package/src/internals/isCommand.ts

@@ -0,0 +1,11 @@
+export const COMMAND_REGEXP = /^(?:[a-z][-a-z0-9]*[a-z])+(?:\s(?:[a-z][-a-z0-9]*[a-z])+)*$/iu;
+
+/**
+ * A function that checks if a value is an argument that looks like command, i.e. space-separated words consisting only of letters, numbers (but not at the start of the word) or dashes.
+ *
+ * @param value The value to check.
+ * @return `true` if `value` is a command.
+ */
+export function isCommand(value: string): boolean {
+  return COMMAND_REGEXP.test(value);
+}

package/src/internals/isFalseString.ts

@@ -0,0 +1,10 @@
+const FALSE_STRING_REGEXP = /^\s*(?:false|0|no|off)\s*$/iu;
+
+/**
+ * A function that checks if a string value is a false string. A false string is `'false'`, `'0'`, `'no'`, or `'off'` (case insensitive).
+ *
+ * @param value The value to be tested.
+ * @return `true` if string is a false string. */
+export function isFalseString(value: string) {
+  return FALSE_STRING_REGEXP.test(value);
+}

package/src/internals/isLongOption.ts

@@ -0,0 +1,11 @@
+const LONG_OPTION_REGEXP = /^--[a-z][-a-z0-9]+$/iu;
+
+/**
+ * A function that checks if a value is an argument that looks like a long option, i.e. two dashes and a single word consisting only of letters, numbers (but not at the start of the word) or dashes; e.g. `'--some-option'`.
+ *
+ * @param value The value to check.
+ * @return `true` if `value` is a long option.
+ */
+export function isLongOption(arg: string): boolean {
+  return LONG_OPTION_REGEXP.test(arg);
+}

package/src/internals/isOptionLike.ts

@@ -0,0 +1,11 @@
+const OPTION_LIKE = /^-{1,2}[a-z][-a-z0-9]*=?/iu;
+
+/**
+ * A function that checks if a value is an argument that looks like a long option, short option, or a short options group i.e. one or two dashes and a single word consisting only of letters, numbers (but not at the start of the word) or dashes, optionally followed by `=`.
+ *
+ * @param value The value to check.
+ * @return `true` if `value` is an option.
+ */
+export function isOptionLike(value: string): boolean {
+  return OPTION_LIKE.test(value);
+}

package/src/internals/isShortOption.ts

@@ -0,0 +1,11 @@
+const SHORT_OPTION_REGEXP = /^-[a-z]{1}$/iu;
+
+/**
+ * A function that checks if a value is an argument that looks like a short option, i.e. a dash and a single letter; e.g. `'-x'`.
+ *
+ * @param value The value to check.
+ * @return `true` if `value` is a short option.
+ */
+export function isShortOption(arg: string): boolean {
+  return SHORT_OPTION_REGEXP.test(arg);
+}

package/src/internals/isShortOptionsGroup.ts

@@ -0,0 +1,11 @@
+export const SHORT_OPTIONS_GROUP_REGEXP = /^-[a-z]{2,}$/iu;
+
+/**
+ * A function that checks if a value is an argument that looks like a short options group, i.e. a dash and a single letter; e.g. `'-x'`.
+ *
+ * @param value The value to check.
+ * @return `true` if `value` is a short option.
+ */
+export function isShortOptionsGroup(arg: string): boolean {
+  return SHORT_OPTIONS_GROUP_REGEXP.test(arg);
+}

package/src/internals/isTrueString.ts

@@ -0,0 +1,10 @@
+const TRUE_STRING_REGEXP = /^\s*(?:true|1|yes|on)\s*$/iu;
+
+/**
+ * A function that checks if a string value is a true string. A true string is `'true'`, `'1'`, `'yes'`, or `'on'` (case insensitive).
+ *
+ * @param value The value to be tested.
+ * @return `true` if string is a true string. */
+export function isTrueString(value: string) {
+  return TRUE_STRING_REGEXP.test(value);
+}

package/src/internals.ts

@@ -0,0 +1,14 @@
+export * from './internals/castValue.js';
+export * from './internals/CommandScope.js';
+export * from './internals/commandToArguments.js';
+export * from './internals/createOptionShortNameMap.js';
+export * from './internals/expandArguments.js';
+export * from './internals/Checker.js';
+export * from './internals/isCommand.js';
+export * from './internals/isFalseString.js';
+export * from './internals/isLongOption.js';
+export * from './internals/isOptionLike.js';
+export * from './internals/isShortOption.js';
+export * from './internals/isShortOptionsGroup.js';
+export * from './internals/isTrueString.js';
+export * from './internals/OptionScope.js';

package/src/main.ts

@@ -0,0 +1,4 @@
+export * from './parseArguments.js';
+export * from './ParsingError.js';
+export * from './types.js';
+export * from './ValidationError.js';