@boneskull/bargs 1.0.0 → 3.0.0

package/dist/bargs.js

@@ -1,183 +1,503 @@
 /**
- * Core bargs parsing functions for both sync and async CLI execution.
+ * Core bargs API using parser combinator pattern.
  *
- * Provides `bargs()` (synchronous) and `bargsAsync()` (asynchronous) entry
- * points that handle configuration validation, built-in `--help` and
- * `--version` flags, argument parsing, and handler invocation. Supports both
- * simple CLIs with options/positionals and command-based CLIs with
- * subcommands.
+ * Provides `bargs.create()` for building CLIs with a fluent API, plus
+ * combinator functions like `pipe()`, `map()`, and `handle()`.
  *
  * @packageDocumentation
  */
-import { HelpError } from "./errors.js";
+import { BargsError, HelpError } from "./errors.js";
 import { generateCommandHelp, generateHelp } from "./help.js";
-import { parseCommandsAsync, parseCommandsSync, parseSimple, runHandler, runSyncHandler, runSyncTransforms, runTransforms, } from "./parser.js";
+import { parseSimple } from "./parser.js";
 import { defaultTheme, getTheme } from "./theme.js";
-import { validateConfig } from "./validate.js";
-/**
- * Check if config has commands.
- */
-const hasCommands = (config) => config.commands !== undefined && Object.keys(config.commands).length > 0;
-/**
- * Check if user defined their own help option (by name or alias).
- */
-const hasUserDefinedHelp = (options) => {
-    if (!options) {
-        return false;
+export function handle(parserOrFn, maybeFn) {
+    // Direct form: handle(parser, fn) returns Command
+    // Check for Parser first since CallableParser is also a function
+    if (isParser(parserOrFn)) {
+        const parser = parserOrFn;
+        const parserWithTransform = parser;
+        const fn = maybeFn;
+        const cmd = {
+            __brand: 'Command',
+            __optionsSchema: parser.__optionsSchema,
+            __positionalsSchema: parser.__positionalsSchema,
+            handler: fn,
+        };
+        // Preserve transforms from the parser
+        if (parserWithTransform.__transform) {
+            cmd.__transform = parserWithTransform.__transform;
+        }
+        return cmd;
+    }
+    // Curried form: handle(fn) returns (parser) => Command
+    const fn = parserOrFn;
+    return (parser) => {
+        const parserWithTransform = parser;
+        const cmd = {
+            __brand: 'Command',
+            __optionsSchema: parser.__optionsSchema,
+            __positionalsSchema: parser.__positionalsSchema,
+            handler: fn,
+        };
+        // Preserve transforms from the parser
+        if (parserWithTransform.__transform) {
+            cmd.__transform = parserWithTransform.__transform;
+        }
+        return cmd;
+    };
+}
+export function map(parserOrFn, maybeFn) {
+    // Direct form: map(parser, fn) returns Parser
+    // Check for Parser first since CallableParser is also a function
+    if (isParser(parserOrFn)) {
+        const parser = parserOrFn;
+        const fn = maybeFn;
+        return {
+            ...parser,
+            __brand: 'Parser',
+            __positionals: [],
+            __transform: fn,
+            __values: {},
+        };
+    }
+    // Curried form: map(fn) returns (parser) => Parser
+    const fn = parserOrFn;
+    return (parser) => {
+        return {
+            ...parser,
+            __brand: 'Parser',
+            __positionals: [],
+            __transform: fn,
+            __values: {},
+        };
+    };
+}
+export function merge(...parsers) {
+    if (parsers.length === 0) {
+        throw new BargsError('merge() requires at least one parser');
     }
-    if ('help' in options) {
-        return true;
+    // Start with the first parser and fold the rest in
+    let result = parsers[0];
+    for (let i = 1; i < parsers.length; i++) {
+        const next = parsers[i];
+        // Merge options schemas
+        const mergedOptions = {
+            ...result.__optionsSchema,
+            ...next.__optionsSchema,
+        };
+        // Merge positionals schemas
+        const mergedPositionals = [
+            ...result.__positionalsSchema,
+            ...next.__positionalsSchema,
+        ];
+        const resultWithTransform = result;
+        const nextWithTransform = next;
+        let mergedTransform;
+        if (resultWithTransform.__transform && nextWithTransform.__transform) {
+            // Chain transforms
+            const t1 = resultWithTransform.__transform;
+            const t2 = nextWithTransform.__transform;
+            mergedTransform = (r) => {
+                const r1 = t1(r);
+                if (r1 instanceof Promise) {
+                    return r1.then(t2);
+                }
+                return t2(r1);
+            };
+        }
+        else {
+            mergedTransform =
+                nextWithTransform.__transform ?? resultWithTransform.__transform;
+        }
+        result = {
+            __brand: 'Parser',
+            __optionsSchema: mergedOptions,
+            __positionals: [],
+            __positionalsSchema: mergedPositionals,
+            __values: {},
+        };
+        if (mergedTransform) {
+            result.__transform =
+                mergedTransform;
+        }
     }
-    // Check if any option has 'h' as an alias
-    return Object.values(options).some((opt) => opt.aliases?.includes('h'));
+    return result;
+}
+// ═══════════════════════════════════════════════════════════════════════════════
+// CLI BUILDER
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Create a new CLI.
+ *
+ * @example
+ *
+ * ```typescript
+ * const cli = await bargs
+ *   .create('my-app', { version: '1.0.0' })
+ *   .globals(
+ *     map(opt.options({ verbose: opt.boolean() }), ({ values }) => ({
+ *       values: { ...values, ts: Date.now() },
+ *       positionals: [] as const,
+ *     })),
+ *   )
+ *   .command(
+ *     'greet',
+ *     pos.positionals(pos.string({ name: 'name', required: true })),
+ *     ({ positionals }) => console.log(`Hello, ${positionals[0]}!`),
+ *   )
+ *   .parseAsync();
+ * ```
+ */
+const create = (name, options = {}) => {
+    const theme = options.theme ? getTheme(options.theme) : defaultTheme;
+    return createCliBuilder({
+        commands: new Map(),
+        name,
+        options,
+        theme,
+    });
 };
 /**
- * Check if user defined their own version option (by name or alias).
+ * Check if something is a Command (has __brand: 'Command').
  */
-const hasUserDefinedVersion = (options) => {
-    if (!options) {
+const isCommand = (x) => {
+    if (x === null || x === undefined) {
         return false;
     }
-    if ('version' in options) {
-        return true;
-    }
-    // Check if any option has 'V' as an alias
-    return Object.values(options).some((opt) => opt.aliases?.includes('V'));
+    const obj = x;
+    return '__brand' in obj && obj.__brand === 'Command';
 };
 /**
- * Handle help and version flags. Returns true if we should exit.
+ * Create a CLI builder.
  */
-const handleBuiltinFlags = (config, args, theme = defaultTheme) => {
-    // Handle --help (unless user defined their own help option)
-    const userDefinedHelp = hasUserDefinedHelp(config.options);
-    if (!userDefinedHelp && (args.includes('--help') || args.includes('-h'))) {
-        if (hasCommands(config)) {
-            // Check for command-specific help: cmd --help
-            const helpIndex = args.findIndex((a) => a === '--help' || a === '-h');
-            const commandIndex = args.findIndex((a) => !a.startsWith('-'));
-            if (commandIndex >= 0 && commandIndex < helpIndex) {
-                const commandName = args[commandIndex];
-                console.log(generateCommandHelp(config, commandName, theme));
+const createCliBuilder = (state) => {
+    return {
+        // Overloaded command(): accepts either (name, Command, desc?) or (name, Parser, handler, desc?)
+        command(name, cmdOrParser, handlerOrDesc, maybeDesc) {
+            let cmd;
+            let description;
+            if (isCommand(cmdOrParser)) {
+                // Form 1: command(name, Command, description?)
+                cmd = cmdOrParser;
+                description = handlerOrDesc;
+            }
+            else if (isParser(cmdOrParser)) {
+                // Form 2: command(name, Parser, handler, description?)
+                const parser = cmdOrParser;
+                const handler = handlerOrDesc;
+                description = maybeDesc;
+                // Create Command from Parser + handler
+                const parserWithTransform = parser;
+                const newCmd = {
+                    __brand: 'Command',
+                    __optionsSchema: parser.__optionsSchema,
+                    __positionalsSchema: parser.__positionalsSchema,
+                    handler,
+                };
+                // Preserve transforms from the parser
+                if (parserWithTransform.__transform) {
+                    newCmd.__transform = parserWithTransform.__transform;
+                }
+                cmd = newCmd;
             }
             else {
-                console.log(generateHelp(config, theme));
+                throw new Error('command() requires a Command or Parser as second argument');
+            }
+            state.commands.set(name, { cmd, description });
+            return this;
+        },
+        // Overloaded defaultCommand(): accepts name, Command, or (Parser, handler)
+        defaultCommand(nameOrCmdOrParser, maybeHandler) {
+            // Form 1: defaultCommand(name) - just set the name
+            if (typeof nameOrCmdOrParser === 'string') {
+                return createCliBuilder({
+                    ...state,
+                    defaultCommandName: nameOrCmdOrParser,
+                });
+            }
+            // Generate a unique name for the default command
+            const defaultName = '__default__';
+            if (isCommand(nameOrCmdOrParser)) {
+                // Form 2: defaultCommand(Command)
+                state.commands.set(defaultName, {
+                    cmd: nameOrCmdOrParser,
+                    description: undefined,
+                });
+            }
+            else if (isParser(nameOrCmdOrParser)) {
+                // Form 3: defaultCommand(Parser, handler)
+                const parser = nameOrCmdOrParser;
+                const handler = maybeHandler;
+                const parserWithTransform = parser;
+                const newCmd = {
+                    __brand: 'Command',
+                    __optionsSchema: parser.__optionsSchema,
+                    __positionalsSchema: parser.__positionalsSchema,
+                    handler,
+                };
+                // Preserve transforms from the parser
+                if (parserWithTransform.__transform) {
+                    newCmd.__transform = parserWithTransform.__transform;
+                }
+                state.commands.set(defaultName, {
+                    cmd: newCmd,
+                    description: undefined,
+                });
+            }
+            else {
+                throw new Error('defaultCommand() requires a name, Command, or Parser');
+            }
+            return createCliBuilder({
+                ...state,
+                defaultCommandName: defaultName,
+            });
+        },
+        globals(parser) {
+            return createCliBuilder({
+                ...state,
+                globalParser: parser,
+            });
+        },
+        parse(args = process.argv.slice(2)) {
+            const result = parseCore(state, args, false);
+            if (result instanceof Promise) {
+                throw new BargsError('Async transform or handler detected. Use parseAsync() instead of parse().');
+            }
+            return result;
+        },
+        async parseAsync(args = process.argv.slice(2)) {
+            return parseCore(state, args, true);
+        },
+    };
+};
+/**
+ * Core parse logic shared between parse() and parseAsync().
+ */
+const parseCore = (state, args, allowAsync) => {
+    const { commands, options, theme } = state;
+    // Handle --help
+    if (args.includes('--help') || args.includes('-h')) {
+        // Check for command-specific help
+        const helpIndex = args.findIndex((a) => a === '--help' || a === '-h');
+        const commandIndex = args.findIndex((a) => !a.startsWith('-'));
+        if (commandIndex >= 0 && commandIndex < helpIndex && commands.size > 0) {
+            const commandName = args[commandIndex];
+            if (commands.has(commandName)) {
+                console.log(generateCommandHelpNew(state, commandName, theme));
+                process.exit(0);
             }
         }
-        else {
-            console.log(generateHelp(config, theme));
-        }
+        console.log(generateHelpNew(state, theme));
         process.exit(0);
     }
-    // Handle --version (unless user defined their own version option)
-    const userDefinedVersion = hasUserDefinedVersion(config.options);
-    if (!userDefinedVersion && args.includes('--version') && config.version) {
-        console.log(config.version);
+    // Handle --version
+    if (args.includes('--version') && options.version) {
+        console.log(options.version);
         process.exit(0);
     }
-    return false;
+    // If we have commands, dispatch to the appropriate one
+    if (commands.size > 0) {
+        return runWithCommands(state, args, allowAsync);
+    }
+    // Simple CLI (no commands)
+    return runSimple(state, args, allowAsync);
 };
 /**
- * Handle HelpError by printing message and help text.
+ * Generate command-specific help.
  */
-const handleHelpError = (error, config, theme = defaultTheme) => {
-    if (error instanceof HelpError) {
-        console.error(error.message);
-        if (hasCommands(config)) {
-            console.log(generateHelp(config, theme));
-        }
-        else {
-            console.log(generateHelp(config, theme));
-        }
-        process.exit(1);
+const generateCommandHelpNew = (state, commandName, theme) => {
+    const commandEntry = state.commands.get(commandName);
+    if (!commandEntry) {
+        return `Unknown command: ${commandName}`;
     }
-    throw error;
+    // TODO: Implement proper command help generation
+    const config = {
+        commands: {
+            [commandName]: {
+                description: commandEntry.description ?? '',
+                options: commandEntry.cmd.__optionsSchema,
+                positionals: commandEntry.cmd.__positionalsSchema,
+            },
+        },
+        name: state.name,
+    };
+    return generateCommandHelp(config, commandName, theme);
 };
 /**
- * Main bargs entry point (sync implementation). Throws BargsError if any
- * handler returns a thenable.
+ * Generate help for the new CLI structure.
  */
-export function bargs(config, options) {
-    // Validate config upfront (throws ValidationError if invalid)
-    validateConfig(config);
-    const args = config.args ?? process.argv.slice(2);
-    const theme = options?.theme
-        ? getTheme(options.theme)
-        : getTheme('default');
-    try {
-        handleBuiltinFlags(config, args, theme);
-        // Parse
-        if (hasCommands(config)) {
-            return parseCommandsSync({ ...config, args });
-        }
-        else {
-            const parsed = parseSimple({
-                args,
-                options: config.options,
-                positionals: config.positionals,
-            });
-            // Run transforms if present (type-erased in implementation)
-            const transforms = config.transforms;
-            const transformed = transforms
-                ? runSyncTransforms(transforms, parsed.values, parsed.positionals)
-                : { positionals: parsed.positionals, values: parsed.values };
-            const result = {
-                command: undefined,
-                positionals: transformed.positionals,
-                values: transformed.values,
-            };
-            // Call handler if provided (sync)
-            if (config.handler) {
-                runSyncHandler(config.handler, result);
+const generateHelpNew = (state, theme) => {
+    // TODO: Implement proper help generation for new structure
+    // For now, delegate to existing help generator with minimal config
+    const config = {
+        commands: Object.fromEntries(Array.from(state.commands.entries()).map(([name, { description }]) => [
+            name,
+            { description: description ?? '' },
+        ])),
+        description: state.options.description,
+        name: state.name,
+        options: state.globalParser?.__optionsSchema,
+        version: state.options.version,
+    };
+    return generateHelp(config, theme);
+};
+/**
+ * Check if something is a Parser (has __brand: 'Parser'). Parsers can be either
+ * objects or functions (CallableParser).
+ */
+const isParser = (x) => {
+    if (x === null || x === undefined) {
+        return false;
+    }
+    // Handle both plain objects and functions with Parser properties
+    const obj = x;
+    return '__brand' in obj && obj.__brand === 'Parser';
+};
+/**
+ * Run a simple CLI (no commands).
+ */
+const runSimple = (state, args, allowAsync) => {
+    const { globalParser } = state;
+    const optionsSchema = globalParser?.__optionsSchema ?? {};
+    const positionalsSchema = globalParser?.__positionalsSchema ?? [];
+    const parsed = parseSimple({
+        args,
+        options: optionsSchema,
+        positionals: positionalsSchema,
+    });
+    let result = {
+        positionals: parsed.positionals,
+        values: parsed.values,
+    };
+    // Apply transforms if any
+    const transform = globalParser?.__transform;
+    if (transform) {
+        const transformed = transform(result);
+        if (transformed instanceof Promise) {
+            if (!allowAsync) {
+                throw new BargsError('Async transform detected. Use parseAsync() instead of parse().');
             }
-            return result;
+            return transformed.then((r) => ({
+                ...r,
+                command: undefined,
+            }));
         }
+        result = transformed;
     }
-    catch (error) {
-        return handleHelpError(error, config, theme);
-    }
-}
+    return { ...result, command: undefined };
+};
+// ═══════════════════════════════════════════════════════════════════════════════
+// PUBLIC API
+// ═══════════════════════════════════════════════════════════════════════════════
 /**
- * Main bargs entry point (async implementation). Awaits all handlers,
- * supporting async handlers.
+ * Run a CLI with commands.
  */
-export async function bargsAsync(config, options) {
-    // Validate config upfront (throws ValidationError if invalid)
-    validateConfig(config);
-    const args = config.args ?? process.argv.slice(2);
-    const theme = options?.theme
-        ? getTheme(options.theme)
-        : getTheme('default');
-    try {
-        handleBuiltinFlags(config, args, theme);
-        // Parse
-        if (hasCommands(config)) {
-            return await parseCommandsAsync({ ...config, args });
+const runWithCommands = (state, args, allowAsync) => {
+    const { commands, defaultCommandName, globalParser } = state;
+    // Find command name (first non-flag argument)
+    const commandIndex = args.findIndex((arg) => !arg.startsWith('-'));
+    const potentialCommandName = commandIndex >= 0 ? args[commandIndex] : undefined;
+    // Check if it's a known command
+    let commandName;
+    let remainingArgs;
+    if (potentialCommandName && commands.has(potentialCommandName)) {
+        // It's a known command - remove it from args
+        commandName = potentialCommandName;
+        remainingArgs = [
+            ...args.slice(0, commandIndex),
+            ...args.slice(commandIndex + 1),
+        ];
+    }
+    else if (defaultCommandName) {
+        // Not a known command, but we have a default - use all args as positionals/options
+        commandName = defaultCommandName;
+        remainingArgs = args;
+    }
+    else if (potentialCommandName) {
+        // Not a known command and no default
+        throw new HelpError(`Unknown command: ${potentialCommandName}`);
+    }
+    else {
+        // No command and no default
+        throw new HelpError('No command specified.');
+    }
+    const commandEntry = commands.get(commandName);
+    if (!commandEntry) {
+        throw new HelpError(`Unknown command: ${commandName}`);
+    }
+    const { cmd } = commandEntry;
+    // Merge global and command options schemas
+    const globalOptionsSchema = globalParser?.__optionsSchema ?? {};
+    const commandOptionsSchema = cmd.__optionsSchema;
+    const mergedOptionsSchema = {
+        ...globalOptionsSchema,
+        ...commandOptionsSchema,
+    };
+    const commandPositionalsSchema = cmd.__positionalsSchema;
+    // Parse with merged schema
+    const parsed = parseSimple({
+        args: remainingArgs,
+        options: mergedOptionsSchema,
+        positionals: commandPositionalsSchema,
+    });
+    let result = {
+        positionals: parsed.positionals,
+        values: parsed.values,
+    };
+    // Helper to check for async and throw if not allowed
+    const checkAsync = (value, context) => {
+        if (value instanceof Promise && !allowAsync) {
+            throw new BargsError(`Async ${context} detected. Use parseAsync() instead of parse().`);
         }
-        else {
-            const parsed = parseSimple({
-                args,
-                options: config.options,
-                positionals: config.positionals,
-            });
-            // Run transforms if present (type-erased in implementation)
-            const transforms = config.transforms;
-            const transformed = transforms
-                ? await runTransforms(transforms, parsed.values, parsed.positionals)
-                : { positionals: parsed.positionals, values: parsed.values };
-            const result = {
-                command: undefined,
-                positionals: transformed.positionals,
-                values: transformed.values,
-            };
-            // Call handler if provided (async)
-            if (config.handler) {
-                await runHandler(config.handler, result);
+    };
+    // Get transforms
+    const globalTransform = globalParser?.__transform;
+    const commandTransform = cmd?.__transform;
+    // Apply transforms and run handler
+    const applyTransformsAndHandle = () => {
+        // Apply global transforms first
+        if (globalTransform) {
+            const transformed = globalTransform(result);
+            checkAsync(transformed, 'global transform');
+            if (transformed instanceof Promise) {
+                return transformed.then((r) => {
+                    result = r;
+                    return continueWithCommandTransform();
+                });
             }
-            return result;
+            result = transformed;
         }
-    }
-    catch (error) {
-        return handleHelpError(error, config, theme);
-    }
-}
+        return continueWithCommandTransform();
+    };
+    const continueWithCommandTransform = () => {
+        // Apply command transforms
+        if (commandTransform) {
+            const transformed = commandTransform(result);
+            checkAsync(transformed, 'command transform');
+            if (transformed instanceof Promise) {
+                return transformed.then((r) => {
+                    result = r;
+                    return runHandler();
+                });
+            }
+            result = transformed;
+        }
+        return runHandler();
+    };
+    const runHandler = () => {
+        const handlerResult = cmd.handler(result);
+        checkAsync(handlerResult, 'handler');
+        if (handlerResult instanceof Promise) {
+            return handlerResult.then(() => ({ ...result, command: commandName }));
+        }
+        return { ...result, command: commandName };
+    };
+    return applyTransformsAndHandle();
+};
+/**
+ * Main bargs namespace.
+ */
+export const bargs = {
+    create,
+};
 //# sourceMappingURL=bargs.js.map