@boneskull/bargs 1.0.0 → 3.0.0

package/dist/index.d.ts

@@ -1,96 +1,33 @@
 /**
  * Main entry point for the bargs CLI argument parser.
  *
- * This module exports the primary `bargs` and `bargsAsync` functions with
- * attached option builder methods (e.g., `bargs.string()`, `bargs.boolean()`),
- * allowing both function-call and builder-namespace usage patterns. It also
- * re-exports all public types, error classes, help generators, theme utilities,
- * and OSC hyperlink functions.
+ * Provides a combinator-style API for building type-safe CLIs.
  *
  * @example
  *
  * ```typescript
- * import { bargs } from 'bargs';
+ * import { bargs, opt, pos } from '@boneskull/bargs';
  *
- * // Use as function
- * const result = bargs({
- *   name: 'myapp',
- *   options: { verbose: bargs.boolean({ aliases: ['v'] }) },
- * });
- *
- * // Access builder namespace
- * const opts = bargs.options({ name: bargs.string() });
+ * await bargs
+ *   .create('my-app', { version: '1.0.0' })
+ *   .globals(opt.options({ verbose: opt.boolean({ aliases: ['v'] }) }))
+ *   .command(
+ *     'greet',
+ *     pos.positionals(pos.string({ name: 'name', required: true })),
+ *     ({ positionals }) => console.log(`Hello, ${positionals[0]}!`),
+ *     'Say hello',
+ *   )
+ *   .parseAsync();
  * ```
  *
  * @packageDocumentation
  */
-import { bargsAsync as bargsAsyncBase, bargs as bargsBase } from "./bargs.js";
-/**
- * Main bargs entry point (sync). Also provides access to all opt builders via
- * bargs.string(), bargs.boolean(), etc.
- */
-export declare const bargs: typeof bargsBase & {
-    array: (items: "number" | "string", props?: Omit<import("./types.js").ArrayOption, "items" | "type">) => import("./types.js").ArrayOption;
-    boolean: <P extends Omit<import("./types.js").BooleanOption, "type"> = Omit<import("./types.js").BooleanOption, "type">>(props?: P) => import("./types.js").BooleanOption & P;
-    command: <TOptions extends import("./types.js").OptionsSchema = import("./types.js").OptionsSchema, TPositionals extends import("./types.js").PositionalsSchema = import("./types.js").PositionalsSchema, TTransforms extends import("./types.js").TransformsConfig<any, any, any, any> | undefined = undefined>(config: import("./types.js").CommandConfig<TOptions, TPositionals, TTransforms>) => import("./types.js").CommandConfig<TOptions, TPositionals, TTransforms>;
-    count: (props?: Omit<import("./types.js").CountOption, "type">) => import("./types.js").CountOption;
-    enum: <const T extends readonly string[], P extends Omit<import("./types.js").EnumOption<T[number]>, "choices" | "type"> = Omit<import("./types.js").EnumOption<T[number]>, "type" | "choices">>(choices: T, props?: P) => import("./types.js").EnumOption<T[number]> & P;
-    enumPos: <const T extends readonly string[], P extends Omit<import("./types.js").EnumPositional<T[number]>, "choices" | "type"> = Omit<import("./types.js").EnumPositional<T[number]>, "type" | "choices">>(choices: T, props?: P) => import("./types.js").EnumPositional<T[number]> & P;
-    number: <P extends Omit<import("./types.js").NumberOption, "type"> = Omit<import("./types.js").NumberOption, "type">>(props?: P) => import("./types.js").NumberOption & P;
-    numberPos: (props?: Omit<import("./types.js").NumberPositional, "type">) => import("./types.js").NumberPositional;
-    options: {
-        <A extends import("./types.js").OptionsSchema>(a: A): A;
-        <A extends import("./types.js").OptionsSchema, B extends import("./types.js").OptionsSchema>(a: A, b: B): A & B;
-        <A extends import("./types.js").OptionsSchema, B extends import("./types.js").OptionsSchema, C extends import("./types.js").OptionsSchema>(a: A, b: B, c: C): A & B & C;
-        <A extends import("./types.js").OptionsSchema, B extends import("./types.js").OptionsSchema, C extends import("./types.js").OptionsSchema, D extends import("./types.js").OptionsSchema>(a: A, b: B, c: C, d: D): A & B & C & D;
-        (...schemas: import("./types.js").OptionsSchema[]): import("./types.js").OptionsSchema;
-    };
-    positionals: {
-        <A extends import("./types.js").PositionalDef>(a: A): [A];
-        <A extends import("./types.js").PositionalDef, B extends import("./types.js").PositionalDef>(a: A, b: B): [A, B];
-        <A extends import("./types.js").PositionalDef, B extends import("./types.js").PositionalDef, C extends import("./types.js").PositionalDef>(a: A, b: B, c: C): [A, B, C];
-        <A extends import("./types.js").PositionalDef, B extends import("./types.js").PositionalDef, C extends import("./types.js").PositionalDef, D extends import("./types.js").PositionalDef>(a: A, b: B, c: C, d: D): [A, B, C, D];
-        (...positionals: import("./types.js").PositionalDef[]): import("./types.js").PositionalsSchema;
-    };
-    string: <P extends Omit<import("./types.js").StringOption, "type"> = Omit<import("./types.js").StringOption, "type">>(props?: P) => P & import("./types.js").StringOption;
-    stringPos: (props?: Omit<import("./types.js").StringPositional, "type">) => import("./types.js").StringPositional;
-    variadic: (items: "number" | "string", props?: Omit<import("./types.js").VariadicPositional, "items" | "type">) => import("./types.js").VariadicPositional;
-};
-/**
- * Async bargs entry point. Also provides access to all opt builders via
- * bargsAsync.string(), etc.
- */
-export declare const bargsAsync: typeof bargsAsyncBase & {
-    array: (items: "number" | "string", props?: Omit<import("./types.js").ArrayOption, "items" | "type">) => import("./types.js").ArrayOption;
-    boolean: <P extends Omit<import("./types.js").BooleanOption, "type"> = Omit<import("./types.js").BooleanOption, "type">>(props?: P) => import("./types.js").BooleanOption & P;
-    command: <TOptions extends import("./types.js").OptionsSchema = import("./types.js").OptionsSchema, TPositionals extends import("./types.js").PositionalsSchema = import("./types.js").PositionalsSchema, TTransforms extends import("./types.js").TransformsConfig<any, any, any, any> | undefined = undefined>(config: import("./types.js").CommandConfig<TOptions, TPositionals, TTransforms>) => import("./types.js").CommandConfig<TOptions, TPositionals, TTransforms>;
-    count: (props?: Omit<import("./types.js").CountOption, "type">) => import("./types.js").CountOption;
-    enum: <const T extends readonly string[], P extends Omit<import("./types.js").EnumOption<T[number]>, "choices" | "type"> = Omit<import("./types.js").EnumOption<T[number]>, "type" | "choices">>(choices: T, props?: P) => import("./types.js").EnumOption<T[number]> & P;
-    enumPos: <const T extends readonly string[], P extends Omit<import("./types.js").EnumPositional<T[number]>, "choices" | "type"> = Omit<import("./types.js").EnumPositional<T[number]>, "type" | "choices">>(choices: T, props?: P) => import("./types.js").EnumPositional<T[number]> & P;
-    number: <P extends Omit<import("./types.js").NumberOption, "type"> = Omit<import("./types.js").NumberOption, "type">>(props?: P) => import("./types.js").NumberOption & P;
-    numberPos: (props?: Omit<import("./types.js").NumberPositional, "type">) => import("./types.js").NumberPositional;
-    options: {
-        <A extends import("./types.js").OptionsSchema>(a: A): A;
-        <A extends import("./types.js").OptionsSchema, B extends import("./types.js").OptionsSchema>(a: A, b: B): A & B;
-        <A extends import("./types.js").OptionsSchema, B extends import("./types.js").OptionsSchema, C extends import("./types.js").OptionsSchema>(a: A, b: B, c: C): A & B & C;
-        <A extends import("./types.js").OptionsSchema, B extends import("./types.js").OptionsSchema, C extends import("./types.js").OptionsSchema, D extends import("./types.js").OptionsSchema>(a: A, b: B, c: C, d: D): A & B & C & D;
-        (...schemas: import("./types.js").OptionsSchema[]): import("./types.js").OptionsSchema;
-    };
-    positionals: {
-        <A extends import("./types.js").PositionalDef>(a: A): [A];
-        <A extends import("./types.js").PositionalDef, B extends import("./types.js").PositionalDef>(a: A, b: B): [A, B];
-        <A extends import("./types.js").PositionalDef, B extends import("./types.js").PositionalDef, C extends import("./types.js").PositionalDef>(a: A, b: B, c: C): [A, B, C];
-        <A extends import("./types.js").PositionalDef, B extends import("./types.js").PositionalDef, C extends import("./types.js").PositionalDef, D extends import("./types.js").PositionalDef>(a: A, b: B, c: C, d: D): [A, B, C, D];
-        (...positionals: import("./types.js").PositionalDef[]): import("./types.js").PositionalsSchema;
-    };
-    string: <P extends Omit<import("./types.js").StringOption, "type"> = Omit<import("./types.js").StringOption, "type">>(props?: P) => P & import("./types.js").StringOption;
-    stringPos: (props?: Omit<import("./types.js").StringPositional, "type">) => import("./types.js").StringPositional;
-    variadic: (items: "number" | "string", props?: Omit<import("./types.js").VariadicPositional, "items" | "type">) => import("./types.js").VariadicPositional;
-};
+export { bargs, handle, map, merge } from "./bargs.js";
 export { BargsError, HelpError, ValidationError } from "./errors.js";
 export { generateCommandHelp, generateHelp } from "./help.js";
+export { opt, pos } from "./opt.js";
 export { link, linkifyUrls, supportsHyperlinks } from "./osc.js";
 export { ansi, createStyler, defaultTheme, stripAnsi, themes, } from "./theme.js";
 export type { StyleFn, Styler, Theme, ThemeColors, ThemeInput, } from "./theme.js";
-export type { AnyCommandConfig, ArrayOption, BargsConfig, BargsConfigWithCommands, BargsOptions, BargsResult, BooleanOption, CommandConfig, 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";
+export type { ArrayOption, BooleanOption, CliBuilder, CliResult, Command, CommandDef, CountOption, CreateOptions, EnumOption, EnumPositional, HandlerFn, InferOption, InferOptions, InferPositional, InferPositionals, InferTransformedPositionals, InferTransformedValues, NumberOption, NumberPositional, OptionDef, OptionsSchema, Parser, ParseResult, PositionalDef, PositionalsSchema, PositionalsTransformFn, StringOption, StringPositional, TransformsConfig, ValuesTransformFn, VariadicPositional, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,UAAU,IAAI,cAAc,EAAE,KAAK,IAAI,SAAS,EAAE,mBAAmB;AAG9E;;;GAGG;AACH,eAAO,MAAM,KAAK;;;;;;;;;;;;;;SAsE0yI,GAAG;;;;;;;SAAo1B,GAAG;;;;;CAtEpmK,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;SAgEqyI,GAAG;;;;;;;SAAo1B,GAAG;;;;;CAhE1lK,CAAC;AAG7D,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,eAAe,EAAE,oBAAoB;AAGrE,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,kBAAkB;AAG9D,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,kBAAkB,EAAE,iBAAiB;AAGjE,OAAO,EACL,IAAI,EACJ,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,MAAM,GACP,mBAAmB;AAGpB,YAAY,EACV,OAAO,EACP,MAAM,EACN,KAAK,EACL,WAAW,EACX,UAAU,GACX,mBAAmB;AAGpB,YAAY,EACV,gBAAgB,EAChB,WAAW,EACX,WAAW,EACX,uBAAuB,EACvB,YAAY,EACZ,WAAW,EACX,aAAa,EACb,aAAa,EACb,kBAAkB,EAClB,WAAW,EACX,UAAU,EACV,cAAc,EACd,OAAO,EACP,SAAS,EACT,WAAW,EACX,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,2BAA2B,EAC3B,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,aAAa,EACb,iBAAiB,EACjB,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,GACnB,mBAAmB"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,mBAAmB;AAGvD,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,eAAe,EAAE,oBAAoB;AAGrE,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,kBAAkB;AAG9D,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,iBAAiB;AAGpC,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,kBAAkB,EAAE,iBAAiB;AAGjE,OAAO,EACL,IAAI,EACJ,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,MAAM,GACP,mBAAmB;AAGpB,YAAY,EACV,OAAO,EACP,MAAM,EACN,KAAK,EACL,WAAW,EACX,UAAU,GACX,mBAAmB;AAGpB,YAAY,EAEV,WAAW,EACX,aAAa,EAEb,UAAU,EACV,SAAS,EACT,OAAO,EACP,UAAU,EACV,WAAW,EACX,aAAa,EACb,UAAU,EAEV,cAAc,EACd,SAAS,EAET,WAAW,EACX,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,2BAA2B,EAC3B,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,MAAM,EACN,WAAW,EACX,aAAa,EACb,iBAAiB,EAEjB,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,GACnB,mBAAmB"}

package/dist/index.js

@@ -1,47 +1,37 @@
 /**
  * Main entry point for the bargs CLI argument parser.
  *
- * This module exports the primary `bargs` and `bargsAsync` functions with
- * attached option builder methods (e.g., `bargs.string()`, `bargs.boolean()`),
- * allowing both function-call and builder-namespace usage patterns. It also
- * re-exports all public types, error classes, help generators, theme utilities,
- * and OSC hyperlink functions.
+ * Provides a combinator-style API for building type-safe CLIs.
  *
  * @example
  *
  * ```typescript
- * import { bargs } from 'bargs';
+ * import { bargs, opt, pos } from '@boneskull/bargs';
  *
- * // Use as function
- * const result = bargs({
- *   name: 'myapp',
- *   options: { verbose: bargs.boolean({ aliases: ['v'] }) },
- * });
- *
- * // Access builder namespace
- * const opts = bargs.options({ name: bargs.string() });
+ * await bargs
+ *   .create('my-app', { version: '1.0.0' })
+ *   .globals(opt.options({ verbose: opt.boolean({ aliases: ['v'] }) }))
+ *   .command(
+ *     'greet',
+ *     pos.positionals(pos.string({ name: 'name', required: true })),
+ *     ({ positionals }) => console.log(`Hello, ${positionals[0]}!`),
+ *     'Say hello',
+ *   )
+ *   .parseAsync();
  * ```
  *
  * @packageDocumentation
  */
-import { bargsAsync as bargsAsyncBase, bargs as bargsBase } from "./bargs.js";
-import { opt } from "./opt.js";
-/**
- * Main bargs entry point (sync). Also provides access to all opt builders via
- * bargs.string(), bargs.boolean(), etc.
- */
-export const bargs = Object.assign(bargsBase, opt);
-/**
- * Async bargs entry point. Also provides access to all opt builders via
- * bargsAsync.string(), etc.
- */
-export const bargsAsync = Object.assign(bargsAsyncBase, opt);
-// Re-export errors
+// Main API
+export { bargs, handle, map, merge } from "./bargs.js";
+// Errors
 export { BargsError, HelpError, ValidationError } from "./errors.js";
-// Re-export help generators
+// Help generators
 export { generateCommandHelp, generateHelp } from "./help.js";
-// Re-export OSC utilities for terminal hyperlinks
+// Option and positional builders
+export { opt, pos } from "./opt.js";
+// OSC utilities for terminal hyperlinks
 export { link, linkifyUrls, supportsHyperlinks } from "./osc.js";
-// Re-export theme utilities
+// Theme utilities
 export { ansi, createStyler, defaultTheme, stripAnsi, themes, } from "./theme.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAAE,UAAU,IAAI,cAAc,EAAE,KAAK,IAAI,SAAS,EAAE,mBAAmB;AAC9E,OAAO,EAAE,GAAG,EAAE,iBAAiB;AAE/B;;;GAGG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC;AAEnD;;;GAGG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,CAAC,cAAc,EAAE,GAAG,CAAC,CAAC;AAE7D,mBAAmB;AACnB,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,eAAe,EAAE,oBAAoB;AAErE,4BAA4B;AAC5B,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,kBAAkB;AAE9D,kDAAkD;AAClD,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,kBAAkB,EAAE,iBAAiB;AAEjE,4BAA4B;AAC5B,OAAO,EACL,IAAI,EACJ,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,MAAM,GACP,mBAAmB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,WAAW;AACX,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,mBAAmB;AAEvD,SAAS;AACT,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,eAAe,EAAE,oBAAoB;AAErE,kBAAkB;AAClB,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,kBAAkB;AAE9D,iCAAiC;AACjC,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,iBAAiB;AAEpC,wCAAwC;AACxC,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,kBAAkB,EAAE,iBAAiB;AAEjE,kBAAkB;AAClB,OAAO,EACL,IAAI,EACJ,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,MAAM,GACP,mBAAmB"}

package/dist/opt.cjs

@@ -1,22 +1,19 @@
 "use strict";
 /**
- * Builder functions for defining CLI options, positionals, and commands.
+ * Builder functions for defining CLI options and positionals.
  *
  * Provides ergonomic helpers with full TypeScript type inference for
  * constructing option schemas (`opt.string()`, `opt.boolean()`, `opt.enum()`,
- * etc.), positional schemas (`opt.stringPos()`, `opt.numberPos()`,
- * `opt.variadic()`), and command definitions (`opt.command()`). Includes
- * composition utilities for merging schemas (`opt.options()`,
- * `opt.positionals()`).
+ * etc.) and positional schemas (`opt.stringPos()`, `opt.numberPos()`,
+ * `opt.variadic()`).
  *
  * @packageDocumentation
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.opt = void 0;
+exports.pos = exports.opt = void 0;
 const errors_js_1 = require("./errors.cjs");
 /**
- * Validate that no alias conflicts exist in a merged options schema. Throws
- * BargsError if the same alias is used by multiple options.
+ * Validate that no alias conflicts exist in a merged options schema.
  */
 const validateAliasConflicts = (schema) => {
     const aliasToOption = new Map();
@@ -34,32 +31,56 @@ const validateAliasConflicts = (schema) => {
     }
 };
 /**
- * Compose multiple option schemas into one.
+ * Create a Parser from an options schema that can also merge with existing
+ * parsers.
+ *
+ * Supports two usage patterns:
+ *
+ * 1. Standalone: `opt.options({ ... })` - returns a Parser
+ * 2. Merging: `pos.positionals(...)(opt.options(...))` - merges positionals into
+ *    options
  */
-const optionsImpl = (...schemas) => {
-    const merged = Object.assign({}, ...schemas);
-    validateAliasConflicts(merged);
-    return merged;
+const optionsImpl = (schema) => {
+    validateAliasConflicts(schema);
+    // Create the merge function
+    const merger = (parser) => {
+        const mergedSchema = { ...parser.__optionsSchema, ...schema };
+        validateAliasConflicts(mergedSchema);
+        // Preserve transforms from the incoming parser
+        const transformed = parser;
+        const result = {
+            ...parser,
+            __brand: 'Parser',
+            __optionsSchema: mergedSchema,
+            __values: {},
+        };
+        if (transformed.__transform) {
+            result.__transform = transformed.__transform;
+        }
+        return result;
+    };
+    // Add Parser properties to the function
+    const parserProps = {
+        __brand: 'Parser',
+        __optionsSchema: schema,
+        __positionals: [],
+        __positionalsSchema: [],
+        __values: {},
+    };
+    return Object.assign(merger, parserProps);
 };
-/**
- * Create a positionals schema from positional definitions.
- */
-const positionalsImpl = (...positionals) => positionals;
 /**
  * Namespaced option builders.
  *
- * Provides ergonomic helpers for defining CLI options, positionals, and
- * commands with full TypeScript type inference.
- *
  * @example
  *
  * ```typescript
  * import { opt } from 'bargs';
  *
- * const options = opt.options({
+ * const parser = opt.options({
  *   verbose: opt.boolean({ aliases: ['v'] }),
  *   name: opt.string({ default: 'world' }),
- *   level: opt.enum(['low', 'medium', 'high'] as const),
+ *   level: opt.enum(['low', 'medium', 'high']),
  * });
  * ```
  */
@@ -74,34 +95,12 @@ exports.opt = {
         ...props,
     }),
     /**
-     * Define a boolean option. Props type is preserved to enable default
-     * inference.
+     * Define a boolean option.
      */
     boolean: (props = {}) => ({
         type: 'boolean',
         ...props,
     }),
-    /**
-     * Define a command with proper type inference.
-     *
-     * @example
-     *
-     * ```typescript
-     * const greetCmd = opt.command({
-     *   description: 'Greet someone',
-     *   options: opt.options({
-     *     name: opt.string({ default: 'world' }),
-     *   }),
-     *   transforms: {
-     *     values: (v) => ({ ...v, timestamp: Date.now() }),
-     *   },
-     *   handler: ({ values }) => {
-     *     console.log(`Hello, ${values.name}! (${values.timestamp})`);
-     *   },
-     * });
-     * ```
-     */
-    command: (config) => config,
     /**
      * Define a count option (--verbose --verbose = 2).
      */
@@ -110,9 +109,7 @@ exports.opt = {
         ...props,
     }),
     /**
-     * Define an enum option with string choices. The choices array is inferred as
-     * a tuple of literal types automatically. Props type is preserved to enable
-     * default inference.
+     * Define an enum option with string choices.
      */
     enum: (choices, props = {}) => ({
         choices,
@@ -120,8 +117,7 @@ exports.opt = {
         ...props,
     }),
     /**
-     * Define an enum positional argument with string choices. The choices array
-     * is inferred as a tuple of literal types automatically.
+     * Define an enum positional argument with string choices.
      */
     enumPos: (choices, props = {}) => ({
         choices,
@@ -129,14 +125,12 @@ exports.opt = {
         ...props,
     }),
     /**
-     * Define a number option. Props type is preserved to enable default
-     * inference.
+     * Define a number option.
      */
     number: (props = {}) => ({
         type: 'number',
         ...props,
     }),
-    // ─── Positional Builders ───────────────────────────────────────────
     /**
      * Define a number positional argument.
      */
@@ -145,57 +139,130 @@ exports.opt = {
         ...props,
     }),
     /**
-     * Compose multiple option schemas into one. Later schemas override earlier
-     * ones for duplicate option names. Validates that no alias conflicts exist.
+     * Create a Parser from an options schema.
      *
      * @example
      *
      * ```typescript
-     * // Single schema (identity, enables reuse)
-     * const loggingOpts = opt.options({
+     * const parser = opt.options({
      *   verbose: opt.boolean({ aliases: ['v'] }),
-     *   quiet: opt.boolean({ aliases: ['q'] }),
-     * });
-     *
-     * // Merge multiple schemas
-     * const allOpts = opt.options(loggingOpts, ioOpts, {
-     *   format: opt.enum(['json', 'yaml'] as const),
+     *   name: opt.string({ default: 'world' }),
      * });
+     * // Type: Parser<{ verbose: boolean | undefined, name: string }, []>
      * ```
-     *
-     * @throws BargsError if multiple options use the same alias
      */
     options: optionsImpl,
     /**
-     * Create a positionals schema with proper tuple type inference.
+     * Define a string option.
+     */
+    string: (props = {}) => ({
+        type: 'string',
+        ...props,
+    }),
+    /**
+     * Define a string positional argument.
+     */
+    stringPos: (props = {}) => ({
+        type: 'string',
+        ...props,
+    }),
+    /**
+     * Define a variadic positional (rest args).
+     */
+    variadic: (items, props = {}) => ({
+        items,
+        type: 'variadic',
+        ...props,
+    }),
+};
+/**
+ * Create a Parser from positional definitions that can also merge with existing
+ * parsers.
+ *
+ * Supports two usage patterns:
+ *
+ * 1. Standalone: `pos.positionals(...)` - returns a Parser
+ * 2. Merging: `pos.positionals(...)(opt.options(...))` - merges positionals into
+ *    options
+ */
+const positionalsImpl = (...positionals) => {
+    // Create the merge function - just passes through V2, no intersection needed
+    const merger = (parser) => {
+        // Preserve transforms from the incoming parser
+        const transformed = parser;
+        const result = {
+            ...parser,
+            __brand: 'Parser',
+            __positionals: [],
+            __positionalsSchema: [...parser.__positionalsSchema, ...positionals],
+        };
+        if (transformed.__transform) {
+            result.__transform = transformed.__transform;
+        }
+        return result;
+    };
+    // Add Parser properties to the function
+    // Use empty object {} instead of Record<string, never> for better intersection behavior
+    const parserProps = {
+        __brand: 'Parser',
+        __optionsSchema: {},
+        __positionals: [],
+        __positionalsSchema: positionals,
+        __values: {},
+    };
+    return Object.assign(merger, parserProps);
+};
+/**
+ * Namespaced positional builders.
+ *
+ * @example
+ *
+ * ```typescript
+ * import { pos } from 'bargs';
+ *
+ * const parser = pos.positionals(
+ *   pos.string({ name: 'input', required: true }),
+ *   pos.string({ name: 'output' }),
+ * );
+ * ```
+ */
+exports.pos = {
+    /**
+     * Define an enum positional argument with string choices.
+     */
+    enum: (choices, props = {}) => ({
+        choices,
+        type: 'enum',
+        ...props,
+    }),
+    /**
+     * Define a number positional argument.
+     */
+    number: (props = {}) => ({
+        type: 'number',
+        ...props,
+    }),
+    /**
+     * Create a Parser from positional definitions.
      *
      * @example
      *
      * ```typescript
-     * const positionals = opt.positionals(
-     *   opt.stringPos({ description: 'Input file', required: true }),
-     *   opt.stringPos({ description: 'Output file' }),
+     * const parser = pos.positionals(
+     *   pos.string({ name: 'input', required: true }),
+     *   pos.string({ name: 'output' }),
      * );
+     * // Type: Parser<{}, readonly [string, string | undefined]>
      * ```
      */
     positionals: positionalsImpl,
-    /**
-     * Define a string option. Props type is preserved to enable default
-     * inference.
-     */
-    string: (props = {}) => ({
-        type: 'string',
-        ...props,
-    }),
-    // ─── Composition ───────────────────────────────────────────────────
     /**
      * Define a string positional argument.
      */
-    stringPos: (props = {}) => ({
+    string: (props = {}) => ({
         type: 'string',
         ...props,
     }),
-    // ─── Command Builder ───────────────────────────────────────────────
     /**
      * Define a variadic positional (rest args).
      */

package/dist/opt.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"opt.js","sourceRoot":"","sources":["../src/opt.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"opt.js","sourceRoot":"","sources":["../src/opt.ts"],"names":[],"mappings":"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"}