argot-cli 0.0.0-stage → 0.4.0-beta

package/src/errors.ts

@@ -0,0 +1,272 @@
+/**
+ * Runtime error.
+ * Represents errors that occur while parsing input arguments.
+ * These errors are triggered by invalid or unexpected user input,
+ * such as unknown options, missing values, or values of the wrong type.
+ * Runtime errors are produced during the execution of the `.parse()`
+ * method and depend on the provided input rather than the parser
+ * configuration.
+ */
+export class RuntimeError extends Error {}
+
+/**
+ * Configuration error.
+ * Represents errors caused by an invalid parser configuration.
+ * These errors occur when defining or initializing the parser,
+ * such as using unsupported option types or referencing invalid
+ * alias targets.
+ * Configuration errors are independent of user input and are
+ * typically raised before any parsing takes place.
+ */
+export class ConfigError extends Error {
+  private _errors: Error[] = [];
+
+  public push(error: Error): void {
+    this._errors.push(error);
+  }
+
+  get errors(): Error[] {
+    return this._errors;
+  }
+}
+
+/**
+ * Invalid integer argument error.
+ * Raised when an option of type "int" is provided with an associated
+ * value that cannot be parsed as an integer.
+ * This error only applies when a value is present. Missing values are
+ * reported using NullIntError.
+ */
+export class InvalidIntError extends RuntimeError {
+  public value: string;
+
+  constructor(value: string) {
+    super(`'${value}' is not a valid integer`);
+    this.value = value;
+    Object.freeze(this);
+  }
+}
+
+/**
+ * Invalid float argument error.
+ * Raised when an option of type "float" is provided with an associated
+ * value that cannot be parsed as a number.
+ * This error only applies when a value is present. Missing values are
+ * reported using NullFloatError.
+ */
+export class InvalidFloatError extends RuntimeError {
+  public value: string;
+
+  constructor(value: string) {
+    super(`'${value}' is not a valid integer`);
+    this.value = value;
+    Object.freeze(this);
+  }
+}
+
+/**
+ * Unsafe integer error.
+ * Raised when a parsed integer cannot be safely represented
+ * by the underlying runtime.
+ * This error only applies to values that are successfully parsed
+ * as integers.
+ */
+export class UnsafeIntegerError extends RuntimeError {
+  public value: number;
+
+  constructor(value: number) {
+    super(`${value} is not a safe integer`);
+    this.value = value;
+    Object.freeze(this);
+  }
+}
+
+/**
+ * Missing argument error.
+ * Raised when an option that requires an associated value is provided
+ * without one.
+ * If the option is an alias, the error message includes both the
+ * alias name and its target.
+ */
+export class NullArgError extends RuntimeError {
+  public option: string;
+  public target?: string;
+
+  constructor(name: string, target?: string) {
+    const msg = target
+      ? `option '${name}' (alias for '${target}') must take an argument`
+      : `option '${name}' must take an argument`;
+    super(msg);
+    this.option = name;
+    if (target) {
+      this.target = target;
+    }
+    Object.freeze(this);
+  }
+}
+
+/**
+ * Missing integer argument error.
+ * Raised when an option of type "int" is provided without an
+ * associated value.
+ * This error does not cover invalid integer values. Invalid values
+ * are reported using InvalidIntError.
+ * If the option is an alias, the error message includes both the
+ * alias name and its target.
+ */
+export class NullIntError extends RuntimeError {
+  public option: string;
+  public target?: string;
+
+  constructor(name: string, target?: string) {
+    const msg = target
+      ? `option '${name}' (alias for '${target}') requires an integer number argument`
+      : `option '${name}' requires an integer number argument`;
+    super(msg);
+    this.option = name;
+    if (target) {
+      this.target = target;
+    }
+    Object.freeze(this);
+  }
+}
+
+/**
+ * Missing float argument error.
+ * Raised when an option of type "float" is provided without an
+ * associated value.
+ * This error does not cover invalid float values. Invalid values
+ * are reported using InvalidFloatError.
+ * If the option is an alias, the error message includes both the
+ * alias name and its target.
+ */
+export class NullFloatError extends RuntimeError {
+  public option: string;
+  public target?: string;
+
+  constructor(name: string, target?: string) {
+    const msg = target
+      ? `option '${name}' (alias for '${target}') requires a numeric argument`
+      : `option '${name}' requires a numeric argument`;
+    super(msg);
+    this.option = name;
+    if (target) {
+      this.target = target;
+    }
+    Object.freeze(this);
+  }
+}
+
+/**
+ * Unknown option error.
+ * Raised when an input contains an option that is not defined in the
+ * parser configuration.
+ * This applies to both long and short options. The error is triggered
+ * as soon as the parser encounters an unrecognized option name.
+ */
+export class UnknownOptionError extends RuntimeError {
+  public option: string;
+
+  constructor(name: string) {
+    super(`option '${name}' is not supported`);
+    this.option = name;
+    Object.freeze(this);
+  }
+}
+
+/**
+ * Invalid option type error.
+ * Raised when an option is declared with a type that is not supported
+ * by the parser.
+ * This is a configuration error and typically occurs during parser
+ * initialization rather than at parse time.
+ */
+export class InvalidOptionTypeError extends ConfigError {
+  public type: string;
+
+  constructor(tag: string) {
+    super(`option type '${tag}' is not supported`);
+    this.type = tag;
+    Object.freeze(this);
+  }
+}
+
+/**
+ * Alias target not found error.
+ * Raised when an alias references a target option that does not exist
+ * in the parser configuration.
+ * This is a configuration error and indicates that the alias points
+ * to an undefined option.
+ */
+export class AliasTargetNotFoundError extends ConfigError {
+  public option: string;
+  public target: string;
+
+  constructor(name: string, target: string) {
+    super(`target value '${target}' for option '${name}' was not found`);
+    this.option = name;
+    this.target = target;
+    Object.freeze(this);
+  }
+}
+
+/**
+ * Invalid alias target error.
+ * Raised when an alias references a target that is not a valid option
+ * for aliasing.
+ * This may occur if the target is itself an alias (when alias chaining
+ * is not supported) or if the target cannot accept the alias due to
+ * type or configuration constraints.
+ */
+export class InvalidAliasTargetError extends ConfigError {
+  public option: string;
+  public target: string;
+
+  constructor(name: string, target: string) {
+    super(`cannot create an alias to another alias (${name} => ${target})`);
+    this.option = name;
+    this.target = target;
+    Object.freeze(this);
+  }
+}
+
+/**
+ * Missing option property error.
+ * Raised when an option entry in the parser configuration is missing
+ * one or more required properties.
+ * This is a configuration error and indicates that the option
+ * definition is incomplete or malformed.
+ * Implementations may include the option name and the missing
+ * property name to aid debugging.
+ */
+export class MissingOptionPropertyError extends ConfigError {
+  public option: string;
+  public property: string;
+
+  constructor(option: string, property: string) {
+    super(`option '${option}' is missing required property '${property}'`);
+    this.option = option;
+    this.property = property;
+    Object.freeze(this);
+  }
+}
+
+/**
+ * Missing option type error.
+ * Raised when a configuration entry does not define a "type" property.
+ * The "type" property is required for all option entries and determines
+ * how the option is parsed and validated. Without it, the entry cannot
+ * be interpreted by the parser.
+ * This is a configuration error and is typically raised during
+ * configuration validation.
+ */
+export class MissingOptionTypeError extends ConfigError {
+  public option: string;
+
+  constructor(name: string) {
+    const msg = `option '${name}' is missing required property 'type'`;
+    super(msg);
+    this.option = name;
+    Object.freeze(this);
+  }
+}

package/src/mod.ts

@@ -0,0 +1,49 @@
+/**
+ * Argot CLI argument parser.
+ *
+ * This module provides a schema-based command-line argument parser.
+ * The parser processes an array of strings and produces a structured
+ * result containing options, parameters, and operands.
+ *
+ * Parsing behavior is fully determined by a configuration object.
+ *
+ * Example:
+ *
+ * ```ts
+ * import {
+ *   ArgParser,
+ *   ParserConfig,
+ *   type ConfigEntries,
+ * } from '@argot-cli/argot';
+ *
+ * const entries: ConfigEntries = {
+ *   verbose: { type: 'flag' },
+ *   count: { type: 'int' },
+ *   name: { type: 'text', default: 'world' },
+ * };
+ *
+ * const config = new ParserConfig(entries);
+ *
+ * const parser = new ArgParser(config);
+ *
+ * const result = parser.parse([
+ *   '--verbose',
+ *   '--count=3',
+ *   'mode=fast',
+ *   'file.txt',
+ * ]);
+ *
+ * console.log(result.options.get('verbose')); // true
+ * console.log(result.options.get('count'));   // 3
+ * console.log(result.options.get('name'));    // "world"
+ *
+ * console.log(result.parameters.get('mode')); // "fast"
+ *
+ * console.log(result.operands); // ["file.txt"]
+ * ```
+ * @module
+ */
+export { ArgParser } from './arg_parser.ts';
+export { ParserConfig } from './parser_config.ts';
+export { readJSONConfig } from './read_config.ts';
+export type { ConfigEntry, ConfigEntries } from './types.ts';

package/src/parser_config.ts

@@ -0,0 +1,104 @@
+import type {
+  ConfigEntry,
+  ConfigEntries,
+  ParserConfigInput,
+  StrictParserOptions,
+} from './types.ts';
+import { validateEntries, validateEntriesAggregate } from './utils.ts';
+
+function isObject(obj: unknown): obj is Record<string, unknown> {
+  if (Array.isArray(obj) || obj == null || typeof obj !== 'object')
+    return false;
+  return true;
+}
+
+/**
+ * Immutable configuration for the argument parser.
+ * The configuration defines the set of supported options and their types.
+ * Entries are provided as an object mapping option names to configuration
+ * entries.
+ * The configuration is normalized and validated during construction.
+ * The resulting object is immutable.
+ */
+export class ParserConfig {
+  #entries: ConfigEntries;
+  #parser: StrictParserOptions;
+  #size: number;
+
+  constructor(input: ParserConfigInput) {
+    if (!isObject(input)) {
+      throw new TypeError('input value must be a plain object');
+    } else if (!isObject(input.options)) {
+      throw new TypeError('"options" value must be a plain object');
+    } else if (input.parser != null && !isObject(input.parser)) {
+      throw new TypeError('"parser" value must be a plain object');
+    }
+
+    const { options, parser } = input;
+
+    this.#parser = {
+      allowUnknown: parser?.allowUnknown ?? false,
+      parseParameters: parser?.parseParameters ?? true,
+      aggregateErrors: parser?.aggregateErrors ?? false,
+    };
+
+    this.#size = 0;
+    const entryMap = Object.create(null);
+    for (const [key, value] of Object.entries(options)) {
+      entryMap[key] = Object.freeze({ ...value });
+      this.#size += 1;
+    }
+    this.#entries = entryMap;
+
+    if (this.#parser.aggregateErrors)
+      validateEntriesAggregate(this.#entries);
+    else
+      validateEntries(this.#entries);
+    Object.freeze(this.#entries);
+    Object.freeze(this.#parser);
+    Object.freeze(this);
+  }
+
+  public entries(): Iterable<[string, ConfigEntry]> {
+    return Object.entries(this.#entries);
+  }
+
+  public get(key: string): ConfigEntry | undefined {
+    return this.#entries[key];
+  }
+
+  public has(key: string): boolean {
+    return Object.hasOwn(this.#entries, key);
+  }
+
+  public keys(): Iterable<string> {
+    return Object.keys(this.#entries);
+  }
+
+  public values(): Iterable<ConfigEntry> {
+    return Object.values(this.#entries);
+  }
+
+  public toJSON(): ParserConfigInput {
+    return {
+      options: this.#entries,
+      parser: this.#parser,
+    };
+  }
+
+  get size(): number {
+    return this.#size;
+  }
+
+  get allowUnknown(): boolean {
+    return this.#parser.allowUnknown;
+  }
+
+  get parseParameters(): boolean {
+    return this.#parser.parseParameters;
+  }
+
+  get aggregateErrors(): boolean {
+    return this.#parser.aggregateErrors;
+  }
+}

package/src/read_config.ts

@@ -0,0 +1,14 @@
+import fs from 'node:fs';
+import { ParserConfig } from './parser_config.ts';
+import type { ParserConfigInput } from './types.ts';
+
+/**
+ * Reads a parser configuration from a JSON file.
+ * The file must contain a valid configuration object that can be
+ * passed to the ParserConfig constructor.
+ */
+export function readJSONConfig(configFile: string): ParserConfig {
+  const content: string = fs.readFileSync(configFile, { encoding: 'utf8' });
+  const configObj: ParserConfigInput = JSON.parse(content);
+  return new ParserConfig(configObj);
+}

package/src/types.ts

@@ -0,0 +1,262 @@
+/**
+ * Option type.
+ * Defines the kind of value an option accepts and how it is parsed.
+ */
+export type OptionType =
+  | 'flag'
+  | 'text'
+  | 'int'
+  | 'float'
+  | 'count'
+  | 'list'
+  | 'alias';
+
+/**
+ * Alias target type.
+ * Represents the set of option types that an alias may reference.
+ * Aliases cannot target other aliases.
+ */
+export type AliasType =
+  | 'flag'
+  | 'text'
+  | 'int'
+  | 'float'
+  | 'count'
+  | 'list';
+
+/**
+ * Flag option entry.
+ * A flag is a boolean option that is set to true when present.
+ */
+export type FlagEntry = { type: 'flag' };
+
+/**
+ * Text option entry.
+ * A text option accepts a string value. A default value may be
+ * defined for command-line options provided without an associated
+ * value.
+ */
+export type TextEntry = { type: 'text'; default?: string };
+
+/**
+ * Integer option entry.
+ * An integer option accepts a numeric value. The value must be a
+ * valid integer and must be a safe integer. A default value may
+ * be defined for command-line options provided without an
+ * associated value.
+ */
+export type IntEntry = { type: 'int'; default?: number };
+
+/**
+ * Float option entry.
+ * A float option takes any value that can be represented as a
+ * floating point number. Integer values are converted to floats.
+ */
+export type FloatEntry = { type: 'float', default?: number };
+
+/**
+ * Count option entry.
+ * A count option increments a numeric counter each time the option
+ * is provided.
+ */
+export type CountEntry = { type: 'count' };
+
+/**
+ * List option entry.
+ * A list option accepts a string value and splits it into multiple
+ * entries using a separator.
+ * The separator defaults to a comma if not specified.
+ */
+export type ListEntry = { type: 'list'; sep?: string };
+
+/**
+ * Alias option entry.
+ * An alias forwards its value to another option.
+ * The target must reference a valid, non-alias option.
+ */
+export type AliasEntry = { type: 'alias'; target: string };
+
+/**
+ * A configuration entry representing a single command-line option.
+ */
+export type ConfigEntry = (
+  | FlagEntry
+  | TextEntry
+  | IntEntry
+  | FloatEntry
+  | CountEntry
+  | ListEntry
+  | AliasEntry
+);
+
+/**
+ * An object holding option configuration entries.
+ */
+export type ConfigEntries = Record<string, ConfigEntry>;
+
+/**
+ * ParserConfig configuration flags that don't refer to a single
+ * command-line option.
+ */
+export type ParserOptions = {
+  allowUnknown?: boolean;
+  parseParameters?: boolean;
+  aggregateErrors?: boolean;
+};
+
+export type StrictParserOptions = {
+  allowUnknown: boolean;
+  parseParameters: boolean;
+  aggregateErrors: boolean;
+};
+
+/**
+ * The input object for the ParserConfig constructor.
+ * Contains configuration for specific command-line options
+ * and general configuration options.
+ */
+export type ParserConfigInput = {
+  options: ConfigEntries;
+  parser?: ParserOptions;
+}
+
+/**
+ * Option value.
+ * Represents the possible values returned for parsed options.
+ */
+export type OptionValue = boolean | string | number | string[];
+
+/**
+ * Result mapping.
+ * A map-like structure used to store parsed key-value pairs.
+ * Instances can be frozen to prevent further modifications.
+ */
+abstract class ResultMapping<K, V> extends Map<K, V> {
+  protected isFrozen = false;
+
+  constructor(entries?: [K, V][]) {
+    super(entries);
+
+    // Prevent property from showing up in console.log.
+    Object.defineProperty(this, 'isFrozen', {
+      enumerable: false,
+    });
+
+    // Prevent regular object property assignments.
+    Object.preventExtensions(this);
+  }
+
+  /**
+   * Sets a value for the given key.
+   * Throws if the mapping is frozen.
+   */
+  override set(key: K, value: V): this {
+    if (this.isFrozen) {
+      const name = this.constructor.name.toLowerCase();
+      throw new TypeError(`you cannot modify parsed ${name}`);
+    }
+    return super.set(key, value);
+  }
+
+  /**
+   * Deletes a key from the mapping.
+   * Throws if the mapping is frozen.
+   */
+  override delete(key: K): boolean {
+    if (this.isFrozen) {
+      const name = this.constructor.name.toLowerCase();
+      throw new TypeError(`you cannot delete parsed ${name}`);
+    }
+    return super.delete(key);
+  }
+
+  /**
+   * Clears all entries from the mapping.
+   * Throws if the mapping is frozen.
+   */
+  override clear(): void {
+    if (this.isFrozen) {
+      const name = this.constructor.name.toLowerCase();
+      throw new TypeError(`you cannot delete parsed ${name}`);
+    }
+    super.clear();
+  }
+
+  /**
+   * Freezes the mapping, preventing further modifications.
+   */
+  public freeze(): void {
+    this.isFrozen = true;
+    Object.freeze(this);
+  }
+
+  /**
+   * Serializes the mapping to a plain object.
+   */
+  public toJSON(): Record<string, V> {
+    return Object.fromEntries(this.entries());
+  }
+}
+
+/**
+ * Result list.
+ * An array-like structure used to store ordered values.
+ * Only numeric indices and the length property may be modified.
+ * Assigning any other property will throw an error.
+ */
+abstract class ResultList<T> extends Array<T> {
+  constructor(args?: T[]) {
+    const length = (args as T[])?.length ?? 0;
+    super(length);
+    for (let i = 0; i < length; i++) {
+      this[i] = (args as T[])[i]!;
+    }
+
+    return new Proxy(this, {
+      set(target, prop, value) {
+        if (prop === 'length') {
+          target[prop] = value;
+          return true;
+        } else if (String(Number(prop)) === prop) {
+          target[Number(prop)] = value;
+          return true;
+        }
+
+        throw new TypeError(`Cannot add non-index property: ${String(prop)}`);
+      }
+    });
+  }
+}
+
+/**
+ * Parsed option values.
+ * Values are determined by the parser configuration. Repeated options
+ * either overwrite previous values or accumulate them, depending on
+ * their type.
+ */
+export class Options extends ResultMapping<string, OptionValue> {}
+
+/**
+ * Parsed key/value assignments.
+ * Parameters are parsed from arguments of the form "key=value" and do
+ * not depend on the parser configuration.
+ */
+export class Parameters extends ResultMapping<string, string> {}
+
+/**
+ * Positional arguments.
+ * Operands are arguments that are not parsed as options or parameters.
+ */
+export class Operands extends ResultList<string> {}
+
+/**
+ * The result of parsing operations.
+ * - options: parsed option values
+ * - parameters: parsed named parameters
+ * - operands: positional arguments
+ */
+export interface ParseResult {
+  options: Options;
+  parameters?: Parameters;
+  operands: Operands;
+}