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

package/dist/types.d.ts

@@ -0,0 +1,185 @@
+/**
+ * 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.
+ */
+declare abstract class ResultMapping<K, V> extends Map<K, V> {
+    protected isFrozen: boolean;
+    constructor(entries?: [K, V][]);
+    /**
+     * Sets a value for the given key.
+     * Throws if the mapping is frozen.
+     */
+    set(key: K, value: V): this;
+    /**
+     * Deletes a key from the mapping.
+     * Throws if the mapping is frozen.
+     */
+    delete(key: K): boolean;
+    /**
+     * Clears all entries from the mapping.
+     * Throws if the mapping is frozen.
+     */
+    clear(): void;
+    /**
+     * Freezes the mapping, preventing further modifications.
+     */
+    freeze(): void;
+    /**
+     * Serializes the mapping to a plain object.
+     */
+    toJSON(): Record<string, V>;
+}
+/**
+ * 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.
+ */
+declare abstract class ResultList<T> extends Array<T> {
+    constructor(args?: T[]);
+}
+/**
+ * Parsed option values.
+ * Values are determined by the parser configuration. Repeated options
+ * either overwrite previous values or accumulate them, depending on
+ * their type.
+ */
+export declare 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 declare class Parameters extends ResultMapping<string, string> {
+}
+/**
+ * Positional arguments.
+ * Operands are arguments that are not parsed as options or parameters.
+ */
+export declare 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;
+}
+export {};

package/dist/types.js

@@ -0,0 +1,112 @@
+/**
+ * Result mapping.
+ * A map-like structure used to store parsed key-value pairs.
+ * Instances can be frozen to prevent further modifications.
+ */
+class ResultMapping extends Map {
+    isFrozen = false;
+    constructor(entries) {
+        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.
+     */
+    set(key, value) {
+        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.
+     */
+    delete(key) {
+        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.
+     */
+    clear() {
+        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.
+     */
+    freeze() {
+        this.isFrozen = true;
+        Object.freeze(this);
+    }
+    /**
+     * Serializes the mapping to a plain object.
+     */
+    toJSON() {
+        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.
+ */
+class ResultList extends Array {
+    constructor(args) {
+        const length = args?.length ?? 0;
+        super(length);
+        for (let i = 0; i < length; i++) {
+            this[i] = args[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 {
+}
+/**
+ * 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 {
+}
+/**
+ * Positional arguments.
+ * Operands are arguments that are not parsed as options or parameters.
+ */
+export class Operands extends ResultList {
+}

package/dist/utils.d.ts

@@ -0,0 +1,48 @@
+import type { ConfigEntry, ConfigEntries } from './types.ts';
+/**
+ * Parses a string as an integer.
+ * The value must consist only of an optional sign followed by digits.
+ * The resulting number must be safely representable by the runtime.
+ * Throws:
+ * - InvalidIntError if the value is not a valid integer string
+ * - UnsafeIntegerError if the parsed value cannot be safely represented
+ */
+export declare function parseIntStrict(value: string): number;
+/**
+ * Parses a string as a floating-point number.
+ * The value must consist only of:
+ * - an optional sign
+ * - digits
+ * - an optional fractional part
+ * - an optional exponent
+ *
+ * Whitespace, Infinity and NaN are not allowed.
+ *
+ * Throws:
+ * - InvalidFloatError if the value is not a valid float string
+ */
+export declare function parseFloatStrict(value: string): number;
+/**
+ * Validates a single configuration entry.
+ * The entry must be a labeled object containing at least the "option"
+ * and "type" properties. Additional properties are validated according
+ * to the entry type.
+ * Throws:
+ * - TypeError if the entry is not an object or contains invalid values
+ * - MissingOptionPropertyError if a required property is missing
+ * - InvalidOptionTypeError if the option type is not supported
+ */
+export declare function validateEntry(name: string, entry: ConfigEntry): void;
+/**
+ * Validates a set of configuration entries.
+ * Each entry is validated individually. Alias entries are validated
+ * after all entries have been processed to ensure that:
+ * - the target exists
+ * - the target is not itself an alias
+ * Throws:
+ * - Any error raised by validateEntry
+ * - AliasTargetNotFoundError if an alias target does not exist
+ * - InvalidAliasTargetError if an alias targets another alias
+ */
+export declare function validateEntries(entries: ConfigEntries): void;
+export declare function validateEntriesAggregate(entries: ConfigEntries): void;

package/dist/utils.js

@@ -0,0 +1,175 @@
+import { AliasTargetNotFoundError, ConfigError, InvalidAliasTargetError, InvalidFloatError, InvalidIntError, InvalidOptionTypeError, MissingOptionPropertyError, MissingOptionTypeError, UnsafeIntegerError, } from './errors.js';
+/**
+ * Parses a string as an integer.
+ * The value must consist only of an optional sign followed by digits.
+ * The resulting number must be safely representable by the runtime.
+ * Throws:
+ * - InvalidIntError if the value is not a valid integer string
+ * - UnsafeIntegerError if the parsed value cannot be safely represented
+ */
+export function parseIntStrict(value) {
+    if (!/^(-|\+)?\d+$/.test(value)) {
+        throw new InvalidIntError(value);
+    }
+    const num = Number(value);
+    if (!Number.isSafeInteger(num)) {
+        throw new UnsafeIntegerError(num);
+    }
+    return num;
+}
+/**
+ * Parses a string as a floating-point number.
+ * The value must consist only of:
+ * - an optional sign
+ * - digits
+ * - an optional fractional part
+ * - an optional exponent
+ *
+ * Whitespace, Infinity and NaN are not allowed.
+ *
+ * Throws:
+ * - InvalidFloatError if the value is not a valid float string
+ */
+export function parseFloatStrict(value) {
+    if (!/^(-|\+)?(\d+(\.\d+)?|\.\d+)([eE](-|\+)?\d+)?$/.test(value)) {
+        throw new InvalidFloatError(value);
+    }
+    const num = Number(value);
+    if (!Number.isFinite(num)) {
+        throw new InvalidFloatError(value);
+    }
+    return num;
+}
+/**
+ * Validates a single configuration entry.
+ * The entry must be a labeled object containing at least the "option"
+ * and "type" properties. Additional properties are validated according
+ * to the entry type.
+ * Throws:
+ * - TypeError if the entry is not an object or contains invalid values
+ * - MissingOptionPropertyError if a required property is missing
+ * - InvalidOptionTypeError if the option type is not supported
+ */
+export function validateEntry(name, entry) {
+    if (entry == null || typeof entry !== 'object') {
+        throw new TypeError('option config entry must be an object');
+    }
+    else if (!Object.hasOwn(entry, 'type')) {
+        throw new MissingOptionTypeError(name);
+    }
+    const tag = entry.type;
+    switch (tag) {
+        case 'flag':
+        case 'count': {
+            /* these types have no extra mandatory values */
+            break;
+        }
+        case 'text': {
+            if (!Object.hasOwn(entry, 'default'))
+                break;
+            const { default: def } = entry;
+            if (typeof def !== 'string')
+                throw new TypeError('default value must be a string');
+            break;
+        }
+        case 'int': {
+            if (!Object.hasOwn(entry, 'default'))
+                break;
+            const { default: def } = entry;
+            if (typeof def !== 'number' || !Number.isInteger(def))
+                throw new TypeError('default value must be an integer');
+            break;
+        }
+        case 'float': {
+            if (!Object.hasOwn(entry, 'default'))
+                break;
+            const { default: def } = entry;
+            if (typeof def !== 'number' || !Number.isFinite(def))
+                throw new TypeError('default value must be a number');
+            break;
+        }
+        case 'list': {
+            if (!Object.hasOwn(entry, 'sep'))
+                break;
+            const { sep } = entry;
+            if (typeof sep !== 'string')
+                throw new TypeError('sep value must be a string');
+            break;
+        }
+        case 'alias': {
+            if (!Object.hasOwn(entry, 'target')) {
+                throw new MissingOptionPropertyError(name, 'target');
+            }
+            const { target } = entry;
+            if (typeof target !== 'string')
+                throw new TypeError('target value must be a string');
+            break;
+        }
+        default: {
+            throw new InvalidOptionTypeError(tag);
+        }
+    }
+}
+/**
+ * Validates a set of configuration entries.
+ * Each entry is validated individually. Alias entries are validated
+ * after all entries have been processed to ensure that:
+ * - the target exists
+ * - the target is not itself an alias
+ * Throws:
+ * - Any error raised by validateEntry
+ * - AliasTargetNotFoundError if an alias target does not exist
+ * - InvalidAliasTargetError if an alias targets another alias
+ */
+export function validateEntries(entries) {
+    const aliases = [];
+    for (const [name, entry] of Object.entries(entries)) {
+        validateEntry(name, entry);
+        const tag = entry.type;
+        if (tag === 'alias') {
+            const { target } = entry;
+            aliases.push([name, target]);
+        }
+    }
+    for (const [name, target] of aliases) {
+        if (!Object.hasOwn(entries, target)) {
+            throw new AliasTargetNotFoundError(name, target);
+        }
+        const targetEntry = entries[target];
+        if (targetEntry.type === 'alias') {
+            throw new InvalidAliasTargetError(name, target);
+        }
+    }
+}
+export function validateEntriesAggregate(entries) {
+    const aliases = [];
+    const error = new ConfigError('parser configuration is not valid');
+    for (const [name, entry] of Object.entries(entries)) {
+        try {
+            validateEntry(name, entry);
+        }
+        catch (err) {
+            error.push(err);
+            continue;
+        }
+        const tag = entry.type;
+        if (tag === 'alias') {
+            const { target } = entry;
+            aliases.push([name, target]);
+        }
+    }
+    for (const [name, target] of aliases) {
+        if (!Object.hasOwn(entries, target)) {
+            error.push(new AliasTargetNotFoundError(name, target));
+            continue;
+        }
+        const targetEntry = entries[target];
+        if (targetEntry.type === 'alias') {
+            error.push(new InvalidAliasTargetError(name, target));
+        }
+    }
+    if (error.errors.length === 1)
+        throw error.errors[0];
+    else if (error.errors.length > 1)
+        throw error;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argot-cli",
-  "version": "0.4.0-beta",
+  "version": "0.4.0-beta.1",
   "description": "ArgotCLI is a command-line argument parser with a simple configuration format.",
   "type": "module",
   "scripts": {