refactor!: remove pipe() function

BREAKING CHANGE: The `pipe()` function has been removed from the public API.

The direct API patterns provide better type inference:
- Parser merging: `positionals(options)` instead of `pipe(options, positionals)`
- Transforms: `map(parser, fn)` instead of `pipe(parser, map(fn))`
- Commands: `.command(name, parser, handler)` instead of `pipe(parser, handle(fn))`

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

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

Author: boneskull

README.md

@@ -545,12 +545,7 @@ const plain = stripAnsi('\x1b[32m--verbose\x1b[0m'); // '--verbose'
 
 ### Low-Level Utilities
 
-The `pipe()` and `handle()` functions are exported for advanced use cases, but they're rarely needed with the standard API:
-
-- **`pipe(a, b, c)`** - General function composition. Mostly superseded by direct parser merging (`positionals(options)`) and `map(parser, fn)`.
-- **`handle(parser, fn)`** - Creates a `Command` from a parser and handler. Mostly superseded by `.command(name, parser, handler)`.
-
-These exist for edge cases where you need to compose functions outside the fluent builder, but the main API covers most use cases with better type inference.
+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)`.
 
 ## Motivation
 

src/bargs.ts

@@ -22,7 +22,7 @@ import { parseSimple } from './parser.js';
 import { defaultTheme, getTheme, type Theme } from './theme.js';
 
 // ═══════════════════════════════════════════════════════════════════════════════
-// PIPE COMBINATOR
+// INTERNAL TYPES
 // ═══════════════════════════════════════════════════════════════════════════════
 
 // Type for commands that may have transforms
@@ -166,55 +166,6 @@ export function map<
     } as Parser<V2, P2> & { __transform: typeof fn };
   };
 }
-/**
- * Compose functions left-to-right.
- */
-export function pipe<A, B>(a: A, ab: (a: A) => B): B;
-export function pipe<A, B, C>(a: A, ab: (a: A) => B, bc: (b: B) => C): C;
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// HANDLE COMBINATOR (TERMINAL)
-// ═══════════════════════════════════════════════════════════════════════════════
-
-export function pipe<A, B, C, D>(
-  a: A,
-  ab: (a: A) => B,
-  bc: (b: B) => C,
-  cd: (c: C) => D,
-): D;
-
-export function pipe<A, B, C, D, E>(
-  a: A,
-  ab: (a: A) => B,
-  bc: (b: B) => C,
-  cd: (c: C) => D,
-  de: (d: D) => E,
-): E;
-
-export function pipe<A, B, C, D, E, F>(
-  a: A,
-  ab: (a: A) => B,
-  bc: (b: B) => C,
-  cd: (c: C) => D,
-  de: (d: D) => E,
-  ef: (e: E) => F,
-): F;
-export function pipe<A, B, C, D, E, F, G>(
-  a: A,
-  ab: (a: A) => B,
-  bc: (b: B) => C,
-  cd: (c: C) => D,
-  de: (d: D) => E,
-  ef: (e: E) => F,
-  fg: (f: F) => G,
-): G;
-export function pipe(
-  initial: unknown,
-  ...fns: Array<(arg: unknown) => unknown>
-): unknown {
-  return fns.reduce((acc, fn) => fn(acc), initial);
-}
-
 // ═══════════════════════════════════════════════════════════════════════════════
 // CLI BUILDER
 // ═══════════════════════════════════════════════════════════════════════════════
@@ -225,27 +176,20 @@ export function pipe(
  * @example
  *
  * ```typescript
- * const cli = bargs
+ * const cli = await bargs
  *   .create('my-app', { version: '1.0.0' })
  *   .globals(
- *     pipe(
- *       opt.options({ verbose: opt.boolean() }),
- *       map(({ values }) => ({
- *         values: { ...values, ts: Date.now() },
- *         positionals: [] as const,
- *       })),
- *     ),
+ *     map(opt.options({ verbose: opt.boolean() }), ({ values }) => ({
+ *       values: { ...values, ts: Date.now() },
+ *       positionals: [] as const,
+ *     })),
  *   )
  *   .command(
  *     'greet',
- *     pipe(
- *       pos.positionals(pos.string({ name: 'name', required: true })),
- *       handle(({ positionals }) =>
- *         console.log(`Hello, ${positionals[0]}!`),
- *       ),
- *     ),
+ *     pos.positionals(pos.string({ name: 'name', required: true })),
+ *     ({ positionals }) => console.log(`Hello, ${positionals[0]}!`),
  *   )
- *   .run();
+ *   .parseAsync();
  * ```
  */
 const create = (

src/index.ts

@@ -1,24 +1,20 @@
 /**
  * Main entry point for the bargs CLI argument parser.
  *
- * Provides a parser combinator-inspired API for building type-safe CLIs.
+ * Provides a combinator-style API for building type-safe CLIs.
  *
  * @example
  *
  * ```typescript
- * import { bargs, opt, pos, pipe, map, handle } from '@boneskull/bargs';
+ * import { bargs, opt, pos } from '@boneskull/bargs';
  *
- * const cli = bargs
+ * await bargs
  *   .create('my-app', { version: '1.0.0' })
  *   .globals(opt.options({ verbose: opt.boolean({ aliases: ['v'] }) }))
  *   .command(
  *     'greet',
- *     pipe(
- *       pos.positionals(pos.string({ name: 'name', required: true })),
- *       handle(({ positionals }) =>
- *         console.log(`Hello, ${positionals[0]}!`),
- *       ),
- *     ),
+ *     pos.positionals(pos.string({ name: 'name', required: true })),
+ *     ({ positionals }) => console.log(`Hello, ${positionals[0]}!`),
  *     'Say hello',
  *   )
  *   .parseAsync();
@@ -28,7 +24,7 @@
  */
 
 // Main API
-export { bargs, handle, map, pipe } from './bargs.js';
+export { bargs, handle, map } from './bargs.js';
 
 // Errors
 export { BargsError, HelpError, ValidationError } from './errors.js';

src/opt.ts

@@ -69,11 +69,11 @@ type CallableOptionsParser<V> = (<V2, P2 extends readonly unknown[]>(
  * Create a Parser from an options schema that can also merge with existing
  * parsers.
  *
- * Supports two usage patterns in pipe():
+ * Supports two usage patterns:
  *
- * 1. As first arg: `pipe(opt.options(...), ...)` - used as Parser directly
- * 2. As later arg: `pipe(pos.positionals(...), opt.options(...), ...)` - called to
- *    merge
+ * 1. Standalone: `opt.options({ ... })` - returns a Parser
+ * 2. Merging: `pos.positionals(...)(opt.options(...))` - merges positionals into
+ *    options
  */
 const optionsImpl = <T extends OptionsSchema>(
   schema: T,
@@ -310,11 +310,11 @@ type EmptyObject = {};
  * Create a Parser from positional definitions that can also merge with existing
  * parsers.
  *
- * Supports two usage patterns in pipe():
+ * Supports two usage patterns:
  *
- * 1. As first arg: `pipe(pos.positionals(...), ...)` - used as Parser directly
- * 2. As later arg: `pipe(opt.options(...), pos.positionals(...), ...)` - called to
- *    merge
+ * 1. Standalone: `pos.positionals(...)` - returns a Parser
+ * 2. Merging: `pos.positionals(...)(opt.options(...))` - merges positionals into
+ *    options
  */
 const positionalsImpl = <T extends PositionalsSchema>(
   ...positionals: T

test/bargs.test.ts

@@ -6,7 +6,7 @@ import { describe, it } from 'node:test';
 
 import type { StringOption } from '../src/types.js';
 
-import { bargs, handle, map, pipe } from '../src/bargs.js';
+import { bargs, handle, map } from '../src/bargs.js';
 import { opt, pos } from '../src/opt.js';
 
 describe('bargs.create()', () => {
@@ -52,10 +52,7 @@ describe('.command()', () => {
   it('registers a command', () => {
     const cli = bargs.create('test-cli').command(
       'greet',
-      pipe(
-        opt.options({ name: opt.string({ default: 'world' }) }),
-        handle(() => {}),
-      ),
+      handle(opt.options({ name: opt.string({ default: 'world' }) }), () => {}),
     );
 
     expect(cli, 'to be defined');
@@ -64,10 +61,7 @@ describe('.command()', () => {
   it('accepts description as third argument', () => {
     const cli = bargs.create('test-cli').command(
       'greet',
-      pipe(
-        opt.options({}),
-        handle(() => {}),
-      ),
+      handle(opt.options({}), () => {}),
       'Greet someone',
     );
 
@@ -139,13 +133,11 @@ describe('.parseAsync()', () => {
 
     const cli = bargs.create('test-cli').command(
       'greet',
-      pipe(
-        opt.options({ name: opt.string({ default: 'world' }) }),
-        handle(({ values }) => {
-          handlerCalled = true;
-          handlerResult = values;
-        }),
-      ),
+      opt.options({ name: opt.string({ default: 'world' }) }),
+      ({ values }) => {
+        handlerCalled = true;
+        handlerResult = values;
+      },
       'Greet someone',
     );
 
@@ -163,12 +155,10 @@ describe('.parseAsync()', () => {
       .globals(opt.options({ verbose: opt.boolean({ default: false }) }))
       .command(
         'greet',
-        pipe(
-          opt.options({ name: opt.string({ default: 'world' }) }),
-          handle(({ values }) => {
-            handlerResult = values;
-          }),
-        ),
+        opt.options({ name: opt.string({ default: 'world' }) }),
+        ({ values }) => {
+          handlerResult = values;
+        },
       );
 
     await cli.parseAsync(['greet', '--verbose', '--name', 'Bob']);
@@ -211,13 +201,13 @@ describe('.parseAsync()', () => {
   });
 
   it('returns parsed result with command name', async () => {
-    const cli = bargs.create('test-cli').command(
-      'greet',
-      pipe(
+    const cli = bargs
+      .create('test-cli')
+      .command(
+        'greet',
         opt.options({ name: opt.string({ default: 'world' }) }),
-        handle(() => {}),
-      ),
-    );
+        () => {},
+      );
 
     const result = await cli.parseAsync(['greet', '--name', 'Test']);
 
@@ -233,20 +223,17 @@ describe('transforms via map()', () => {
     const cli = bargs
       .create('test-cli')
       .globals(
-        pipe(
+        map(
           opt.options({ name: opt.string({ default: 'world' }) }),
-          map(({ values }) => ({
+          ({ values }) => ({
             positionals: [] as const,
             values: { ...values, greeting: `Hello, ${values.name}!` },
-          })),
+          }),
         ),
       )
-      .command(
-        'greet',
-        handle(opt.options({}), ({ values }) => {
-          handlerResult = values;
-        }),
-      );
+      .command('greet', opt.options({}), ({ values }) => {
+        handlerResult = values;
+      });
 
     await cli.parseAsync(['greet', '--name', 'Alice']);
 
@@ -350,15 +337,15 @@ describe('positionals', () => {
   it('parses positional arguments', async () => {
     let handlerResult: unknown;
 
-    const cli = bargs.create('test-cli').command(
-      'echo',
-      pipe(
+    const cli = bargs
+      .create('test-cli')
+      .command(
+        'echo',
         pos.positionals(pos.string({ name: 'message', required: true })),
-        handle(({ positionals }) => {
+        ({ positionals }) => {
           handlerResult = positionals;
-        }),
-      ),
-    );
+        },
+      );
 
     await cli.parseAsync(['echo', 'Hello, world!']);
 
@@ -368,18 +355,18 @@ describe('positionals', () => {
   it('handles multiple positionals', async () => {
     let handlerResult: unknown;
 
-    const cli = bargs.create('test-cli').command(
-      'copy',
-      pipe(
+    const cli = bargs
+      .create('test-cli')
+      .command(
+        'copy',
         pos.positionals(
           pos.string({ name: 'source', required: true }),
           pos.string({ name: 'dest', required: true }),
         ),
-        handle(({ positionals }) => {
+        ({ positionals }) => {
           handlerResult = positionals;
-        }),
-      ),
-    );
+        },
+      );
 
     await cli.parseAsync(['copy', 'src.txt', 'dst.txt']);
 
@@ -389,15 +376,15 @@ describe('positionals', () => {
   it('handles variadic positionals', async () => {
     let handlerResult: unknown;
 
-    const cli = bargs.create('test-cli').command(
-      'concat',
-      pipe(
+    const cli = bargs
+      .create('test-cli')
+      .command(
+        'concat',
         pos.positionals(pos.variadic('string', { name: 'files' })),
-        handle(({ positionals }) => {
+        ({ positionals }) => {
           handlerResult = positionals;
-        }),
-      ),
-    );
+        },
+      );
 
     await cli.parseAsync(['concat', 'a.txt', 'b.txt', 'c.txt']);