@boneskull/bargs 0.1.1

package/dist/index.js

@@ -0,0 +1,47 @@
+/**
+ * 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.
+ *
+ * @example
+ *
+ * ```typescript
+ * import { bargs } from '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() });
+ * ```
+ *
+ * @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
+export { BargsError, HelpError, ValidationError } from "./errors.js";
+// Re-export help generators
+export { generateCommandHelp, generateHelp } from "./help.js";
+// Re-export OSC utilities for terminal hyperlinks
+export { link, linkifyUrls, supportsHyperlinks } from "./osc.js";
+// Re-export theme utilities
+export { ansi, createStyler, defaultTheme, stripAnsi, themes, } from "./theme.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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"}

package/dist/opt.cjs

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * Builder functions for defining CLI options, positionals, and commands.
+ *
+ * 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()`).
+ *
+ * @packageDocumentation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+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.
+ */
+const validateAliasConflicts = (schema) => {
+    const aliasToOption = new Map();
+    for (const [optionName, def] of Object.entries(schema)) {
+        if (!def.aliases) {
+            continue;
+        }
+        for (const alias of def.aliases) {
+            const existing = aliasToOption.get(alias);
+            if (existing && existing !== optionName) {
+                throw new errors_js_1.BargsError(`Alias conflict: "-${alias}" is used by both "--${existing}" and "--${optionName}"`);
+            }
+            aliasToOption.set(alias, optionName);
+        }
+    }
+};
+/**
+ * Compose multiple option schemas into one.
+ */
+const optionsImpl = (...schemas) => {
+    const merged = Object.assign({}, ...schemas);
+    validateAliasConflicts(merged);
+    return merged;
+};
+/**
+ * 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({
+ *   verbose: opt.boolean({ aliases: ['v'] }),
+ *   name: opt.string({ default: 'world' }),
+ *   level: opt.enum(['low', 'medium', 'high'] as const),
+ * });
+ * ```
+ */
+exports.opt = {
+    // ─── Option Builders ───────────────────────────────────────────────
+    /**
+     * Define an array option (--flag value --flag value2).
+     */
+    array: (items, props = {}) => ({
+        items,
+        type: 'array',
+        ...props,
+    }),
+    /**
+     * Define a boolean option. Props type is preserved to enable default
+     * inference.
+     */
+    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' }),
+     *   }),
+     *   handler: ({ values }) => {
+     *     console.log(`Hello, ${values.name}!`);
+     *   },
+     * });
+     * ```
+     */
+    command: (config) => config,
+    /**
+     * Define a count option (--verbose --verbose = 2).
+     */
+    count: (props = {}) => ({
+        type: 'count',
+        ...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.
+     */
+    enum: (choices, props = {}) => ({
+        choices,
+        type: 'enum',
+        ...props,
+    }),
+    /**
+     * Define an enum positional argument with string choices. The choices array
+     * is inferred as a tuple of literal types automatically.
+     */
+    enumPos: (choices, props = {}) => ({
+        choices,
+        type: 'enum',
+        ...props,
+    }),
+    /**
+     * Define a number option. Props type is preserved to enable default
+     * inference.
+     */
+    number: (props = {}) => ({
+        type: 'number',
+        ...props,
+    }),
+    // ─── Positional Builders ───────────────────────────────────────────
+    /**
+     * Define a number positional argument.
+     */
+    numberPos: (props = {}) => ({
+        type: 'number',
+        ...props,
+    }),
+    /**
+     * Compose multiple option schemas into one. Later schemas override earlier
+     * ones for duplicate option names. Validates that no alias conflicts exist.
+     *
+     * @example
+     *
+     * ```typescript
+     * // Single schema (identity, enables reuse)
+     * const loggingOpts = 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),
+     * });
+     * ```
+     *
+     * @throws BargsError if multiple options use the same alias
+     */
+    options: optionsImpl,
+    /**
+     * Create a positionals schema with proper tuple type inference.
+     *
+     * @example
+     *
+     * ```typescript
+     * const positionals = opt.positionals(
+     *   opt.stringPos({ description: 'Input file', required: true }),
+     *   opt.stringPos({ description: 'Output file' }),
+     * );
+     * ```
+     */
+    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 = {}) => ({
+        type: 'string',
+        ...props,
+    }),
+    // ─── Command Builder ───────────────────────────────────────────────
+    /**
+     * Define a variadic positional (rest args).
+     */
+    variadic: (items, props = {}) => ({
+        items,
+        type: 'variadic',
+        ...props,
+    }),
+};
+//# sourceMappingURL=opt.js.map

package/dist/opt.cjs.map

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

package/dist/opt.d.cts

@@ -0,0 +1,145 @@
+/**
+ * Builder functions for defining CLI options, positionals, and commands.
+ *
+ * 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()`).
+ *
+ * @packageDocumentation
+ */
+import type { ArrayOption, BooleanOption, CommandConfig, CountOption, EnumOption, EnumPositional, NumberOption, NumberPositional, OptionsSchema, PositionalDef, PositionalsSchema, StringOption, StringPositional, VariadicPositional } from "./types.cjs";
+/**
+ * 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({
+ *   verbose: opt.boolean({ aliases: ['v'] }),
+ *   name: opt.string({ default: 'world' }),
+ *   level: opt.enum(['low', 'medium', 'high'] as const),
+ * });
+ * ```
+ */
+export declare const opt: {
+    /**
+     * Define an array option (--flag value --flag value2).
+     */
+    array: (items: "number" | "string", props?: Omit<ArrayOption, "items" | "type">) => ArrayOption;
+    /**
+     * Define a boolean option. Props type is preserved to enable default
+     * inference.
+     */
+    boolean: <P extends Omit<BooleanOption, "type"> = Omit<BooleanOption, "type">>(props?: P) => BooleanOption & P;
+    /**
+     * Define a command with proper type inference.
+     *
+     * @example
+     *
+     * ```typescript
+     * const greetCmd = opt.command({
+     *   description: 'Greet someone',
+     *   options: opt.options({
+     *     name: opt.string({ default: 'world' }),
+     *   }),
+     *   handler: ({ values }) => {
+     *     console.log(`Hello, ${values.name}!`);
+     *   },
+     * });
+     * ```
+     */
+    command: <TOptions extends OptionsSchema = OptionsSchema, TPositionals extends PositionalsSchema = PositionalsSchema>(config: CommandConfig<TOptions, TPositionals>) => CommandConfig<TOptions, TPositionals>;
+    /**
+     * Define a count option (--verbose --verbose = 2).
+     */
+    count: (props?: Omit<CountOption, "type">) => CountOption;
+    /**
+     * 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.
+     */
+    enum: <const T extends readonly string[], P extends Omit<EnumOption<T[number]>, "choices" | "type"> = Omit<EnumOption<T[number]>, "type" | "choices">>(choices: T, props?: P) => EnumOption<T[number]> & P;
+    /**
+     * Define an enum positional argument with string choices. The choices array
+     * is inferred as a tuple of literal types automatically.
+     */
+    enumPos: <const T extends readonly string[], P extends Omit<EnumPositional<T[number]>, "choices" | "type"> = Omit<EnumPositional<T[number]>, "type" | "choices">>(choices: T, props?: P) => EnumPositional<T[number]> & P;
+    /**
+     * Define a number option. Props type is preserved to enable default
+     * inference.
+     */
+    number: <P extends Omit<NumberOption, "type"> = Omit<NumberOption, "type">>(props?: P) => NumberOption & P;
+    /**
+     * Define a number positional argument.
+     */
+    numberPos: (props?: Omit<NumberPositional, "type">) => NumberPositional;
+    /**
+     * Compose multiple option schemas into one. Later schemas override earlier
+     * ones for duplicate option names. Validates that no alias conflicts exist.
+     *
+     * @example
+     *
+     * ```typescript
+     * // Single schema (identity, enables reuse)
+     * const loggingOpts = 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),
+     * });
+     * ```
+     *
+     * @throws BargsError if multiple options use the same alias
+     */
+    options: {
+        <A extends OptionsSchema>(a: A): A;
+        <A extends OptionsSchema, B extends OptionsSchema>(a: A, b: B): A & B;
+        <A extends OptionsSchema, B extends OptionsSchema, C extends OptionsSchema>(a: A, b: B, c: C): A & B & C;
+        <A extends OptionsSchema, B extends OptionsSchema, C extends OptionsSchema, D extends OptionsSchema>(a: A, b: B, c: C, d: D): A & B & C & D;
+        (...schemas: OptionsSchema[]): OptionsSchema;
+    };
+    /**
+     * Create a positionals schema with proper tuple type inference.
+     *
+     * @example
+     *
+     * ```typescript
+     * const positionals = opt.positionals(
+     *   opt.stringPos({ description: 'Input file', required: true }),
+     *   opt.stringPos({ description: 'Output file' }),
+     * );
+     * ```
+     */
+    positionals: {
+        <A extends PositionalDef>(a: A): [A];
+        <A extends PositionalDef, B extends PositionalDef>(a: A, b: B): [A, B];
+        <A extends PositionalDef, B extends PositionalDef, C extends PositionalDef>(a: A, b: B, c: C): [A, B, C];
+        <A extends PositionalDef, B extends PositionalDef, C extends PositionalDef, D extends PositionalDef>(a: A, b: B, c: C, d: D): [A, B, C, D];
+        (...positionals: PositionalDef[]): PositionalsSchema;
+    };
+    /**
+     * Define a string option. Props type is preserved to enable default
+     * inference.
+     */
+    string: <P extends Omit<StringOption, "type"> = Omit<StringOption, "type">>(props?: P) => P & StringOption;
+    /**
+     * Define a string positional argument.
+     */
+    stringPos: (props?: Omit<StringPositional, "type">) => StringPositional;
+    /**
+     * Define a variadic positional (rest args).
+     */
+    variadic: (items: "number" | "string", props?: Omit<VariadicPositional, "items" | "type">) => VariadicPositional;
+};
+//# sourceMappingURL=opt.d.ts.map

package/dist/opt.d.cts.map

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

package/dist/opt.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Builder functions for defining CLI options, positionals, and commands.
+ *
+ * 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()`).
+ *
+ * @packageDocumentation
+ */
+import type { ArrayOption, BooleanOption, CommandConfig, CountOption, EnumOption, EnumPositional, NumberOption, NumberPositional, OptionsSchema, PositionalDef, PositionalsSchema, StringOption, StringPositional, VariadicPositional } from "./types.js";
+/**
+ * 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({
+ *   verbose: opt.boolean({ aliases: ['v'] }),
+ *   name: opt.string({ default: 'world' }),
+ *   level: opt.enum(['low', 'medium', 'high'] as const),
+ * });
+ * ```
+ */
+export declare const opt: {
+    /**
+     * Define an array option (--flag value --flag value2).
+     */
+    array: (items: "number" | "string", props?: Omit<ArrayOption, "items" | "type">) => ArrayOption;
+    /**
+     * Define a boolean option. Props type is preserved to enable default
+     * inference.
+     */
+    boolean: <P extends Omit<BooleanOption, "type"> = Omit<BooleanOption, "type">>(props?: P) => BooleanOption & P;
+    /**
+     * Define a command with proper type inference.
+     *
+     * @example
+     *
+     * ```typescript
+     * const greetCmd = opt.command({
+     *   description: 'Greet someone',
+     *   options: opt.options({
+     *     name: opt.string({ default: 'world' }),
+     *   }),
+     *   handler: ({ values }) => {
+     *     console.log(`Hello, ${values.name}!`);
+     *   },
+     * });
+     * ```
+     */
+    command: <TOptions extends OptionsSchema = OptionsSchema, TPositionals extends PositionalsSchema = PositionalsSchema>(config: CommandConfig<TOptions, TPositionals>) => CommandConfig<TOptions, TPositionals>;
+    /**
+     * Define a count option (--verbose --verbose = 2).
+     */
+    count: (props?: Omit<CountOption, "type">) => CountOption;
+    /**
+     * 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.
+     */
+    enum: <const T extends readonly string[], P extends Omit<EnumOption<T[number]>, "choices" | "type"> = Omit<EnumOption<T[number]>, "type" | "choices">>(choices: T, props?: P) => EnumOption<T[number]> & P;
+    /**
+     * Define an enum positional argument with string choices. The choices array
+     * is inferred as a tuple of literal types automatically.
+     */
+    enumPos: <const T extends readonly string[], P extends Omit<EnumPositional<T[number]>, "choices" | "type"> = Omit<EnumPositional<T[number]>, "type" | "choices">>(choices: T, props?: P) => EnumPositional<T[number]> & P;
+    /**
+     * Define a number option. Props type is preserved to enable default
+     * inference.
+     */
+    number: <P extends Omit<NumberOption, "type"> = Omit<NumberOption, "type">>(props?: P) => NumberOption & P;
+    /**
+     * Define a number positional argument.
+     */
+    numberPos: (props?: Omit<NumberPositional, "type">) => NumberPositional;
+    /**
+     * Compose multiple option schemas into one. Later schemas override earlier
+     * ones for duplicate option names. Validates that no alias conflicts exist.
+     *
+     * @example
+     *
+     * ```typescript
+     * // Single schema (identity, enables reuse)
+     * const loggingOpts = 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),
+     * });
+     * ```
+     *
+     * @throws BargsError if multiple options use the same alias
+     */
+    options: {
+        <A extends OptionsSchema>(a: A): A;
+        <A extends OptionsSchema, B extends OptionsSchema>(a: A, b: B): A & B;
+        <A extends OptionsSchema, B extends OptionsSchema, C extends OptionsSchema>(a: A, b: B, c: C): A & B & C;
+        <A extends OptionsSchema, B extends OptionsSchema, C extends OptionsSchema, D extends OptionsSchema>(a: A, b: B, c: C, d: D): A & B & C & D;
+        (...schemas: OptionsSchema[]): OptionsSchema;
+    };
+    /**
+     * Create a positionals schema with proper tuple type inference.
+     *
+     * @example
+     *
+     * ```typescript
+     * const positionals = opt.positionals(
+     *   opt.stringPos({ description: 'Input file', required: true }),
+     *   opt.stringPos({ description: 'Output file' }),
+     * );
+     * ```
+     */
+    positionals: {
+        <A extends PositionalDef>(a: A): [A];
+        <A extends PositionalDef, B extends PositionalDef>(a: A, b: B): [A, B];
+        <A extends PositionalDef, B extends PositionalDef, C extends PositionalDef>(a: A, b: B, c: C): [A, B, C];
+        <A extends PositionalDef, B extends PositionalDef, C extends PositionalDef, D extends PositionalDef>(a: A, b: B, c: C, d: D): [A, B, C, D];
+        (...positionals: PositionalDef[]): PositionalsSchema;
+    };
+    /**
+     * Define a string option. Props type is preserved to enable default
+     * inference.
+     */
+    string: <P extends Omit<StringOption, "type"> = Omit<StringOption, "type">>(props?: P) => P & StringOption;
+    /**
+     * Define a string positional argument.
+     */
+    stringPos: (props?: Omit<StringPositional, "type">) => StringPositional;
+    /**
+     * Define a variadic positional (rest args).
+     */
+    variadic: (items: "number" | "string", props?: Omit<VariadicPositional, "items" | "type">) => VariadicPositional;
+};
+//# sourceMappingURL=opt.d.ts.map

package/dist/opt.d.ts.map

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