@boneskull/bargs 3.2.0 → 3.4.0

package/README.md

@@ -27,8 +27,7 @@ A CLI with an optional command and a couple options:
 ```typescript
 import { bargs, opt, pos } from '@boneskull/bargs';
 
-await bargs
-  .create('greet', { version: '1.0.0' })
+await bargs('greet', { version: '1.0.0' })
   .globals(
     opt.options({
       name: opt.string({ default: 'world' }),
@@ -112,11 +111,10 @@ const parser = pos.positionals(pos.variadic('string', { name: 'text' }))(
   }),
 );
 
-const { values, positionals } = await bargs
-  .create('echo', {
-    description: 'Echo text to stdout',
-    version: '1.0.0',
-  })
+const { values, positionals } = await bargs('echo', {
+  description: 'Echo text to stdout',
+  version: '1.0.0',
+})
   .globals(parser)
   .parseAsync();
 
@@ -132,11 +130,10 @@ For a CLI with multiple subcommands:
 ```typescript
 import { bargs, merge, opt, pos } from '@boneskull/bargs';
 
-await bargs
-  .create('tasks', {
-    description: 'A task manager',
-    version: '1.0.0',
-  })
+await bargs('tasks', {
+  description: 'A task manager',
+  version: '1.0.0',
+})
   .globals(
     opt.options({
       verbose: opt.boolean({ aliases: ['v'], default: false }),
@@ -183,36 +180,36 @@ All tasks
 
 ### Nested Commands (Subcommands)
 
-Commands can be nested to arbitrary depth by passing a `CliBuilder` as the second argument to `.command()`:
+Commands can be nested to arbitrary depth. Use the **factory pattern** for full type inference of parent globals:
 
 ```typescript
 import { bargs, opt, pos } from '@boneskull/bargs';
 
-// Define subcommands as a separate builder
-const remoteCommands = bargs
-  .create('remote')
+await bargs('git')
+  .globals(opt.options({ verbose: opt.boolean({ aliases: ['v'] }) }))
+  // Factory pattern: receives a builder with parent globals already typed
   .command(
-    'add',
-    pos.positionals(
-      pos.string({ name: 'name', required: true }),
-      pos.string({ name: 'url', required: true }),
-    ),
-    ({ positionals, values }) => {
-      const [name, url] = positionals;
-      // Parent globals (verbose) are available here!
-      if (values.verbose) console.log(`Adding ${name}: ${url}`);
-    },
-    'Add a remote',
+    'remote',
+    (remote) =>
+      remote
+        .command(
+          'add',
+          pos.positionals(
+            pos.string({ name: 'name', required: true }),
+            pos.string({ name: 'url', required: true }),
+          ),
+          ({ positionals, values }) => {
+            const [name, url] = positionals;
+            // values.verbose is fully typed! (from parent globals)
+            if (values.verbose) console.log(`Adding ${name}: ${url}`);
+          },
+          'Add a remote',
+        )
+        .command('remove' /* ... */)
+        .defaultCommand('add'),
+    'Manage remotes',
   )
-  .command('remove' /* ... */)
-  .defaultCommand('add');
-
-// Nest under parent CLI
-await bargs
-  .create('git')
-  .globals(opt.options({ verbose: opt.boolean({ aliases: ['v'] }) }))
-  .command('remote', remoteCommands, 'Manage remotes') // ← CliBuilder
-  .command('commit', commitParser, commitHandler) // ← Regular command
+  .command('commit', commitParser, commitHandler) // Regular command
   .parseAsync();
 ```
 
@@ -223,11 +220,13 @@ Adding origin: https://github.com/...
 $ git remote remove origin
 ```
 
-Parent globals automatically flow to nested command handlers. You can nest as deep as you like—just nest `CliBuilder`s inside `CliBuilder`s. See `examples/nested-commands.ts` for a full example.
+The factory function receives a `CliBuilder` that already has parent globals typed, so all nested command handlers get full type inference for merged `global + command` options.
+
+You can also pass a pre-built `CliBuilder` directly (see [.command(name, cliBuilder)](#commandname-clibuilder-description)), but handlers won't have parent globals typed at compile time. See `examples/nested-commands.ts` for a full example.
 
 ## API
 
-### bargs.create(name, options?)
+### bargs(name, options?)
 
 Create a CLI builder.
 
@@ -243,7 +242,7 @@ Create a CLI builder.
 Set global options and transforms that apply to all commands.
 
 ```typescript
-bargs.create('my-cli').globals(opt.options({ verbose: opt.boolean() }));
+bargs('my-cli').globals(opt.options({ verbose: opt.boolean() }));
 // ...
 ```
 
@@ -265,12 +264,12 @@ Register a command. The handler receives merged global + command types.
 
 ### .command(name, cliBuilder, description?)
 
-Register a nested command group. The `cliBuilder` is another `CliBuilder` whose commands become subcommands. Parent globals are passed down to nested handlers.
+Register a nested command group. The `cliBuilder` is another `CliBuilder` whose commands become subcommands. Parent globals are passed down to nested handlers at runtime, but **handlers won't have parent globals typed** at compile time.
 
 ```typescript
-const subCommands = bargs.create('sub').command('foo', ...).command('bar', ...);
+const subCommands = bargs('sub').command('foo', ...).command('bar', ...);
 
-bargs.create('main')
+bargs('main')
   .command('nested', subCommands, 'Nested commands')  // nested group
   .parseAsync();
 
@@ -278,6 +277,26 @@ bargs.create('main')
 // $ main nested bar
 ```
 
+### .command(name, factory, description?)
+
+Register a nested command group using a factory function. **This is the recommended form** because the factory receives a builder that already has parent globals typed, giving full type inference in nested handlers.
+
+```typescript
+bargs('main')
+  .globals(opt.options({ verbose: opt.boolean() }))
+  .command(
+    'nested',
+    (nested) =>
+      nested
+        .command('foo', fooParser, ({ values }) => {
+          // values.verbose is typed correctly!
+        })
+        .command('bar', barParser, barHandler),
+    'Nested commands',
+  )
+  .parseAsync();
+```
+
 ### .defaultCommand(name)
 
 > Or `.defaultCommand(parser, handler)`
@@ -304,11 +323,11 @@ Parse arguments and execute handlers.
 
 ```typescript
 // Async (supports async transforms/handlers)
-const result = await bargs.create('my-cli').globals(...).parseAsync();
+const result = await bargs('my-cli').globals(...).parseAsync();
 console.log(result.values, result.positionals, result.command);
 
 // Sync (no async transforms/handlers)
-const result = bargs.create('my-cli').globals(...).parse();
+const result = bargs('my-cli').globals(...).parse();
 ```
 
 ## Option Helpers
@@ -336,6 +355,32 @@ opt.count(); // -vvv → 3
 | `hidden`      | `boolean`  | Hide from `--help` output                        |
 | `required`    | `boolean`  | Mark as required (makes the option non-nullable) |
 
+### Boolean Negation (`--no-<flag>`)
+
+All boolean options automatically support a negated form `--no-<flag>` to explicitly set the option to `false`:
+
+```shell
+$ my-cli --verbose      # verbose: true
+$ my-cli --no-verbose   # verbose: false
+$ my-cli                # verbose: undefined (or default)
+```
+
+If both `--flag` and `--no-flag` are specified, bargs throws an error:
+
+```shell
+$ my-cli --verbose --no-verbose
+Error: Conflicting options: --verbose and --no-verbose cannot both be specified
+```
+
+In help output, booleans with `default: true` display as `--no-<flag>` (since that's how users would turn them off):
+
+```typescript
+opt.options({
+  colors: opt.boolean({ default: true, description: 'Use colors' }),
+});
+// Help output shows: --no-colors  Use colors  [boolean] default: true
+```
+
 ### `opt.options(schema)`
 
 Create a parser from an options schema:
@@ -443,8 +488,7 @@ const globals = map(
   }),
 );
 
-await bargs
-  .create('my-cli')
+await bargs('my-cli')
   .globals(globals)
   .command(
     'info',
@@ -480,18 +524,47 @@ const globals = map(
 );
 ```
 
+### CamelCase Option Keys
+
+If you prefer camelCase property names instead of kebab-case, use the `camelCaseValues` transform:
+
+```typescript
+import { bargs, map, opt, camelCaseValues } from '@boneskull/bargs';
+
+const { values } = await bargs('my-cli')
+  .globals(
+    map(
+      opt.options({
+        'output-dir': opt.string({ default: '/tmp' }),
+        'dry-run': opt.boolean(),
+      }),
+      camelCaseValues,
+    ),
+  )
+  .parseAsync(['--output-dir', './dist', '--dry-run']);
+
+console.log(values.outputDir); // './dist'
+console.log(values.dryRun); // true
+```
+
+The `camelCaseValues` transform:
+
+- Converts all kebab-case keys to camelCase (`output-dir` → `outputDir`)
+- Preserves keys that are already camelCase or have no hyphens
+- Is fully type-safe—TypeScript knows the transformed key names
+
 ## Epilog
 
 By default, **bargs** displays your package's homepage and repository URLs (from `package.json`) at the end of help output. URLs become clickable hyperlinks in supported terminals.
 
 ```typescript
 // Custom epilog
-bargs.create('my-cli', {
+bargs('my-cli', {
   epilog: 'For more info, visit https://example.com',
 });
 
 // Disable epilog entirely
-bargs.create('my-cli', { epilog: false });
+bargs('my-cli', { epilog: false });
 ```
 
 ## Theming
@@ -500,10 +573,10 @@ Customize help output colors with built-in themes or your own:
 
 ```typescript
 // Use a built-in theme: 'default', 'mono', 'ocean', 'warm'
-bargs.create('my-cli', { theme: 'ocean' });
+bargs('my-cli', { theme: 'ocean' });
 
 // Disable colors entirely
-bargs.create('my-cli', { theme: 'mono' });
+bargs('my-cli', { theme: 'mono' });
 ```
 
 The `ansi` export provides common ANSI escape codes for styled terminal output:
@@ -511,7 +584,7 @@ The `ansi` export provides common ANSI escape codes for styled terminal output:
 ```typescript
 import { ansi } from '@boneskull/bargs';
 
-bargs.create('my-cli', {
+bargs('my-cli', {
   theme: {
     command: ansi.bold,
     flag: ansi.brightCyan,
@@ -557,7 +630,7 @@ import {
 } from '@boneskull/bargs';
 
 try {
-  await bargs.create('my-cli').parseAsync();
+  await bargs('my-cli').parseAsync();
 } catch (error) {
   if (error instanceof ValidationError) {
     // Config validation failed (e.g., invalid schema)

package/dist/bargs.cjs

@@ -2,13 +2,13 @@
 /**
  * Core bargs API using parser combinator pattern.
  *
- * Provides `bargs.create()` for building CLIs with a fluent API, plus
- * combinator functions like `pipe()`, `map()`, and `handle()`.
+ * Provides `bargs()` for building CLIs with a fluent API, plus combinator
+ * functions like `pipe()`, `map()`, and `handle()`.
  *
  * @packageDocumentation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.bargs = void 0;
+exports.bargs = exports.camelCaseValues = void 0;
 exports.handle = handle;
 exports.map = map;
 exports.merge = merge;
@@ -53,27 +53,47 @@ function handle(parserOrFn, maybeFn) {
     };
 }
 function map(parserOrFn, maybeFn) {
+    // Helper to compose transforms (chains existing + new)
+    /**
+     * @function
+     */
+    const composeTransform = (parser, fn) => {
+        const existing = parser.__transform;
+        if (!existing) {
+            return fn;
+        }
+        // Chain: existing transform first, then new transform
+        return (r) => {
+            const r1 = existing(r);
+            if (r1 instanceof Promise) {
+                return r1.then(fn);
+            }
+            return fn(r1);
+        };
+    };
     // 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;
+        const composedTransform = composeTransform(parser, fn);
         return {
             ...parser,
             __brand: 'Parser',
             __positionals: [],
-            __transform: fn,
+            __transform: composedTransform,
             __values: {},
         };
     }
     // Curried form: map(fn) returns (parser) => Parser
     const fn = parserOrFn;
     return (parser) => {
+        const composedTransform = composeTransform(parser, fn);
         return {
             ...parser,
             __brand: 'Parser',
             __positionals: [],
-            __transform: fn,
+            __transform: composedTransform,
             __values: {},
         };
     };
@@ -130,6 +150,43 @@ function merge(...parsers) {
     return result;
 }
 // ═══════════════════════════════════════════════════════════════════════════════
+// CAMEL CASE HELPER
+// ═══════════════════════════════════════════════════════════════════════════════
+/**
+ * Convert kebab-case string to camelCase.
+ *
+ * @function
+ */
+const kebabToCamel = (s) => s.replace(/-([a-zA-Z])/g, (_, c) => c.toUpperCase());
+/**
+ * Transform for use with `map()` that converts kebab-case option keys to
+ * camelCase.
+ *
+ * @example
+ *
+ * ```typescript
+ * import { bargs, opt, map, camelCaseValues } from '@boneskull/bargs';
+ *
+ * const { values } = await bargs('my-cli')
+ *   .globals(
+ *     map(opt.options({ 'output-dir': opt.string() }), camelCaseValues),
+ *   )
+ *   .parseAsync();
+ *
+ * console.log(values.outputDir); // camelCased!
+ * ```
+ *
+ * @function
+ */
+const camelCaseValues = (result) => ({
+    ...result,
+    values: Object.fromEntries(Object.entries(result.values).map(([k, v]) => [
+        kebabToCamel(k),
+        v,
+    ])),
+});
+exports.camelCaseValues = camelCaseValues;
+// ═══════════════════════════════════════════════════════════════════════════════
 // CLI BUILDER
 // ═══════════════════════════════════════════════════════════════════════════════
 /**
@@ -138,8 +195,7 @@ function merge(...parsers) {
  * @example
  *
  * ```typescript
- * const cli = await bargs
- *   .create('my-app', { version: '1.0.0' })
+ * const cli = await bargs('my-app', { version: '1.0.0' })
  *   .globals(
  *     map(opt.options({ verbose: opt.boolean() }), ({ values }) => ({
  *       values: { ...values, ts: Date.now() },
@@ -153,8 +209,10 @@ function merge(...parsers) {
  *   )
  *   .parseAsync();
  * ```
+ *
+ * @function
  */
-const create = (name, options = {}) => {
+const bargs = (name, options = {}) => {
     const theme = options.theme ? (0, theme_js_1.getTheme)(options.theme) : theme_js_1.defaultTheme;
     return createCliBuilder({
         commands: new Map(),
@@ -163,8 +221,11 @@ const create = (name, options = {}) => {
         theme,
     });
 };
+exports.bargs = bargs;
 /**
  * Check if something is a Command (has __brand: 'Command').
+ *
+ * @function
  */
 const isCommand = (x) => {
     if (x === null || x === undefined) {
@@ -175,6 +236,8 @@ const isCommand = (x) => {
 };
 /**
  * Create a CLI builder.
+ *
+ * @function
  */
 const createCliBuilder = (state) => {
     const builder = {
@@ -183,11 +246,39 @@ const createCliBuilder = (state) => {
             const stateWithGlobals = { ...state, parentGlobals };
             return parseCore(stateWithGlobals, args, allowAsync);
         },
-        // Overloaded command(): accepts (name, Command, desc?), (name, Parser, handler, desc?), or (name, CliBuilder, desc?)
-        command(name, cmdOrParserOrBuilder, handlerOrDesc, maybeDesc) {
+        // Overloaded command(): accepts (name, factory, desc?), (name, CliBuilder, desc?),
+        // (name, Command, desc?), or (name, Parser, handler, desc?)
+        command(name, cmdOrParserOrBuilderOrFactory, handlerOrDesc, maybeDesc) {
+            // Form 4: command(name, factory, description?) - factory for nested commands with parent globals
+            // Check this FIRST before isCliBuilder/isParser since those check for __brand which a plain function won't have
+            if (typeof cmdOrParserOrBuilderOrFactory === 'function' &&
+                !isParser(cmdOrParserOrBuilderOrFactory) &&
+                !isCommand(cmdOrParserOrBuilderOrFactory) &&
+                !isCliBuilder(cmdOrParserOrBuilderOrFactory)) {
+                const factory = cmdOrParserOrBuilderOrFactory;
+                const description = handlerOrDesc;
+                // Create a child builder with parent global TYPES (for type inference)
+                // but NOT the globalParser (parent globals are passed via parentGlobals at runtime,
+                // not re-parsed from args)
+                const childBuilder = createCliBuilder({
+                    commands: new Map(),
+                    globalParser: undefined, // Parent globals come via parentGlobals, not re-parsing
+                    name,
+                    options: state.options,
+                    theme: state.theme,
+                });
+                // Call factory to let user add commands
+                const nestedBuilder = factory(childBuilder);
+                state.commands.set(name, {
+                    builder: nestedBuilder,
+                    description,
+                    type: 'nested',
+                });
+                return this;
+            }
             // Form 3: command(name, CliBuilder, description?) - nested commands
-            if (isCliBuilder(cmdOrParserOrBuilder)) {
-                const builder = cmdOrParserOrBuilder;
+            if (isCliBuilder(cmdOrParserOrBuilderOrFactory)) {
+                const builder = cmdOrParserOrBuilderOrFactory;
                 const description = handlerOrDesc;
                 state.commands.set(name, {
                     builder: builder,
@@ -198,14 +289,14 @@ const createCliBuilder = (state) => {
             }
             let cmd;
             let description;
-            if (isCommand(cmdOrParserOrBuilder)) {
+            if (isCommand(cmdOrParserOrBuilderOrFactory)) {
                 // Form 1: command(name, Command, description?)
-                cmd = cmdOrParserOrBuilder;
+                cmd = cmdOrParserOrBuilderOrFactory;
                 description = handlerOrDesc;
             }
-            else if (isParser(cmdOrParserOrBuilder)) {
+            else if (isParser(cmdOrParserOrBuilderOrFactory)) {
                 // Form 2: command(name, Parser, handler, description?)
-                const parser = cmdOrParserOrBuilder;
+                const parser = cmdOrParserOrBuilderOrFactory;
                 const handler = handlerOrDesc;
                 description = maybeDesc;
                 // Create Command from Parser + handler
@@ -223,7 +314,7 @@ const createCliBuilder = (state) => {
                 cmd = newCmd;
             }
             else {
-                throw new Error('command() requires a Command, Parser, or CliBuilder as second argument');
+                throw new Error('command() requires a Command, Parser, CliBuilder, or factory function as second argument');
             }
             state.commands.set(name, { cmd, description, type: 'command' });
             return this;
@@ -298,6 +389,8 @@ const createCliBuilder = (state) => {
 };
 /**
  * Core parse logic shared between parse() and parseAsync().
+ *
+ * @function
  */
 const parseCore = (state, args, allowAsync) => {
     const { commands, options, theme } = state;
@@ -330,6 +423,8 @@ const parseCore = (state, args, allowAsync) => {
 };
 /**
  * Generate command-specific help.
+ *
+ * @function
  */
 const generateCommandHelpNew = (state, commandName, theme) => {
     const commandEntry = state.commands.get(commandName);
@@ -356,6 +451,8 @@ const generateCommandHelpNew = (state, commandName, theme) => {
 };
 /**
  * Generate help for the new CLI structure.
+ *
+ * @function
  */
 const generateHelpNew = (state, theme) => {
     // TODO: Implement proper help generation for new structure
@@ -375,6 +472,8 @@ const generateHelpNew = (state, theme) => {
 /**
  * Check if something is a Parser (has __brand: 'Parser'). Parsers can be either
  * objects or functions (CallableParser).
+ *
+ * @function
  */
 const isParser = (x) => {
     if (x === null || x === undefined) {
@@ -387,6 +486,8 @@ const isParser = (x) => {
 /**
  * Check if something is a CliBuilder (has command, globals, parse, parseAsync
  * methods).
+ *
+ * @function
  */
 const isCliBuilder = (x) => {
     if (x === null || x === undefined || typeof x !== 'object') {
@@ -400,6 +501,8 @@ const isCliBuilder = (x) => {
 };
 /**
  * Run a simple CLI (no commands).
+ *
+ * @function
  */
 const runSimple = (state, args, allowAsync) => {
     const { globalParser } = state;
@@ -436,6 +539,8 @@ const runSimple = (state, args, allowAsync) => {
 // ═══════════════════════════════════════════════════════════════════════════════
 /**
  * Delegate parsing to a nested CliBuilder, passing down parent globals.
+ *
+ * @function
  */
 const delegateToNestedBuilder = (builder, remainingArgs, parentGlobals, allowAsync) => {
     // Access the internal parse function that accepts parent globals
@@ -444,6 +549,8 @@ const delegateToNestedBuilder = (builder, remainingArgs, parentGlobals, allowAsy
 };
 /**
  * Run a CLI with commands.
+ *
+ * @function
  */
 const runWithCommands = (state, args, allowAsync) => {
     const { commands, defaultCommandName, globalParser } = state;
@@ -532,6 +639,9 @@ const runWithCommands = (state, args, allowAsync) => {
         values: { ...parentValues, ...parsed.values },
     };
     // Helper to check for async and throw if not allowed
+    /**
+     * @function
+     */
     const checkAsync = (value, context) => {
         if (value instanceof Promise && !allowAsync) {
             throw new errors_js_1.BargsError(`Async ${context} detected. Use parseAsync() instead of parse().`);
@@ -541,6 +651,9 @@ const runWithCommands = (state, args, allowAsync) => {
     const globalTransform = globalParser?.__transform;
     const commandTransform = cmd?.__transform;
     // Apply transforms and run handler
+    /**
+     * @function
+     */
     const applyTransformsAndHandle = () => {
         // Apply global transforms first
         if (globalTransform) {
@@ -556,6 +669,9 @@ const runWithCommands = (state, args, allowAsync) => {
         }
         return continueWithCommandTransform();
     };
+    /**
+     * @function
+     */
     const continueWithCommandTransform = () => {
         // Apply command transforms
         if (commandTransform) {
@@ -571,6 +687,9 @@ const runWithCommands = (state, args, allowAsync) => {
         }
         return runHandler();
     };
+    /**
+     * @function
+     */
     const runHandler = () => {
         const handlerResult = cmd.handler(result);
         checkAsync(handlerResult, 'handler');
@@ -582,9 +701,8 @@ const runWithCommands = (state, args, allowAsync) => {
     return applyTransformsAndHandle();
 };
 /**
- * Main bargs namespace.
+ * @ignore
+ * @deprecated
  */
-exports.bargs = {
-    create,
-};
+exports.bargs.create = exports.bargs;
 //# sourceMappingURL=bargs.js.map