From 61e1a26f91eaf50e1bd12a0b90344f0f13706b57 Mon Sep 17 00:00:00 2001 From: John Gee Date: Mon, 27 Jul 2026 10:48:02 +1200 Subject: [PATCH 1/2] Deprecate storeOptionsAsProperties --- Readme.md | 20 -------------------- Readme_zh-CN.md | 17 ----------------- docs/deprecated.md | 32 ++++++++++++++++++++++++++++++++ 3 files changed, 32 insertions(+), 37 deletions(-) diff --git a/Readme.md b/Readme.md index 9f1ff3c14..0b0a9b83b 100644 --- a/Readme.md +++ b/Readme.md @@ -44,7 +44,6 @@ Read this in other languages: English | [简体中文](./Readme_zh-CN.md) - [Bits and pieces](#bits-and-pieces) - [.parse() and .parseAsync()](#parse-and-parseasync) - [Parsing Configuration](#parsing-configuration) - - [Legacy options as properties](#legacy-options-as-properties) - [TypeScript](#typescript) - [createCommand()](#createcommand) - [Node options such as `--harmony`](#node-options-such-as---harmony) @@ -1016,25 +1015,6 @@ By default, the option processing shows an error for an unknown option. To have By default, the argument processing displays an error for more command-arguments than expected. To suppress the error for excess arguments, use `.allowExcessArguments()`. -### Legacy options as properties - -Before Commander 7, the option values were stored as properties on the command. -This was convenient to code, but the downside was possible clashes with -existing properties of `Command`. - -You can revert to the old behaviour to run unmodified legacy code by using `.storeOptionsAsProperties()`. - -```js -program - .storeOptionsAsProperties() - .option('-d, --debug') - .action((commandAndOptions) => { - if (commandAndOptions.debug) { - console.error(`Called ${commandAndOptions.name()}`); - } - }); -``` - ### TypeScript **extra-typings:** There is an optional project to infer extra type information from the option and argument definitions. diff --git a/Readme_zh-CN.md b/Readme_zh-CN.md index 9a8b259d8..0e390b0b1 100644 --- a/Readme_zh-CN.md +++ b/Readme_zh-CN.md @@ -43,7 +43,6 @@ - [零碎知识](#%e9%9b%b6%e7%a2%8e%e7%9f%a5%e8%af%86) - [.parse() 和 .parseAsync()](#parse-%e5%92%8c-parseasync) - [解析配置](#%E8%A7%A3%E6%9E%90%E9%85%8D%E7%BD%AE) - - [作为属性的遗留选项](#%E4%BD%9C%E4%B8%BA%E5%B1%9E%E6%80%A7%E7%9A%84%E9%81%97%E7%95%99%E9%80%89%E9%A1%B9) - [TypeScript](#typescript) - [createCommand()](#createCommand) - [Node 选项，如 --harmony](#node-%E9%80%89%E9%A1%B9%EF%BC%8C%E5%A6%82---harmony) @@ -953,22 +952,6 @@ program arg --port=80 默认情况下，传入过多的命令参数并不会报错。可以使用`.allowExcessArguments(false)`来启用这一检查。 -### 作为属性的遗留选项 - -在 Commander 7 以前，选项的值是作为属性存储在命令对象上的。 -这种处理方式便于实现，但缺点在于，选项可能会与`Command`的已有属性相冲突。通过使用`.storeOptionsAsProperties()`，可以恢复到这种旧的处理方式，并可以不加改动地继续运行遗留代码。 - -```js -program - .storeOptionsAsProperties() - .option('-d, --debug') - .action((commandAndOptions) => { - if (commandAndOptions.debug) { - console.error(`Called ${commandAndOptions.name()}`); - } - }); -``` - ### TypeScript 如果你使用 ts-node，并有`.ts`文件作为独立可执行文件，那么需要用 node 运行你的程序以使子命令能正确调用，例如： diff --git a/docs/deprecated.md b/docs/deprecated.md index 165ee00c1..d850d4c3d 100644 --- a/docs/deprecated.md +++ b/docs/deprecated.md @@ -14,6 +14,7 @@ They are currently still available for backwards compatibility, but should not b - [InvalidOptionArgumentError](#invalidoptionargumenterror) - [cmd.\_args](#cmd_args) - [.addHelpCommand(string|boolean|undefined)](#addhelpcommandstringbooleanundefined) + - [.storeOptionsAsProperties()](#storeoptionsasproperties) - [Removed](#removed) - [Short option flag longer than a single character](#short-option-flag-longer-than-a-single-character) - [Default import of global Command object](#default-import-of-global-command-object) @@ -208,6 +209,37 @@ program.addHelpCommand(new Command('assist').argument('[command]').description(' - Removed from README in Commander v12. - Deprecated from Commander v12. +### .storeOptionsAsProperties() + +Before Commander 7, the option values were stored as properties on the command, +and the command was passed to the action handler after the command-arguments. +You could revert to the old behaviour to run unmodified legacy code by using `.storeOptionsAsProperties()`. + +```js +program.storeOptionsAsProperties(); +program.option('-d, --debug'); +program.parse(); +// Legacy code +if (program.debug) showDiagnostics(); +``` + +Since Commander 7, the properies are stored separately. The options are available +from a command using `.opts()`. The action handler is passed the options after the command-arguments, +followed by the command. + +```js +// New code +const options = program.opts(); +if (options.debug) showDiagnostics(); +``` + +See more in the Migration Tips for Commander v7.0.0 in the [CHANGELOG](../CHANGELOG.md#700-2021-01-15) +or online in the [Release Notes](https://github.com/tj/commander.js/releases/tag/v7.0.0). + +- Removed from README in Commander v15. +- Deprecated from Commander v15. + + ## Removed ### Short option flag longer than a single character From 2e7b89def6907d9ee7db1e8ed5963ca5e92eeca1 Mon Sep 17 00:00:00 2001 From: John Gee Date: Mon, 27 Jul 2026 11:15:17 +1200 Subject: [PATCH 2/2] Deprecate storeOptionsAsProperties --- typings/index.d.ts | 3 +++ 1 file changed, 3 insertions(+) diff --git a/typings/index.d.ts b/typings/index.d.ts index 88b2b47a6..4c5667aca 100644 --- a/typings/index.d.ts +++ b/typings/index.d.ts @@ -710,10 +710,13 @@ export class Command { * * @returns `this` command for chaining */ + /** @deprecated since v15 */ storeOptionsAsProperties(): this & T; + /** @deprecated since v15 */ storeOptionsAsProperties( storeAsProperties: true, ): this & T; + /** @deprecated since v15 */ storeOptionsAsProperties(storeAsProperties?: boolean): this; /**