argot-cli 0.0.0-stage → 0.4.0-beta.1

package/dist/errors.d.ts

@@ -0,0 +1,172 @@
+/**
+ * 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 declare 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 declare class ConfigError extends Error {
+    private _errors;
+    push(error: Error): void;
+    get errors(): Error[];
+}
+/**
+ * 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 declare class InvalidIntError extends RuntimeError {
+    value: string;
+    constructor(value: string);
+}
+/**
+ * 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 declare class InvalidFloatError extends RuntimeError {
+    value: string;
+    constructor(value: string);
+}
+/**
+ * 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 declare class UnsafeIntegerError extends RuntimeError {
+    value: number;
+    constructor(value: number);
+}
+/**
+ * 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 declare class NullArgError extends RuntimeError {
+    option: string;
+    target?: string;
+    constructor(name: string, target?: string);
+}
+/**
+ * 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 declare class NullIntError extends RuntimeError {
+    option: string;
+    target?: string;
+    constructor(name: string, target?: string);
+}
+/**
+ * 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 declare class NullFloatError extends RuntimeError {
+    option: string;
+    target?: string;
+    constructor(name: string, target?: string);
+}
+/**
+ * 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 declare class UnknownOptionError extends RuntimeError {
+    option: string;
+    constructor(name: string);
+}
+/**
+ * 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 declare class InvalidOptionTypeError extends ConfigError {
+    type: string;
+    constructor(tag: string);
+}
+/**
+ * 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 declare class AliasTargetNotFoundError extends ConfigError {
+    option: string;
+    target: string;
+    constructor(name: string, target: string);
+}
+/**
+ * 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 declare class InvalidAliasTargetError extends ConfigError {
+    option: string;
+    target: string;
+    constructor(name: string, target: string);
+}
+/**
+ * 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 declare class MissingOptionPropertyError extends ConfigError {
+    option: string;
+    property: string;
+    constructor(option: string, property: string);
+}
+/**
+ * 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 declare class MissingOptionTypeError extends ConfigError {
+    option: string;
+    constructor(name: string);
+}

package/dist/errors.js

@@ -0,0 +1,246 @@
+/**
+ * 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 {
+    _errors = [];
+    push(error) {
+        this._errors.push(error);
+    }
+    get errors() {
+        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 {
+    value;
+    constructor(value) {
+        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 {
+    value;
+    constructor(value) {
+        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 {
+    value;
+    constructor(value) {
+        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 {
+    option;
+    target;
+    constructor(name, target) {
+        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 {
+    option;
+    target;
+    constructor(name, target) {
+        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 {
+    option;
+    target;
+    constructor(name, target) {
+        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 {
+    option;
+    constructor(name) {
+        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 {
+    type;
+    constructor(tag) {
+        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 {
+    option;
+    target;
+    constructor(name, target) {
+        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 {
+    option;
+    target;
+    constructor(name, target) {
+        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 {
+    option;
+    property;
+    constructor(option, property) {
+        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 {
+    option;
+    constructor(name) {
+        const msg = `option '${name}' is missing required property 'type'`;
+        super(msg);
+        this.option = name;
+        Object.freeze(this);
+    }
+}

package/dist/mod.d.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/dist/mod.js

@@ -0,0 +1,48 @@
+/**
+ * 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.js';
+export { ParserConfig } from './parser_config.js';
+export { readJSONConfig } from './read_config.js';

package/dist/parser_config.d.ts

@@ -0,0 +1,23 @@
+import type { ConfigEntry, ParserConfigInput } from './types.ts';
+/**
+ * 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 declare class ParserConfig {
+    #private;
+    constructor(input: ParserConfigInput);
+    entries(): Iterable<[string, ConfigEntry]>;
+    get(key: string): ConfigEntry | undefined;
+    has(key: string): boolean;
+    keys(): Iterable<string>;
+    values(): Iterable<ConfigEntry>;
+    toJSON(): ParserConfigInput;
+    get size(): number;
+    get allowUnknown(): boolean;
+    get parseParameters(): boolean;
+    get aggregateErrors(): boolean;
+}

package/dist/parser_config.js

@@ -0,0 +1,83 @@
+import { validateEntries, validateEntriesAggregate } from './utils.js';
+function isObject(obj) {
+    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;
+    #parser;
+    #size;
+    constructor(input) {
+        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);
+    }
+    entries() {
+        return Object.entries(this.#entries);
+    }
+    get(key) {
+        return this.#entries[key];
+    }
+    has(key) {
+        return Object.hasOwn(this.#entries, key);
+    }
+    keys() {
+        return Object.keys(this.#entries);
+    }
+    values() {
+        return Object.values(this.#entries);
+    }
+    toJSON() {
+        return {
+            options: this.#entries,
+            parser: this.#parser,
+        };
+    }
+    get size() {
+        return this.#size;
+    }
+    get allowUnknown() {
+        return this.#parser.allowUnknown;
+    }
+    get parseParameters() {
+        return this.#parser.parseParameters;
+    }
+    get aggregateErrors() {
+        return this.#parser.aggregateErrors;
+    }
+}

package/dist/read_config.d.ts

@@ -0,0 +1,7 @@
+import { ParserConfig } from './parser_config.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 declare function readJSONConfig(configFile: string): ParserConfig;

package/dist/read_config.js

@@ -0,0 +1,12 @@
+import fs from 'node:fs';
+import { ParserConfig } from './parser_config.js';
+/**
+ * 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) {
+    const content = fs.readFileSync(configFile, { encoding: 'utf8' });
+    const configObj = JSON.parse(content);
+    return new ParserConfig(configObj);
+}