@boneskull/bargs 0.1.1

package/dist/types.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;GAcG"}

package/dist/types.d.cts

@@ -0,0 +1,244 @@
+/**
+ * TypeScript type definitions for the bargs CLI argument parser.
+ *
+ * Defines all public interfaces and types including:
+ *
+ * - Option definitions (`StringOption`, `BooleanOption`, `EnumOption`, etc.)
+ * - Positional definitions (`StringPositional`, `VariadicPositional`, etc.)
+ * - Schema types (`OptionsSchema`, `PositionalsSchema`)
+ * - Configuration types (`BargsConfig`, `BargsConfigWithCommands`)
+ * - Command types (`CommandConfig`, `CommandConfigInput`)
+ * - Type inference utilities (`InferOptions`, `InferPositionals`)
+ * - Result types (`BargsResult`)
+ *
+ * @packageDocumentation
+ */
+import type { ThemeInput } from "./theme.cjs";
+/**
+ * Any command config (type-erased for collections). Uses a permissive handler
+ * type to avoid variance issues.
+ */
+export interface AnyCommandConfig {
+    description: string;
+    handler: ((result: any) => Promise<void> | void)[] | ((result: any) => Promise<void> | void);
+    options?: OptionsSchema;
+    positionals?: PositionalsSchema;
+}
+/**
+ * Array option definition (--flag value --flag value2).
+ */
+export interface ArrayOption extends OptionBase {
+    default?: number[] | string[];
+    /** Element type of the array */
+    items: 'number' | 'string';
+    type: 'array';
+}
+/**
+ * Main bargs configuration.
+ */
+export interface BargsConfig<TOptions extends OptionsSchema = OptionsSchema, TPositionals extends PositionalsSchema = PositionalsSchema, TCommands extends Record<string, AnyCommandConfig> | undefined = undefined> {
+    args?: string[];
+    commands?: TCommands;
+    description?: string;
+    /**
+     * Epilog text shown after help output. By default, shows homepage and
+     * repository URLs from package.json if available. Set to `false` or empty
+     * string to disable.
+     */
+    epilog?: false | string;
+    handler?: Handler<BargsResult<InferOptions<TOptions>, InferPositionals<TPositionals>, undefined>>;
+    name: string;
+    options?: TOptions;
+    positionals?: TPositionals;
+    version?: string;
+}
+/**
+ * Bargs config with commands (requires commands, allows defaultHandler).
+ *
+ * Commands can be defined in two ways:
+ *
+ * 1. Using opt.command() - handler receives local options only (legacy)
+ * 2. Inline definition - handler can receive both global and local options
+ *
+ * Note: Top-level `positionals` is not allowed for command-based CLIs. Each
+ * command defines its own positionals.
+ */
+export type BargsConfigWithCommands<TOptions extends OptionsSchema = OptionsSchema, TCommands extends Record<string, CommandConfigInput> = Record<string, CommandConfigInput>> = Omit<BargsConfig<TOptions, PositionalsSchema, TCommands>, 'handler' | 'positionals'> & {
+    commands: TCommands;
+    defaultHandler?: Handler<BargsResult<InferOptions<TOptions>, [], undefined>> | keyof TCommands;
+};
+/**
+ * Runtime options for bargs (separate from parsing config).
+ */
+export interface BargsOptions {
+    /** Color theme for help output */
+    theme?: ThemeInput;
+}
+/**
+ * Result from parsing CLI arguments.
+ */
+export interface BargsResult<TValues = Record<string, unknown>, TPositionals extends readonly unknown[] = [], TCommand extends string | undefined = string | undefined> {
+    command: TCommand;
+    positionals: TPositionals;
+    values: TValues;
+}
+/**
+ * Boolean option definition.
+ */
+export interface BooleanOption extends OptionBase {
+    default?: boolean;
+    type: 'boolean';
+}
+/**
+ * Command configuration.
+ *
+ * The handler receives typed local options plus access to global options (as
+ * Record<string, unknown>). Global options are available at runtime but require
+ * type narrowing to access safely.
+ */
+export interface CommandConfig<TOptions extends OptionsSchema = OptionsSchema, TPositionals extends PositionalsSchema = PositionalsSchema> {
+    description: string;
+    handler: Handler<BargsResult<InferOptions<TOptions> & Record<string, unknown>, InferPositionals<TPositionals>, string>>;
+    options?: TOptions;
+    positionals?: TPositionals;
+}
+/**
+ * Command config input type for inline command definitions. The handler type is
+ * intentionally loose here - it accepts any result type, allowing commands
+ * defined with opt.command() or inline to work.
+ */
+export interface CommandConfigInput {
+    description: string;
+    handler: Handler<any>;
+    options?: OptionsSchema;
+    positionals?: PositionalsSchema;
+}
+/**
+ * Count option definition (--verbose --verbose = 2).
+ */
+export interface CountOption extends OptionBase {
+    default?: number;
+    type: 'count';
+}
+/**
+ * Enum option definition with string choices.
+ */
+export interface EnumOption<T extends string = string> extends OptionBase {
+    choices: readonly T[];
+    default?: T;
+    type: 'enum';
+}
+/**
+ * Enum positional definition with string choices.
+ */
+export interface EnumPositional<T extends string = string> extends PositionalBase {
+    choices: readonly T[];
+    default?: T;
+    type: 'enum';
+}
+/**
+ * Handler - either a single function or an array of functions. When an array is
+ * provided, handlers run sequentially in order.
+ */
+export type Handler<TResult> = HandlerFn<TResult> | HandlerFn<TResult>[];
+/**
+ * Single handler function signature.
+ */
+export type HandlerFn<TResult> = (result: TResult) => Promise<void> | void;
+/**
+ * Infer the TypeScript type from an option definition.
+ */
+export type InferOption<T extends OptionDef> = T extends BooleanOption ? T['required'] extends true ? boolean : T['default'] extends boolean ? boolean : boolean | undefined : T extends NumberOption ? T['required'] extends true ? number : T['default'] extends number ? number : number | undefined : T extends StringOption ? T['required'] extends true ? string : T['default'] extends string ? string : string | undefined : T extends EnumOption<infer E> ? T['required'] extends true ? E : T['default'] extends E ? E : E | undefined : T extends ArrayOption ? T['items'] extends 'number' ? number[] : string[] : T extends CountOption ? number : never;
+/**
+ * Infer values type from an options schema.
+ */
+export type InferOptions<T extends OptionsSchema> = {
+    [K in keyof T]: InferOption<T[K]>;
+};
+/**
+ * Infer a single positional's type.
+ */
+export type InferPositional<T extends PositionalDef> = T extends NumberPositional ? T['required'] extends true ? number : T['default'] extends number ? number : number | undefined : T extends StringPositional ? T['required'] extends true ? string : T['default'] extends string ? string : string | undefined : T extends EnumPositional<infer E> ? T['required'] extends true ? E : T['default'] extends E ? E : E | undefined : T extends VariadicPositional ? T['items'] extends 'number' ? number[] : string[] : never;
+/**
+ * Infer positionals tuple type from schema.
+ */
+export type InferPositionals<T extends PositionalsSchema> = {
+    [K in keyof T]: T[K] extends PositionalDef ? InferPositional<T[K]> : never;
+};
+/**
+ * Number option definition.
+ */
+export interface NumberOption extends OptionBase {
+    default?: number;
+    type: 'number';
+}
+/**
+ * Number positional.
+ */
+export interface NumberPositional extends PositionalBase {
+    default?: number;
+    type: 'number';
+}
+/**
+ * Union of all option definitions.
+ */
+export type OptionDef = ArrayOption | BooleanOption | CountOption | EnumOption<string> | NumberOption | StringOption;
+/**
+ * Options schema: a record of option names to their definitions.
+ */
+export type OptionsSchema = Record<string, OptionDef>;
+/**
+ * Union of positional definitions.
+ */
+export type PositionalDef = EnumPositional<string> | NumberPositional | StringPositional | VariadicPositional;
+/**
+ * Positionals can be a tuple (ordered) or a single variadic.
+ */
+export type PositionalsSchema = PositionalDef[];
+/**
+ * String option definition.
+ */
+export interface StringOption extends OptionBase {
+    default?: string;
+    type: 'string';
+}
+/**
+ * String positional.
+ */
+export interface StringPositional extends PositionalBase {
+    default?: string;
+    type: 'string';
+}
+/**
+ * Variadic positional (rest args).
+ */
+export interface VariadicPositional extends PositionalBase {
+    items: 'number' | 'string';
+    type: 'variadic';
+}
+/**
+ * Base properties shared by all option definitions.
+ */
+interface OptionBase {
+    /** Aliases for this option (e.g., ['v'] for --verbose) */
+    aliases?: string[];
+    /** Option description displayed in help text */
+    description?: string;
+    /** Group name for help text organization */
+    group?: string;
+    /** Whether this option is hidden from help */
+    hidden?: boolean;
+    /** Whether this option is required */
+    required?: boolean;
+}
+/**
+ * Base properties for positional definitions.
+ */
+interface PositionalBase {
+    description?: string;
+    /** Display name for help text (defaults to arg0, arg1, etc.) */
+    name?: string;
+    required?: boolean;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.cts.map

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

package/dist/types.d.ts

@@ -0,0 +1,244 @@
+/**
+ * TypeScript type definitions for the bargs CLI argument parser.
+ *
+ * Defines all public interfaces and types including:
+ *
+ * - Option definitions (`StringOption`, `BooleanOption`, `EnumOption`, etc.)
+ * - Positional definitions (`StringPositional`, `VariadicPositional`, etc.)
+ * - Schema types (`OptionsSchema`, `PositionalsSchema`)
+ * - Configuration types (`BargsConfig`, `BargsConfigWithCommands`)
+ * - Command types (`CommandConfig`, `CommandConfigInput`)
+ * - Type inference utilities (`InferOptions`, `InferPositionals`)
+ * - Result types (`BargsResult`)
+ *
+ * @packageDocumentation
+ */
+import type { ThemeInput } from "./theme.js";
+/**
+ * Any command config (type-erased for collections). Uses a permissive handler
+ * type to avoid variance issues.
+ */
+export interface AnyCommandConfig {
+    description: string;
+    handler: ((result: any) => Promise<void> | void)[] | ((result: any) => Promise<void> | void);
+    options?: OptionsSchema;
+    positionals?: PositionalsSchema;
+}
+/**
+ * Array option definition (--flag value --flag value2).
+ */
+export interface ArrayOption extends OptionBase {
+    default?: number[] | string[];
+    /** Element type of the array */
+    items: 'number' | 'string';
+    type: 'array';
+}
+/**
+ * Main bargs configuration.
+ */
+export interface BargsConfig<TOptions extends OptionsSchema = OptionsSchema, TPositionals extends PositionalsSchema = PositionalsSchema, TCommands extends Record<string, AnyCommandConfig> | undefined = undefined> {
+    args?: string[];
+    commands?: TCommands;
+    description?: string;
+    /**
+     * Epilog text shown after help output. By default, shows homepage and
+     * repository URLs from package.json if available. Set to `false` or empty
+     * string to disable.
+     */
+    epilog?: false | string;
+    handler?: Handler<BargsResult<InferOptions<TOptions>, InferPositionals<TPositionals>, undefined>>;
+    name: string;
+    options?: TOptions;
+    positionals?: TPositionals;
+    version?: string;
+}
+/**
+ * Bargs config with commands (requires commands, allows defaultHandler).
+ *
+ * Commands can be defined in two ways:
+ *
+ * 1. Using opt.command() - handler receives local options only (legacy)
+ * 2. Inline definition - handler can receive both global and local options
+ *
+ * Note: Top-level `positionals` is not allowed for command-based CLIs. Each
+ * command defines its own positionals.
+ */
+export type BargsConfigWithCommands<TOptions extends OptionsSchema = OptionsSchema, TCommands extends Record<string, CommandConfigInput> = Record<string, CommandConfigInput>> = Omit<BargsConfig<TOptions, PositionalsSchema, TCommands>, 'handler' | 'positionals'> & {
+    commands: TCommands;
+    defaultHandler?: Handler<BargsResult<InferOptions<TOptions>, [], undefined>> | keyof TCommands;
+};
+/**
+ * Runtime options for bargs (separate from parsing config).
+ */
+export interface BargsOptions {
+    /** Color theme for help output */
+    theme?: ThemeInput;
+}
+/**
+ * Result from parsing CLI arguments.
+ */
+export interface BargsResult<TValues = Record<string, unknown>, TPositionals extends readonly unknown[] = [], TCommand extends string | undefined = string | undefined> {
+    command: TCommand;
+    positionals: TPositionals;
+    values: TValues;
+}
+/**
+ * Boolean option definition.
+ */
+export interface BooleanOption extends OptionBase {
+    default?: boolean;
+    type: 'boolean';
+}
+/**
+ * Command configuration.
+ *
+ * The handler receives typed local options plus access to global options (as
+ * Record<string, unknown>). Global options are available at runtime but require
+ * type narrowing to access safely.
+ */
+export interface CommandConfig<TOptions extends OptionsSchema = OptionsSchema, TPositionals extends PositionalsSchema = PositionalsSchema> {
+    description: string;
+    handler: Handler<BargsResult<InferOptions<TOptions> & Record<string, unknown>, InferPositionals<TPositionals>, string>>;
+    options?: TOptions;
+    positionals?: TPositionals;
+}
+/**
+ * Command config input type for inline command definitions. The handler type is
+ * intentionally loose here - it accepts any result type, allowing commands
+ * defined with opt.command() or inline to work.
+ */
+export interface CommandConfigInput {
+    description: string;
+    handler: Handler<any>;
+    options?: OptionsSchema;
+    positionals?: PositionalsSchema;
+}
+/**
+ * Count option definition (--verbose --verbose = 2).
+ */
+export interface CountOption extends OptionBase {
+    default?: number;
+    type: 'count';
+}
+/**
+ * Enum option definition with string choices.
+ */
+export interface EnumOption<T extends string = string> extends OptionBase {
+    choices: readonly T[];
+    default?: T;
+    type: 'enum';
+}
+/**
+ * Enum positional definition with string choices.
+ */
+export interface EnumPositional<T extends string = string> extends PositionalBase {
+    choices: readonly T[];
+    default?: T;
+    type: 'enum';
+}
+/**
+ * Handler - either a single function or an array of functions. When an array is
+ * provided, handlers run sequentially in order.
+ */
+export type Handler<TResult> = HandlerFn<TResult> | HandlerFn<TResult>[];
+/**
+ * Single handler function signature.
+ */
+export type HandlerFn<TResult> = (result: TResult) => Promise<void> | void;
+/**
+ * Infer the TypeScript type from an option definition.
+ */
+export type InferOption<T extends OptionDef> = T extends BooleanOption ? T['required'] extends true ? boolean : T['default'] extends boolean ? boolean : boolean | undefined : T extends NumberOption ? T['required'] extends true ? number : T['default'] extends number ? number : number | undefined : T extends StringOption ? T['required'] extends true ? string : T['default'] extends string ? string : string | undefined : T extends EnumOption<infer E> ? T['required'] extends true ? E : T['default'] extends E ? E : E | undefined : T extends ArrayOption ? T['items'] extends 'number' ? number[] : string[] : T extends CountOption ? number : never;
+/**
+ * Infer values type from an options schema.
+ */
+export type InferOptions<T extends OptionsSchema> = {
+    [K in keyof T]: InferOption<T[K]>;
+};
+/**
+ * Infer a single positional's type.
+ */
+export type InferPositional<T extends PositionalDef> = T extends NumberPositional ? T['required'] extends true ? number : T['default'] extends number ? number : number | undefined : T extends StringPositional ? T['required'] extends true ? string : T['default'] extends string ? string : string | undefined : T extends EnumPositional<infer E> ? T['required'] extends true ? E : T['default'] extends E ? E : E | undefined : T extends VariadicPositional ? T['items'] extends 'number' ? number[] : string[] : never;
+/**
+ * Infer positionals tuple type from schema.
+ */
+export type InferPositionals<T extends PositionalsSchema> = {
+    [K in keyof T]: T[K] extends PositionalDef ? InferPositional<T[K]> : never;
+};
+/**
+ * Number option definition.
+ */
+export interface NumberOption extends OptionBase {
+    default?: number;
+    type: 'number';
+}
+/**
+ * Number positional.
+ */
+export interface NumberPositional extends PositionalBase {
+    default?: number;
+    type: 'number';
+}
+/**
+ * Union of all option definitions.
+ */
+export type OptionDef = ArrayOption | BooleanOption | CountOption | EnumOption<string> | NumberOption | StringOption;
+/**
+ * Options schema: a record of option names to their definitions.
+ */
+export type OptionsSchema = Record<string, OptionDef>;
+/**
+ * Union of positional definitions.
+ */
+export type PositionalDef = EnumPositional<string> | NumberPositional | StringPositional | VariadicPositional;
+/**
+ * Positionals can be a tuple (ordered) or a single variadic.
+ */
+export type PositionalsSchema = PositionalDef[];
+/**
+ * String option definition.
+ */
+export interface StringOption extends OptionBase {
+    default?: string;
+    type: 'string';
+}
+/**
+ * String positional.
+ */
+export interface StringPositional extends PositionalBase {
+    default?: string;
+    type: 'string';
+}
+/**
+ * Variadic positional (rest args).
+ */
+export interface VariadicPositional extends PositionalBase {
+    items: 'number' | 'string';
+    type: 'variadic';
+}
+/**
+ * Base properties shared by all option definitions.
+ */
+interface OptionBase {
+    /** Aliases for this option (e.g., ['v'] for --verbose) */
+    aliases?: string[];
+    /** Option description displayed in help text */
+    description?: string;
+    /** Group name for help text organization */
+    group?: string;
+    /** Whether this option is hidden from help */
+    hidden?: boolean;
+    /** Whether this option is required */
+    required?: boolean;
+}
+/**
+ * Base properties for positional definitions.
+ */
+interface PositionalBase {
+    description?: string;
+    /** Display name for help text (defaults to arg0, arg1, etc.) */
+    name?: string;
+    required?: boolean;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,mBAAmB;AAE7C;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IAEpB,OAAO,EACH,CAAC,CAAC,MAAM,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,EAAE,GACzC,CAAC,CAAC,MAAM,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC;IAC5C,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,WAAW,CAAC,EAAE,iBAAiB,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC7C,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;IAC9B,gCAAgC;IAChC,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC3B,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,WAAW,CAC1B,QAAQ,SAAS,aAAa,GAAG,aAAa,EAC9C,YAAY,SAAS,iBAAiB,GAAG,iBAAiB,EAC1D,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAAG,SAAS,GAAG,SAAS;IAE1E,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,CACf,WAAW,CACT,YAAY,CAAC,QAAQ,CAAC,EACtB,gBAAgB,CAAC,YAAY,CAAC,EAC9B,SAAS,CACV,CACF,CAAC;IACF,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,uBAAuB,CACjC,QAAQ,SAAS,aAAa,GAAG,aAAa,EAC9C,SAAS,SAAS,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,GAAG,MAAM,CAC3D,MAAM,EACN,kBAAkB,CACnB,IACC,IAAI,CACN,WAAW,CAAC,QAAQ,EAAE,iBAAiB,EAAE,SAAS,CAAC,EACnD,SAAS,GAAG,aAAa,CAC1B,GAAG;IACF,QAAQ,EAAE,SAAS,CAAC;IACpB,cAAc,CAAC,EACX,OAAO,CAAC,WAAW,CAAC,YAAY,CAAC,QAAQ,CAAC,EAAE,EAAE,EAAE,SAAS,CAAC,CAAC,GAC3D,MAAM,SAAS,CAAC;CACrB,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,kCAAkC;IAClC,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW,CAC1B,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,YAAY,SAAS,SAAS,OAAO,EAAE,GAAG,EAAE,EAC5C,QAAQ,SAAS,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS;IAExD,OAAO,EAAE,QAAQ,CAAC;IAClB,WAAW,EAAE,YAAY,CAAC;IAC1B,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,aAAc,SAAQ,UAAU;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,SAAS,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa,CAC5B,QAAQ,SAAS,aAAa,GAAG,aAAa,EAC9C,YAAY,SAAS,iBAAiB,GAAG,iBAAiB;IAE1D,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CACd,WAAW,CACT,YAAY,CAAC,QAAQ,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChD,gBAAgB,CAAC,YAAY,CAAC,EAC9B,MAAM,CACP,CACF,CAAC;IACF,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,WAAW,CAAC,EAAE,YAAY,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IACtB,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,WAAW,CAAC,EAAE,iBAAiB,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,UAAU;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,UAAU;IACvE,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;IACtB,OAAO,CAAC,EAAE,CAAC,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;GAEG;AACH,MAAM,WAAW,cAAc,CAC7B,CAAC,SAAS,MAAM,GAAG,MAAM,CACzB,SAAQ,cAAc;IACtB,OAAO,EAAE,SAAS,CAAC,EAAE,CAAC;IACtB,OAAO,CAAC,EAAE,CAAC,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,MAAM,OAAO,CAAC,OAAO,IAAI,SAAS,CAAC,OAAO,CAAC,GAAG,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;AAEzE;;GAEG;AACH,MAAM,MAAM,SAAS,CAAC,OAAO,IAAI,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAE3E;;GAEG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,SAAS,IAAI,CAAC,SAAS,aAAa,GAClE,CAAC,CAAC,UAAU,CAAC,SAAS,IAAI,GACxB,OAAO,GACP,CAAC,CAAC,SAAS,CAAC,SAAS,OAAO,GAC1B,OAAO,GACP,OAAO,GAAG,SAAS,GACvB,CAAC,SAAS,YAAY,GACpB,CAAC,CAAC,UAAU,CAAC,SAAS,IAAI,GACxB,MAAM,GACN,CAAC,CAAC,SAAS,CAAC,SAAS,MAAM,GACzB,MAAM,GACN,MAAM,GAAG,SAAS,GACtB,CAAC,SAAS,YAAY,GACpB,CAAC,CAAC,UAAU,CAAC,SAAS,IAAI,GACxB,MAAM,GACN,CAAC,CAAC,SAAS,CAAC,SAAS,MAAM,GACzB,MAAM,GACN,MAAM,GAAG,SAAS,GACtB,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,CAAC,GAC3B,CAAC,CAAC,UAAU,CAAC,SAAS,IAAI,GACxB,CAAC,GACD,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,GACpB,CAAC,GACD,CAAC,GAAG,SAAS,GACjB,CAAC,SAAS,WAAW,GACnB,CAAC,CAAC,OAAO,CAAC,SAAS,QAAQ,GACzB,MAAM,EAAE,GACR,MAAM,EAAE,GACV,CAAC,SAAS,WAAW,GACnB,MAAM,GACN,KAAK,CAAC;AAEpB;;GAEG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,aAAa,IAAI;KACjD,CAAC,IAAI,MAAM,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAClC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,aAAa,IACjD,CAAC,SAAS,gBAAgB,GACtB,CAAC,CAAC,UAAU,CAAC,SAAS,IAAI,GACxB,MAAM,GACN,CAAC,CAAC,SAAS,CAAC,SAAS,MAAM,GACzB,MAAM,GACN,MAAM,GAAG,SAAS,GACtB,CAAC,SAAS,gBAAgB,GACxB,CAAC,CAAC,UAAU,CAAC,SAAS,IAAI,GACxB,MAAM,GACN,CAAC,CAAC,SAAS,CAAC,SAAS,MAAM,GACzB,MAAM,GACN,MAAM,GAAG,SAAS,GACtB,CAAC,SAAS,cAAc,CAAC,MAAM,CAAC,CAAC,GAC/B,CAAC,CAAC,UAAU,CAAC,SAAS,IAAI,GACxB,CAAC,GACD,CAAC,CAAC,SAAS,CAAC,SAAS,CAAC,GACpB,CAAC,GACD,CAAC,GAAG,SAAS,GACjB,CAAC,SAAS,kBAAkB,GAC1B,CAAC,CAAC,OAAO,CAAC,SAAS,QAAQ,GACzB,MAAM,EAAE,GACR,MAAM,EAAE,GACV,KAAK,CAAC;AAElB;;GAEG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,iBAAiB,IAAI;KACzD,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,aAAa,GAAG,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,KAAK;CAC3E,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,MAAM,SAAS,GACjB,WAAW,GACX,aAAa,GACb,WAAW,GACX,UAAU,CAAC,MAAM,CAAC,GAClB,YAAY,GACZ,YAAY,CAAC;AAEjB;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,aAAa,GACrB,cAAc,CAAC,MAAM,CAAC,GACtB,gBAAgB,GAChB,gBAAgB,GAChB,kBAAkB,CAAC;AAEvB;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,aAAa,EAAE,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,YAAa,SAAQ,UAAU;IAC9C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,cAAc;IACxD,KAAK,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC3B,IAAI,EAAE,UAAU,CAAC;CAClB;AAED;;GAEG;AACH,UAAU,UAAU;IAClB,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;GAEG;AACH,UAAU,cAAc;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB"}

package/dist/types.js

@@ -0,0 +1,17 @@
+/**
+ * TypeScript type definitions for the bargs CLI argument parser.
+ *
+ * Defines all public interfaces and types including:
+ *
+ * - Option definitions (`StringOption`, `BooleanOption`, `EnumOption`, etc.)
+ * - Positional definitions (`StringPositional`, `VariadicPositional`, etc.)
+ * - Schema types (`OptionsSchema`, `PositionalsSchema`)
+ * - Configuration types (`BargsConfig`, `BargsConfigWithCommands`)
+ * - Command types (`CommandConfig`, `CommandConfigInput`)
+ * - Type inference utilities (`InferOptions`, `InferPositionals`)
+ * - Result types (`BargsResult`)
+ *
+ * @packageDocumentation
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}