@boneskull/bargs 1.0.0 → 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +305 -299
- package/dist/bargs.cjs +464 -142
- package/dist/bargs.cjs.map +1 -1
- package/dist/bargs.d.cts +35 -17
- package/dist/bargs.d.cts.map +1 -1
- package/dist/bargs.d.ts +35 -17
- package/dist/bargs.d.ts.map +1 -1
- package/dist/bargs.js +462 -142
- package/dist/bargs.js.map +1 -1
- package/dist/help.cjs +1 -2
- package/dist/help.cjs.map +1 -1
- package/dist/help.d.cts +20 -3
- package/dist/help.d.cts.map +1 -1
- package/dist/help.d.ts +20 -3
- package/dist/help.d.ts.map +1 -1
- package/dist/help.js +1 -2
- package/dist/help.js.map +1 -1
- package/dist/index.cjs +27 -31
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +15 -78
- package/dist/index.d.cts.map +1 -1
- package/dist/index.d.ts +15 -78
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +20 -30
- package/dist/index.js.map +1 -1
- package/dist/opt.cjs +147 -80
- package/dist/opt.cjs.map +1 -1
- package/dist/opt.d.cts +88 -77
- package/dist/opt.d.cts.map +1 -1
- package/dist/opt.d.ts +88 -77
- package/dist/opt.d.ts.map +1 -1
- package/dist/opt.js +146 -79
- package/dist/opt.js.map +1 -1
- package/dist/parser.cjs +3 -230
- package/dist/parser.cjs.map +1 -1
- package/dist/parser.d.cts +3 -51
- package/dist/parser.d.cts.map +1 -1
- package/dist/parser.d.ts +3 -51
- package/dist/parser.d.ts.map +1 -1
- package/dist/parser.js +2 -223
- package/dist/parser.js.map +1 -1
- package/dist/types.cjs +1 -3
- package/dist/types.cjs.map +1 -1
- package/dist/types.d.cts +110 -122
- package/dist/types.d.cts.map +1 -1
- package/dist/types.d.ts +110 -122
- package/dist/types.d.ts.map +1 -1
- package/dist/types.js +1 -3
- package/dist/types.js.map +1 -1
- package/package.json +2 -2
- package/dist/validate.cjs +0 -463
- package/dist/validate.cjs.map +0 -1
- package/dist/validate.d.cts +0 -28
- package/dist/validate.d.cts.map +0 -1
- package/dist/validate.d.ts +0 -28
- package/dist/validate.d.ts.map +0 -1
- package/dist/validate.js +0 -459
- package/dist/validate.js.map +0 -1
package/dist/opt.d.cts
CHANGED
|
@@ -1,31 +1,34 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Builder functions for defining CLI options
|
|
2
|
+
* Builder functions for defining CLI options and positionals.
|
|
3
3
|
*
|
|
4
4
|
* Provides ergonomic helpers with full TypeScript type inference for
|
|
5
5
|
* constructing option schemas (`opt.string()`, `opt.boolean()`, `opt.enum()`,
|
|
6
|
-
* etc.)
|
|
7
|
-
* `opt.variadic()`)
|
|
8
|
-
* composition utilities for merging schemas (`opt.options()`,
|
|
9
|
-
* `opt.positionals()`).
|
|
6
|
+
* etc.) and positional schemas (`opt.stringPos()`, `opt.numberPos()`,
|
|
7
|
+
* `opt.variadic()`).
|
|
10
8
|
*
|
|
11
9
|
* @packageDocumentation
|
|
12
10
|
*/
|
|
13
|
-
import type { ArrayOption, BooleanOption,
|
|
11
|
+
import type { ArrayOption, BooleanOption, CountOption, EnumOption, EnumPositional, InferOptions, InferPositionals, NumberOption, NumberPositional, OptionsSchema, Parser, PositionalDef, StringOption, StringPositional, VariadicPositional } from "./types.cjs";
|
|
14
12
|
/**
|
|
15
|
-
*
|
|
13
|
+
* A Parser that can also be called as a function to merge with another parser.
|
|
14
|
+
* This allows `opt.options()` to work both as:
|
|
16
15
|
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
16
|
+
* - First arg in pipe: used directly as a Parser
|
|
17
|
+
* - Later arg in pipe: called as function to merge with incoming Parser
|
|
18
|
+
*/
|
|
19
|
+
type CallableOptionsParser<V> = (<V2, P2 extends readonly unknown[]>(parser: Parser<V2, P2>) => Parser<V & V2, P2>) & Parser<V, readonly []>;
|
|
20
|
+
/**
|
|
21
|
+
* Namespaced option builders.
|
|
19
22
|
*
|
|
20
23
|
* @example
|
|
21
24
|
*
|
|
22
25
|
* ```typescript
|
|
23
26
|
* import { opt } from 'bargs';
|
|
24
27
|
*
|
|
25
|
-
* const
|
|
28
|
+
* const parser = opt.options({
|
|
26
29
|
* verbose: opt.boolean({ aliases: ['v'] }),
|
|
27
30
|
* name: opt.string({ default: 'world' }),
|
|
28
|
-
* level: opt.enum(['low', 'medium', 'high']
|
|
31
|
+
* level: opt.enum(['low', 'medium', 'high']),
|
|
29
32
|
* });
|
|
30
33
|
* ```
|
|
31
34
|
*/
|
|
@@ -35,114 +38,122 @@ export declare const opt: {
|
|
|
35
38
|
*/
|
|
36
39
|
array: (items: "number" | "string", props?: Omit<ArrayOption, "items" | "type">) => ArrayOption;
|
|
37
40
|
/**
|
|
38
|
-
* Define a boolean option.
|
|
39
|
-
* inference.
|
|
41
|
+
* Define a boolean option.
|
|
40
42
|
*/
|
|
41
43
|
boolean: <P extends Omit<BooleanOption, "type"> = Omit<BooleanOption, "type">>(props?: P) => BooleanOption & P;
|
|
42
|
-
/**
|
|
43
|
-
* Define a command with proper type inference.
|
|
44
|
-
*
|
|
45
|
-
* @example
|
|
46
|
-
*
|
|
47
|
-
* ```typescript
|
|
48
|
-
* const greetCmd = opt.command({
|
|
49
|
-
* description: 'Greet someone',
|
|
50
|
-
* options: opt.options({
|
|
51
|
-
* name: opt.string({ default: 'world' }),
|
|
52
|
-
* }),
|
|
53
|
-
* transforms: {
|
|
54
|
-
* values: (v) => ({ ...v, timestamp: Date.now() }),
|
|
55
|
-
* },
|
|
56
|
-
* handler: ({ values }) => {
|
|
57
|
-
* console.log(`Hello, ${values.name}! (${values.timestamp})`);
|
|
58
|
-
* },
|
|
59
|
-
* });
|
|
60
|
-
* ```
|
|
61
|
-
*/
|
|
62
|
-
command: <TOptions extends OptionsSchema = OptionsSchema, TPositionals extends PositionalsSchema = PositionalsSchema, TTransforms extends TransformsConfig<any, any, any, any> | undefined = undefined>(config: CommandConfig<TOptions, TPositionals, TTransforms>) => CommandConfig<TOptions, TPositionals, TTransforms>;
|
|
63
44
|
/**
|
|
64
45
|
* Define a count option (--verbose --verbose = 2).
|
|
65
46
|
*/
|
|
66
47
|
count: (props?: Omit<CountOption, "type">) => CountOption;
|
|
67
48
|
/**
|
|
68
|
-
* Define an enum option with string choices.
|
|
69
|
-
* a tuple of literal types automatically. Props type is preserved to enable
|
|
70
|
-
* default inference.
|
|
49
|
+
* Define an enum option with string choices.
|
|
71
50
|
*/
|
|
72
51
|
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;
|
|
73
52
|
/**
|
|
74
|
-
* Define an enum positional argument with string choices.
|
|
75
|
-
* is inferred as a tuple of literal types automatically.
|
|
53
|
+
* Define an enum positional argument with string choices.
|
|
76
54
|
*/
|
|
77
55
|
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;
|
|
78
56
|
/**
|
|
79
|
-
* Define a number option.
|
|
80
|
-
* inference.
|
|
57
|
+
* Define a number option.
|
|
81
58
|
*/
|
|
82
59
|
number: <P extends Omit<NumberOption, "type"> = Omit<NumberOption, "type">>(props?: P) => NumberOption & P;
|
|
83
60
|
/**
|
|
84
61
|
* Define a number positional argument.
|
|
85
62
|
*/
|
|
86
|
-
numberPos:
|
|
63
|
+
numberPos: <P extends Omit<NumberPositional, "type"> = Omit<NumberPositional, "type">>(props?: P) => NumberPositional & P;
|
|
87
64
|
/**
|
|
88
|
-
*
|
|
89
|
-
* ones for duplicate option names. Validates that no alias conflicts exist.
|
|
65
|
+
* Create a Parser from an options schema.
|
|
90
66
|
*
|
|
91
67
|
* @example
|
|
92
68
|
*
|
|
93
69
|
* ```typescript
|
|
94
|
-
*
|
|
95
|
-
* const loggingOpts = opt.options({
|
|
70
|
+
* const parser = opt.options({
|
|
96
71
|
* verbose: opt.boolean({ aliases: ['v'] }),
|
|
97
|
-
*
|
|
98
|
-
* });
|
|
99
|
-
*
|
|
100
|
-
* // Merge multiple schemas
|
|
101
|
-
* const allOpts = opt.options(loggingOpts, ioOpts, {
|
|
102
|
-
* format: opt.enum(['json', 'yaml'] as const),
|
|
72
|
+
* name: opt.string({ default: 'world' }),
|
|
103
73
|
* });
|
|
74
|
+
* // Type: Parser<{ verbose: boolean | undefined, name: string }, []>
|
|
104
75
|
* ```
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
76
|
+
*/
|
|
77
|
+
options: <T extends OptionsSchema>(schema: T) => CallableOptionsParser<InferOptions<T>>;
|
|
78
|
+
/**
|
|
79
|
+
* Define a string option.
|
|
80
|
+
*/
|
|
81
|
+
string: <P extends Omit<StringOption, "type"> = Omit<StringOption, "type">>(props?: P) => P & StringOption;
|
|
82
|
+
/**
|
|
83
|
+
* Define a string positional argument.
|
|
84
|
+
*/
|
|
85
|
+
stringPos: <P extends Omit<StringPositional, "type"> = Omit<StringPositional, "type">>(props?: P) => P & StringPositional;
|
|
86
|
+
/**
|
|
87
|
+
* Define a variadic positional (rest args).
|
|
88
|
+
*/
|
|
89
|
+
variadic: (items: "number" | "string", props?: Omit<VariadicPositional, "items" | "type">) => VariadicPositional;
|
|
90
|
+
};
|
|
91
|
+
/**
|
|
92
|
+
* A Parser that can also be called as a function to merge with another parser.
|
|
93
|
+
* This allows `pos.positionals()` to work both as:
|
|
94
|
+
*
|
|
95
|
+
* - First arg in pipe: used directly as a Parser
|
|
96
|
+
* - Later arg in pipe: called as function to merge with incoming Parser
|
|
97
|
+
*
|
|
98
|
+
* For positionals, we DON'T intersect values - we just pass through V2.
|
|
99
|
+
*/
|
|
100
|
+
type CallablePositionalsParser<P extends readonly unknown[]> = (<V2, P2 extends readonly unknown[]>(parser: Parser<V2, P2>) => Parser<V2, readonly [...P2, ...P]>) & Parser<EmptyObject, P>;
|
|
101
|
+
/**
|
|
102
|
+
* Empty object type that works better with intersections than Record<string,
|
|
103
|
+
* never>. {} & T = T, but Record<string, never> & T can be problematic.
|
|
104
|
+
*/
|
|
105
|
+
type EmptyObject = {};
|
|
106
|
+
/**
|
|
107
|
+
* Namespaced positional builders.
|
|
108
|
+
*
|
|
109
|
+
* @example
|
|
110
|
+
*
|
|
111
|
+
* ```typescript
|
|
112
|
+
* import { pos } from 'bargs';
|
|
113
|
+
*
|
|
114
|
+
* const parser = pos.positionals(
|
|
115
|
+
* pos.string({ name: 'input', required: true }),
|
|
116
|
+
* pos.string({ name: 'output' }),
|
|
117
|
+
* );
|
|
118
|
+
* ```
|
|
119
|
+
*/
|
|
120
|
+
export declare const pos: {
|
|
121
|
+
/**
|
|
122
|
+
* Define an enum positional argument with string choices.
|
|
123
|
+
*/
|
|
124
|
+
enum: <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;
|
|
115
125
|
/**
|
|
116
|
-
*
|
|
126
|
+
* Define a number positional argument.
|
|
127
|
+
*/
|
|
128
|
+
number: <P extends Omit<NumberPositional, "type"> = Omit<NumberPositional, "type">>(props?: P) => NumberPositional & P;
|
|
129
|
+
/**
|
|
130
|
+
* Create a Parser from positional definitions.
|
|
117
131
|
*
|
|
118
132
|
* @example
|
|
119
133
|
*
|
|
120
134
|
* ```typescript
|
|
121
|
-
* const
|
|
122
|
-
*
|
|
123
|
-
*
|
|
135
|
+
* const parser = pos.positionals(
|
|
136
|
+
* pos.string({ name: 'input', required: true }),
|
|
137
|
+
* pos.string({ name: 'output' }),
|
|
124
138
|
* );
|
|
139
|
+
* // Type: Parser<{}, readonly [string, string | undefined]>
|
|
125
140
|
* ```
|
|
126
141
|
*/
|
|
127
142
|
positionals: {
|
|
128
|
-
<A extends PositionalDef>(a: A): [A]
|
|
129
|
-
<A extends PositionalDef, B extends PositionalDef>(a: A, b: B): [A, B]
|
|
130
|
-
<A extends PositionalDef, B extends PositionalDef, C extends PositionalDef>(a: A, b: B, c: C): [A, B, C]
|
|
131
|
-
<A extends PositionalDef, B extends PositionalDef, C extends PositionalDef, D extends PositionalDef>(a: A, b: B, c: C, d: D): [A, B, C, D]
|
|
132
|
-
(...positionals: PositionalDef[]):
|
|
143
|
+
<A extends PositionalDef>(a: A): CallablePositionalsParser<readonly [InferPositionals<readonly [A]>[0]]>;
|
|
144
|
+
<A extends PositionalDef, B extends PositionalDef>(a: A, b: B): CallablePositionalsParser<InferPositionals<readonly [A, B]>>;
|
|
145
|
+
<A extends PositionalDef, B extends PositionalDef, C extends PositionalDef>(a: A, b: B, c: C): CallablePositionalsParser<InferPositionals<readonly [A, B, C]>>;
|
|
146
|
+
<A extends PositionalDef, B extends PositionalDef, C extends PositionalDef, D extends PositionalDef>(a: A, b: B, c: C, d: D): CallablePositionalsParser<InferPositionals<readonly [A, B, C, D]>>;
|
|
147
|
+
(...positionals: PositionalDef[]): CallablePositionalsParser<readonly unknown[]>;
|
|
133
148
|
};
|
|
134
|
-
/**
|
|
135
|
-
* Define a string option. Props type is preserved to enable default
|
|
136
|
-
* inference.
|
|
137
|
-
*/
|
|
138
|
-
string: <P extends Omit<StringOption, "type"> = Omit<StringOption, "type">>(props?: P) => P & StringOption;
|
|
139
149
|
/**
|
|
140
150
|
* Define a string positional argument.
|
|
141
151
|
*/
|
|
142
|
-
|
|
152
|
+
string: <P extends Omit<StringPositional, "type"> = Omit<StringPositional, "type">>(props?: P) => P & StringPositional;
|
|
143
153
|
/**
|
|
144
154
|
* Define a variadic positional (rest args).
|
|
145
155
|
*/
|
|
146
156
|
variadic: (items: "number" | "string", props?: Omit<VariadicPositional, "items" | "type">) => VariadicPositional;
|
|
147
157
|
};
|
|
158
|
+
export {};
|
|
148
159
|
//# sourceMappingURL=opt.d.ts.map
|
package/dist/opt.d.cts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"opt.d.ts","sourceRoot":"","sources":["../src/opt.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"opt.d.ts","sourceRoot":"","sources":["../src/opt.ts"],"names":[],"mappings":"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"}
|
package/dist/opt.d.ts
CHANGED
|
@@ -1,31 +1,34 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Builder functions for defining CLI options
|
|
2
|
+
* Builder functions for defining CLI options and positionals.
|
|
3
3
|
*
|
|
4
4
|
* Provides ergonomic helpers with full TypeScript type inference for
|
|
5
5
|
* constructing option schemas (`opt.string()`, `opt.boolean()`, `opt.enum()`,
|
|
6
|
-
* etc.)
|
|
7
|
-
* `opt.variadic()`)
|
|
8
|
-
* composition utilities for merging schemas (`opt.options()`,
|
|
9
|
-
* `opt.positionals()`).
|
|
6
|
+
* etc.) and positional schemas (`opt.stringPos()`, `opt.numberPos()`,
|
|
7
|
+
* `opt.variadic()`).
|
|
10
8
|
*
|
|
11
9
|
* @packageDocumentation
|
|
12
10
|
*/
|
|
13
|
-
import type { ArrayOption, BooleanOption,
|
|
11
|
+
import type { ArrayOption, BooleanOption, CountOption, EnumOption, EnumPositional, InferOptions, InferPositionals, NumberOption, NumberPositional, OptionsSchema, Parser, PositionalDef, StringOption, StringPositional, VariadicPositional } from "./types.js";
|
|
14
12
|
/**
|
|
15
|
-
*
|
|
13
|
+
* A Parser that can also be called as a function to merge with another parser.
|
|
14
|
+
* This allows `opt.options()` to work both as:
|
|
16
15
|
*
|
|
17
|
-
*
|
|
18
|
-
*
|
|
16
|
+
* - First arg in pipe: used directly as a Parser
|
|
17
|
+
* - Later arg in pipe: called as function to merge with incoming Parser
|
|
18
|
+
*/
|
|
19
|
+
type CallableOptionsParser<V> = (<V2, P2 extends readonly unknown[]>(parser: Parser<V2, P2>) => Parser<V & V2, P2>) & Parser<V, readonly []>;
|
|
20
|
+
/**
|
|
21
|
+
* Namespaced option builders.
|
|
19
22
|
*
|
|
20
23
|
* @example
|
|
21
24
|
*
|
|
22
25
|
* ```typescript
|
|
23
26
|
* import { opt } from 'bargs';
|
|
24
27
|
*
|
|
25
|
-
* const
|
|
28
|
+
* const parser = opt.options({
|
|
26
29
|
* verbose: opt.boolean({ aliases: ['v'] }),
|
|
27
30
|
* name: opt.string({ default: 'world' }),
|
|
28
|
-
* level: opt.enum(['low', 'medium', 'high']
|
|
31
|
+
* level: opt.enum(['low', 'medium', 'high']),
|
|
29
32
|
* });
|
|
30
33
|
* ```
|
|
31
34
|
*/
|
|
@@ -35,114 +38,122 @@ export declare const opt: {
|
|
|
35
38
|
*/
|
|
36
39
|
array: (items: "number" | "string", props?: Omit<ArrayOption, "items" | "type">) => ArrayOption;
|
|
37
40
|
/**
|
|
38
|
-
* Define a boolean option.
|
|
39
|
-
* inference.
|
|
41
|
+
* Define a boolean option.
|
|
40
42
|
*/
|
|
41
43
|
boolean: <P extends Omit<BooleanOption, "type"> = Omit<BooleanOption, "type">>(props?: P) => BooleanOption & P;
|
|
42
|
-
/**
|
|
43
|
-
* Define a command with proper type inference.
|
|
44
|
-
*
|
|
45
|
-
* @example
|
|
46
|
-
*
|
|
47
|
-
* ```typescript
|
|
48
|
-
* const greetCmd = opt.command({
|
|
49
|
-
* description: 'Greet someone',
|
|
50
|
-
* options: opt.options({
|
|
51
|
-
* name: opt.string({ default: 'world' }),
|
|
52
|
-
* }),
|
|
53
|
-
* transforms: {
|
|
54
|
-
* values: (v) => ({ ...v, timestamp: Date.now() }),
|
|
55
|
-
* },
|
|
56
|
-
* handler: ({ values }) => {
|
|
57
|
-
* console.log(`Hello, ${values.name}! (${values.timestamp})`);
|
|
58
|
-
* },
|
|
59
|
-
* });
|
|
60
|
-
* ```
|
|
61
|
-
*/
|
|
62
|
-
command: <TOptions extends OptionsSchema = OptionsSchema, TPositionals extends PositionalsSchema = PositionalsSchema, TTransforms extends TransformsConfig<any, any, any, any> | undefined = undefined>(config: CommandConfig<TOptions, TPositionals, TTransforms>) => CommandConfig<TOptions, TPositionals, TTransforms>;
|
|
63
44
|
/**
|
|
64
45
|
* Define a count option (--verbose --verbose = 2).
|
|
65
46
|
*/
|
|
66
47
|
count: (props?: Omit<CountOption, "type">) => CountOption;
|
|
67
48
|
/**
|
|
68
|
-
* Define an enum option with string choices.
|
|
69
|
-
* a tuple of literal types automatically. Props type is preserved to enable
|
|
70
|
-
* default inference.
|
|
49
|
+
* Define an enum option with string choices.
|
|
71
50
|
*/
|
|
72
51
|
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;
|
|
73
52
|
/**
|
|
74
|
-
* Define an enum positional argument with string choices.
|
|
75
|
-
* is inferred as a tuple of literal types automatically.
|
|
53
|
+
* Define an enum positional argument with string choices.
|
|
76
54
|
*/
|
|
77
55
|
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;
|
|
78
56
|
/**
|
|
79
|
-
* Define a number option.
|
|
80
|
-
* inference.
|
|
57
|
+
* Define a number option.
|
|
81
58
|
*/
|
|
82
59
|
number: <P extends Omit<NumberOption, "type"> = Omit<NumberOption, "type">>(props?: P) => NumberOption & P;
|
|
83
60
|
/**
|
|
84
61
|
* Define a number positional argument.
|
|
85
62
|
*/
|
|
86
|
-
numberPos:
|
|
63
|
+
numberPos: <P extends Omit<NumberPositional, "type"> = Omit<NumberPositional, "type">>(props?: P) => NumberPositional & P;
|
|
87
64
|
/**
|
|
88
|
-
*
|
|
89
|
-
* ones for duplicate option names. Validates that no alias conflicts exist.
|
|
65
|
+
* Create a Parser from an options schema.
|
|
90
66
|
*
|
|
91
67
|
* @example
|
|
92
68
|
*
|
|
93
69
|
* ```typescript
|
|
94
|
-
*
|
|
95
|
-
* const loggingOpts = opt.options({
|
|
70
|
+
* const parser = opt.options({
|
|
96
71
|
* verbose: opt.boolean({ aliases: ['v'] }),
|
|
97
|
-
*
|
|
98
|
-
* });
|
|
99
|
-
*
|
|
100
|
-
* // Merge multiple schemas
|
|
101
|
-
* const allOpts = opt.options(loggingOpts, ioOpts, {
|
|
102
|
-
* format: opt.enum(['json', 'yaml'] as const),
|
|
72
|
+
* name: opt.string({ default: 'world' }),
|
|
103
73
|
* });
|
|
74
|
+
* // Type: Parser<{ verbose: boolean | undefined, name: string }, []>
|
|
104
75
|
* ```
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
76
|
+
*/
|
|
77
|
+
options: <T extends OptionsSchema>(schema: T) => CallableOptionsParser<InferOptions<T>>;
|
|
78
|
+
/**
|
|
79
|
+
* Define a string option.
|
|
80
|
+
*/
|
|
81
|
+
string: <P extends Omit<StringOption, "type"> = Omit<StringOption, "type">>(props?: P) => P & StringOption;
|
|
82
|
+
/**
|
|
83
|
+
* Define a string positional argument.
|
|
84
|
+
*/
|
|
85
|
+
stringPos: <P extends Omit<StringPositional, "type"> = Omit<StringPositional, "type">>(props?: P) => P & StringPositional;
|
|
86
|
+
/**
|
|
87
|
+
* Define a variadic positional (rest args).
|
|
88
|
+
*/
|
|
89
|
+
variadic: (items: "number" | "string", props?: Omit<VariadicPositional, "items" | "type">) => VariadicPositional;
|
|
90
|
+
};
|
|
91
|
+
/**
|
|
92
|
+
* A Parser that can also be called as a function to merge with another parser.
|
|
93
|
+
* This allows `pos.positionals()` to work both as:
|
|
94
|
+
*
|
|
95
|
+
* - First arg in pipe: used directly as a Parser
|
|
96
|
+
* - Later arg in pipe: called as function to merge with incoming Parser
|
|
97
|
+
*
|
|
98
|
+
* For positionals, we DON'T intersect values - we just pass through V2.
|
|
99
|
+
*/
|
|
100
|
+
type CallablePositionalsParser<P extends readonly unknown[]> = (<V2, P2 extends readonly unknown[]>(parser: Parser<V2, P2>) => Parser<V2, readonly [...P2, ...P]>) & Parser<EmptyObject, P>;
|
|
101
|
+
/**
|
|
102
|
+
* Empty object type that works better with intersections than Record<string,
|
|
103
|
+
* never>. {} & T = T, but Record<string, never> & T can be problematic.
|
|
104
|
+
*/
|
|
105
|
+
type EmptyObject = {};
|
|
106
|
+
/**
|
|
107
|
+
* Namespaced positional builders.
|
|
108
|
+
*
|
|
109
|
+
* @example
|
|
110
|
+
*
|
|
111
|
+
* ```typescript
|
|
112
|
+
* import { pos } from 'bargs';
|
|
113
|
+
*
|
|
114
|
+
* const parser = pos.positionals(
|
|
115
|
+
* pos.string({ name: 'input', required: true }),
|
|
116
|
+
* pos.string({ name: 'output' }),
|
|
117
|
+
* );
|
|
118
|
+
* ```
|
|
119
|
+
*/
|
|
120
|
+
export declare const pos: {
|
|
121
|
+
/**
|
|
122
|
+
* Define an enum positional argument with string choices.
|
|
123
|
+
*/
|
|
124
|
+
enum: <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;
|
|
115
125
|
/**
|
|
116
|
-
*
|
|
126
|
+
* Define a number positional argument.
|
|
127
|
+
*/
|
|
128
|
+
number: <P extends Omit<NumberPositional, "type"> = Omit<NumberPositional, "type">>(props?: P) => NumberPositional & P;
|
|
129
|
+
/**
|
|
130
|
+
* Create a Parser from positional definitions.
|
|
117
131
|
*
|
|
118
132
|
* @example
|
|
119
133
|
*
|
|
120
134
|
* ```typescript
|
|
121
|
-
* const
|
|
122
|
-
*
|
|
123
|
-
*
|
|
135
|
+
* const parser = pos.positionals(
|
|
136
|
+
* pos.string({ name: 'input', required: true }),
|
|
137
|
+
* pos.string({ name: 'output' }),
|
|
124
138
|
* );
|
|
139
|
+
* // Type: Parser<{}, readonly [string, string | undefined]>
|
|
125
140
|
* ```
|
|
126
141
|
*/
|
|
127
142
|
positionals: {
|
|
128
|
-
<A extends PositionalDef>(a: A): [A]
|
|
129
|
-
<A extends PositionalDef, B extends PositionalDef>(a: A, b: B): [A, B]
|
|
130
|
-
<A extends PositionalDef, B extends PositionalDef, C extends PositionalDef>(a: A, b: B, c: C): [A, B, C]
|
|
131
|
-
<A extends PositionalDef, B extends PositionalDef, C extends PositionalDef, D extends PositionalDef>(a: A, b: B, c: C, d: D): [A, B, C, D]
|
|
132
|
-
(...positionals: PositionalDef[]):
|
|
143
|
+
<A extends PositionalDef>(a: A): CallablePositionalsParser<readonly [InferPositionals<readonly [A]>[0]]>;
|
|
144
|
+
<A extends PositionalDef, B extends PositionalDef>(a: A, b: B): CallablePositionalsParser<InferPositionals<readonly [A, B]>>;
|
|
145
|
+
<A extends PositionalDef, B extends PositionalDef, C extends PositionalDef>(a: A, b: B, c: C): CallablePositionalsParser<InferPositionals<readonly [A, B, C]>>;
|
|
146
|
+
<A extends PositionalDef, B extends PositionalDef, C extends PositionalDef, D extends PositionalDef>(a: A, b: B, c: C, d: D): CallablePositionalsParser<InferPositionals<readonly [A, B, C, D]>>;
|
|
147
|
+
(...positionals: PositionalDef[]): CallablePositionalsParser<readonly unknown[]>;
|
|
133
148
|
};
|
|
134
|
-
/**
|
|
135
|
-
* Define a string option. Props type is preserved to enable default
|
|
136
|
-
* inference.
|
|
137
|
-
*/
|
|
138
|
-
string: <P extends Omit<StringOption, "type"> = Omit<StringOption, "type">>(props?: P) => P & StringOption;
|
|
139
149
|
/**
|
|
140
150
|
* Define a string positional argument.
|
|
141
151
|
*/
|
|
142
|
-
|
|
152
|
+
string: <P extends Omit<StringPositional, "type"> = Omit<StringPositional, "type">>(props?: P) => P & StringPositional;
|
|
143
153
|
/**
|
|
144
154
|
* Define a variadic positional (rest args).
|
|
145
155
|
*/
|
|
146
156
|
variadic: (items: "number" | "string", props?: Omit<VariadicPositional, "items" | "type">) => VariadicPositional;
|
|
147
157
|
};
|
|
158
|
+
export {};
|
|
148
159
|
//# sourceMappingURL=opt.d.ts.map
|
package/dist/opt.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"opt.d.ts","sourceRoot":"","sources":["../src/opt.ts"],"names":[],"mappings":"AAAA
|
|
1
|
+
{"version":3,"file":"opt.d.ts","sourceRoot":"","sources":["../src/opt.ts"],"names":[],"mappings":"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"}
|