diff --git a/README.md b/README.md index 1715e36..774e3f0 100644 --- a/README.md +++ b/README.md @@ -145,7 +145,8 @@ preserve that status without reporting it. Usage failures throw for the boundary ## Mutations Call `mutating(command)` for `send`, `submit`, `set`, and `mark-read` commands. The marker is -included by `commandsJson`. Command actions call `confirm` before making an upstream request: +included by `commandsJson`; a CLI that describes its own command tree reads it with +`isMutating(command)` instead of guessing from command names. Command actions call `confirm` before making an upstream request: ```ts const shouldApply = await confirm( diff --git a/dist/program.d.ts b/dist/program.d.ts index f27193d..07c7d1b 100644 --- a/dist/program.d.ts +++ b/dist/program.d.ts @@ -37,4 +37,6 @@ export declare function createProgram(meta: { description: string; }): Command; export declare function mutating(command: Command): Command; +/** Whether `mutating` marked this command, for a CLI that describes its own command tree. */ +export declare function isMutating(command: Command): boolean; export declare function commandsJson(program: Command): ProgramDescription; diff --git a/dist/program.js b/dist/program.js index db4a292..b73e5ce 100644 --- a/dist/program.js +++ b/dist/program.js @@ -41,6 +41,10 @@ export function mutating(command) { mutations.add(command); return command; } +/** Whether `mutating` marked this command, for a CLI that describes its own command tree. */ +export function isMutating(command) { + return mutations.has(command); +} export function commandsJson(program) { return { name: program.name(), diff --git a/src/program.ts b/src/program.ts index 580ebde..1a41126 100644 --- a/src/program.ts +++ b/src/program.ts @@ -82,6 +82,11 @@ export function mutating(command: Command): Command { return command; } +/** Whether `mutating` marked this command, for a CLI that describes its own command tree. */ +export function isMutating(command: Command): boolean { + return mutations.has(command); +} + export function commandsJson(program: Command): ProgramDescription { return { name: program.name(), diff --git a/test/program.test.js b/test/program.test.js index f72941f..259b85c 100644 --- a/test/program.test.js +++ b/test/program.test.js @@ -1,7 +1,7 @@ import assert from "node:assert/strict"; import test from "node:test"; -import { commandsJson, createProgram, mutating } from "../dist/index.js"; +import { commandsJson, createProgram, isMutating, mutating } from "../dist/index.js"; test("commandsJson describes commands and marks mutations", () => { const program = createProgram({ name: "demo", version: "1.2.3", description: "Demo CLI" }); @@ -136,3 +136,11 @@ test("commander usage failures still throw once", async () => { return true; }); }); + +test("isMutating reads the mark that mutating sets", () => { + const program = createProgram({ name: "demo", version: "1.0.0", description: "Demo" }); + const reply = mutating(program.command("reply")); + const show = program.command("show"); + assert.equal(isMutating(reply), true); + assert.equal(isMutating(show), false); +});