gunshi 0.5.3 → 0.5.4

package/README.md

@@ -18,8 +18,8 @@ Gunshi is a modern javascript command-line library
 Gunshi is designed to simplify the creation of modern command-line interfaces:
 
 - 📏 **Simple**: Run the commands with a simple API.
-- 🛡️ **Type Safe**: Arguments parsing and options value resolution type-safely by [args-tokens](https://github.com/kazupon/args-tokens)
 - ⚙️ **Declarative configuration**: Configure the command modules declaratively.
+- 🛡️ **Type Safe**: Arguments parsing and options value resolution type-safely by [args-tokens](https://github.com/kazupon/args-tokens)
 - 🧩 **Composable**: Sub-commands that can be composed with modularized commands.
 - ⏳ **Lazy & Async**: Command modules lazy loading and asynchronously executing.
 - 📜 **Auto usage generation**: Automatic usage message generation with modularized commands.
@@ -62,52 +62,12 @@ Gunshi has a simple API that is a facade:
 ```js
 import { cli } from 'gunshi'
 
-// Run a simple command
+// run a simple command
 cli(process.argv.slice(2), () => {
   console.log('Hello from Gunshi!')
 })
 ```
 
-### 🛡️ Type-Safe Arguments
-
-Gunshi provides type-safe argument parsing with TypeScript:
-
-```ts
-import { cli } from 'gunshi'
-import type { ArgOptions, Command, CommandContext } from 'gunshi'
-
-// Define interfaces for options and values
-interface UserOptions extends ArgOptions {
-  name: { type: 'string'; short: 'n' }
-  age: { type: 'number'; short: 'a'; default: number }
-  verbose: { type: 'boolean'; short: 'v' }
-}
-
-interface UserValues {
-  name?: string
-  age: number
-  verbose?: boolean
-}
-
-// Create a type-safe command
-const command: Command<UserOptions> = {
-  name: 'type-safe',
-  options: {
-    name: { type: 'string', short: 'n' },
-    age: { type: 'number', short: 'a', default: 25 },
-    verbose: { type: 'boolean', short: 'v' }
-  },
-  run: (ctx: CommandContext<UserOptions, UserValues>) => {
-    const { name, age, verbose } = ctx.values
-    console.log(`Hello, ${name || 'World'}! You are ${age} years old.`)
-  }
-}
-
-await cli(process.argv.slice(2), command)
-```
-
-For more detailed examples, check out the [playground/type-safe](https://github.com/kazupon/gunshi/tree/main/playground/type-safe) in the repository.
-
 ### ⚙️ Declarative Configuration
 
 Configure commands declaratively:
@@ -115,7 +75,7 @@ Configure commands declaratively:
 ```js
 import { cli } from 'gunshi'
 
-// Define a command with declarative configuration
+// define a command with declarative configuration
 const command = {
   name: 'greet',
   description: 'A greeting command',
@@ -148,6 +108,52 @@ cli(process.argv.slice(2), command, {
 
 For more detailed examples, check out the [playground/declarative](https://github.com/kazupon/gunshi/tree/main/playground/declarative) in the repository.
 
+### 🛡️ Type-Safe Arguments
+
+Gunshi provides type-safe argument parsing with TypeScript:
+
+```ts
+import { cli } from 'gunshi'
+import type { ArgOptions, Command, CommandContext } from 'gunshi'
+
+// type-safe arguments parsing example
+// this demonstrates how to define and use typed command options with `satisfies`
+
+// define options with types
+const options = {
+  // define string option with short alias
+  name: {
+    type: 'string',
+    short: 'n'
+  },
+  // define number option with default value
+  age: {
+    type: 'number',
+    short: 'a',
+    default: 25
+  },
+  // define boolean flag
+  verbose: {
+    type: 'boolean',
+    short: 'v'
+  }
+} satisfies ArgOptions
+
+// create a type-safe command
+const command = {
+  name: 'type-safe',
+  options,
+  run: (ctx: CommandContext<UserOptions, UserValues>) => {
+    const { name, age, verbose } = ctx.values
+    console.log(`Hello, ${name || 'World'}! You are ${age} years old.`)
+  }
+} satisfies Command<typeof options>
+
+await cli(process.argv.slice(2), command)
+```
+
+For more detailed examples, check out the [playground/type-safe](https://github.com/kazupon/gunshi/tree/main/playground/type-safe) in the repository.
+
 ### 🧩 Composable Sub-commands
 
 Create a CLI with composable sub-commands:
@@ -155,7 +161,7 @@ Create a CLI with composable sub-commands:
 ```js
 import { cli } from 'gunshi'
 
-// Define sub-commands
+// define sub-commands
 const createCommand = {
   name: 'create',
   description: 'Create a new resource',
@@ -175,12 +181,12 @@ const listCommand = {
   }
 }
 
-// Create a Map of sub-commands
+// create a Map of sub-commands
 const subCommands = new Map()
 subCommands.set('create', createCommand)
 subCommands.set('list', listCommand)
 
-// Define the main command
+// define the main command
 const mainCommand = {
   name: 'resource-manager',
   description: 'Manage resources',
@@ -189,7 +195,7 @@ const mainCommand = {
   }
 }
 
-// Run the CLI with composable sub-commands
+// run the CLI with composable sub-commands
 cli(process.argv.slice(2), mainCommand, {
   name: 'my-app',
   version: '1.0.0',
@@ -206,28 +212,28 @@ Load commands lazily and execute them asynchronously:
 ```js
 import { cli } from 'gunshi'
 
-// Define a command that will be loaded lazily
+// define a command that will be loaded lazily
 const lazyCommand = async () => {
-  // Simulate async loading
+  // simulate async loading
   await new Promise(resolve => setTimeout(resolve, 1000))
 
-  // Return the actual command
+  // return the actual command
   return {
     name: 'lazy',
     description: 'A command that is loaded lazily',
     run: async ctx => {
-      // Async execution
+      // async execution
       await new Promise(resolve => setTimeout(resolve, 500))
       console.log('Command executed!')
     }
   }
 }
 
-// Create a Map of sub-commands with lazy-loaded commands
+// create a Map of sub-commands with lazy-loaded commands
 const subCommands = new Map()
 subCommands.set('lazy', lazyCommand)
 
-// Run the CLI with lazy-loaded commands
+// run the CLI with lazy-loaded commands
 cli(
   process.argv.slice(2),
   { name: 'main', run: () => {} },
@@ -264,11 +270,11 @@ const command = {
     examples: '# Example\n$ my-app --operation list --path ./src'
   },
   run: ctx => {
-    // Command implementation
+    // command implementation
   }
 }
 
-// Run with --help to see the automatically generated usage information
+// run with --help to see the automatically generated usage information
 cli(process.argv.slice(2), command, {
   name: 'my-app',
   version: '1.0.0'
@@ -284,7 +290,7 @@ Customize the usage message generation:
 ```js
 import { cli } from 'gunshi'
 
-// Custom header renderer
+// custom header renderer
 const customHeaderRenderer = ctx => {
   return Promise.resolve(`
 ╔═══════════════════════╗
@@ -295,7 +301,7 @@ Version: ${ctx.env.version}
 `)
 }
 
-// Custom usage renderer
+// custom usage renderer
 const customUsageRenderer = ctx => {
   const lines = []
   lines.push('USAGE:')
@@ -303,7 +309,7 @@ const customUsageRenderer = ctx => {
   lines.push('')
   lines.push('OPTIONS:')
 
-  for (const [key, option] of Object.entries(ctx.options || {})) {
+  for (const [key, option] of Object.entries(ctx.options || Object.create(null))) {
     const shortFlag = option.short ? `-${option.short}, ` : '    '
     lines.push(`  ${shortFlag}--${key.padEnd(10)} ${ctx.translation(key)}`)
   }
@@ -311,7 +317,7 @@ const customUsageRenderer = ctx => {
   return Promise.resolve(lines.join('\n'))
 }
 
-// Run with custom renderers
+// run with custom renderers
 cli(
   process.argv.slice(2),
   { name: 'app', run: () => {} },
@@ -341,14 +347,14 @@ const command = {
     name: { type: 'string', short: 'n' },
     formal: { type: 'boolean', short: 'f' }
   },
-  // Resource fetcher for translations
+  // resource fetcher for translations
   resource: async ctx => {
     if (ctx.locale.toString() === 'ja-JP') {
       const resource = await import('./locales/ja-JP.json', { with: { type: 'json' } })
       return resource.default
     }
 
-    // Default to English
+    // default to English
     return enUS
   },
   run: ctx => {
@@ -358,12 +364,12 @@ const command = {
   }
 }
 
-// Run with locale support
+// run with locale support
 cli(process.argv.slice(2), command, {
   name: 'my-app',
   version: '1.0.0',
-  // Set the locale via an environment variable
-  // If Node v21 or later is used, you can use the built-in `navigator.language` instead)
+  // set the locale via an environment variable
+  // if Node v21 or later is used, you can use the built-in `navigator.language` instead)
   locale: new Intl.Locale(process.env.MY_LOCALE || 'en-US')
 })
 ```

package/lib/context.d.ts

@@ -1,5 +1,5 @@
 import { ArgOptions, ArgValues } from 'args-tokens';
-import { C as Command, a as CommandOptions, b as CommandContext } from './types.d-veidyA82.js';
+import { C as Command, a as CommandOptions, b as CommandContext } from './types.d-CxaX4FVV.js';
 
 /**
 * The default locale string, which format is BCP 47 language tag
@@ -43,7 +43,7 @@ interface CommandContextParams<
 * @returns A {@link CommandContext | command context}, which is readonly
 */
 declare function createCommandContext<
-	Options extends ArgOptions,
+	Options extends ArgOptions = ArgOptions,
 	Values = ArgValues<Options>
 >({ options, values, positionals, command, commandOptions, omitted }: CommandContextParams<Options, Values>): Promise<Readonly<CommandContext<Options, Values>>>;
 

package/lib/index.d.ts

@@ -1,7 +1,7 @@
 import { ArgOptions } from 'args-tokens';
 export { ArgOptionSchema, ArgOptions, ArgValues } from 'args-tokens';
-import { C as Command, c as CommandRunner, a as CommandOptions } from './types.d-veidyA82.js';
-export { f as CommandBuiltinKeys, d as CommandBuiltinOptionsKeys, e as CommandBuiltinResourceKeys, b as CommandContext, g as CommandEnvironment, h as CommandResource, i as CommandResourceFetcher, L as LazyCommand } from './types.d-veidyA82.js';
+import { C as Command, c as CommandRunner, a as CommandOptions } from './types.d-CxaX4FVV.js';
+export { f as CommandBuiltinKeys, d as CommandBuiltinOptionsKeys, e as CommandBuiltinResourceKeys, b as CommandContext, g as CommandEnvironment, h as CommandResource, i as CommandResourceFetcher, j as Commandable, L as LazyCommand } from './types.d-CxaX4FVV.js';
 
 /**
 * Run the command
@@ -9,6 +9,6 @@ export { f as CommandBuiltinKeys, d as CommandBuiltinOptionsKeys, e as CommandBu
 * @param entry - A {@link Command | entry command} or an {@link CommandRunner | inline command runner}
 * @param opts - A {@link CommandOptions | command options}
 */
-declare function cli<Options extends ArgOptions>(args: string[], entry: Command<Options> | CommandRunner<Options>, opts?: CommandOptions<Options>): Promise<void>;
+declare function cli<Options extends ArgOptions = ArgOptions>(args: string[], entry: Command<Options> | CommandRunner<Options>, opts?: CommandOptions<Options>): Promise<void>;
 
 export { Command, CommandOptions, CommandRunner, cli };

package/lib/renderer/index.d.ts

@@ -1,19 +1,19 @@
 import { ArgOptions } from 'args-tokens';
-import { b as CommandContext } from '../types.d-veidyA82.js';
+import { b as CommandContext } from '../types.d-CxaX4FVV.js';
 
 /**
 * Render the header
 * @param ctx A {@link CommandContext | command context}
 * @returns A rendered header
 */
-declare function renderHeader<Options extends ArgOptions>(ctx: Readonly<CommandContext<Options>>): Promise<string>;
+declare function renderHeader<Options extends ArgOptions = ArgOptions>(ctx: Readonly<CommandContext<Options>>): Promise<string>;
 
 /**
 * Render the usage
 * @param ctx A {@link CommandContext | command context}
 * @returns A rendered usage
 */
-declare function renderUsage<Options extends ArgOptions>(ctx: Readonly<CommandContext<Options>>): Promise<string>;
+declare function renderUsage<Options extends ArgOptions = ArgOptions>(ctx: Readonly<CommandContext<Options>>): Promise<string>;
 
 /**
 * Render the validation errors
@@ -21,6 +21,6 @@ declare function renderUsage<Options extends ArgOptions>(ctx: Readonly<CommandCo
 * @param error An {@link AggregateError} of option in `args-token` validation
 * @returns A rendered validation error
 */
-declare function renderValidationErrors<Options extends ArgOptions>(_ctx: CommandContext<Options>, error: AggregateError): Promise<string>;
+declare function renderValidationErrors<Options extends ArgOptions = ArgOptions>(_ctx: CommandContext<Options>, error: AggregateError): Promise<string>;
 
 export { renderHeader, renderUsage, renderValidationErrors };

package/lib/{types.d-veidyA82.d.ts → types.d-CxaX4FVV.d.ts}

@@ -88,7 +88,7 @@ interface CommandEnvironment<Options extends ArgOptions = ArgOptions> {
 	* Sub commands
 	* @see {@link CommandOptions.subCommands}
 	*/
-	subCommands: Map<string, Command<Options> | LazyCommand<Options>> | undefined;
+	subCommands: Map<string, Command<any> | LazyCommand<any>> | undefined;
 	/**
 	* Render function the command usage
 	*/
@@ -105,7 +105,7 @@ interface CommandEnvironment<Options extends ArgOptions = ArgOptions> {
 /**
 * Command options
 */
-interface CommandOptions<Options extends ArgOptions> {
+interface CommandOptions<Options extends ArgOptions = ArgOptions> {
 	/**
 	* Current working directory
 	*/
@@ -130,7 +130,7 @@ interface CommandOptions<Options extends ArgOptions> {
 	/**
 	* Sub commands
 	*/
-	subCommands?: Map<string, Command<Options> | LazyCommand<Options>>;
+	subCommands?: Map<string, Command<any> | LazyCommand<any>>;
 	/**
 	* Left margin of the command output
 	*/
@@ -161,7 +161,7 @@ interface CommandOptions<Options extends ArgOptions> {
 * @description Command context is the context of the command execution
 */
 interface CommandContext<
-	Options extends ArgOptions,
+	Options extends ArgOptions = ArgOptions,
 	Values = ArgValues<Options>
 > {
 	/**
@@ -227,7 +227,7 @@ interface CommandContext<
 /**
 * Command usage
 */
-interface CommandUsage<Options extends ArgOptions> {
+interface CommandUsage<Options extends ArgOptions = ArgOptions> {
 	/**
 	* Options usage
 	*/
@@ -240,7 +240,7 @@ interface CommandUsage<Options extends ArgOptions> {
 /**
 * Command interface
 */
-interface Command<Options extends ArgOptions> {
+interface Command<Options extends ArgOptions = ArgOptions> {
 	/**
 	* Command name
 	* @description
@@ -282,7 +282,7 @@ interface Command<Options extends ArgOptions> {
 * Command resource
 * @experimental
 */
-interface CommandResource<Options extends ArgOptions> {
+interface CommandResource<Options extends ArgOptions = ArgOptions> {
 	/**
 	* Command description
 	*/
@@ -302,16 +302,20 @@ interface CommandResource<Options extends ArgOptions> {
 * @returns A fetched {@link CommandResource | command resource}
 * @experimental
 */
-type CommandResourceFetcher<Options extends ArgOptions> = (ctx: Readonly<CommandContext<Options>>) => Promise<CommandResource<Options>>;
+type CommandResourceFetcher<Options extends ArgOptions = ArgOptions> = (ctx: Readonly<CommandContext<Options>>) => Promise<CommandResource<Options>>;
 /**
 * Command runner
 * @param ctx A {@link CommandContext | command context}
 */
-type CommandRunner<Options extends ArgOptions> = (ctx: Readonly<CommandContext<Options>>) => Awaitable<void>;
+type CommandRunner<Options extends ArgOptions = ArgOptions> = (ctx: Readonly<CommandContext<Options>>) => Awaitable<void>;
 /**
 * Lazy command interface
 * @description lazy command that's not loaded until it is executed
 */
-type LazyCommand<Options extends ArgOptions> = () => Awaitable<Command<Options>>;
+type LazyCommand<Options extends ArgOptions = ArgOptions> = () => Awaitable<Command<Options>>;
+/**
+* Define a command type
+*/
+type Commandable<Options extends ArgOptions> = Command<Options> | LazyCommand<Options>;
 
-export type { Command as C, LazyCommand as L, CommandOptions as a, CommandContext as b, CommandRunner as c, CommandBuiltinOptionsKeys as d, CommandBuiltinResourceKeys as e, CommandBuiltinKeys as f, CommandEnvironment as g, CommandResource as h, CommandResourceFetcher as i };
+export type { Command as C, LazyCommand as L, CommandOptions as a, CommandContext as b, CommandRunner as c, CommandBuiltinOptionsKeys as d, CommandBuiltinResourceKeys as e, CommandBuiltinKeys as f, CommandEnvironment as g, CommandResource as h, CommandResourceFetcher as i, Commandable as j };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gunshi",
   "description": "Modern javascript command-line library",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"