@optique/run 1.0.0-dev.431 → 1.0.0-dev.432

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.
Files changed (5) hide show
  1. package/dist/run.cjs +43 -51
  2. package/dist/run.d.cts +41 -80
  3. package/dist/run.d.ts +41 -80
  4. package/dist/run.js +43 -51
  5. package/package.json +2 -2
package/dist/run.cjs CHANGED
@@ -56,68 +56,60 @@ function runAsync(parserOrProgram, options = {}) {
56
56
  */
57
57
  function buildCoreOptions(options, programMetadata) {
58
58
  const { programName = node_path.default.basename(node_process.default.argv[1] || "cli"), args = node_process.default.argv.slice(2), colors = node_process.default.stdout.isTTY, maxWidth = node_process.default.stdout.columns, showDefault, showChoices, sectionOrder, help, version, completion, aboveError = "usage", errorExitCode = 1, brief = programMetadata?.brief, description = programMetadata?.description, examples = programMetadata?.examples, author = programMetadata?.author, bugs = programMetadata?.bugs, footer = programMetadata?.footer } = options;
59
- const helpConfig = help ? typeof help === "string" ? {
60
- mode: help,
61
- onShow: () => node_process.default.exit(0)
62
- } : {
63
- mode: help.mode,
64
- group: help.group,
65
- onShow: () => node_process.default.exit(0)
66
- } : void 0;
59
+ const onShow = () => node_process.default.exit(0);
60
+ const helpConfig = (() => {
61
+ if (!help) return void 0;
62
+ if (typeof help === "string") switch (help) {
63
+ case "command": return {
64
+ command: true,
65
+ onShow
66
+ };
67
+ case "option": return {
68
+ option: true,
69
+ onShow
70
+ };
71
+ case "both": return {
72
+ command: true,
73
+ option: true,
74
+ onShow
75
+ };
76
+ }
77
+ return {
78
+ ...help,
79
+ onShow
80
+ };
81
+ })();
67
82
  const versionConfig = (() => {
68
83
  if (!version) return void 0;
69
84
  if (typeof version === "string") return {
70
- mode: "option",
71
85
  value: version,
72
- onShow: () => node_process.default.exit(0)
73
- };
74
- const mode = version.mode ?? "option";
75
- if (mode === "command" || mode === "both") return {
76
- mode,
77
- value: version.value,
78
- group: version.group,
79
- onShow: () => node_process.default.exit(0)
86
+ option: true,
87
+ onShow
80
88
  };
81
89
  return {
82
- mode,
83
- value: version.value,
84
- onShow: () => node_process.default.exit(0)
90
+ ...version,
91
+ onShow
85
92
  };
86
93
  })();
87
94
  const completionConfig = (() => {
88
95
  if (!completion) return void 0;
89
- const onShow = () => node_process.default.exit(0);
90
- if (typeof completion === "string") return {
91
- mode: completion,
92
- name: "both",
93
- helpVisibility: "both",
94
- onShow
95
- };
96
- const mode = completion.mode ?? "both";
97
- const shells = completion.shells;
98
- const cGroup = completion.group;
99
- if (completion.name === "singular") return {
100
- mode,
101
- shells,
102
- ...cGroup != null && { group: cGroup },
103
- name: "singular",
104
- helpVisibility: completion.helpVisibility ?? "singular",
105
- onShow
106
- };
107
- if (completion.name === "plural") return {
108
- mode,
109
- shells,
110
- ...cGroup != null && { group: cGroup },
111
- name: "plural",
112
- helpVisibility: completion.helpVisibility ?? "plural",
113
- onShow
114
- };
96
+ if (typeof completion === "string") switch (completion) {
97
+ case "command": return {
98
+ command: true,
99
+ onShow
100
+ };
101
+ case "option": return {
102
+ option: true,
103
+ onShow
104
+ };
105
+ case "both": return {
106
+ command: true,
107
+ option: true,
108
+ onShow
109
+ };
110
+ }
115
111
  return {
116
- mode,
117
- shells,
118
- ...cGroup != null && { group: cGroup },
119
- name: "both",
120
- helpVisibility: completion.helpVisibility ?? "both",
112
+ ...completion,
121
113
  onShow
122
114
  };
123
115
  })();
package/dist/run.d.cts CHANGED
@@ -1,6 +1,6 @@
1
1
  import { ShellCompletion } from "@optique/core/completion";
2
2
  import { SourceContext } from "@optique/core/context";
3
- import { ExtractRequiredOptions } from "@optique/core/facade";
3
+ import { CommandSubConfig, ExtractRequiredOptions, OptionSubConfig } from "@optique/core/facade";
4
4
  import { InferMode, InferValue, Mode, ModeValue, Parser } from "@optique/core/parser";
5
5
  import { Program } from "@optique/core/program";
6
6
  import { DocSection, ShowChoicesOptions, ShowDefaultOptions } from "@optique/core/doc";
@@ -84,63 +84,66 @@ interface RunOptions {
84
84
  * - `"command"`: Only the `help` subcommand is available
85
85
  * - `"option"`: Only the `--help` option is available
86
86
  * - `"both"`: Both `help` subcommand and `--help` option are available
87
- * - `object`: Advanced configuration with mode and group
88
- * - `mode`: "command" | "both"
89
- * - `group`: Group label for help command in help output (optional)
87
+ * - `object`: Advanced configuration with `command` and/or `option`
88
+ * sub-configs. At least one of `command` or `option` must be specified.
90
89
  *
91
90
  * When not provided, help functionality is disabled.
91
+ *
92
+ * @since 1.0.0
92
93
  */
93
- readonly help?: "command" | "option" | "both" | {
94
- readonly mode: "command" | "both";
95
- /**
96
- * Group label for the help command in help output.
97
- * @since 0.10.0
98
- */
99
- readonly group?: string;
100
- };
94
+ readonly help?: "command" | "option" | "both" | (({
95
+ readonly command: true | CommandSubConfig;
96
+ readonly option?: true | OptionSubConfig;
97
+ } | {
98
+ readonly option: true | OptionSubConfig;
99
+ readonly command?: true | CommandSubConfig;
100
+ }));
101
101
  /**
102
102
  * Version configuration. Determines how version is made available:
103
103
  *
104
104
  * - `string`: Version value with default `"option"` mode (--version only)
105
- * - `object`: Advanced configuration with version value and mode
106
- * - `value`: The version string to display
107
- * - `mode`: "command" | "option" | "both" (default: "option")
108
- * - `group`: Group label for version command in help output (only
109
- * when mode is "command" or "both")
105
+ * - `object`: Advanced configuration with version value and `command`
106
+ * and/or `option` sub-configs. At least one of `command` or `option`
107
+ * must be specified.
110
108
  *
111
109
  * When not provided, version functionality is disabled.
110
+ *
111
+ * @since 1.0.0
112
112
  */
113
- readonly version?: string | {
113
+ readonly version?: string | ({
114
114
  readonly value: string;
115
- readonly mode: "command" | "both";
116
- /**
117
- * Group label for the version command in help output.
118
- * @since 0.10.0
119
- */
120
- readonly group?: string;
115
+ } & ({
116
+ readonly command: true | CommandSubConfig;
117
+ readonly option?: true | OptionSubConfig;
121
118
  } | {
122
- readonly value: string;
123
- readonly mode?: "option";
124
- readonly group?: never;
125
- };
119
+ readonly option: true | OptionSubConfig;
120
+ readonly command?: true | CommandSubConfig;
121
+ }));
126
122
  /**
127
- * Completion configuration. Determines how shell completion is made available:
123
+ * Completion configuration. Determines how shell completion is made
124
+ * available:
128
125
  *
129
126
  * - `"command"`: Only the `completion` subcommand is available
130
127
  * - `"option"`: Only the `--completion` option is available
131
- * - `"both"`: Both `completion` subcommand and `--completion` option are available
132
- * - `object`: Advanced configuration with mode and custom shells
133
- * - `mode`: "command" | "option" | "both" (default: "both")
134
- * - `name`: "singular" | "plural" | "both" (default: "both")
135
- * - `helpVisibility`: "singular" | "plural" | "both" | "none"
136
- * (default: matches `name`)
137
- * - `shells`: Custom shell completions (optional)
128
+ * - `"both"`: Both `completion` subcommand and `--completion` option
129
+ * are available
130
+ * - `object`: Advanced configuration with `command` and/or `option`
131
+ * sub-configs and optional custom shells. At least one of `command`
132
+ * or `option` must be specified.
138
133
  *
139
134
  * When not provided, completion functionality is disabled.
140
135
  *
141
- * @since 0.6.0
136
+ * @since 1.0.0
142
137
  */
143
- readonly completion?: "command" | "option" | "both" | CompletionOptions;
138
+ readonly completion?: "command" | "option" | "both" | ({
139
+ readonly shells?: Record<string, ShellCompletion>;
140
+ } & ({
141
+ readonly command: true | CommandSubConfig;
142
+ readonly option?: true | OptionSubConfig;
143
+ } | {
144
+ readonly option: true | OptionSubConfig;
145
+ readonly command?: true | CommandSubConfig;
146
+ }));
144
147
  /**
145
148
  * What to display above error messages:
146
149
  *
@@ -203,48 +206,6 @@ interface RunOptions {
203
206
  */
204
207
  readonly contexts?: readonly SourceContext<unknown>[];
205
208
  }
206
- type CompletionHelpVisibility = "singular" | "plural" | "both" | "none";
207
- type CompletionOptionsBase = {
208
- readonly mode?: "command" | "both";
209
- /**
210
- * Group label for the completion command in help output.
211
- * @since 0.10.0
212
- */
213
- readonly group?: string;
214
- readonly shells?: Record<string, ShellCompletion>;
215
- } | {
216
- readonly mode: "option";
217
- readonly group?: never;
218
- readonly shells?: Record<string, ShellCompletion>;
219
- };
220
- type CompletionOptionsBoth = CompletionOptionsBase & {
221
- readonly name?: "both";
222
- /**
223
- * Controls which completion aliases are shown in help and usage output.
224
- *
225
- * @since 0.10.0
226
- */
227
- readonly helpVisibility?: CompletionHelpVisibility;
228
- };
229
- type CompletionOptionsSingular = CompletionOptionsBase & {
230
- readonly name: "singular";
231
- /**
232
- * Controls which completion aliases are shown in help and usage output.
233
- *
234
- * @since 0.10.0
235
- */
236
- readonly helpVisibility?: "singular" | "none";
237
- };
238
- type CompletionOptionsPlural = CompletionOptionsBase & {
239
- readonly name: "plural";
240
- /**
241
- * Controls which completion aliases are shown in help and usage output.
242
- *
243
- * @since 0.10.0
244
- */
245
- readonly helpVisibility?: "plural" | "none";
246
- };
247
- type CompletionOptions = CompletionOptionsBoth | CompletionOptionsSingular | CompletionOptionsPlural;
248
209
  /**
249
210
  * Runs a command-line parser with automatic process integration.
250
211
  *
package/dist/run.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { ExtractRequiredOptions } from "@optique/core/facade";
1
+ import { CommandSubConfig, ExtractRequiredOptions, OptionSubConfig } from "@optique/core/facade";
2
2
  import { Message } from "@optique/core/message";
3
3
  import { ShellCompletion } from "@optique/core/completion";
4
4
  import { SourceContext } from "@optique/core/context";
@@ -84,63 +84,66 @@ interface RunOptions {
84
84
  * - `"command"`: Only the `help` subcommand is available
85
85
  * - `"option"`: Only the `--help` option is available
86
86
  * - `"both"`: Both `help` subcommand and `--help` option are available
87
- * - `object`: Advanced configuration with mode and group
88
- * - `mode`: "command" | "both"
89
- * - `group`: Group label for help command in help output (optional)
87
+ * - `object`: Advanced configuration with `command` and/or `option`
88
+ * sub-configs. At least one of `command` or `option` must be specified.
90
89
  *
91
90
  * When not provided, help functionality is disabled.
91
+ *
92
+ * @since 1.0.0
92
93
  */
93
- readonly help?: "command" | "option" | "both" | {
94
- readonly mode: "command" | "both";
95
- /**
96
- * Group label for the help command in help output.
97
- * @since 0.10.0
98
- */
99
- readonly group?: string;
100
- };
94
+ readonly help?: "command" | "option" | "both" | (({
95
+ readonly command: true | CommandSubConfig;
96
+ readonly option?: true | OptionSubConfig;
97
+ } | {
98
+ readonly option: true | OptionSubConfig;
99
+ readonly command?: true | CommandSubConfig;
100
+ }));
101
101
  /**
102
102
  * Version configuration. Determines how version is made available:
103
103
  *
104
104
  * - `string`: Version value with default `"option"` mode (--version only)
105
- * - `object`: Advanced configuration with version value and mode
106
- * - `value`: The version string to display
107
- * - `mode`: "command" | "option" | "both" (default: "option")
108
- * - `group`: Group label for version command in help output (only
109
- * when mode is "command" or "both")
105
+ * - `object`: Advanced configuration with version value and `command`
106
+ * and/or `option` sub-configs. At least one of `command` or `option`
107
+ * must be specified.
110
108
  *
111
109
  * When not provided, version functionality is disabled.
110
+ *
111
+ * @since 1.0.0
112
112
  */
113
- readonly version?: string | {
113
+ readonly version?: string | ({
114
114
  readonly value: string;
115
- readonly mode: "command" | "both";
116
- /**
117
- * Group label for the version command in help output.
118
- * @since 0.10.0
119
- */
120
- readonly group?: string;
115
+ } & ({
116
+ readonly command: true | CommandSubConfig;
117
+ readonly option?: true | OptionSubConfig;
121
118
  } | {
122
- readonly value: string;
123
- readonly mode?: "option";
124
- readonly group?: never;
125
- };
119
+ readonly option: true | OptionSubConfig;
120
+ readonly command?: true | CommandSubConfig;
121
+ }));
126
122
  /**
127
- * Completion configuration. Determines how shell completion is made available:
123
+ * Completion configuration. Determines how shell completion is made
124
+ * available:
128
125
  *
129
126
  * - `"command"`: Only the `completion` subcommand is available
130
127
  * - `"option"`: Only the `--completion` option is available
131
- * - `"both"`: Both `completion` subcommand and `--completion` option are available
132
- * - `object`: Advanced configuration with mode and custom shells
133
- * - `mode`: "command" | "option" | "both" (default: "both")
134
- * - `name`: "singular" | "plural" | "both" (default: "both")
135
- * - `helpVisibility`: "singular" | "plural" | "both" | "none"
136
- * (default: matches `name`)
137
- * - `shells`: Custom shell completions (optional)
128
+ * - `"both"`: Both `completion` subcommand and `--completion` option
129
+ * are available
130
+ * - `object`: Advanced configuration with `command` and/or `option`
131
+ * sub-configs and optional custom shells. At least one of `command`
132
+ * or `option` must be specified.
138
133
  *
139
134
  * When not provided, completion functionality is disabled.
140
135
  *
141
- * @since 0.6.0
136
+ * @since 1.0.0
142
137
  */
143
- readonly completion?: "command" | "option" | "both" | CompletionOptions;
138
+ readonly completion?: "command" | "option" | "both" | ({
139
+ readonly shells?: Record<string, ShellCompletion>;
140
+ } & ({
141
+ readonly command: true | CommandSubConfig;
142
+ readonly option?: true | OptionSubConfig;
143
+ } | {
144
+ readonly option: true | OptionSubConfig;
145
+ readonly command?: true | CommandSubConfig;
146
+ }));
144
147
  /**
145
148
  * What to display above error messages:
146
149
  *
@@ -203,48 +206,6 @@ interface RunOptions {
203
206
  */
204
207
  readonly contexts?: readonly SourceContext<unknown>[];
205
208
  }
206
- type CompletionHelpVisibility = "singular" | "plural" | "both" | "none";
207
- type CompletionOptionsBase = {
208
- readonly mode?: "command" | "both";
209
- /**
210
- * Group label for the completion command in help output.
211
- * @since 0.10.0
212
- */
213
- readonly group?: string;
214
- readonly shells?: Record<string, ShellCompletion>;
215
- } | {
216
- readonly mode: "option";
217
- readonly group?: never;
218
- readonly shells?: Record<string, ShellCompletion>;
219
- };
220
- type CompletionOptionsBoth = CompletionOptionsBase & {
221
- readonly name?: "both";
222
- /**
223
- * Controls which completion aliases are shown in help and usage output.
224
- *
225
- * @since 0.10.0
226
- */
227
- readonly helpVisibility?: CompletionHelpVisibility;
228
- };
229
- type CompletionOptionsSingular = CompletionOptionsBase & {
230
- readonly name: "singular";
231
- /**
232
- * Controls which completion aliases are shown in help and usage output.
233
- *
234
- * @since 0.10.0
235
- */
236
- readonly helpVisibility?: "singular" | "none";
237
- };
238
- type CompletionOptionsPlural = CompletionOptionsBase & {
239
- readonly name: "plural";
240
- /**
241
- * Controls which completion aliases are shown in help and usage output.
242
- *
243
- * @since 0.10.0
244
- */
245
- readonly helpVisibility?: "plural" | "none";
246
- };
247
- type CompletionOptions = CompletionOptionsBoth | CompletionOptionsSingular | CompletionOptionsPlural;
248
209
  /**
249
210
  * Runs a command-line parser with automatic process integration.
250
211
  *
package/dist/run.js CHANGED
@@ -55,68 +55,60 @@ function runAsync(parserOrProgram, options = {}) {
55
55
  */
56
56
  function buildCoreOptions(options, programMetadata) {
57
57
  const { programName = path.basename(process.argv[1] || "cli"), args = process.argv.slice(2), colors = process.stdout.isTTY, maxWidth = process.stdout.columns, showDefault, showChoices, sectionOrder, help, version, completion, aboveError = "usage", errorExitCode = 1, brief = programMetadata?.brief, description = programMetadata?.description, examples = programMetadata?.examples, author = programMetadata?.author, bugs = programMetadata?.bugs, footer = programMetadata?.footer } = options;
58
- const helpConfig = help ? typeof help === "string" ? {
59
- mode: help,
60
- onShow: () => process.exit(0)
61
- } : {
62
- mode: help.mode,
63
- group: help.group,
64
- onShow: () => process.exit(0)
65
- } : void 0;
58
+ const onShow = () => process.exit(0);
59
+ const helpConfig = (() => {
60
+ if (!help) return void 0;
61
+ if (typeof help === "string") switch (help) {
62
+ case "command": return {
63
+ command: true,
64
+ onShow
65
+ };
66
+ case "option": return {
67
+ option: true,
68
+ onShow
69
+ };
70
+ case "both": return {
71
+ command: true,
72
+ option: true,
73
+ onShow
74
+ };
75
+ }
76
+ return {
77
+ ...help,
78
+ onShow
79
+ };
80
+ })();
66
81
  const versionConfig = (() => {
67
82
  if (!version) return void 0;
68
83
  if (typeof version === "string") return {
69
- mode: "option",
70
84
  value: version,
71
- onShow: () => process.exit(0)
72
- };
73
- const mode = version.mode ?? "option";
74
- if (mode === "command" || mode === "both") return {
75
- mode,
76
- value: version.value,
77
- group: version.group,
78
- onShow: () => process.exit(0)
85
+ option: true,
86
+ onShow
79
87
  };
80
88
  return {
81
- mode,
82
- value: version.value,
83
- onShow: () => process.exit(0)
89
+ ...version,
90
+ onShow
84
91
  };
85
92
  })();
86
93
  const completionConfig = (() => {
87
94
  if (!completion) return void 0;
88
- const onShow = () => process.exit(0);
89
- if (typeof completion === "string") return {
90
- mode: completion,
91
- name: "both",
92
- helpVisibility: "both",
93
- onShow
94
- };
95
- const mode = completion.mode ?? "both";
96
- const shells = completion.shells;
97
- const cGroup = completion.group;
98
- if (completion.name === "singular") return {
99
- mode,
100
- shells,
101
- ...cGroup != null && { group: cGroup },
102
- name: "singular",
103
- helpVisibility: completion.helpVisibility ?? "singular",
104
- onShow
105
- };
106
- if (completion.name === "plural") return {
107
- mode,
108
- shells,
109
- ...cGroup != null && { group: cGroup },
110
- name: "plural",
111
- helpVisibility: completion.helpVisibility ?? "plural",
112
- onShow
113
- };
95
+ if (typeof completion === "string") switch (completion) {
96
+ case "command": return {
97
+ command: true,
98
+ onShow
99
+ };
100
+ case "option": return {
101
+ option: true,
102
+ onShow
103
+ };
104
+ case "both": return {
105
+ command: true,
106
+ option: true,
107
+ onShow
108
+ };
109
+ }
114
110
  return {
115
- mode,
116
- shells,
117
- ...cGroup != null && { group: cGroup },
118
- name: "both",
119
- helpVisibility: completion.helpVisibility ?? "both",
111
+ ...completion,
120
112
  onShow
121
113
  };
122
114
  })();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@optique/run",
3
- "version": "1.0.0-dev.431+01c1abaf",
3
+ "version": "1.0.0-dev.432+dddcca3d",
4
4
  "description": "Type-safe combinatorial command-line interface parser",
5
5
  "keywords": [
6
6
  "CLI",
@@ -70,7 +70,7 @@
70
70
  },
71
71
  "sideEffects": false,
72
72
  "dependencies": {
73
- "@optique/core": "1.0.0-dev.431+01c1abaf"
73
+ "@optique/core": "1.0.0-dev.432+dddcca3d"
74
74
  },
75
75
  "devDependencies": {
76
76
  "@types/node": "^20.19.9",