feat: add camelCaseValues transform for kebab-to-camel option keys

Adds a transform helper for use with map() that converts kebab-case
option keys to camelCase in the result values:

  const parser = map(
    opt.options({ 'output-dir': opt.string() }),
    camelCaseValues,
  );
  // --output-dir ./dist → values.outputDir

Also fixes map() to properly compose transforms when chaining multiple
map() calls (was previously overwriting instead of chaining).

Includes:
- camelCaseValues transform function
- KebabToCamel and CamelCaseKeys type utilities
- Tests for the new functionality
- README documentation
- Updated transforms.ts example to demonstrate usage

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

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

Author: boneskull

README.md

@@ -480,6 +480,36 @@ 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
+  .create('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.

examples/transforms.ts

@@ -5,6 +5,7 @@
  * Demonstrates how to use map() transforms:
  *
  * - Global transforms via map() applied to globals parser
+ * - Using camelCaseValues to convert kebab-case to camelCase
  * - Command-specific transforms via map() in command parsers
  * - Computed/derived values flowing through handlers
  * - Full type inference with the (Parser, handler) API
@@ -15,7 +16,7 @@
  */
 import { existsSync, readFileSync } from 'node:fs';
 
-import { bargs, map, opt, pos } from '../src/index.js';
+import { bargs, camelCaseValues, map, opt, pos } from '../src/index.js';
 
 // ═══════════════════════════════════════════════════════════════════════════════
 // CONFIG TYPE
@@ -31,15 +32,18 @@ interface Config {
 // GLOBAL OPTIONS WITH TRANSFORM
 // ═══════════════════════════════════════════════════════════════════════════════
 
-// Global options with transform that loads config from file
+// Global options using kebab-case (CLI-friendly)
 const baseGlobals = opt.options({
   config: opt.string(),
-  outputDir: opt.string(),
+  'output-dir': opt.string(), // CLI: --output-dir
   verbose: opt.boolean({ default: false }),
 });
 
-// Apply transform to add computed properties using map(parser, fn) form
-const globals = map(baseGlobals, ({ positionals, values }) => {
+// First, convert kebab-case to camelCase for ergonomic property access
+const camelGlobals = map(baseGlobals, camelCaseValues);
+
+// Then apply additional transforms for computed properties
+const globals = map(camelGlobals, ({ positionals, values }) => {
   let fileConfig: Config = {};
 
   // Load config from JSON file if specified
@@ -49,6 +53,7 @@ const globals = map(baseGlobals, ({ positionals, values }) => {
   }
 
   // Return enriched values with file config merged in
+  // Note: values.outputDir is now camelCase thanks to camelCaseValues!
   return {
     positionals,
     values: {

src/bargs.ts

@@ -8,6 +8,7 @@
  */
 
 import type {
+  CamelCaseKeys,
   CliBuilder,
   Command,
   CreateOptions,
@@ -155,30 +156,59 @@ export function map<
   parserOrFn: Parser<V1, P1> | TransformFn<V1, P1, V2, P2>,
   maybeFn?: TransformFn<V1, P1, V2, P2>,
 ): ((parser: Parser<V1, P1>) => Parser<V2, P2>) | Parser<V2, P2> {
+  // Helper to compose transforms (chains existing + new)
+  const composeTransform = (
+    parser: Parser<V1, P1>,
+    fn: TransformFn<V1, P1, V2, P2>,
+  ): TransformFn<unknown, readonly unknown[], V2, P2> => {
+    const existing = (
+      parser as {
+        __transform?: (
+          r: ParseResult<unknown, readonly unknown[]>,
+        ) => ParseResult<V1, P1> | Promise<ParseResult<V1, P1>>;
+      }
+    ).__transform;
+
+    if (!existing) {
+      return fn as TransformFn<unknown, readonly unknown[], V2, P2>;
+    }
+
+    // Chain: existing transform first, then new transform
+    return (r: ParseResult<unknown, readonly unknown[]>) => {
+      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: [] as unknown as P2,
-      __transform: fn,
+      __transform: composedTransform,
       __values: {} as V2,
-    } as Parser<V2, P2> & { __transform: typeof fn };
+    } as Parser<V2, P2> & { __transform: typeof composedTransform };
   }
 
   // Curried form: map(fn) returns (parser) => Parser
   const fn = parserOrFn;
   return (parser: Parser<V1, P1>): Parser<V2, P2> => {
+    const composedTransform = composeTransform(parser, fn);
     return {
       ...parser,
       __brand: 'Parser',
       __positionals: [] as unknown as P2,
-      __transform: fn,
+      __transform: composedTransform,
       __values: {} as V2,
-    } as Parser<V2, P2> & { __transform: typeof fn };
+    } as Parser<V2, P2> & { __transform: typeof composedTransform };
   };
 }
 /**
@@ -307,6 +337,48 @@ export function merge(
 
   return result;
 }
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// CAMEL CASE HELPER
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Convert kebab-case string to camelCase.
+ */
+const kebabToCamel = (s: string): string =>
+  s.replace(/-([a-z])/g, (_, c: string) => 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
+ *   .create('my-cli')
+ *   .globals(
+ *     map(opt.options({ 'output-dir': opt.string() }), camelCaseValues),
+ *   )
+ *   .parseAsync();
+ *
+ * console.log(values.outputDir); // camelCased!
+ * ```
+ */
+export const camelCaseValues = <V, P extends readonly unknown[]>(
+  result: ParseResult<V, P>,
+): ParseResult<CamelCaseKeys<V>, P> => ({
+  ...result,
+  values: Object.fromEntries(
+    Object.entries(result.values as Record<string, unknown>).map(([k, v]) => [
+      kebabToCamel(k),
+      v,
+    ]),
+  ) as CamelCaseKeys<V>,
+});
+
 // ═══════════════════════════════════════════════════════════════════════════════
 // CLI BUILDER
 // ═══════════════════════════════════════════════════════════════════════════════

src/index.ts

@@ -24,7 +24,7 @@
  */
 
 // Main API
-export { bargs, handle, map, merge } from './bargs.js';
+export { bargs, camelCaseValues, handle, map, merge } from './bargs.js';
 export type { TransformFn } from './bargs.js';
 
 // Errors
@@ -67,6 +67,8 @@ export type {
   // Option definitions
   ArrayOption,
   BooleanOption,
+  // CamelCase utilities
+  CamelCaseKeys,
   // Parser combinator types
   CliBuilder,
   CliResult,
@@ -86,6 +88,7 @@ export type {
   InferPositionals,
   InferTransformedPositionals,
   InferTransformedValues,
+  KebabToCamel,
   NumberOption,
   NumberPositional,
   OptionDef,

src/types.ts

@@ -36,6 +36,22 @@ export interface BooleanOption extends OptionBase {
   type: 'boolean';
 }
 
+/**
+ * Transform all keys of an object type from kebab-case to camelCase.
+ *
+ * Used with `camelCaseValues` to provide type-safe camelCase option keys.
+ *
+ * @example
+ *
+ * ```typescript
+ * type Original = { 'output-dir': string; 'dry-run': boolean };
+ * type Camel = CamelCaseKeys<Original>; // { outputDir: string; dryRun: boolean }
+ * ```
+ */
+export type CamelCaseKeys<T> = {
+  [K in keyof T as KebabToCamel<K & string>]: T[K];
+};
+
 /**
  * CLI builder for fluent configuration.
  */
@@ -211,6 +227,10 @@ export interface EnumArrayOption<T extends string = string> extends OptionBase {
   type: 'array';
 }
 
+// ═══════════════════════════════════════════════════════════════════════════════
+// POSITIONAL DEFINITIONS
+// ═══════════════════════════════════════════════════════════════════════════════
+
 /**
  * Enum option definition with string choices.
  */
@@ -220,10 +240,6 @@ export interface EnumOption<T extends string = string> extends OptionBase {
   type: 'enum';
 }
 
-// ═══════════════════════════════════════════════════════════════════════════════
-// POSITIONAL DEFINITIONS
-// ═══════════════════════════════════════════════════════════════════════════════
-
 /**
  * Enum positional definition with string choices.
  */
@@ -279,6 +295,10 @@ export type InferOption<T extends OptionDef> = T extends BooleanOption
               ? number
               : never;
 
+// ═══════════════════════════════════════════════════════════════════════════════
+// CAMELCASE UTILITIES
+// ═══════════════════════════════════════════════════════════════════════════════
+
 /**
  * Infer values type from an options schema.
  */
@@ -346,10 +366,6 @@ export type InferTransformedPositionals<
     : TPositionalsIn
   : TPositionalsIn;
 
-// ═══════════════════════════════════════════════════════════════════════════════
-// TYPE INFERENCE
-// ═══════════════════════════════════════════════════════════════════════════════
-
 /**
  * Infer the output values type from a transforms config.
  */
@@ -358,6 +374,24 @@ export type InferTransformedValues<TValuesIn, TTransforms> =
     ? TOut
     : TValuesIn;
 
+// ═══════════════════════════════════════════════════════════════════════════════
+// TYPE INFERENCE
+// ═══════════════════════════════════════════════════════════════════════════════
+
+/**
+ * Convert a kebab-case string type to camelCase.
+ *
+ * @example
+ *
+ * ```typescript
+ * type Result = KebabToCamel<'output-dir'>; // 'outputDir'
+ * type Nested = KebabToCamel<'my-long-option'>; // 'myLongOption'
+ * ```
+ */
+export type KebabToCamel<S extends string> = S extends `${infer T}-${infer U}`
+  ? `${T}${Capitalize<KebabToCamel<U>>}`
+  : S;
+
 /**
  * Number option definition.
  */

test/combinators.test.ts

@@ -4,7 +4,7 @@
 import { expect } from 'bupkis';
 import { describe, it } from 'node:test';
 
-import { handle, map, merge } from '../src/bargs.js';
+import { camelCaseValues, handle, map, merge } from '../src/bargs.js';
 import { opt, pos } from '../src/opt.js';
 
 describe('merge()', () => {
@@ -222,3 +222,60 @@ describe('combined usage', () => {
     ]);
   });
 });
+
+describe('camelCaseValues()', () => {
+  it('converts kebab-case keys to camelCase', () => {
+    const result = camelCaseValues({
+      positionals: [] as const,
+      values: {
+        'dry-run': true,
+        'output-dir': '/tmp',
+        verbose: false,
+      },
+    });
+
+    expect(result.values, 'to satisfy', {
+      dryRun: true,
+      outputDir: '/tmp',
+      verbose: false,
+    });
+    // Original keys should NOT exist
+    expect(result.values, 'not to have key', 'output-dir');
+    expect(result.values, 'not to have key', 'dry-run');
+  });
+
+  it('handles nested kebab-case', () => {
+    const result = camelCaseValues({
+      positionals: [] as const,
+      values: { 'my-long-option-name': 'value' },
+    });
+
+    expect(result.values, 'to satisfy', { myLongOptionName: 'value' });
+  });
+
+  it('preserves positionals unchanged', () => {
+    const result = camelCaseValues({
+      positionals: ['file1', 'file2'] as const,
+      values: { 'output-dir': '/tmp' },
+    });
+
+    expect(result.positionals, 'to satisfy', ['file1', 'file2']);
+  });
+
+  it('works with map() for type-safe transforms', () => {
+    const parser = map(
+      opt.options({
+        'dry-run': opt.boolean(),
+        'output-dir': opt.string({ default: '/tmp' }),
+      }),
+      camelCaseValues,
+    );
+
+    expect(parser.__brand, 'to be', 'Parser');
+    expect(parser.__optionsSchema, 'to satisfy', {
+      'dry-run': { type: 'boolean' },
+      'output-dir': { type: 'string' },
+    });
+    // Note: schema keeps original keys, transform happens at runtime
+  });
+});