@boneskull/bargs 0.1.1

package/dist/parser.cjs

@@ -0,0 +1,293 @@
+"use strict";
+/**
+ * Low-level argument parsing logic wrapping Node.js `util.parseArgs()`.
+ *
+ * Handles the transformation of CLI arguments into typed values by:
+ *
+ * - Building `parseArgs` configuration from bargs option schemas
+ * - Coercing parsed string values to their declared types (number, enum, etc.)
+ * - Processing positional arguments including variadic rest args
+ * - Running handler functions (sync or async) after successful parsing
+ * - Supporting both simple CLIs and command-based CLIs with subcommand dispatch
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCommandsAsync = exports.parseCommandsSync = exports.parseSimple = exports.runHandlers = exports.runSyncHandlers = void 0;
+const node_util_1 = require("node:util");
+const errors_js_1 = require("./errors.cjs");
+/**
+ * Check if a value is a thenable (Promise-like). Uses duck-typing for
+ * cross-realm compatibility.
+ */
+const isThenable = (value) => value !== null &&
+    typeof value === 'object' &&
+    typeof value.then === 'function';
+/**
+ * Run a handler or array of handlers synchronously. Throws if any handler
+ * returns a thenable.
+ */
+const runSyncHandlers = (handler, result) => {
+    const handlers = Array.isArray(handler) ? handler : [handler];
+    for (const h of handlers) {
+        const maybePromise = h(result);
+        if (isThenable(maybePromise)) {
+            throw new errors_js_1.BargsError('Handler returned a thenable. Use bargsAsync() for async handlers.');
+        }
+    }
+};
+exports.runSyncHandlers = runSyncHandlers;
+/**
+ * Run a handler or array of handlers sequentially (async).
+ */
+const runHandlers = async (handler, result) => {
+    const handlers = Array.isArray(handler) ? handler : [handler];
+    for (const h of handlers) {
+        await h(result);
+    }
+};
+exports.runHandlers = runHandlers;
+/**
+ * Build parseArgs options config from our options schema.
+ */
+const buildParseArgsConfig = (schema) => {
+    const config = {};
+    for (const [name, def] of Object.entries(schema)) {
+        const opt = {
+            type: def.type === 'boolean' ? 'boolean' : 'string',
+        };
+        // First single-char alias becomes short option
+        const shortAlias = def.aliases?.find((a) => a.length === 1);
+        if (shortAlias) {
+            opt.short = shortAlias;
+        }
+        // Arrays need multiple: true
+        if (def.type === 'array') {
+            opt.multiple = true;
+        }
+        config[name] = opt;
+    }
+    return config;
+};
+/**
+ * Coerce parsed values to their expected types.
+ */
+const coerceValues = (values, schema) => {
+    const result = {};
+    for (const [name, def] of Object.entries(schema)) {
+        let value = values[name];
+        // Apply default if undefined
+        if (value === undefined && 'default' in def) {
+            value = def.default;
+        }
+        // Type coercion
+        if (value !== undefined) {
+            switch (def.type) {
+                case 'array':
+                    if (def.items === 'number' && Array.isArray(value)) {
+                        result[name] = value.map((v) => (typeof v === 'string' ? Number(v) : v));
+                    }
+                    else {
+                        result[name] = value;
+                    }
+                    break;
+                case 'count':
+                    // Count options count occurrences
+                    result[name] = typeof value === 'number' ? value : value ? 1 : 0;
+                    break;
+                case 'enum': {
+                    const enumValue = value;
+                    if (value !== undefined && !def.choices.includes(enumValue)) {
+                        throw new Error(`Invalid value for --${name}: "${enumValue}". Must be one of: ${def.choices.join(', ')}`);
+                    }
+                    result[name] = value;
+                    break;
+                }
+                case 'number':
+                    result[name] = typeof value === 'string' ? Number(value) : value;
+                    break;
+                default:
+                    result[name] = value;
+            }
+        }
+        else {
+            result[name] = value;
+        }
+    }
+    return result;
+};
+/**
+ * Coerce positional values.
+ *
+ * Note: Schema validation (variadic last, required order) is done upfront by
+ * validateConfig in bargs.ts.
+ */
+const coercePositionals = (positionals, schema) => {
+    const result = [];
+    for (let i = 0; i < schema.length; i++) {
+        const def = schema[i];
+        const value = positionals[i];
+        if (def.type === 'variadic') {
+            // Rest of positionals - def is narrowed to VariadicPositional here
+            const variadicDef = def;
+            const rest = positionals.slice(i);
+            if (variadicDef.items === 'number') {
+                result.push(rest.map(Number));
+            }
+            else {
+                result.push(rest);
+            }
+            break;
+        }
+        if (value !== undefined) {
+            if (def.type === 'number') {
+                result.push(Number(value));
+            }
+            else if (def.type === 'enum') {
+                // Validate enum choice
+                if (!def.choices.includes(value)) {
+                    throw new Error(`Invalid value for positional ${i}: "${value}". Must be one of: ${def.choices.join(', ')}`);
+                }
+                result.push(value);
+            }
+            else {
+                result.push(value);
+            }
+        }
+        else if ('default' in def && def.default !== undefined) {
+            result.push(def.default);
+        }
+        else if (def.required) {
+            throw new Error(`Missing required positional argument at position ${i}`);
+        }
+        else {
+            result.push(undefined);
+        }
+    }
+    return result;
+};
+/**
+ * Parse arguments for a simple CLI (no commands). This is synchronous - it only
+ * parses, does not run handlers.
+ */
+const parseSimple = (config) => {
+    const { args = process.argv.slice(2), options: optionsSchema = {}, positionals: positionalsSchema = [], } = config;
+    // Build parseArgs config
+    const parseArgsOptions = buildParseArgsConfig(optionsSchema);
+    // Parse with Node.js util.parseArgs
+    const { positionals, values } = (0, node_util_1.parseArgs)({
+        allowPositionals: positionalsSchema.length > 0,
+        args,
+        options: parseArgsOptions,
+        strict: true,
+    });
+    // Coerce and apply defaults
+    const coercedValues = coerceValues(values, optionsSchema);
+    const coercedPositionals = coercePositionals(positionals, positionalsSchema);
+    return {
+        command: undefined,
+        positionals: coercedPositionals,
+        values: coercedValues,
+    };
+};
+exports.parseSimple = parseSimple;
+/**
+ * Core command parsing logic (sync, no handler execution). Returns the parsed
+ * result and the handler to run.
+ */
+const parseCommandsCore = (config) => {
+    const { args = process.argv.slice(2), commands, defaultHandler, options: globalOptions = {}, } = config;
+    const commandsRecord = commands;
+    // Find command name (first non-flag argument)
+    const commandIndex = args.findIndex((arg) => !arg.startsWith('-'));
+    const commandName = commandIndex >= 0 ? args[commandIndex] : undefined;
+    const remainingArgs = commandName
+        ? [...args.slice(0, commandIndex), ...args.slice(commandIndex + 1)]
+        : args;
+    // No command specified
+    if (!commandName) {
+        if (typeof defaultHandler === 'string') {
+            // Use named default command (recursive)
+            return parseCommandsCore({
+                ...config,
+                args: [defaultHandler, ...args],
+                defaultHandler: undefined,
+            });
+        }
+        else if (typeof defaultHandler === 'function' ||
+            Array.isArray(defaultHandler)) {
+            // Parse global options only
+            const parseArgsOptions = buildParseArgsConfig(globalOptions);
+            const { values } = (0, node_util_1.parseArgs)({
+                allowPositionals: false,
+                args: remainingArgs,
+                options: parseArgsOptions,
+                strict: true,
+            });
+            const coercedValues = coerceValues(values, globalOptions);
+            const result = {
+                command: undefined,
+                positionals: [],
+                values: coercedValues,
+            };
+            return {
+                handler: defaultHandler,
+                result,
+            };
+        }
+        else {
+            throw new errors_js_1.HelpError('No command specified.');
+        }
+    }
+    // Find command config
+    const command = commandsRecord[commandName];
+    if (!command) {
+        throw new errors_js_1.HelpError(`Unknown command: ${commandName}`);
+    }
+    // Merge global and command options
+    const commandOptions = command.options ?? {};
+    const mergedOptionsSchema = { ...globalOptions, ...commandOptions };
+    const commandPositionals = command.positionals ?? [];
+    // Build parseArgs config
+    const parseArgsOptions = buildParseArgsConfig(mergedOptionsSchema);
+    // Parse
+    const { positionals, values } = (0, node_util_1.parseArgs)({
+        allowPositionals: commandPositionals.length > 0,
+        args: remainingArgs,
+        options: parseArgsOptions,
+        strict: true,
+    });
+    // Coerce
+    const coercedValues = coerceValues(values, mergedOptionsSchema);
+    const coercedPositionals = coercePositionals(positionals, commandPositionals);
+    const result = {
+        command: commandName,
+        positionals: coercedPositionals,
+        values: coercedValues,
+    };
+    return { handler: command.handler, result };
+};
+/**
+ * Parse arguments for a command-based CLI (sync). Throws if any handler returns
+ * a thenable.
+ */
+const parseCommandsSync = (config) => {
+    const { handler, result } = parseCommandsCore(config);
+    if (handler) {
+        (0, exports.runSyncHandlers)(handler, result);
+    }
+    return result;
+};
+exports.parseCommandsSync = parseCommandsSync;
+/**
+ * Parse arguments for a command-based CLI (async).
+ */
+const parseCommandsAsync = async (config) => {
+    const { handler, result } = parseCommandsCore(config);
+    if (handler) {
+        await (0, exports.runHandlers)(handler, result);
+    }
+    return result;
+};
+exports.parseCommandsAsync = parseCommandsAsync;
+//# sourceMappingURL=parser.js.map

package/dist/parser.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"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"}

package/dist/parser.d.cts

@@ -0,0 +1,47 @@
+/**
+ * Low-level argument parsing logic wrapping Node.js `util.parseArgs()`.
+ *
+ * Handles the transformation of CLI arguments into typed values by:
+ *
+ * - Building `parseArgs` configuration from bargs option schemas
+ * - Coercing parsed string values to their declared types (number, enum, etc.)
+ * - Processing positional arguments including variadic rest args
+ * - Running handler functions (sync or async) after successful parsing
+ * - Supporting both simple CLIs and command-based CLIs with subcommand dispatch
+ *
+ * @packageDocumentation
+ */
+import type { BargsConfigWithCommands, BargsResult, CommandConfigInput, HandlerFn, InferOptions, InferPositionals, OptionsSchema, PositionalsSchema } from "./types.cjs";
+/**
+ * Run a handler or array of handlers synchronously. Throws if any handler
+ * returns a thenable.
+ */
+export declare const runSyncHandlers: <T>(handler: HandlerFn<T> | HandlerFn<T>[], result: T) => void;
+/**
+ * Run a handler or array of handlers sequentially (async).
+ */
+export declare const runHandlers: <T>(handler: HandlerFn<T> | HandlerFn<T>[], result: T) => Promise<void>;
+/**
+ * Options for parseSimple.
+ */
+interface ParseSimpleOptions<TOptions extends OptionsSchema = OptionsSchema, TPositionals extends PositionalsSchema = PositionalsSchema> {
+    args?: string[];
+    options?: TOptions;
+    positionals?: TPositionals;
+}
+/**
+ * Parse arguments for a simple CLI (no commands). This is synchronous - it only
+ * parses, does not run handlers.
+ */
+export declare const parseSimple: <TOptions extends OptionsSchema = OptionsSchema, TPositionals extends PositionalsSchema = PositionalsSchema>(config: ParseSimpleOptions<TOptions, TPositionals>) => BargsResult<InferOptions<TOptions>, InferPositionals<TPositionals>, undefined>;
+/**
+ * Parse arguments for a command-based CLI (sync). Throws if any handler returns
+ * a thenable.
+ */
+export declare const parseCommandsSync: <TOptions extends OptionsSchema = OptionsSchema, TCommands extends Record<string, CommandConfigInput> = Record<string, CommandConfigInput>>(config: BargsConfigWithCommands<TOptions, TCommands>) => BargsResult<InferOptions<TOptions>, unknown[], string | undefined>;
+/**
+ * Parse arguments for a command-based CLI (async).
+ */
+export declare const parseCommandsAsync: <TOptions extends OptionsSchema = OptionsSchema, TCommands extends Record<string, CommandConfigInput> = Record<string, CommandConfigInput>>(config: BargsConfigWithCommands<TOptions, TCommands>) => Promise<BargsResult<InferOptions<TOptions>, unknown[], string | undefined>>;
+export {};
+//# sourceMappingURL=parser.d.ts.map

package/dist/parser.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EACV,uBAAuB,EACvB,WAAW,EACX,kBAAkB,EAClB,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EAClB,oBAAmB;AAapB;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAC/B,SAAS,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,EAAE,EACtC,QAAQ,CAAC,KACR,IAUF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAU,CAAC,EACjC,SAAS,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,EAAE,EACtC,QAAQ,CAAC,KACR,OAAO,CAAC,IAAI,CAKd,CAAC;AAyJF;;GAEG;AACH,UAAU,kBAAkB,CAC1B,QAAQ,SAAS,aAAa,GAAG,aAAa,EAC9C,YAAY,SAAS,iBAAiB,GAAG,iBAAiB;IAE1D,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,WAAW,CAAC,EAAE,YAAY,CAAC;CAC5B;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,GACtB,QAAQ,SAAS,aAAa,GAAG,aAAa,EAC9C,YAAY,SAAS,iBAAiB,GAAG,iBAAiB,EAE1D,QAAQ,kBAAkB,CAAC,QAAQ,EAAE,YAAY,CAAC,KACjD,WAAW,CACZ,YAAY,CAAC,QAAQ,CAAC,EACtB,gBAAgB,CAAC,YAAY,CAAC,EAC9B,SAAS,CA4BV,CAAC;AAoHF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,SAAS,aAAa,GAAG,aAAa,EAC9C,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,MAAM,CAC3D,MAAM,EACN,kBAAkB,CACnB,EAED,QAAQ,uBAAuB,CAAC,QAAQ,EAAE,SAAS,CAAC,KACnD,WAAW,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,EAAE,MAAM,GAAG,SAAS,CAQnE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,SAAS,aAAa,GAAG,aAAa,EAC9C,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,MAAM,CAC3D,MAAM,EACN,kBAAkB,CACnB,EAED,QAAQ,uBAAuB,CAAC,QAAQ,EAAE,SAAS,CAAC,KACnD,OAAO,CACR,WAAW,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,CASnE,CAAC"}

package/dist/parser.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Low-level argument parsing logic wrapping Node.js `util.parseArgs()`.
+ *
+ * Handles the transformation of CLI arguments into typed values by:
+ *
+ * - Building `parseArgs` configuration from bargs option schemas
+ * - Coercing parsed string values to their declared types (number, enum, etc.)
+ * - Processing positional arguments including variadic rest args
+ * - Running handler functions (sync or async) after successful parsing
+ * - Supporting both simple CLIs and command-based CLIs with subcommand dispatch
+ *
+ * @packageDocumentation
+ */
+import type { BargsConfigWithCommands, BargsResult, CommandConfigInput, HandlerFn, InferOptions, InferPositionals, OptionsSchema, PositionalsSchema } from "./types.js";
+/**
+ * Run a handler or array of handlers synchronously. Throws if any handler
+ * returns a thenable.
+ */
+export declare const runSyncHandlers: <T>(handler: HandlerFn<T> | HandlerFn<T>[], result: T) => void;
+/**
+ * Run a handler or array of handlers sequentially (async).
+ */
+export declare const runHandlers: <T>(handler: HandlerFn<T> | HandlerFn<T>[], result: T) => Promise<void>;
+/**
+ * Options for parseSimple.
+ */
+interface ParseSimpleOptions<TOptions extends OptionsSchema = OptionsSchema, TPositionals extends PositionalsSchema = PositionalsSchema> {
+    args?: string[];
+    options?: TOptions;
+    positionals?: TPositionals;
+}
+/**
+ * Parse arguments for a simple CLI (no commands). This is synchronous - it only
+ * parses, does not run handlers.
+ */
+export declare const parseSimple: <TOptions extends OptionsSchema = OptionsSchema, TPositionals extends PositionalsSchema = PositionalsSchema>(config: ParseSimpleOptions<TOptions, TPositionals>) => BargsResult<InferOptions<TOptions>, InferPositionals<TPositionals>, undefined>;
+/**
+ * Parse arguments for a command-based CLI (sync). Throws if any handler returns
+ * a thenable.
+ */
+export declare const parseCommandsSync: <TOptions extends OptionsSchema = OptionsSchema, TCommands extends Record<string, CommandConfigInput> = Record<string, CommandConfigInput>>(config: BargsConfigWithCommands<TOptions, TCommands>) => BargsResult<InferOptions<TOptions>, unknown[], string | undefined>;
+/**
+ * Parse arguments for a command-based CLI (async).
+ */
+export declare const parseCommandsAsync: <TOptions extends OptionsSchema = OptionsSchema, TCommands extends Record<string, CommandConfigInput> = Record<string, CommandConfigInput>>(config: BargsConfigWithCommands<TOptions, TCommands>) => Promise<BargsResult<InferOptions<TOptions>, unknown[], string | undefined>>;
+export {};
+//# sourceMappingURL=parser.d.ts.map

package/dist/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EACV,uBAAuB,EACvB,WAAW,EACX,kBAAkB,EAClB,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EAClB,mBAAmB;AAapB;;;GAGG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,EAC/B,SAAS,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,EAAE,EACtC,QAAQ,CAAC,KACR,IAUF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,WAAW,GAAU,CAAC,EACjC,SAAS,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,EAAE,EACtC,QAAQ,CAAC,KACR,OAAO,CAAC,IAAI,CAKd,CAAC;AAyJF;;GAEG;AACH,UAAU,kBAAkB,CAC1B,QAAQ,SAAS,aAAa,GAAG,aAAa,EAC9C,YAAY,SAAS,iBAAiB,GAAG,iBAAiB;IAE1D,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,WAAW,CAAC,EAAE,YAAY,CAAC;CAC5B;AAED;;;GAGG;AACH,eAAO,MAAM,WAAW,GACtB,QAAQ,SAAS,aAAa,GAAG,aAAa,EAC9C,YAAY,SAAS,iBAAiB,GAAG,iBAAiB,EAE1D,QAAQ,kBAAkB,CAAC,QAAQ,EAAE,YAAY,CAAC,KACjD,WAAW,CACZ,YAAY,CAAC,QAAQ,CAAC,EACtB,gBAAgB,CAAC,YAAY,CAAC,EAC9B,SAAS,CA4BV,CAAC;AAoHF;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,SAAS,aAAa,GAAG,aAAa,EAC9C,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,MAAM,CAC3D,MAAM,EACN,kBAAkB,CACnB,EAED,QAAQ,uBAAuB,CAAC,QAAQ,EAAE,SAAS,CAAC,KACnD,WAAW,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,EAAE,MAAM,GAAG,SAAS,CAQnE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,SAAS,aAAa,GAAG,aAAa,EAC9C,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,MAAM,CAC3D,MAAM,EACN,kBAAkB,CACnB,EAED,QAAQ,uBAAuB,CAAC,QAAQ,EAAE,SAAS,CAAC,KACnD,OAAO,CACR,WAAW,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,OAAO,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC,CASnE,CAAC"}