feat: [Command] example, examples

Signed-off-by: Lexus Drumgold <[email protected]>

Author: unicornware

README.md

@@ -50,6 +50,8 @@
     - [`Command#done([done])`](#commanddonedone)
     - [`Command#emit(event)`](#commandemitevent)
     - [`Command#emitOption(option, value, source[, flags])`](#commandemitoptionoption-value-source-flag)
+    - [`Command#example(info[, prefix])`](#commandexampleinfo-prefix)
+    - [`Command#examples([examples])`](#commandexamplesexamples)
     - [`Command#error(info)`](#commanderrorinfo)
     - [`Command#exit([e])`](#commandexite)
     - [`Command#exiter([exit])`](#commandexiterexit)
@@ -149,6 +151,8 @@
   - [`CommandSnapshot`](#commandsnapshot-1)
   - [`DefaultInfo`](#defaultinfo)
   - [`EmptyString`](#emptystring)
+  - [`ExampleInfo`](#exampleinfo)
+  - [`ExamplesData`](#examplesdata)
   - [`ExitCode`](#exitcode)
   - [`ExitProcess`](#exitprocess)
   - [`Exit`](#exit)
@@ -729,6 +733,46 @@ Display an error message and exit.
 
 (`never`) Never, exits erroneously
 
+#### `Command#example(info[, prefix])`
+
+Add an example for the command.
+
+> 👉 **Note**: This method can be called more than once to add multiple examples.
+
+##### Overloads
+
+- `example(info: ExampleInfo | string): this`
+- `example(info: string, prefix?: string | null | undefined): this`
+
+##### Parameters
+
+- `info` ([`ExampleInfo`](#exampleinfo) | `string`)
+  — example info or text
+- `prefix` (`string` | `null` | `undefined`)
+  — the example text prefix
+
+##### Returns
+
+([`this`](#commandinfo)) `this` command
+
+#### `Command#examples([examples])`
+
+Get or add examples for the command.
+
+##### Overloads
+
+- `examples(examples: ExamplesData | null | undefined): this`
+- `examples(): ExampleInfo[]`
+
+##### Parameters
+
+- `examples` ([`ExamplesData`](#examplesdata) | `null` | `undefined`)
+  — example info, example text, or a list of such
+
+##### Returns
+
+([`ExampleInfo[]`](#exampleinfo) | [`this`](#commandinfo)) List of examples or `this` command
+
 #### `Command#exit([e])`
 
 Exit the process.
@@ -2029,6 +2073,8 @@ Command metadata (TypeScript interface).
   — list of command aliases
 - `arguments` ([`Argument[]`](#argumentinfo))
   — list of command arguments
+- `examples` ([`ExampleInfo[]`](#exampleinfo))
+  — list of command examples
 - `helpOption` ([`Option`](#optioninfo) | `null` | `undefined`)
   — the help option
 - `options` ([`Map<string, Option>`](#optioninfo))
@@ -2097,6 +2143,25 @@ An empty string (TypeScript type).
 type EmptyString = ''
 ```
 
+### `ExampleInfo`
+
+Command example info (TypeScript interface).
+
+#### Properties
+
+- `prefix?` (`string`, optional)
+  — the example text prefix
+- `text` (`string`)
+  — the example text
+
+### `ExamplesData`
+
+Union of types used to configure command examples (TypeScript type).
+
+```ts
+type ExamplesData = ExampleInfo | List<ExampleInfo | string> | string
+```
+
 ### `ExitCode`
 
 Union of exit status code types (TypeScript type).

src/interfaces/__tests__/command.data.spec-d.mts

@@ -8,6 +8,7 @@ import type {
   Action,
   ArgumentsData,
   Command,
+  ExamplesData,
   Exit,
   HelpableInfo,
   HelpOptionData,
@@ -60,6 +61,12 @@ describe('unit-d:interfaces/CommandData', () => {
       .toEqualTypeOf<Nilable<Action<any>>>()
   })
 
+  it('should match [examples?: ExamplesData | null | undefined]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('examples')
+      .toEqualTypeOf<Nilable<ExamplesData>>()
+  })
+
   it('should match [exit?: Exit | null | undefined]', () => {
     expectTypeOf<TestSubject>()
       .toHaveProperty('exit')

src/interfaces/__tests__/command.metadata.spec-d.mts

@@ -11,6 +11,7 @@ import type {
   Argument,
   Command,
   CommandInfo,
+  ExampleInfo,
   Option,
   VersionOption
 } from '@flex-development/kronk'
@@ -37,6 +38,12 @@ describe('unit-d:interfaces/CommandMetadata', () => {
       .toEqualTypeOf<Argument[]>()
   })
 
+  it('should match [examples: ExampleInfo[]]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('examples')
+      .toEqualTypeOf<ExampleInfo[]>()
+  })
+
   it('should match [helpCommand: Command | null | undefined]', () => {
     expectTypeOf<TestSubject>()
       .toHaveProperty('helpCommand')

src/interfaces/__tests__/example.info.spec-d.mts

@@ -0,0 +1,21 @@
+/**
+ * @file Type Tests - ExampleInfo
+ * @module kronk/interfaces/tests/unit-d/ExampleInfo
+ */
+
+import type TestSubject from '#interfaces/example.info'
+import type { Nilable } from '@flex-development/tutils'
+
+describe('unit-d:interfaces/ExampleInfo', () => {
+  it('should match [prefix?: string | null | undefined]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('prefix')
+      .toEqualTypeOf<Nilable<string>>()
+  })
+
+  it('should match [text: string]', () => {
+    expectTypeOf<TestSubject>()
+      .toHaveProperty('text')
+      .toEqualTypeOf<string>()
+  })
+})

src/interfaces/command.data.mts

@@ -7,6 +7,7 @@ import type {
   Action,
   ArgumentsData,
   Command,
+  ExamplesData,
   Exit,
   HelpableInfo,
   HelpCommandData,
@@ -61,6 +62,13 @@ interface CommandData extends HelpableInfo {
    */
   done?: Action<any> | null | undefined
 
+  /**
+   * An example of the command, or a list of examples.
+   *
+   * @see {@linkcode ExamplesData}
+   */
+  examples?: ExamplesData | null | undefined
+
   /**
    * The callback to fire when the process is exited.
    *

src/interfaces/command.metadata.mts

@@ -7,6 +7,7 @@ import type {
   Argument,
   Command,
   CommandInfo,
+  ExampleInfo,
   Option,
   VersionOption
 } from '@flex-development/kronk'
@@ -38,6 +39,15 @@ interface CommandMetadata extends Omit<CommandInfo, Skip> {
    */
   arguments: Argument[]
 
+  /**
+   * A list of command examples.
+   *
+   * @see {@linkcode ExampleInfo}
+   *
+   * @override
+   */
+  examples: ExampleInfo[]
+
   /**
    * The help subcommand.
    *

src/interfaces/example.info.mts

@@ -0,0 +1,21 @@
+/**
+ * @file Interfaces - ExampleInfo
+ * @module kronk/interfaces/ExampleInfo
+ */
+
+/**
+ * Command example info.
+ */
+interface ExampleInfo {
+  /**
+   * The example {@linkcode text} prefix.
+   */
+  prefix?: string | null | undefined
+
+  /**
+   * The example text.
+   */
+  text: string
+}
+
+export type { ExampleInfo as default }

src/interfaces/index.mts

@@ -21,6 +21,7 @@ export type { default as CommandInfo } from '#interfaces/command.info'
 export type { default as CommandMetadata } from '#interfaces/command.metadata'
 export type { default as CommandSnapshot } from '#interfaces/command.snapshot'
 export type { default as DefaultInfo } from '#interfaces/default.info'
+export type { default as ExampleInfo } from '#interfaces/example.info'
 export type { default as HelpableInfo } from '#interfaces/helpable.info'
 export type { default as KronkErrorCause } from '#interfaces/kronk-error.cause'
 export type { default as KronkErrorInfo } from '#interfaces/kronk-error.info'

src/lib/__snapshots__/command.snap

@@ -58,6 +58,19 @@ exports[`unit:lib/Command > #addOption > should throw on short flag conflict 1`]
 }
 `;
 
+exports[`unit:lib/Command > #examples > should add examples and return \`this\` 1`] = `
+[
+  {
+    "prefix": undefined,
+    "text": "bump -w 1.0.0",
+  },
+  {
+    "prefix": "ch",
+    "text": "--releases=0 --to=$(jq .version package.json -r) -sw",
+  },
+]
+`;
+
 exports[`unit:lib/Command > #helpCommand > should return help subcommand (0) 1`] = `
 Command {
   "info": {
@@ -67,6 +80,7 @@ Command {
     "hidden": false,
     "aliases": Set {},
     "arguments": [],
+    "examples": [],
     "helpOption": Option {
       "info": {
         "description": "show help",
@@ -156,6 +170,7 @@ Command {
       "hidden": false,
       "aliases": Set {},
       "arguments": [],
+      "examples": [],
       "helpCommand": [Circular],
       "helpOption": Option {
         "info": {

src/lib/__tests__/command.spec.mts

@@ -24,6 +24,7 @@ import type {
   Action,
   CommandInfo,
   CommandName,
+  ExampleInfo,
   Exit,
   HelpCommandData,
   HelpOptionData,
@@ -313,6 +314,57 @@ describe('unit:lib/Command', () => {
     })
   })
 
+  describe('#example', () => {
+    let subject: TestSubject
+
+    beforeEach(() => {
+      subject = new TestSubject()
+    })
+
+    it.each<[ExampleInfo | string, (string | null | undefined)?]>([
+      ['--to=0ea3bcf737edf29d0a0ad3dc7702f29615e16b29', 'ch'],
+      [{ text: '-s' }]
+    ])('should add example and return `this` (%#)', (info, prefix) => {
+      // Arrange
+      const property: string = 'info.examples'
+
+      // Act
+      const result = subject.example(info as never, prefix)
+
+      // Expect
+      expect(result).to.eq(subject)
+      expect(result).to.have.nested.property(property).satisfy(Array.isArray)
+      expect(result).to.have.nested.property(property).be.of.length(1)
+    })
+  })
+
+  describe('#examples', () => {
+    let subject: TestSubject
+
+    beforeEach(() => {
+      subject = new TestSubject()
+    })
+
+    it('should add examples and return `this`', () => {
+      // Act
+      const result = subject.examples([
+        'bump -w 1.0.0',
+        {
+          prefix: 'ch',
+          text: '--releases=0 --to=$(jq .version package.json -r) -sw'
+        }
+      ])
+
+      // Expect
+      expect(result).to.eq(subject)
+      expect(subject.examples()).toMatchSnapshot()
+    })
+
+    it('should return list of command examples', () => {
+      expect(subject.examples()).to.satisfy(Array.isArray).and.be.empty
+    })
+  })
+
   describe('#error', () => {
     let exit: MockInstance<TestSubject['exit']>
     let info: KronkError