gunshi 0.2.1 → 0.2.2

package/lib/{context-BQKZW5bg.js → context-DmZAeiph.js}

@@ -95,7 +95,8 @@ async function createCommandContext({ options, values, positionals, command, com
 		localeResources.set(locale.toString(), builtInLoadedResources);
 	} catch {}
 	/**
-	* define the translation function
+	* define the translation function, which is used to {@link CommandContext.translation}.
+	*
 	*/
 	function translation(key) {
 		if (COMMAND_I18N_RESOURCE_KEYS.includes(key)) {

package/lib/context.d.ts

@@ -1,17 +1,50 @@
 import { ArgOptions, ArgValues } from 'args-tokens';
-import { C as Command, a as CommandOptions, b as CommandContext } from './types.d-B3YGxDV6.js';
+import { C as Command, a as CommandOptions, b as CommandContext } from './types.d-00BVt8hZ.js';
 
+/**
+* The default locale string, which format is BCP 47 language tag
+*/
 declare const DEFAULT_LOCALE = "en-US";
+/**
+* Parameters of {@link createCommandContext}
+*/
+interface CommandContextParams<
+	Options extends ArgOptions,
+	Values
+> {
+	/**
+	* An options of target command
+	*/
+	options: Options | undefined;
+	/**
+	* A values of target command
+	*/
+	values: Values;
+	/**
+	* A positionals arguments, which passed to the target command
+	*/
+	positionals: string[];
+	/**
+	* Whether the command is omitted
+	*/
+	omitted: boolean;
+	/**
+	* A target {@link Command | command}
+	*/
+	command: Command<Options>;
+	/**
+	* A command options, which is spicialized from `cli` function
+	*/
+	commandOptions: CommandOptions<Options>;
+}
+/**
+* Create a {@link CommandContext | command context}
+* @param param A {@link CommandContextParams | parameters} to create a {@link CommandContext | command context}
+* @returns A {@link CommandContext | command context}, which is readonly
+*/
 declare function createCommandContext<
 	Options extends ArgOptions,
 	Values = ArgValues<Options>
->({ options, values, positionals, command, commandOptions, omitted }: {
-	options: Options | undefined
-	values: Values
-	positionals: string[]
-	omitted: boolean
-	command: Command<Options>
-	commandOptions: CommandOptions<Options>
-}): Promise<Readonly<CommandContext<Options, Values>>>;
+>({ options, values, positionals, command, commandOptions, omitted }: CommandContextParams<Options, Values>): Promise<Readonly<CommandContext<Options, Values>>>;
 
 export { DEFAULT_LOCALE, createCommandContext };

package/lib/context.js

@@ -1,4 +1,4 @@
-import { DEFAULT_LOCALE, createCommandContext } from "./context-BQKZW5bg.js";
+import { DEFAULT_LOCALE, createCommandContext } from "./context-DmZAeiph.js";
 import "./utils-NHs5DuHk.js";
 
 export { DEFAULT_LOCALE, createCommandContext };

package/lib/index.d.ts

@@ -1,13 +1,13 @@
 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-B3YGxDV6.js';
-export { f as CommandBuiltinKeys, d as CommandBuiltinOptionsKeys, e as CommandBuiltinResourceKeys, b as CommandContext, g as CommandEnvironment, i as CommandResource, j as CommandResourceFetcher, h as CommandUsageRender, L as LazyCommand } from './types.d-B3YGxDV6.js';
+import { C as Command, c as CommandRunner, a as CommandOptions } from './types.d-00BVt8hZ.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-00BVt8hZ.js';
 
 /**
 * Run the command
 * @param args - command line arguments
-* @param entry - a {@link Command | entry command} or an {@link CommandRunner | inline command runner}
-* @param opts - a {@link CommandOptions | command options}
+* @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>;
 

package/lib/index.js

@@ -1,4 +1,4 @@
-import { COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, createCommandContext } from "./context-BQKZW5bg.js";
+import { COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, createCommandContext } from "./context-DmZAeiph.js";
 import { create, log, resolveLazyCommand } from "./utils-NHs5DuHk.js";
 import { renderHeader, renderUsage, renderValidationErrors } from "./renderer-Bo0DibAK.js";
 import { parseArgs, resolveArgs } from "args-tokens";
@@ -33,7 +33,7 @@ async function cli(args, entry, opts = {}) {
 	}
 	if (error) {
 		await showValidationErrors(ctx, error);
-		throw error;
+		return;
 	}
 	await command.run(ctx);
 }

package/lib/renderer.d.ts

@@ -1,8 +1,24 @@
 import { ArgOptions } from 'args-tokens';
-import { b as CommandContext } from './types.d-B3YGxDV6.js';
+import { b as CommandContext } from './types.d-00BVt8hZ.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>;
+/**
+* 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>;
+/**
+* Render the validation errors
+* @param ctx A {@link CommandContext | command context}
+* @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>;
 
 export { renderHeader, renderUsage, renderValidationErrors };

package/lib/{types.d-B3YGxDV6.d.ts → types.d-00BVt8hZ.d.ts}

@@ -25,54 +25,54 @@ declare namespace __constants {
 */
 type Awaitable<T> = T | Promise<T>;
 /**
-* The command i18n built-in options keys
+* Command i18n built-in options keys
 * @experimental
 */
 type CommandBuiltinOptionsKeys = keyof (typeof __constants)["COMMON_OPTIONS"];
 /**
-* The command i18n built-in resource keys
+* Command i18n built-in resource keys
 * @experimental
 */
 type CommandBuiltinResourceKeys = (typeof __constants)["COMMAND_I18N_RESOURCE_KEYS"][number];
 /**
-* The command i18n built-in keys
+* Command i18n built-in keys
 * @description The command i18n built-in keys are used to {@link CommandContext.translation | translate} function
 * @experimental
 */
 type CommandBuiltinKeys = CommandBuiltinOptionsKeys | CommandBuiltinResourceKeys | "description" | "examples";
 /**
-* The command environment
+* Command environment
 */
 interface CommandEnvironment<Options extends ArgOptions = ArgOptions> {
 	/**
-	* The current working directory
+	* Current working directory
 	* @see {@link CommandOptions.cwd}
 	*/
 	cwd: string | undefined;
 	/**
-	* The command name
+	* Command name
 	* @see {@link CommandOptions.name}
 	*/
 	name: string | undefined;
 	/**
-	* The command description
+	* Command description
 	* @see {@link CommandOptions.description}
 	*
 	*/
 	description: string | undefined;
 	/**
-	* The command version
+	* Command version
 	* @see {@link CommandOptions.version}
 	*/
 	version: string | undefined;
 	/**
-	* The left margin of the command output
+	* Left margin of the command output
 	* @default 2
 	* @see {@link CommandOptions.leftMargin}
 	*/
 	leftMargin: number;
 	/**
-	* The middle margin of the command output
+	* Middle margin of the command output
 	* @default 10
 	* @see {@link CommandOptions.middleMargin}
 	*/
@@ -84,7 +84,7 @@ interface CommandEnvironment<Options extends ArgOptions = ArgOptions> {
 	*/
 	usageOptionType: boolean;
 	/**
-	* The sub commands
+	* Sub commands
 	* @see {@link CommandOptions.subCommands}
 	*/
 	subCommands: Map<string, Command<Options> | LazyCommand<Options>> | undefined;
@@ -102,45 +102,40 @@ interface CommandEnvironment<Options extends ArgOptions = ArgOptions> {
 	renderValidationErrors: ((ctx: CommandContext<Options>, error: AggregateError) => Promise<string>) | null | undefined;
 }
 /**
-* The command options
+* Command options
 */
 interface CommandOptions<Options extends ArgOptions> {
 	/**
-	* The current working directory
-	* @description This is the current working directory path passed in the context of the run command. This is useful if you need your command about the current execution directory.
+	* Current working directory
 	*/
 	cwd?: string;
 	/**
-	* The command name
-	* @description Please specify the name of the command that was executed. If you would specify it, gunshi will be displayed in the usage.
+	* Command program name
 	*/
 	name?: string;
 	/**
-	* The command description
-	* @description Please specify the description (summary) of the command that was executed. If you would specify it, gunshi will be displayed in the usage.
+	* Command program description
 	*
 	*/
 	description?: string;
 	/**
-	* The command version
-	* @description Please specify the version of the command that was executed. If you would specify it, gunshi will be displayed in the usage.
+	* Command program version
 	*/
 	version?: string;
 	/**
-	* The locale of the command
-	* @description The locale of the command that was executed. If you would specify it, gunshi command usage will be localized.
+	* Command program locale
 	*/
 	locale?: string | Intl.Locale;
 	/**
-	* The sub commands
+	* Sub commands
 	*/
 	subCommands?: Map<string, Command<Options> | LazyCommand<Options>>;
 	/**
-	* The left margin of the command output
+	* Left margin of the command output
 	*/
 	leftMargin?: number;
 	/**
-	* The middle margin of the command output
+	* Middle margin of the command output
 	*/
 	middleMargin?: number;
 	/**
@@ -161,44 +156,44 @@ interface CommandOptions<Options extends ArgOptions> {
 	renderValidationErrors?: ((ctx: Readonly<CommandContext<Options>>, error: AggregateError) => Promise<string>) | null;
 }
 /**
-* The command context
-* @description The command context is the context of the command execution
+* Command context
+* @description Command context is the context of the command execution
 */
 interface CommandContext<
 	Options extends ArgOptions,
 	Values = ArgValues<Options>
 > {
 	/**
-	* The command name, that is the command that is executed
+	* Command name, that is the command that is executed
 	* @description The command name is same {@link CommandEnvironment.name}
 	*/
 	name: string | undefined;
 	/**
-	* The command description, that is the description of the command that is executed
+	* Command description, that is the description of the command that is executed
 	* @description The command description is same {@link CommandEnvironment.description}
 	*/
 	description: string | undefined;
 	/**
-	* The command locale, that is the locale of the command that is executed
+	* Command locale, that is the locale of the command that is executed
 	*/
 	locale: Intl.Locale;
 	/**
-	* The command environment, that is the environment of the command that is executed
+	* Command environment, that is the environment of the command that is executed
 	* @description The command environment is same {@link CommandEnvironment}
 	*/
 	env: CommandEnvironment<Options>;
 	/**
-	* The command options, that is the options of the command that is executed
+	* Command options, that is the options of the command that is executed
 	* @description The command options is same {@link Command.options}
 	*/
 	options: Options | undefined;
 	/**
-	* The command values, that is the values of the command that is executed
+	* Command values, that is the values of the command that is executed
 	* @description Resolve values with `resolveArgs` from command arguments and {@link Command.options}
 	*/
 	values: Values;
 	/**
-	* The command positionals, that is the positionals of the command that is executed
+	* Command positionals arguments, that is the positionals of the command that is executed
 	* @description Resolve positionals with `resolveArgs` from command arguments
 	*/
 	positionals: string[];
@@ -207,20 +202,20 @@ interface CommandContext<
 	*/
 	omitted: boolean;
 	/**
-	* The usage of the command
-	* @description The usage of the command is same {@link Command.usage}, and more has `--help` and `--version` options
+	* Command usage
+	* @description Usage of the command is same {@link Command.usage}, and more has `--help` and `--version` options
 	*/
 	usage: CommandUsage<Options>;
 	/**
-	* Load the sub-commands
+	* Load sub-commands
 	* @description The loaded commands are cached and returned when called again
 	* @returns loaded commands
 	*/
 	loadCommands: () => Promise<Command<Options>[]>;
 	/**
-	* The translation function
-	* @param key {CommandBuiltinKeys | T} - The key to be translated
-	* @returns The translated string, if the key is not found, the key itself is returned
+	* Translation function
+	* @param key the key to be translated
+	* @returns A translated string
 	* @experimental
 	*/
 	translation: <
@@ -229,37 +224,32 @@ interface CommandContext<
 	>(key: Key) => string;
 }
 /**
-* The command usage render
-* @description if the render function is async, it should return a promise
-*/
-type CommandUsageRender<Options extends ArgOptions> = ((ctx: Readonly<CommandContext<Options>>) => Promise<string>) | string;
-/**
-* The command usage
+* Command usage
 */
 interface CommandUsage<Options extends ArgOptions> {
 	/**
-	* The options usage
+	* Options usage
 	*/
 	options?: { [Option in keyof Options] : string };
 	/**
-	* The examples usage
+	* Examples usage
 	*/
 	examples?: string;
 }
 /**
-* The command interface
+* Command interface
 */
 interface Command<Options extends ArgOptions> {
 	/**
-	* The command name
+	* Command name
 	* @description
-	* The command name is used to find command line arguments to execute from sub commands, so it's recommended to specify.
+	* Command name is used to find command line arguments to execute from sub commands, so it's recommended to specify.
 	*/
 	name?: string;
 	/**
-	* The command description
+	* Command description
 	* @description
-	* The command description is used to describe the command in usage, so it's recommended to specify.
+	* Command description is used to describe the command in usage, so it's recommended to specify.
 	*/
 	description?: string;
 	/**
@@ -268,57 +258,59 @@ interface Command<Options extends ArgOptions> {
 	*/
 	default?: boolean;
 	/**
-	* The command options
+	* Command options
 	*/
 	options?: Options;
 	/**
-	* The command usage
+	* Command usage
 	* @description
-	* The command usage is used to describe the command in usage, so it's recommended to specify.
+	* Command usage is used to describe the command in usage, so it's recommended to specify.
 	*/
 	usage?: CommandUsage<Options>;
 	/**
-	* The command runner, that's the command to be executed
+	* Command runner, that's the command to be executed
 	*/
 	run: CommandRunner<Options>;
 	/**
-	* The command resource fetcher
+	* Command resource fetcher
 	* @experimental
 	*/
 	resource?: CommandResourceFetcher<Options>;
 }
 /**
-* The command resource
+* Command resource
 * @experimental
 */
 interface CommandResource<Options extends ArgOptions> {
 	/**
-	* The command description resource
+	* Command description
 	*/
 	description: string;
 	/**
-	* The options usage resources
+	* Options usage
 	*/
 	options: { [Option in keyof Options] : string };
 	/**
-	* The examples usage resources
+	* Examples usage
 	*/
 	examples: string;
 }
 /**
-* The command resource fetcher
+* Command resource fetcher
+* @param ctx A {@link CommandContext | command context}
+* @returns A fetched {@link CommandResource | command resource}
 * @experimental
 */
 type CommandResourceFetcher<Options extends ArgOptions> = (ctx: Readonly<CommandContext<Options>>) => Promise<CommandResource<Options>>;
 /**
-* The command runner interface
-* @param ctx - The {@link CommandContext | command context}
+* Command runner
+* @param ctx A {@link CommandContext | command context}
 */
 type CommandRunner<Options extends ArgOptions> = (ctx: Readonly<CommandContext<Options>>) => Awaitable<void>;
 /**
-* The lazy command interface
-* @description The lazy command that's not loaded until it is executed
+* Lazy command interface
+* @description lazy command that's not loaded until it is executed
 */
 type LazyCommand<Options extends ArgOptions> = () => Awaitable<Command<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, CommandUsageRender as h, CommandResource as i, CommandResourceFetcher as j };
+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 };

package/package.json

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