fix: type inference issues; inference no longer reliant on property ordering

boneskull · boneskull · commit 43cb4fb46862 · 2026-01-04T00:29:53.000-08:00
diff --git a/examples/transforms-inline.ts b/examples/transforms-inline.ts
@@ -0,0 +1,156 @@
+#!/usr/bin/env npx tsx
+/**
+ * Transform example (inline version)
+ *
+ * Same as transforms.ts but with everything inlined to test type inference for
+ * inline command definitions.
+ *
+ * NOTE: Inline command definitions can be fully typed, but you must preserve
+ * schema shapes:
+ *
+ * - Use `bargsAsync.positionals(...)` (not array literals) to get tuple
+ *   positionals inference
+ * - Use `bargsAsync.options(...)` when composing or reusing option schemas
+ *
+ * If you want maximum inference with fewer moving parts, prefer
+ * `bargsAsync.command<TGlobalOptions, TGlobalTransforms>()()` as shown in
+ * transforms.ts.
+ *
+ * Usage: npx tsx examples/transforms-inline.ts process file1.txt --verbose npx
+ * tsx examples/transforms-inline.ts info --config config.json npx tsx
+ * examples/transforms-inline.ts --help
+ */
+import { existsSync, readFileSync } from 'node:fs';
+
+import { bargsAsync } from '../src/index.js';
+
+/**
+ * Config that can be loaded from a JSON file.
+ */
+interface Config {
+  maxRetries?: number;
+  outputDir?: string;
+  verbose?: boolean;
+}
+
+const main = async () => {
+  // Everything is inlined here - no separate variables for options, transforms, or commands
+  await bargsAsync({
+    commands: {
+      // Inline command definition
+      info: {
+        description: 'Show configuration info',
+        handler: ({ values }) => {
+          console.log('Current configuration:');
+          console.log(`  Config file: ${values.config ?? '(none)'}`);
+          console.log(`  Output dir: ${values.outputDir ?? '(default)'}`);
+          console.log(`  Verbose: ${values.verbose}`);
+          // These come from global transforms
+          console.log(`  Config loaded: ${values.configLoaded}`);
+          console.log(`  Timestamp: ${values.timestamp}`);
+        },
+      },
+      // Inline command with its own options and transforms
+      process: {
+        description: 'Process files',
+        handler: ({ positionals, values }) => {
+          const isStringArray = (value: unknown): value is string[] =>
+            Array.isArray(value) && value.every((v) => typeof v === 'string');
+
+          const [maybeFiles] = positionals;
+          const files = isStringArray(maybeFiles) ? maybeFiles : [];
+
+          if (values.verbose) {
+            console.log('Processing configuration:', {
+              configLoaded: values.configLoaded,
+              outputDir: values.outputDir,
+              timestamp: values.timestamp,
+              verbose: values.verbose,
+            });
+          }
+
+          console.log(`Processing ${files.length} file(s):`);
+          for (const file of files) {
+            console.log(`  - ${file}`);
+          }
+
+          if (values.outputDir) {
+            console.log(`Output will be written to: ${values.outputDir}`);
+          }
+        },
+        positionals: bargsAsync.positionals(
+          bargsAsync.variadic('string', {
+            description: 'Input files to process',
+            name: 'files',
+          }),
+        ),
+        // Inline command-level transform
+        transforms: {
+          positionals: (positionals: readonly [string[]]) => {
+            const [files] = positionals;
+            const validFiles = files.filter((f) => {
+              if (!existsSync(f)) {
+                console.warn(`Warning: File not found: ${f}`);
+                return false;
+              }
+              return true;
+            });
+            return [validFiles] as const;
+          },
+        },
+      },
+    },
+    defaultHandler: ({ values }) => {
+      console.log('No command specified. Use --help for usage.');
+      if (values.verbose) {
+        console.log('(verbose mode enabled)');
+      }
+      // These should be typed from global transforms
+      console.log(`Config loaded: ${values.configLoaded}`);
+      console.log(`Timestamp: ${values.timestamp}`);
+    },
+    description: 'Demonstrates inline transforms with commands',
+    name: 'transforms-inline-demo',
+    // Inline global options
+    options: {
+      config: bargsAsync.string({
+        aliases: ['c'],
+        description: 'Path to JSON config file',
+      }),
+      outputDir: bargsAsync.string({
+        aliases: ['o'],
+        description: 'Output directory',
+      }),
+      verbose: bargsAsync.boolean({
+        aliases: ['v'],
+        default: false,
+        description: 'Enable verbose output',
+      }),
+    },
+    // Inline global transforms
+    transforms: {
+      values: (values: {
+        config: string | undefined;
+        outputDir: string | undefined;
+        verbose: boolean;
+      }) => {
+        let fileConfig: Config = {};
+
+        if (values.config && existsSync(values.config)) {
+          const content = readFileSync(values.config, 'utf8');
+          fileConfig = JSON.parse(content) as Config;
+        }
+
+        return {
+          ...fileConfig,
+          ...values,
+          configLoaded: !!values.config,
+          timestamp: new Date().toISOString(),
+        };
+      },
+    },
+    version: '1.0.0',
+  });
+};
+
+void main();
diff --git a/src/bargs.ts b/src/bargs.ts
@@ -11,7 +11,7 @@
  */
 
 import type {
-  AnyCommandConfig,
+  AnyCommandConfigInput,
   BargsConfig,
   BargsConfigWithCommands,
   BargsOptions,
@@ -182,7 +182,7 @@ export function bargs<
  */
 export function bargs<
   const TOptions extends OptionsSchema,
-  const TCommands extends Record<string, AnyCommandConfig>,
+  const TCommands extends Record<string, AnyCommandConfigInput>,
 >(
   config: BargsConfigWithCommands<TOptions, TCommands>,
   options?: BargsOptions,
@@ -273,7 +273,7 @@ export async function bargsAsync<
  */
 export async function bargsAsync<
   const TOptions extends OptionsSchema,
-  const TCommands extends Record<string, AnyCommandConfig>,
+  const TCommands extends Record<string, AnyCommandConfigInput>,
   const TTransforms extends TransformsConfig<any, any, any, any> | undefined =
     undefined,
 >(
diff --git a/src/types.ts b/src/types.ts
@@ -41,6 +41,15 @@ export interface AnyCommandConfig {
   transforms?: TransformsConfig<any, any, any, any>;
 }
 
+/**
+ * Command config shape used for type constraints/inference.
+ *
+ * Intentionally omits `handler` so inline command handlers are not
+ * context-typed as `(result: any) => …` before `CommandsInput` can apply the
+ * computed handler signature.
+ */
+export type AnyCommandConfigInput = Omit<AnyCommandConfig, 'handler'>;
+
 /**
  * Array option definition (--flag value --flag value2).
  */
@@ -62,7 +71,8 @@ export interface ArrayOption extends OptionBase {
 export interface BargsConfig<
   TOptions extends OptionsSchema = OptionsSchema,
   TPositionals extends PositionalsSchema = PositionalsSchema,
-  TCommands extends Record<string, AnyCommandConfig> | undefined = undefined,
+  TCommands extends Record<string, AnyCommandConfigInput> | undefined =
+    undefined,
   TTransforms extends TransformsConfig<any, any, any, any> | undefined =
     undefined,
 > {
@@ -93,17 +103,17 @@ export interface BargsConfig<
 
 export type BargsConfigWithCommands<
   TOptions extends OptionsSchema = OptionsSchema,
-  TCommands extends Record<string, AnyCommandConfig> = Record<
+  TCommands extends Record<string, AnyCommandConfigInput> = Record<
     string,
-    AnyCommandConfig
+    AnyCommandConfigInput
   >,
   TTransforms extends TransformsConfig<any, any, any, any> | undefined =
     undefined,
 > = Omit<
   BargsConfig<TOptions, PositionalsSchema, TCommands, TTransforms>,
   'commands' | 'positionals'
 > & {
-  commands: CommandsInput<TOptions, TTransforms, TCommands>;
+  commands: CommandsInput<TOptions, TTransforms, TCommands> & TCommands;
   defaultHandler?:
     | CommandNames<TCommands>
     | Handler<
@@ -123,9 +133,9 @@ export type BargsConfigWithCommands<
  */
 export type BargsConfigWithCommandsInternal<
   TOptions extends OptionsSchema = OptionsSchema,
-  TCommands extends Record<string, AnyCommandConfig> = Record<
+  TCommands extends Record<string, AnyCommandConfigInput> = Record<
     string,
-    AnyCommandConfig
+    AnyCommandConfigInput
   >,
   TTransforms extends TransformsConfig<any, any, any, any> | undefined =
     undefined,
@@ -400,7 +410,9 @@ export type InferPositionals<T extends PositionalsSchema> = T extends readonly [
     ? Only extends PositionalDef
       ? readonly [InferPositional<Only>]
       : readonly []
-    : readonly [];
+    : T extends readonly []
+      ? readonly []
+      : readonly InferPositional<T[number]>[];
 
 /**
  * Compute proper handler types for each command in a commands record.
@@ -427,7 +439,7 @@ export type InferPositionals<T extends PositionalsSchema> = T extends readonly [
 export type InferredCommands<
   TGlobalOptions extends OptionsSchema,
   TGlobalTransforms extends TransformsConfig<any, any, any, any> | undefined,
-  TCommands extends Record<string, AnyCommandConfig>,
+  TCommands extends Record<string, AnyCommandConfigInput>,
 > = {
   [K in keyof TCommands]: TCommands[K] extends CommandConfig<
     infer _TGlobalOpts,
@@ -445,9 +457,20 @@ export type InferredCommands<
           InferCommandResult<
             TGlobalOptions,
             TGlobalTransforms,
-            TCommands[K]['options'],
-            TCommands[K]['positionals'],
-            TCommands[K]['transforms']
+            NonNullable<TCommands[K]['options']> extends OptionsSchema
+              ? NonNullable<TCommands[K]['options']>
+              : undefined,
+            NonNullable<TCommands[K]['positionals']> extends PositionalsSchema
+              ? NonNullable<TCommands[K]['positionals']>
+              : undefined,
+            NonNullable<TCommands[K]['transforms']> extends TransformsConfig<
+              any,
+              any,
+              any,
+              any
+            >
+              ? NonNullable<TCommands[K]['transforms']>
+              : undefined
           >
         >;
         options?: TCommands[K]['options'];
@@ -620,7 +643,8 @@ interface CommandInput<
  * Helper type to extract command names from a commands record for
  * defaultHandler typing.
  */
-type CommandNames<T> = T extends Record<infer K, AnyCommandConfig> ? K : never;
+type CommandNames<T> =
+  T extends Record<infer K, AnyCommandConfigInput> ? K : never;
 
 /**
  * Bargs config with commands (requires commands, allows defaultHandler).
@@ -644,7 +668,7 @@ type CommandNames<T> = T extends Record<infer K, AnyCommandConfig> ? K : never;
 type CommandsInput<
   TGlobalOptions extends OptionsSchema,
   TGlobalTransforms extends TransformsConfig<any, any, any, any> | undefined,
-  TCommands extends Record<string, AnyCommandConfig>,
+  TCommands extends Record<string, AnyCommandConfigInput>,
 > = {
   [K in keyof TCommands]: TCommands[K] extends CommandConfig<
     infer _TGlobalOpts,
@@ -659,14 +683,19 @@ type CommandsInput<
       CommandInput<
         TGlobalOptions,
         TGlobalTransforms,
-        TCommands[K]['options'] extends OptionsSchema
-          ? TCommands[K]['options']
+        NonNullable<TCommands[K]['options']> extends OptionsSchema
+          ? NonNullable<TCommands[K]['options']>
           : Record<string, never>,
-        TCommands[K]['positionals'] extends PositionalsSchema
-          ? TCommands[K]['positionals']
+        NonNullable<TCommands[K]['positionals']> extends PositionalsSchema
+          ? NonNullable<TCommands[K]['positionals']>
           : [],
-        TCommands[K]['transforms'] extends TransformsConfig<any, any, any, any>
-          ? TCommands[K]['transforms']
+        NonNullable<TCommands[K]['transforms']> extends TransformsConfig<
+          any,
+          any,
+          any,
+          any
+        >
+          ? NonNullable<TCommands[K]['transforms']>
           : undefined
       >;
 };
diff --git a/test/command-inference.test.ts b/test/command-inference.test.ts
@@ -18,14 +18,23 @@ describe('command handler type inference', () => {
           description: 'test command',
           handler: ({ values }) => {
             capturedValues = values;
-            const g: string = values.global;
-            const l: string = values.local;
+            type IsAny<T> = 0 extends 1 & T ? true : false;
+            type AssertFalse<_T extends false> = true;
+
+            // Compile-time guard: inline commands should not leak `any` into handler types.
+            const _globalIsNotAny: AssertFalse<IsAny<typeof values.global>> =
+              true;
+            const _localIsNotAny: AssertFalse<IsAny<typeof values.local>> =
+              true;
+
+            const g = values.global;
+            const l = values.local;
             expect(typeof g, 'to equal', 'string');
             expect(typeof l, 'to equal', 'string');
           },
-          options: {
+          options: bargs.options({
             local: bargs.string({ default: 'l' }),
-          },
+          }),
         },
       },
       name: 'test',
@@ -57,7 +66,10 @@ describe('command handler type inference', () => {
               'to be true',
             );
           },
-          positionals: [bargs.stringPos({ required: true }), bargs.stringPos()],
+          positionals: bargs.positionals(
+            bargs.stringPos({ required: true }),
+            bargs.stringPos(),
+          ),
         },
       },
       name: 'test',
