@gunshi/definition 0.26.3
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/LICENSE +20 -0
- package/README.md +67 -0
- package/lib/index.d.ts +565 -0
- package/lib/index.js +29 -0
- package/package.json +67 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
The MIT License (MIT)
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 kazuya kawaguchi
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of
|
|
6
|
+
this software and associated documentation files (the "Software"), to deal in
|
|
7
|
+
the Software without restriction, including without limitation the rights to
|
|
8
|
+
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
|
|
9
|
+
the Software, and to permit persons to whom the Software is furnished to do so,
|
|
10
|
+
subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
|
|
17
|
+
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
|
|
18
|
+
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
|
|
19
|
+
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
|
20
|
+
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# `@gunshi/definition`
|
|
2
|
+
|
|
3
|
+
> utilities for gunshi command definition
|
|
4
|
+
|
|
5
|
+
This package exports the bellow APIs and types.
|
|
6
|
+
|
|
7
|
+
- `define`: A function to define a command.
|
|
8
|
+
- `lazy`: A function to lazily load a command.
|
|
9
|
+
- Some basic type definitions, such as `Command`, `LazyCommand`, etc.
|
|
10
|
+
|
|
11
|
+
<!-- eslint-disable markdown/no-missing-label-refs -->
|
|
12
|
+
|
|
13
|
+
> [!TIP]
|
|
14
|
+
> **The APIs and type definitions available in this package are the same as those in the `gunshi/definition` entry in the `gunshi` package.**
|
|
15
|
+
> This package is smaller in file size than the `gunshi` package, making it suitable for use when you want to reduce the size of the `node_modules` in your command you are creating.
|
|
16
|
+
|
|
17
|
+
<!-- eslint-enable markdown/no-missing-label-refs -->
|
|
18
|
+
|
|
19
|
+
## 💿 Installation
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
# npm
|
|
23
|
+
npm install --save @gunshi/definition
|
|
24
|
+
|
|
25
|
+
## pnpm
|
|
26
|
+
pnpm add @gunshi/definition
|
|
27
|
+
|
|
28
|
+
## yarn
|
|
29
|
+
yarn add @gunshi/definition
|
|
30
|
+
|
|
31
|
+
## deno
|
|
32
|
+
deno add jsr:@gunshi/definition
|
|
33
|
+
|
|
34
|
+
## bun
|
|
35
|
+
bun add @gunshi/definition
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## 🚀 Usage
|
|
39
|
+
|
|
40
|
+
You can define the gunshi command as JavaScript module with using `define` or `lazy`.
|
|
41
|
+
|
|
42
|
+
The bellow example case which is using `define`:
|
|
43
|
+
|
|
44
|
+
```js
|
|
45
|
+
import { define } from '@gunshi/definition'
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* define `say` command as javascript module
|
|
49
|
+
*/
|
|
50
|
+
export default define({
|
|
51
|
+
name: 'say',
|
|
52
|
+
args: {
|
|
53
|
+
say: {
|
|
54
|
+
type: 'string',
|
|
55
|
+
description: 'say something',
|
|
56
|
+
default: 'hello!'
|
|
57
|
+
}
|
|
58
|
+
},
|
|
59
|
+
run: ctx => {
|
|
60
|
+
return `You said: ${ctx.values.say}`
|
|
61
|
+
}
|
|
62
|
+
})
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## ©️ License
|
|
66
|
+
|
|
67
|
+
[MIT](http://opensource.org/licenses/MIT)
|
package/lib/index.d.ts
ADDED
|
@@ -0,0 +1,565 @@
|
|
|
1
|
+
//#region ../../node_modules/.pnpm/args-tokens@0.20.1/node_modules/args-tokens/lib/parser-FiQIAw-2.d.ts
|
|
2
|
+
//#region src/parser.d.ts
|
|
3
|
+
/**
|
|
4
|
+
* Entry point of argument parser.
|
|
5
|
+
* @module
|
|
6
|
+
*/
|
|
7
|
+
/**
|
|
8
|
+
* forked from `nodejs/node` (`pkgjs/parseargs`)
|
|
9
|
+
* repository url: https://github.com/nodejs/node (https://github.com/pkgjs/parseargs)
|
|
10
|
+
* code url: https://github.com/nodejs/node/blob/main/lib/internal/util/parse_args/parse_args.js
|
|
11
|
+
*
|
|
12
|
+
* @author kazuya kawaguchi (a.k.a. kazupon)
|
|
13
|
+
* @license MIT
|
|
14
|
+
*/
|
|
15
|
+
/**
|
|
16
|
+
* Argument token Kind.
|
|
17
|
+
* - `option`: option token, support short option (e.g. `-x`) and long option (e.g. `--foo`)
|
|
18
|
+
* - `option-terminator`: option terminator (`--`) token, see guideline 10 in https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html
|
|
19
|
+
* - `positional`: positional token
|
|
20
|
+
*/
|
|
21
|
+
type ArgTokenKind = "option" | "option-terminator" | "positional";
|
|
22
|
+
/**
|
|
23
|
+
* Argument token.
|
|
24
|
+
*/
|
|
25
|
+
interface ArgToken {
|
|
26
|
+
/**
|
|
27
|
+
* Argument token kind.
|
|
28
|
+
*/
|
|
29
|
+
kind: ArgTokenKind;
|
|
30
|
+
/**
|
|
31
|
+
* Argument token index, e.g `--foo bar` => `--foo` index is 0, `bar` index is 1.
|
|
32
|
+
*/
|
|
33
|
+
index: number;
|
|
34
|
+
/**
|
|
35
|
+
* Option name, e.g. `--foo` => `foo`, `-x` => `x`.
|
|
36
|
+
*/
|
|
37
|
+
name?: string;
|
|
38
|
+
/**
|
|
39
|
+
* Raw option name, e.g. `--foo` => `--foo`, `-x` => `-x`.
|
|
40
|
+
*/
|
|
41
|
+
rawName?: string;
|
|
42
|
+
/**
|
|
43
|
+
* Option value, e.g. `--foo=bar` => `bar`, `-x=bar` => `bar`.
|
|
44
|
+
* If the `allowCompatible` option is `true`, short option value will be same as Node.js `parseArgs` behavior.
|
|
45
|
+
*/
|
|
46
|
+
value?: string;
|
|
47
|
+
/**
|
|
48
|
+
* Inline value, e.g. `--foo=bar` => `true`, `-x=bar` => `true`.
|
|
49
|
+
*/
|
|
50
|
+
inlineValue?: boolean;
|
|
51
|
+
} //#endregion
|
|
52
|
+
//#region ../../node_modules/.pnpm/args-tokens@0.20.1/node_modules/args-tokens/lib/resolver-U72Jg6Ll.d.ts
|
|
53
|
+
|
|
54
|
+
/**
|
|
55
|
+
* Parser Options.
|
|
56
|
+
*/
|
|
57
|
+
//#region src/resolver.d.ts
|
|
58
|
+
/**
|
|
59
|
+
* An argument schema
|
|
60
|
+
* This schema is similar to the schema of the `node:utils`.
|
|
61
|
+
* difference is that:
|
|
62
|
+
* - `required` property and `description` property are added
|
|
63
|
+
* - `type` is not only 'string' and 'boolean', but also 'number', 'enum', 'positional', 'custom' too.
|
|
64
|
+
* - `default` property type, not support multiple types
|
|
65
|
+
*/
|
|
66
|
+
interface ArgSchema {
|
|
67
|
+
/**
|
|
68
|
+
* Type of argument.
|
|
69
|
+
*/
|
|
70
|
+
type: "string" | "boolean" | "number" | "enum" | "positional" | "custom";
|
|
71
|
+
/**
|
|
72
|
+
* A single character alias for the argument.
|
|
73
|
+
*/
|
|
74
|
+
short?: string;
|
|
75
|
+
/**
|
|
76
|
+
* A description of the argument.
|
|
77
|
+
*/
|
|
78
|
+
description?: string;
|
|
79
|
+
/**
|
|
80
|
+
* Whether the argument is required or not.
|
|
81
|
+
*/
|
|
82
|
+
required?: true;
|
|
83
|
+
/**
|
|
84
|
+
* Whether the argument allow multiple values or not.
|
|
85
|
+
*/
|
|
86
|
+
multiple?: true;
|
|
87
|
+
/**
|
|
88
|
+
* Whether the negatable option for `boolean` type
|
|
89
|
+
*/
|
|
90
|
+
negatable?: boolean;
|
|
91
|
+
/**
|
|
92
|
+
* The allowed values of the argument, and string only. This property is only used when the type is 'enum'.
|
|
93
|
+
*/
|
|
94
|
+
choices?: string[] | readonly string[];
|
|
95
|
+
/**
|
|
96
|
+
* The default value of the argument.
|
|
97
|
+
* if the type is 'enum', the default value must be one of the allowed values.
|
|
98
|
+
*/
|
|
99
|
+
default?: string | boolean | number;
|
|
100
|
+
/**
|
|
101
|
+
* Whether to convert the argument name to kebab-case.
|
|
102
|
+
*/
|
|
103
|
+
toKebab?: true;
|
|
104
|
+
/**
|
|
105
|
+
* A function to parse the value of the argument. if the type is 'custom', this function is required.
|
|
106
|
+
* If argument value will be invalid, this function have to throw an error.
|
|
107
|
+
* @param value
|
|
108
|
+
* @returns Parsed value
|
|
109
|
+
* @throws An Error, If the value is invalid. Error type should be `Error` or extends it
|
|
110
|
+
*/
|
|
111
|
+
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
112
|
+
parse?: (value: string) => any;
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* An object that contains {@link ArgSchema | argument schema}.
|
|
116
|
+
*/
|
|
117
|
+
interface Args {
|
|
118
|
+
[option: string]: ArgSchema;
|
|
119
|
+
}
|
|
120
|
+
/**
|
|
121
|
+
* An object that contains the values of the arguments.
|
|
122
|
+
*/
|
|
123
|
+
type ArgValues<T> = T extends Args ? ResolveArgValues<T, { [Arg in keyof T]: ExtractOptionValue<T[Arg]> }> : {
|
|
124
|
+
[option: string]: string | boolean | number | (string | boolean | number)[] | undefined;
|
|
125
|
+
};
|
|
126
|
+
// eslint-disable-next-line @typescript-eslint/no-explicit-any
|
|
127
|
+
type IsFunction<T> = T extends ((...args: any[]) => any) ? true : false;
|
|
128
|
+
/**
|
|
129
|
+
* @internal
|
|
130
|
+
*/
|
|
131
|
+
type ExtractOptionValue<A extends ArgSchema> = A["type"] extends "string" ? ResolveOptionValue<A, string> : A["type"] extends "boolean" ? ResolveOptionValue<A, boolean> : A["type"] extends "number" ? ResolveOptionValue<A, number> : A["type"] extends "positional" ? ResolveOptionValue<A, string> : A["type"] extends "enum" ? A["choices"] extends string[] | readonly string[] ? ResolveOptionValue<A, A["choices"][number]> : never : A["type"] extends "custom" ? IsFunction<A["parse"]> extends true ? ResolveOptionValue<A, ReturnType<NonNullable<A["parse"]>>> : never : ResolveOptionValue<A, string | boolean | number>;
|
|
132
|
+
type ResolveOptionValue<A extends ArgSchema, T> = A["multiple"] extends true ? T[] : T;
|
|
133
|
+
/**
|
|
134
|
+
* @internal
|
|
135
|
+
*/
|
|
136
|
+
type ResolveArgValues<A extends Args, V extends Record<keyof A, unknown>> = { -readonly [Arg in keyof A]?: V[Arg] } & FilterArgs<A, V, "default"> & FilterArgs<A, V, "required"> & FilterPositionalArgs<A, V> extends infer P ? { [K in keyof P]: P[K] } : never;
|
|
137
|
+
/**
|
|
138
|
+
* @internal
|
|
139
|
+
*/
|
|
140
|
+
type FilterArgs<A extends Args, V extends Record<keyof A, unknown>, K extends keyof ArgSchema> = { [Arg in keyof A as A[Arg][K] extends {} ? Arg : never]: V[Arg] };
|
|
141
|
+
/**
|
|
142
|
+
* @internal
|
|
143
|
+
*/
|
|
144
|
+
type FilterPositionalArgs<A extends Args, V extends Record<keyof A, unknown>> = { [Arg in keyof A as A[Arg]["type"] extends "positional" ? Arg : never]: V[Arg] };
|
|
145
|
+
|
|
146
|
+
//#endregion
|
|
147
|
+
//#region ../gunshi/src/types.d.ts
|
|
148
|
+
/**
|
|
149
|
+
* An arguments for {@link resolveArgs | resolve arguments}.
|
|
150
|
+
*/
|
|
151
|
+
type Awaitable<T> = T | Promise<T>;
|
|
152
|
+
/**
|
|
153
|
+
* Extend command context type. This type is used to extend the command context with additional properties at {@link CommandContext.extensions}.
|
|
154
|
+
*/
|
|
155
|
+
type ExtendContext = Record<string, unknown>;
|
|
156
|
+
/**
|
|
157
|
+
* Gunshi unified parameter type.
|
|
158
|
+
* This type combines both argument definitions and command context extensions.
|
|
159
|
+
*/
|
|
160
|
+
interface GunshiParams<P extends {
|
|
161
|
+
args?: Args;
|
|
162
|
+
extensions?: ExtendContext;
|
|
163
|
+
} = {
|
|
164
|
+
args: Args;
|
|
165
|
+
extensions: {};
|
|
166
|
+
}> {
|
|
167
|
+
/**
|
|
168
|
+
* Command argument definitions
|
|
169
|
+
*/
|
|
170
|
+
args: P extends {
|
|
171
|
+
args: infer A extends Args;
|
|
172
|
+
} ? A : Args;
|
|
173
|
+
/**
|
|
174
|
+
* Command context extensions
|
|
175
|
+
*/
|
|
176
|
+
extensions: P extends {
|
|
177
|
+
extensions: infer E extends ExtendContext;
|
|
178
|
+
} ? E : {};
|
|
179
|
+
}
|
|
180
|
+
/**
|
|
181
|
+
* Default Gunshi parameters
|
|
182
|
+
*/
|
|
183
|
+
type DefaultGunshiParams = GunshiParams;
|
|
184
|
+
/**
|
|
185
|
+
* Generic constraint for command-related types.
|
|
186
|
+
* This type constraint allows both GunshiParams and objects with extensions.
|
|
187
|
+
*/
|
|
188
|
+
type GunshiParamsConstraint = GunshiParams<any> | {
|
|
189
|
+
extensions: ExtendContext;
|
|
190
|
+
};
|
|
191
|
+
/**
|
|
192
|
+
* Type helper to extract args from G
|
|
193
|
+
* @internal
|
|
194
|
+
*/
|
|
195
|
+
type ExtractArgs<G> = G extends GunshiParams<any> ? G['args'] : Args;
|
|
196
|
+
/**
|
|
197
|
+
* Type helper to extract extensions from G
|
|
198
|
+
* @internal
|
|
199
|
+
*/
|
|
200
|
+
type ExtractExtensions<G> = G extends GunshiParams<any> ? G['extensions'] : G extends {
|
|
201
|
+
extensions: infer E;
|
|
202
|
+
} ? E : {};
|
|
203
|
+
/**
|
|
204
|
+
* Type helper to normalize G to GunshiParams
|
|
205
|
+
* @internal
|
|
206
|
+
*/
|
|
207
|
+
|
|
208
|
+
/**
|
|
209
|
+
* Command environment.
|
|
210
|
+
*/
|
|
211
|
+
interface CommandEnvironment<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
212
|
+
/**
|
|
213
|
+
* Current working directory.
|
|
214
|
+
* @see {@link CliOptions.cwd}
|
|
215
|
+
*/
|
|
216
|
+
cwd: string | undefined;
|
|
217
|
+
/**
|
|
218
|
+
* Command name.
|
|
219
|
+
* @see {@link CliOptions.name}
|
|
220
|
+
*/
|
|
221
|
+
name: string | undefined;
|
|
222
|
+
/**
|
|
223
|
+
* Command description.
|
|
224
|
+
* @see {@link CliOptions.description}
|
|
225
|
+
*
|
|
226
|
+
*/
|
|
227
|
+
description: string | undefined;
|
|
228
|
+
/**
|
|
229
|
+
* Command version.
|
|
230
|
+
* @see {@link CliOptions.version}
|
|
231
|
+
*/
|
|
232
|
+
version: string | undefined;
|
|
233
|
+
/**
|
|
234
|
+
* Left margin of the command output.
|
|
235
|
+
* @default 2
|
|
236
|
+
* @see {@link CliOptions.leftMargin}
|
|
237
|
+
*/
|
|
238
|
+
leftMargin: number;
|
|
239
|
+
/**
|
|
240
|
+
* Middle margin of the command output.
|
|
241
|
+
* @default 10
|
|
242
|
+
* @see {@link CliOptions.middleMargin}
|
|
243
|
+
*/
|
|
244
|
+
middleMargin: number;
|
|
245
|
+
/**
|
|
246
|
+
* Whether to display the usage option type.
|
|
247
|
+
* @default false
|
|
248
|
+
* @see {@link CliOptions.usageOptionType}
|
|
249
|
+
*/
|
|
250
|
+
usageOptionType: boolean;
|
|
251
|
+
/**
|
|
252
|
+
* Whether to display the option value.
|
|
253
|
+
* @default true
|
|
254
|
+
* @see {@link CliOptions.usageOptionValue}
|
|
255
|
+
*/
|
|
256
|
+
usageOptionValue: boolean;
|
|
257
|
+
/**
|
|
258
|
+
* Whether to display the command usage.
|
|
259
|
+
* @default false
|
|
260
|
+
* @see {@link CliOptions.usageSilent}
|
|
261
|
+
*/
|
|
262
|
+
usageSilent: boolean;
|
|
263
|
+
/**
|
|
264
|
+
* Sub commands.
|
|
265
|
+
* @see {@link CliOptions.subCommands}
|
|
266
|
+
*/
|
|
267
|
+
subCommands: Map<string, Command<any> | LazyCommand<any>> | undefined;
|
|
268
|
+
/**
|
|
269
|
+
* Render function the command usage.
|
|
270
|
+
*/
|
|
271
|
+
renderUsage: ((ctx: Readonly<CommandContext<G>>) => Promise<string>) | null | undefined;
|
|
272
|
+
/**
|
|
273
|
+
* Render function the header section in the command usage.
|
|
274
|
+
*/
|
|
275
|
+
renderHeader: ((ctx: Readonly<CommandContext<G>>) => Promise<string>) | null | undefined;
|
|
276
|
+
/**
|
|
277
|
+
* Render function the validation errors.
|
|
278
|
+
*/
|
|
279
|
+
renderValidationErrors: ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null | undefined;
|
|
280
|
+
/**
|
|
281
|
+
* Hook that runs before any command execution
|
|
282
|
+
* @see {@link CliOptions.onBeforeCommand}
|
|
283
|
+
*/
|
|
284
|
+
onBeforeCommand: ((ctx: Readonly<CommandContext<G>>) => Awaitable<void>) | undefined;
|
|
285
|
+
/**
|
|
286
|
+
* Hook that runs after successful command execution
|
|
287
|
+
* @see {@link CliOptions.onAfterCommand}
|
|
288
|
+
*/
|
|
289
|
+
onAfterCommand: ((ctx: Readonly<CommandContext<G>>, result: string | void) => Awaitable<void>) | undefined;
|
|
290
|
+
/**
|
|
291
|
+
* Hook that runs when a command throws an error
|
|
292
|
+
* @see {@link CliOptions.onErrorCommand}
|
|
293
|
+
*/
|
|
294
|
+
onErrorCommand: ((ctx: Readonly<CommandContext<G>>, error: Error) => Awaitable<void>) | undefined;
|
|
295
|
+
}
|
|
296
|
+
/**
|
|
297
|
+
* CLI options of `cli` function.
|
|
298
|
+
*/
|
|
299
|
+
|
|
300
|
+
/**
|
|
301
|
+
* Command call mode.
|
|
302
|
+
*/
|
|
303
|
+
type CommandCallMode = 'entry' | 'subCommand' | 'unexpected';
|
|
304
|
+
/**
|
|
305
|
+
* Command context.
|
|
306
|
+
* Command context is the context of the command execution.
|
|
307
|
+
*/
|
|
308
|
+
interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
309
|
+
/**
|
|
310
|
+
* Command name, that is the command that is executed.
|
|
311
|
+
* The command name is same {@link CommandEnvironment.name}.
|
|
312
|
+
*/
|
|
313
|
+
name: string | undefined;
|
|
314
|
+
/**
|
|
315
|
+
* Command description, that is the description of the command that is executed.
|
|
316
|
+
* The command description is same {@link CommandEnvironment.description}.
|
|
317
|
+
*/
|
|
318
|
+
description: string | undefined;
|
|
319
|
+
/**
|
|
320
|
+
* Command environment, that is the environment of the command that is executed.
|
|
321
|
+
* The command environment is same {@link CommandEnvironment}.
|
|
322
|
+
*/
|
|
323
|
+
env: Readonly<CommandEnvironment<G>>;
|
|
324
|
+
/**
|
|
325
|
+
* Command arguments, that is the arguments of the command that is executed.
|
|
326
|
+
* The command arguments is same {@link Command.args}.
|
|
327
|
+
*/
|
|
328
|
+
args: ExtractArgs<G>;
|
|
329
|
+
/**
|
|
330
|
+
* Command values, that is the values of the command that is executed.
|
|
331
|
+
* Resolve values with `resolveArgs` from command arguments and {@link Command.args}.
|
|
332
|
+
*/
|
|
333
|
+
values: ArgValues<ExtractArgs<G>>;
|
|
334
|
+
/**
|
|
335
|
+
* Command positionals arguments, that is the positionals of the command that is executed.
|
|
336
|
+
* Resolve positionals with `resolveArgs` from command arguments.
|
|
337
|
+
*/
|
|
338
|
+
positionals: string[];
|
|
339
|
+
/**
|
|
340
|
+
* Command rest arguments, that is the remaining argument not resolved by the optional command option delimiter `--`.
|
|
341
|
+
*/
|
|
342
|
+
rest: string[];
|
|
343
|
+
/**
|
|
344
|
+
* Original command line arguments.
|
|
345
|
+
* This argument is passed from `cli` function.
|
|
346
|
+
*/
|
|
347
|
+
_: string[];
|
|
348
|
+
/**
|
|
349
|
+
* Argument tokens, that is parsed by `parseArgs` function.
|
|
350
|
+
*/
|
|
351
|
+
tokens: ArgToken[];
|
|
352
|
+
/**
|
|
353
|
+
* Whether the currently executing command has been executed with the sub-command name omitted.
|
|
354
|
+
*/
|
|
355
|
+
omitted: boolean;
|
|
356
|
+
/**
|
|
357
|
+
* Command call mode.
|
|
358
|
+
* The command call mode is `entry` when the command is executed as an entry command, and `subCommand` when the command is executed as a sub-command.
|
|
359
|
+
*/
|
|
360
|
+
callMode: CommandCallMode;
|
|
361
|
+
/**
|
|
362
|
+
* Whether to convert the camel-case style argument name to kebab-case.
|
|
363
|
+
* This context value is set from {@link Command.toKebab} option.
|
|
364
|
+
*/
|
|
365
|
+
toKebab?: boolean;
|
|
366
|
+
/**
|
|
367
|
+
* Output a message.
|
|
368
|
+
* If {@link CommandEnvironment.usageSilent} is true, the message is not output.
|
|
369
|
+
* @param message an output message, @see {@link console.log}
|
|
370
|
+
* @param optionalParams an optional parameters, @see {@link console.log}
|
|
371
|
+
* @internal
|
|
372
|
+
*/
|
|
373
|
+
log: (message?: any, ...optionalParams: any[]) => void;
|
|
374
|
+
/**
|
|
375
|
+
* Command context extensions.
|
|
376
|
+
*/
|
|
377
|
+
extensions: keyof ExtractExtensions<G> extends never ? undefined : ExtractExtensions<G>;
|
|
378
|
+
/**
|
|
379
|
+
* Validation error from argument parsing.
|
|
380
|
+
* This will be set if argument validation fails during CLI execution.
|
|
381
|
+
*/
|
|
382
|
+
validationError?: AggregateError;
|
|
383
|
+
}
|
|
384
|
+
/**
|
|
385
|
+
* CommandContextCore type (base type without extensions)
|
|
386
|
+
*/
|
|
387
|
+
|
|
388
|
+
/**
|
|
389
|
+
* Command interface.
|
|
390
|
+
*/
|
|
391
|
+
interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
|
|
392
|
+
/**
|
|
393
|
+
* Command name.
|
|
394
|
+
* It's used to find command line arguments to execute from sub commands, and it's recommended to specify.
|
|
395
|
+
*/
|
|
396
|
+
name?: string;
|
|
397
|
+
/**
|
|
398
|
+
* Command description.
|
|
399
|
+
* It's used to describe the command in usage and it's recommended to specify.
|
|
400
|
+
*/
|
|
401
|
+
description?: string;
|
|
402
|
+
/**
|
|
403
|
+
* Command arguments.
|
|
404
|
+
* Each argument can include a description property to describe the argument in usage.
|
|
405
|
+
*/
|
|
406
|
+
args?: ExtractArgs<G>;
|
|
407
|
+
/**
|
|
408
|
+
* Command examples.
|
|
409
|
+
* examples of how to use the command.
|
|
410
|
+
*/
|
|
411
|
+
examples?: string | CommandExamplesFetcher<G>;
|
|
412
|
+
/**
|
|
413
|
+
* Command runner. it's the command to be executed
|
|
414
|
+
*/
|
|
415
|
+
run?: CommandRunner<G>;
|
|
416
|
+
/**
|
|
417
|
+
* Whether to convert the camel-case style argument name to kebab-case.
|
|
418
|
+
* If you will set to `true`, All {@link Command.args} names will be converted to kebab-case.
|
|
419
|
+
*/
|
|
420
|
+
toKebab?: boolean;
|
|
421
|
+
}
|
|
422
|
+
/**
|
|
423
|
+
* Lazy command interface.
|
|
424
|
+
* Lazy command that's not loaded until it is executed.
|
|
425
|
+
*/
|
|
426
|
+
type LazyCommand<G extends GunshiParamsConstraint = DefaultGunshiParams> = {
|
|
427
|
+
/**
|
|
428
|
+
* Command load function
|
|
429
|
+
*/
|
|
430
|
+
(): Awaitable<Command<G> | CommandRunner<G>>;
|
|
431
|
+
/**
|
|
432
|
+
* Command name
|
|
433
|
+
*/
|
|
434
|
+
commandName?: string;
|
|
435
|
+
} & Omit<Command<G>, 'run' | 'name'>;
|
|
436
|
+
/**
|
|
437
|
+
* Define a command type.
|
|
438
|
+
*/
|
|
439
|
+
|
|
440
|
+
/**
|
|
441
|
+
* Command examples fetcher.
|
|
442
|
+
* @param ctx A {@link CommandContext | command context}
|
|
443
|
+
* @returns A fetched command examples.
|
|
444
|
+
*/
|
|
445
|
+
type CommandExamplesFetcher<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => Awaitable<string>;
|
|
446
|
+
/**
|
|
447
|
+
* Command runner.
|
|
448
|
+
* @param ctx A {@link CommandContext | command context}
|
|
449
|
+
* @returns void or string (for CLI output)
|
|
450
|
+
*/
|
|
451
|
+
type CommandRunner<G extends GunshiParamsConstraint = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>) => Awaitable<void | string>;
|
|
452
|
+
/**
|
|
453
|
+
* Command loader.
|
|
454
|
+
* A function that returns a command or command runner.
|
|
455
|
+
* This is used to lazily load commands.
|
|
456
|
+
* @returns A command or command runner
|
|
457
|
+
*/
|
|
458
|
+
type CommandLoader<G extends GunshiParamsConstraint = DefaultGunshiParams> = () => Awaitable<Command<G> | CommandRunner<G>>; //#endregion
|
|
459
|
+
//#region ../gunshi/src/definition.d.ts
|
|
460
|
+
|
|
461
|
+
/**
|
|
462
|
+
* Command decorator.
|
|
463
|
+
* A function that wraps a command runner to add or modify its behavior.
|
|
464
|
+
* @param baseRunner The base command runner to decorate
|
|
465
|
+
* @returns The decorated command runner
|
|
466
|
+
*/
|
|
467
|
+
/**
|
|
468
|
+
* Define a {@link Command | command}
|
|
469
|
+
* @param definition A {@link Command | command} definition
|
|
470
|
+
*/
|
|
471
|
+
declare function define<A extends Args>(definition: Command<{
|
|
472
|
+
args: A;
|
|
473
|
+
extensions: {};
|
|
474
|
+
}>): Command<{
|
|
475
|
+
args: A;
|
|
476
|
+
extensions: {};
|
|
477
|
+
}>;
|
|
478
|
+
/**
|
|
479
|
+
* Define a {@link Command | command}
|
|
480
|
+
* @param definition A {@link Command | command} definition
|
|
481
|
+
*/
|
|
482
|
+
declare function define<E extends ExtendContext>(definition: Command<{
|
|
483
|
+
args: Args;
|
|
484
|
+
extensions: E;
|
|
485
|
+
}>): Command<{
|
|
486
|
+
args: Args;
|
|
487
|
+
extensions: E;
|
|
488
|
+
}>;
|
|
489
|
+
/**
|
|
490
|
+
* Define a {@link Command | command}
|
|
491
|
+
* @param definition A {@link Command | command} definition
|
|
492
|
+
*/
|
|
493
|
+
declare function define<G extends GunshiParamsConstraint = DefaultGunshiParams>(definition: Command<G>): Command<G>;
|
|
494
|
+
/**
|
|
495
|
+
* Define a {@link LazyCommand | lazy command}
|
|
496
|
+
* @param loader A {@link CommandLoader | command loader}
|
|
497
|
+
* @returns A {@link LazyCommand | lazy command} loader
|
|
498
|
+
*/
|
|
499
|
+
declare function lazy<A extends Args>(loader: CommandLoader<{
|
|
500
|
+
args: A;
|
|
501
|
+
extensions: {};
|
|
502
|
+
}>): LazyCommand<{
|
|
503
|
+
args: A;
|
|
504
|
+
extensions: {};
|
|
505
|
+
}>;
|
|
506
|
+
/**
|
|
507
|
+
* Define a {@link LazyCommand | lazy command} with definition.
|
|
508
|
+
* @param loader A {@link CommandLoader | command loader} function that returns a command definition
|
|
509
|
+
* @param definition An optional {@link Command | command} definition
|
|
510
|
+
* @returns A {@link LazyCommand | lazy command} that can be executed later
|
|
511
|
+
*/
|
|
512
|
+
declare function lazy<A extends Args>(loader: CommandLoader<{
|
|
513
|
+
args: A;
|
|
514
|
+
extensions: {};
|
|
515
|
+
}>, definition: Command<{
|
|
516
|
+
args: A;
|
|
517
|
+
extensions: {};
|
|
518
|
+
}>): LazyCommand<{
|
|
519
|
+
args: A;
|
|
520
|
+
extensions: {};
|
|
521
|
+
}>;
|
|
522
|
+
/**
|
|
523
|
+
* Define a {@link LazyCommand | lazy command}
|
|
524
|
+
* @param loader A {@link CommandLoader | command loader}
|
|
525
|
+
* @returns A {@link LazyCommand | lazy command} loader
|
|
526
|
+
*/
|
|
527
|
+
declare function lazy<E extends ExtendContext>(loader: CommandLoader<{
|
|
528
|
+
args: Args;
|
|
529
|
+
extensions: E;
|
|
530
|
+
}>): LazyCommand<{
|
|
531
|
+
args: Args;
|
|
532
|
+
extensions: E;
|
|
533
|
+
}>;
|
|
534
|
+
/**
|
|
535
|
+
* Define a {@link LazyCommand | lazy command} with definition.
|
|
536
|
+
* @param loader A {@link CommandLoader | command loader} function that returns a command definition
|
|
537
|
+
* @param definition An optional {@link Command | command} definition
|
|
538
|
+
* @returns A {@link LazyCommand | lazy command} that can be executed later
|
|
539
|
+
*/
|
|
540
|
+
declare function lazy<E extends ExtendContext>(loader: CommandLoader<{
|
|
541
|
+
args: Args;
|
|
542
|
+
extensions: E;
|
|
543
|
+
}>, definition: Command<{
|
|
544
|
+
args: Args;
|
|
545
|
+
extensions: E;
|
|
546
|
+
}>): LazyCommand<{
|
|
547
|
+
args: Args;
|
|
548
|
+
extensions: E;
|
|
549
|
+
}>;
|
|
550
|
+
/**
|
|
551
|
+
* Define a {@link LazyCommand | lazy command}
|
|
552
|
+
* @param loader A {@link CommandLoader | command loader}
|
|
553
|
+
* @returns A {@link LazyCommand | lazy command} loader
|
|
554
|
+
*/
|
|
555
|
+
declare function lazy<G extends GunshiParamsConstraint = DefaultGunshiParams>(loader: CommandLoader<G>): LazyCommand<G>;
|
|
556
|
+
/**
|
|
557
|
+
* Define a {@link LazyCommand | lazy command} with definition.
|
|
558
|
+
* @param loader A {@link CommandLoader | command loader} function that returns a command definition
|
|
559
|
+
* @param definition An optional {@link Command | command} definition
|
|
560
|
+
* @returns A {@link LazyCommand | lazy command} that can be executed later
|
|
561
|
+
*/
|
|
562
|
+
declare function lazy<G extends GunshiParamsConstraint = DefaultGunshiParams>(loader: CommandLoader<G>, definition: Command<G>): LazyCommand<G>;
|
|
563
|
+
|
|
564
|
+
//#endregion
|
|
565
|
+
export { ArgSchema, ArgValues, Args, Command, CommandLoader, CommandRunner, DefaultGunshiParams, ExtendContext, GunshiParams, LazyCommand, define, lazy };
|
package/lib/index.js
ADDED
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
//#region ../gunshi/src/definition.ts
|
|
2
|
+
/**
|
|
3
|
+
* Define a {@link Command | command}
|
|
4
|
+
* @param definition A {@link Command | command} definition
|
|
5
|
+
*/
|
|
6
|
+
function define(definition) {
|
|
7
|
+
return definition;
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* Define a {@link LazyCommand | lazy command} with or without definition.
|
|
11
|
+
* @param loader A {@link CommandLoader | command loader} function that returns a command definition
|
|
12
|
+
* @param definition An optional {@link Command | command} definition
|
|
13
|
+
* @returns A {@link LazyCommand | lazy command} that can be executed later
|
|
14
|
+
*/
|
|
15
|
+
function lazy(loader, definition) {
|
|
16
|
+
const lazyCommand = loader;
|
|
17
|
+
if (definition != null) {
|
|
18
|
+
lazyCommand.commandName = definition.name;
|
|
19
|
+
lazyCommand.description = definition.description;
|
|
20
|
+
lazyCommand.args = definition.args;
|
|
21
|
+
lazyCommand.examples = definition.examples;
|
|
22
|
+
if ("resource" in definition) lazyCommand.resource = definition.resource;
|
|
23
|
+
lazyCommand.toKebab = definition.toKebab;
|
|
24
|
+
}
|
|
25
|
+
return lazyCommand;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
//#endregion
|
|
29
|
+
export { define, lazy };
|
package/package.json
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@gunshi/definition",
|
|
3
|
+
"description": "utilities for gunshi command definition",
|
|
4
|
+
"version": "0.26.3",
|
|
5
|
+
"author": {
|
|
6
|
+
"name": "kazuya kawaguchi",
|
|
7
|
+
"email": "kawakazu80@gmail.com"
|
|
8
|
+
},
|
|
9
|
+
"license": "MIT",
|
|
10
|
+
"funding": "https://github.com/sponsors/kazupon",
|
|
11
|
+
"bugs": {
|
|
12
|
+
"url": "https://github.com/kazupon/gunshi/issues"
|
|
13
|
+
},
|
|
14
|
+
"repository": {
|
|
15
|
+
"type": "git",
|
|
16
|
+
"url": "git+https://github.com/kazupon/gunshi.git",
|
|
17
|
+
"directory": "packages/definition"
|
|
18
|
+
},
|
|
19
|
+
"keywords": [
|
|
20
|
+
"gunshi",
|
|
21
|
+
"command",
|
|
22
|
+
"definition",
|
|
23
|
+
"cli"
|
|
24
|
+
],
|
|
25
|
+
"publishConfig": {
|
|
26
|
+
"access": "public"
|
|
27
|
+
},
|
|
28
|
+
"engines": {
|
|
29
|
+
"node": ">= 20"
|
|
30
|
+
},
|
|
31
|
+
"type": "module",
|
|
32
|
+
"files": [
|
|
33
|
+
"lib"
|
|
34
|
+
],
|
|
35
|
+
"module": "lib/index.js",
|
|
36
|
+
"exports": {
|
|
37
|
+
".": {
|
|
38
|
+
"types": "./lib/index.d.ts",
|
|
39
|
+
"import": "./lib/index.js",
|
|
40
|
+
"require": "./lib/index.js",
|
|
41
|
+
"default": "./lib/index.js"
|
|
42
|
+
},
|
|
43
|
+
"./package.json": "./package.json"
|
|
44
|
+
},
|
|
45
|
+
"types": "lib/index.d.ts",
|
|
46
|
+
"typesVersions": {
|
|
47
|
+
"*": {
|
|
48
|
+
"*": [
|
|
49
|
+
"./lib/*",
|
|
50
|
+
"./*"
|
|
51
|
+
]
|
|
52
|
+
}
|
|
53
|
+
},
|
|
54
|
+
"devDependencies": {
|
|
55
|
+
"deno": "^2.3.3",
|
|
56
|
+
"jsr": "^0.13.4",
|
|
57
|
+
"jsr-exports-lint": "^0.4.1",
|
|
58
|
+
"publint": "^0.3.12",
|
|
59
|
+
"tsdown": "^0.12.3",
|
|
60
|
+
"gunshi": "0.26.3"
|
|
61
|
+
},
|
|
62
|
+
"scripts": {
|
|
63
|
+
"build": "tsdown",
|
|
64
|
+
"lint:jsr": "jsr publish --dry-run --allow-dirty",
|
|
65
|
+
"typecheck:deno": "deno check --import-map=../../importmap.json ./src"
|
|
66
|
+
}
|
|
67
|
+
}
|