refactor(types): improve transform type inference

- Add const modifiers to bargs/bargsAsync generics for literal inference
- Use conditional type for transforms property to allow both explicit
  TTransforms and default undefined cases
- Refactor transform runners to use function overloads eliminating 8
  type assertions
- Remove as const from example transforms return type
- Export runTransforms/runSyncTransforms for testing
- Add comprehensive transforms test suite

The transforms property now uses:
  transforms?: [TTransforms] extends [undefined]
    ? TransformsConfig<any, any, any, any>
    : TTransforms

This allows transforms to work without type assertions when TTransforms
defaults to undefined, while preserving full type safety when explicitly
specified.

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

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

Author: boneskull

examples/transforms.ts

@@ -80,7 +80,7 @@ const main = async () => {
           }
           return true;
         });
-        return [validFiles] as const;
+        return [validFiles];
       },
     },
     handler: ({ values, positionals }) => {

src/bargs.ts

@@ -166,14 +166,8 @@ const handleHelpError = (
 export function bargs<
   const TOptions extends OptionsSchema,
   const TPositionals extends PositionalsSchema,
-  const TTransforms extends
-    | TransformsConfig<
-        InferOptions<TOptions>,
-        any,
-        InferPositionals<TPositionals>,
-        any
-      >
-    | undefined = undefined,
+  const TTransforms extends TransformsConfig<any, any, any, any> | undefined =
+    undefined,
 >(
   config: BargsConfig<TOptions, TPositionals, undefined, TTransforms>,
   options?: BargsOptions,
@@ -265,16 +259,10 @@ export function bargs(
  * Main bargs entry point for simple CLIs (no commands) - async version.
  */
 export async function bargsAsync<
-  TOptions extends OptionsSchema,
-  TPositionals extends PositionalsSchema,
-  TTransforms extends
-    | TransformsConfig<
-        InferOptions<TOptions>,
-        any,
-        InferPositionals<TPositionals>,
-        any
-      >
-    | undefined = undefined,
+  const TOptions extends OptionsSchema,
+  const TPositionals extends PositionalsSchema,
+  const TTransforms extends TransformsConfig<any, any, any, any> | undefined =
+    undefined,
 >(
   config: BargsConfig<TOptions, TPositionals, undefined, TTransforms>,
   options?: BargsOptions,
@@ -290,8 +278,8 @@ export async function bargsAsync<
  * Main bargs entry point for command-based CLIs - async version.
  */
 export async function bargsAsync<
-  TOptions extends OptionsSchema,
-  TCommands extends Record<string, CommandConfigInput>,
+  const TOptions extends OptionsSchema,
+  const TCommands extends Record<string, CommandConfigInput>,
 >(
   config: BargsConfigWithCommands<TOptions, TCommands>,
   options?: BargsOptions,
@@ -307,7 +295,9 @@ export async function bargsAsync(
   config: BargsConfig<
     OptionsSchema,
     PositionalsSchema,
-    Record<string, CommandConfigInput> | undefined
+    Record<string, CommandConfigInput> | undefined,
+    | TransformsConfig<unknown, unknown, readonly unknown[], readonly unknown[]>
+    | undefined
   >,
   options?: BargsOptions,
 ): Promise<BargsResult<unknown, readonly unknown[], string | undefined>> {
@@ -333,14 +323,7 @@ export async function bargsAsync(
       });
 
       // Run transforms if present (type-erased in implementation)
-      const transforms = config.transforms as
-        | TransformsConfig<
-            unknown,
-            unknown,
-            readonly unknown[],
-            readonly unknown[]
-          >
-        | undefined;
+      const transforms = config.transforms;
       const transformed = transforms
         ? await runTransforms(transforms, parsed.values, parsed.positionals)
         : { positionals: parsed.positionals, values: parsed.values };

src/index.ts

@@ -80,19 +80,25 @@ export type {
   CommandConfigInput,
   CountOption,
   EnumOption,
+  EnumPositional,
   Handler,
   HandlerFn,
   InferOption,
   InferOptions,
   InferPositional,
   InferPositionals,
+  InferTransformedPositionals,
+  InferTransformedValues,
   NumberOption,
   NumberPositional,
   OptionDef,
   OptionsSchema,
   PositionalDef,
   PositionalsSchema,
+  PositionalsTransformFn,
   StringOption,
   StringPositional,
+  TransformsConfig,
+  ValuesTransformFn,
   VariadicPositional,
 } from './types.js';

src/parser.ts

@@ -59,10 +59,43 @@ export const runHandler = async <T>(
   await handler(result);
 };
 
+// ─── Sync Transform Runner ──────────────────────────────────────────────────
+
+/**
+ * Run transforms synchronously when transforms are defined.
+ */
+export function runSyncTransforms<
+  TValuesIn,
+  TValuesOut,
+  TPositionalsIn extends readonly unknown[],
+  TPositionalsOut extends readonly unknown[],
+>(
+  transforms: TransformsConfig<
+    TValuesIn,
+    TValuesOut,
+    TPositionalsIn,
+    TPositionalsOut
+  >,
+  values: TValuesIn,
+  positionals: TPositionalsIn,
+): { positionals: TPositionalsOut; values: TValuesOut };
+
+/**
+ * Pass through unchanged when transforms are undefined.
+ */
+export function runSyncTransforms<
+  TValues,
+  TPositionals extends readonly unknown[],
+>(
+  transforms: undefined,
+  values: TValues,
+  positionals: TPositionals,
+): { positionals: TPositionals; values: TValues };
+
 /**
  * Run transforms synchronously. Throws if any transform returns a thenable.
  */
-export const runSyncTransforms = <
+export function runSyncTransforms<
   TValuesIn,
   TValuesOut,
   TPositionalsIn extends readonly unknown[],
@@ -73,40 +106,80 @@ export const runSyncTransforms = <
     | undefined,
   values: TValuesIn,
   positionals: TPositionalsIn,
-): { positionals: TPositionalsOut; values: TValuesOut } => {
-  let currentValues: unknown = values;
-  let currentPositionals: unknown = positionals;
-
-  if (transforms?.values) {
-    const result = transforms.values(currentValues as TValuesIn);
-    if (isThenable(result)) {
-      throw new BargsError(
-        'Transform returned a thenable. Use bargsAsync() for async transforms.',
-      );
-    }
-    currentValues = result;
+): {
+  positionals: TPositionalsIn | TPositionalsOut;
+  values: TValuesIn | TValuesOut;
+} {
+  if (!transforms) {
+    return { positionals, values };
   }
 
-  if (transforms?.positionals) {
-    const result = transforms.positionals(currentPositionals as TPositionalsIn);
-    if (isThenable(result)) {
-      throw new BargsError(
-        'Transform returned a thenable. Use bargsAsync() for async transforms.',
-      );
-    }
-    currentPositionals = result;
-  }
+  // Apply values transform
+  const transformedValues = transforms.values
+    ? (() => {
+        const result = transforms.values(values);
+        if (isThenable(result)) {
+          throw new BargsError(
+            'Transform returned a thenable. Use bargsAsync() for async transforms.',
+          );
+        }
+        return result;
+      })()
+    : values;
+
+  // Apply positionals transform
+  const transformedPositionals = transforms.positionals
+    ? (() => {
+        const result = transforms.positionals(positionals);
+        if (isThenable(result)) {
+          throw new BargsError(
+            'Transform returned a thenable. Use bargsAsync() for async transforms.',
+          );
+        }
+        return result;
+      })()
+    : positionals;
 
   return {
-    positionals: currentPositionals as TPositionalsOut,
-    values: currentValues as TValuesOut,
+    positionals: transformedPositionals,
+    values: transformedValues,
   };
-};
+}
+
+// ─── Async Transform Runner ─────────────────────────────────────────────────
+
+/**
+ * Run transforms asynchronously when transforms are defined.
+ */
+export function runTransforms<
+  TValuesIn,
+  TValuesOut,
+  TPositionalsIn extends readonly unknown[],
+  TPositionalsOut extends readonly unknown[],
+>(
+  transforms: TransformsConfig<
+    TValuesIn,
+    TValuesOut,
+    TPositionalsIn,
+    TPositionalsOut
+  >,
+  values: TValuesIn,
+  positionals: TPositionalsIn,
+): Promise<{ positionals: TPositionalsOut; values: TValuesOut }>;
+
+/**
+ * Pass through unchanged when transforms are undefined.
+ */
+export function runTransforms<TValues, TPositionals extends readonly unknown[]>(
+  transforms: undefined,
+  values: TValues,
+  positionals: TPositionals,
+): Promise<{ positionals: TPositionals; values: TValues }>;
 
 /**
  * Run transforms asynchronously.
  */
-export const runTransforms = async <
+export async function runTransforms<
   TValuesIn,
   TValuesOut,
   TPositionalsIn extends readonly unknown[],
@@ -117,25 +190,29 @@ export const runTransforms = async <
     | undefined,
   values: TValuesIn,
   positionals: TPositionalsIn,
-): Promise<{ positionals: TPositionalsOut; values: TValuesOut }> => {
-  let currentValues: unknown = values;
-  let currentPositionals: unknown = positionals;
-
-  if (transforms?.values) {
-    currentValues = await transforms.values(currentValues as TValuesIn);
+): Promise<{
+  positionals: TPositionalsIn | TPositionalsOut;
+  values: TValuesIn | TValuesOut;
+}> {
+  if (!transforms) {
+    return { positionals, values };
   }
 
-  if (transforms?.positionals) {
-    currentPositionals = await transforms.positionals(
-      currentPositionals as TPositionalsIn,
-    );
-  }
+  // Apply values transform (await if needed)
+  const transformedValues = transforms.values
+    ? await transforms.values(values)
+    : values;
+
+  // Apply positionals transform (await if needed)
+  const transformedPositionals = transforms.positionals
+    ? await transforms.positionals(positionals)
+    : positionals;
 
   return {
-    positionals: currentPositionals as TPositionalsOut,
-    values: currentValues as TValuesOut,
+    positionals: transformedPositionals,
+    values: transformedValues,
   };
-};
+}
 
 /**
  * Build parseArgs options config from our options schema.

src/types.ts

@@ -82,7 +82,9 @@ export interface BargsConfig<
    * Values transform receives InferOptions<TOptions>, positionals transform
    * receives InferPositionals<TPositionals>.
    */
-  transforms?: TTransforms;
+  transforms?: [TTransforms] extends [undefined]
+    ? TransformsConfig<any, any, any, any>
+    : TTransforms;
   version?: string;
 }