feat: add enumPos helper, sync/async API, and positional validations

- Add enumPos() helper for enum positional arguments with choice validation
- Split API into sync bargs() and async bargsAsync() functions
- Add thenable detection to throw if sync handler returns a Promise
- Add runtime validation: variadic positional must be last
- Add runtime validation: required positionals cannot follow optionals
- Add type inference tests for options and positionals with defaults
- Update README with positional helpers and enumPos documentation

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

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

Author: boneskull

examples/greeter.ts

@@ -13,53 +13,57 @@
  * --shout npx tsx examples/greeter.ts World -g "Hey there" npx tsx
  * examples/greeter.ts --help
  */
-import { bargs, opt } from '../src/index.js';
+import { bargs } from '../src/index.js';
 
-const options = opt.options({
-  greeting: opt.string({
+const optionsDef = bargs.options({
+  greeting: bargs.string({
     description: 'The greeting to use',
     default: 'Hello',
     aliases: ['g'],
   }),
-  shout: opt.boolean({
+  shout: bargs.boolean({
     description: 'SHOUT THE GREETING',
     default: false,
     aliases: ['s'],
   }),
-  verbose: opt.boolean({
+  verbose: bargs.boolean({
     description: 'Show extra output',
     default: false,
     aliases: ['v'],
   }),
 });
 
-const positionalsDef = opt.positionals(
-  opt.stringPos({ description: 'Name to greet', required: true }),
+const positionalsDef = bargs.positionals(
+  bargs.stringPos({ description: 'Name to greet', required: true }),
 );
 
-const result = await bargs({
-  name: 'greeter',
-  version: '1.0.0',
-  description: 'A friendly greeter CLI',
-  options,
-  positionals: positionalsDef,
-});
+const main = async () => {
+  const result = await bargs({
+    name: 'greeter',
+    version: '1.0.0',
+    description: 'A friendly greeter CLI',
+    options: optionsDef,
+    positionals: positionalsDef,
+  });
+
+  // Destructure the result
+  const { positionals, values } = result;
+  const [name] = positionals;
+  const { greeting, shout, verbose } = values;
 
-// Destructure the result
-const { positionals, values } = result;
-const [name] = positionals;
-const { greeting, shout, verbose } = values;
+  // Build the message
+  let message = `${greeting}, ${name}!`;
 
-// Build the message
-let message = `${greeting}, ${name}!`;
+  if (shout) {
+    message = message.toUpperCase();
+  }
 
-if (shout) {
-  message = message.toUpperCase();
-}
+  // Output
+  if (verbose) {
+    console.log('Configuration:', { greeting, name, shout });
+  }
 
-// Output
-if (verbose) {
-  console.log('Configuration:', { greeting, name, shout });
-}
+  console.log(message);
+};
 
-console.log(message);
+void main();

examples/tasks.ts

@@ -8,14 +8,14 @@
  * - Global options (--verbose, --file)
  * - Command-specific options (--priority for add)
  * - Command positionals (task text)
- * - Opt.command() for type inference
+ * - Bargs.command() for type inference
  * - DefaultHandler for no-command case
  *
  * Usage: npx tsx examples/tasks.ts add "Buy groceries" --priority high npx tsx
  * examples/tasks.ts list npx tsx examples/tasks.ts done 1 npx tsx
  * examples/tasks.ts --help npx tsx examples/tasks.ts add --help
  */
-import { bargs, opt } from '../src/index.js';
+import bargs from '../src/index.js';
 
 // In-memory task storage (in a real app, this would be a file or database)
 interface Task {
@@ -39,36 +39,36 @@ await bargs({
 
   // Global options available to all commands
   options: {
-    file: opt.string({
+    file: bargs.string({
       description: 'Task storage file',
       default: 'tasks.json',
       aliases: ['f'],
     }),
-    verbose: opt.boolean({
+    verbose: bargs.boolean({
       description: 'Show detailed output',
       default: false,
       aliases: ['v'],
     }),
   },
 
   commands: {
-    add: opt.command({
+    add: bargs.command({
       description: 'Add a new task',
       options: {
-        priority: opt.enum(['low', 'medium', 'high'] as const, {
+        priority: bargs.enum(['low', 'medium', 'high'], {
           description: 'Task priority',
           default: 'medium',
           aliases: ['p'],
         }),
       },
       positionals: [
-        opt.stringPos({ description: 'Task description', required: true }),
+        bargs.stringPos({ description: 'Task description', required: true }),
       ],
       handler: async ({ positionals, values }) => {
         const [text] = positionals;
-        const priority = (values as { priority: 'low' | 'medium' | 'high' })
-          .priority;
-        const verbose = (values as { verbose: boolean }).verbose;
+        // priority is typed from command options
+        // verbose is accessible via Record<string, unknown>
+        const { priority, verbose } = values;
 
         const task: Task = {
           done: false,
@@ -86,18 +86,18 @@ await bargs({
       },
     }),
 
-    list: opt.command({
+    list: bargs.command({
       description: 'List all tasks',
       options: {
-        all: opt.boolean({
+        all: bargs.boolean({
           description: 'Show completed tasks too',
           default: false,
           aliases: ['a'],
         }),
       },
       handler: async ({ values }) => {
-        const all = (values as { all: boolean }).all;
-        const verbose = (values as { verbose: boolean }).verbose;
+        // all is typed from command options, verbose from global
+        const { all, verbose } = values;
 
         const filtered = all ? tasks : tasks.filter((t) => !t.done);
 
@@ -123,13 +123,16 @@ await bargs({
       },
     }),
 
-    done: opt.command({
+    done: bargs.command({
       description: 'Mark a task as complete',
-      positionals: [opt.stringPos({ description: 'Task ID', required: true })],
+      positionals: [
+        bargs.stringPos({ description: 'Task ID', required: true }),
+      ],
       handler: async ({ positionals, values }) => {
         const [idStr] = positionals;
         const id = parseInt(idStr as string, 10);
-        const verbose = (values as { verbose: boolean }).verbose;
+        // verbose is accessible from global options
+        const { verbose } = values;
 
         const task = tasks.find((t) => t.id === id);
         if (!task) {
@@ -151,7 +154,8 @@ await bargs({
   // Default handler when no command is given - show task count
   defaultHandler: async ({ values }) => {
     const pending = tasks.filter((t) => !t.done).length;
-    if ((values as { verbose: boolean }).verbose) {
+    // Global options are fully typed in defaultHandler
+    if (values.verbose) {
       console.log(`Tasks: ${tasks.length} total, ${pending} pending`);
     } else {
       console.log(`${pending} pending task(s)`);