feat!: add merge() combinator for combining parsers

Adds a new merge() function that combines multiple parsers into one,
providing a cleaner alternative to the callable parser syntax:

  // With merge() - linear, readable
  merge(
    opt.options({ priority: opt.enum(['low', 'medium', 'high']) }),
    pos.positionals(pos.string({ name: 'task' })),
  )

  // Callable syntax - inside-out, confusing )(
  pos.positionals(...)(opt.options(...))

The merge() function:
- Accepts 2-4 parsers (with overloads for type safety)
- Merges option schemas (later overrides earlier)
- Concatenates positional schemas
- Chains transforms from merged parsers

Updated README to document merge() and use it in examples.

BREAKING CHANGE: none, additive only

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: boneskull

README.md

@@ -122,16 +122,12 @@ const text = words.join(' ');
 console.log(values.uppercase ? text.toUpperCase() : text);
 ```
 
-### Zero (0) Dependencies
-
-Only Node.js v22+.
-
 ### Command-Based CLI
 
 For a CLI with multiple subcommands:
 
 ```typescript
-import { bargs, opt, pos } from '@boneskull/bargs';
+import { bargs, merge, opt, pos } from '@boneskull/bargs';
 
 await bargs
   .create('tasks', {
@@ -145,10 +141,16 @@ await bargs
   )
   .command(
     'add',
-    pos.positionals(pos.string({ name: 'text', required: true })),
+    // Use merge() to combine positionals with command-specific options
+    merge(
+      opt.options({
+        priority: opt.enum(['low', 'medium', 'high'], { default: 'medium' }),
+      }),
+      pos.positionals(pos.string({ name: 'text', required: true })),
+    ),
     ({ positionals, values }) => {
       const [text] = positionals;
-      console.log(`Adding task: ${text}`);
+      console.log(`Adding ${values.priority} priority task: ${text}`);
       if (values.verbose) console.log('Verbose mode enabled');
     },
     'Add a task',
@@ -168,8 +170,8 @@ await bargs
 ```
 
 ```shell
-$ tasks add "Buy groceries" --verbose
-Adding task: Buy groceries
+$ tasks add "Buy groceries" --priority high --verbose
+Adding high priority task: Buy groceries
 Verbose mode enabled
 
 $ tasks list --all
@@ -322,23 +324,36 @@ const parser = pos.positionals(pos.variadic('string', { name: 'files' }));
 
 ## Merging Parsers
 
-Options and positionals parsers can be merged by calling one with the other:
+Use `merge()` to combine multiple parsers into one:
 
 ```typescript
-const options = opt.options({
-  priority: opt.enum(['low', 'medium', 'high'] as const, { default: 'medium' }),
-});
+import { merge, opt, pos } from '@boneskull/bargs';
+
+const combined = merge(
+  opt.options({
+    priority: opt.enum(['low', 'medium', 'high'], { default: 'medium' }),
+  }),
+  pos.positionals(pos.string({ name: 'task', required: true })),
+);
+// Type: Parser<{ priority: 'low' | 'medium' | 'high' }, [string]>
+```
+
+You can merge as many parsers as needed—options are merged (later overrides earlier), and positionals are concatenated.
 
+Alternatively, parsers can be merged by calling one with the other:
+
+```typescript
+const options = opt.options({ priority: opt.enum(['low', 'medium', 'high']) });
 const positionals = pos.positionals(
   pos.string({ name: 'task', required: true }),
 );
 
-// Merge: call positionals with options
-const combined = positionals(options);
-// Type: Parser<{ priority: 'low' | 'medium' | 'high' }, [string]>
+// These are equivalent:
+const combined1 = positionals(options);
+const combined2 = options(positionals);
 ```
 
-This works in either direction—`options(positionals)` or `positionals(options)`.
+Use whichever style you find more readable.
 
 ## Transforms
 
@@ -481,10 +496,12 @@ try {
 } catch (error) {
   if (error instanceof ValidationError) {
     // Config validation failed (e.g., invalid schema)
+    // i.e., "you screwed up"
     console.error(`Config error at "${error.path}": ${error.message}`);
   } else if (error instanceof HelpError) {
-    // User needs guidance (e.g., unknown option)
-    console.error(error.message);
+    // Likely invalid options, command or positionals;
+    // re-throw to trigger help display
+    throw error;
   } else if (error instanceof BargsError) {
     // General bargs error
     console.error(error.message);
@@ -547,6 +564,10 @@ const plain = stripAnsi('\x1b[32m--verbose\x1b[0m'); // '--verbose'
 
 The `handle(parser, fn)` function is exported for advanced use cases where you need to create a `Command` object outside the fluent builder. It's mostly superseded by `.command(name, parser, handler)`.
 
+## Dependencies
+
+**bargs** has zero (0) dependencies. Only Node.js v22+.
+
 ## Motivation
 
 I've always reached for [yargs](https://github.com/yargs/yargs) in my CLI projects. However, I find myself repeatedly doing the same things; I have a sort of boilerplate in my head, ready to go (`requiresArg: true` and `nargs: 1`, amirite?). I don't want boilerplate in my head. I wanted to distill my chosen subset of yargs' behavior into a composable API. And so **bargs** was begat.

examples/tasks.ts

@@ -50,7 +50,7 @@ const globalOptions = opt.options({
 // Add command parser: priority option + text positional
 // First create options, then merge with positionals
 const addOptions = opt.options({
-  priority: opt.enum(['low', 'medium', 'high'] as const, { default: 'medium' }),
+  priority: opt.enum(['low', 'medium', 'high'], { default: 'medium' }),
 });
 const addPositionals = pos.positionals(
   pos.string({ name: 'text', required: true }),

src/bargs.ts

@@ -59,16 +59,23 @@ type TransformFn<
 > = (
   result: ParseResult<V1, P1>,
 ) => ParseResult<V2, P2> | Promise<ParseResult<V2, P2>>;
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// MERGE COMBINATOR
+// ═══════════════════════════════════════════════════════════════════════════════
+
 /**
  * Create a command with a handler (terminal in the pipeline).
  */
 export function handle<V, P extends readonly unknown[]>(
   fn: HandlerFn<V, P>,
 ): (parser: Parser<V, P>) => Command<V, P>;
+
 export function handle<V, P extends readonly unknown[]>(
   parser: Parser<V, P>,
   fn: HandlerFn<V, P>,
 ): Command<V, P>;
+
 export function handle<V, P extends readonly unknown[]>(
   parserOrFn: HandlerFn<V, P> | Parser<V, P>,
   maybeFn?: HandlerFn<V, P>,
@@ -120,17 +127,12 @@ export function map<
   P2 extends readonly unknown[],
 >(fn: TransformFn<V1, P1, V2, P2>): (parser: Parser<V1, P1>) => Parser<V2, P2>;
 
-// ═══════════════════════════════════════════════════════════════════════════════
-// MAP COMBINATOR
-// ═══════════════════════════════════════════════════════════════════════════════
-
 export function map<
   V1,
   P1 extends readonly unknown[],
   V2,
   P2 extends readonly unknown[],
 >(parser: Parser<V1, P1>, fn: TransformFn<V1, P1, V2, P2>): Parser<V2, P2>;
-
 export function map<
   V1,
   P1 extends readonly unknown[],
@@ -166,6 +168,132 @@ export function map<
     } as Parser<V2, P2> & { __transform: typeof fn };
   };
 }
+/**
+ * Merge multiple parsers into one.
+ *
+ * Combines options and positionals from all parsers. Later parsers' options
+ * override earlier ones if there are conflicts.
+ *
+ * @example
+ *
+ * ```typescript
+ * const parser = merge(
+ *   opt.options({ verbose: opt.boolean() }),
+ *   pos.positionals(pos.string({ name: 'file', required: true })),
+ * );
+ * ```
+ */
+export function merge<
+  V1,
+  P1 extends readonly unknown[],
+  V2,
+  P2 extends readonly unknown[],
+>(
+  p1: Parser<V1, P1>,
+  p2: Parser<V2, P2>,
+): Parser<V1 & V2, readonly [...P1, ...P2]>;
+
+export function merge<
+  V1,
+  P1 extends readonly unknown[],
+  V2,
+  P2 extends readonly unknown[],
+  V3,
+  P3 extends readonly unknown[],
+>(
+  p1: Parser<V1, P1>,
+  p2: Parser<V2, P2>,
+  p3: Parser<V3, P3>,
+): Parser<V1 & V2 & V3, readonly [...P1, ...P2, ...P3]>;
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// MAP COMBINATOR
+// ═══════════════════════════════════════════════════════════════════════════════
+
+export function merge<
+  V1,
+  P1 extends readonly unknown[],
+  V2,
+  P2 extends readonly unknown[],
+  V3,
+  P3 extends readonly unknown[],
+  V4,
+  P4 extends readonly unknown[],
+>(
+  p1: Parser<V1, P1>,
+  p2: Parser<V2, P2>,
+  p3: Parser<V3, P3>,
+  p4: Parser<V4, P4>,
+): Parser<V1 & V2 & V3 & V4, readonly [...P1, ...P2, ...P3, ...P4]>;
+
+export function merge(
+  ...parsers: Array<Parser<unknown, readonly unknown[]>>
+): Parser<unknown, readonly unknown[]> {
+  if (parsers.length === 0) {
+    throw new BargsError('merge() requires at least one parser');
+  }
+
+  // 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,
+    ];
+
+    // Preserve transforms from both parsers (chain them)
+    type AsyncTransform = (
+      r: ParseResult<unknown, readonly unknown[]>,
+    ) =>
+      | ParseResult<unknown, readonly unknown[]>
+      | Promise<ParseResult<unknown, readonly unknown[]>>;
+
+    const resultWithTransform = result as { __transform?: AsyncTransform };
+    const nextWithTransform = next as { __transform?: AsyncTransform };
+
+    let mergedTransform: AsyncTransform | undefined;
+    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: [] as unknown as readonly unknown[],
+      __positionalsSchema: mergedPositionals,
+      __values: {} as unknown,
+    };
+
+    if (mergedTransform) {
+      (result as { __transform?: AsyncTransform }).__transform =
+        mergedTransform;
+    }
+  }
+
+  return result;
+}
 // ═══════════════════════════════════════════════════════════════════════════════
 // CLI BUILDER
 // ═══════════════════════════════════════════════════════════════════════════════

src/index.ts

@@ -24,7 +24,7 @@
  */
 
 // Main API
-export { bargs, handle, map } from './bargs.js';
+export { bargs, handle, map, merge } from './bargs.js';
 
 // Errors
 export { BargsError, HelpError, ValidationError } from './errors.js';

test/combinators.test.ts

@@ -1,12 +1,63 @@
 /**
- * Tests for parser combinators: map, handle.
+ * Tests for parser combinators: merge, map, handle.
  */
 import { expect } from 'bupkis';
 import { describe, it } from 'node:test';
 
-import { handle, map } from '../src/bargs.js';
+import { handle, map, merge } from '../src/bargs.js';
 import { opt, pos } from '../src/opt.js';
 
+describe('merge()', () => {
+  it('merges two parsers', () => {
+    const parser = merge(
+      opt.options({ verbose: opt.boolean() }),
+      pos.positionals(pos.string({ name: 'file', required: true })),
+    );
+
+    expect(parser.__brand, 'to be', 'Parser');
+    expect(parser.__optionsSchema, 'to satisfy', {
+      verbose: { type: 'boolean' },
+    });
+    expect(parser.__positionalsSchema, 'to satisfy', [
+      { name: 'file', type: 'string' },
+    ]);
+  });
+
+  it('merges three parsers', () => {
+    const parser = merge(
+      opt.options({ verbose: opt.boolean() }),
+      opt.options({ output: opt.string() }),
+      pos.positionals(pos.string({ name: 'input' })),
+    );
+
+    expect(parser.__brand, 'to be', 'Parser');
+    expect(parser.__optionsSchema, 'to satisfy', {
+      output: { type: 'string' },
+      verbose: { type: 'boolean' },
+    });
+  });
+
+  it('later options override earlier ones', () => {
+    const parser = merge(
+      opt.options({ name: opt.string({ default: 'first' }) }),
+      opt.options({ name: opt.string({ default: 'second' }) }),
+    );
+
+    expect(parser.__optionsSchema.name?.default, 'to be', 'second');
+  });
+
+  it('concatenates positionals', () => {
+    const parser = merge(
+      pos.positionals(pos.string({ name: 'a' })),
+      pos.positionals(pos.string({ name: 'b' })),
+    );
+
+    expect(parser.__positionalsSchema, 'to have length', 2);
+    expect(parser.__positionalsSchema[0]?.name, 'to be', 'a');
+    expect(parser.__positionalsSchema[1]?.name, 'to be', 'b');
+  });
+});
+
 describe('map()', () => {
   describe('curried form', () => {
     it('returns a function that transforms a parser', () => {