gunshi 0.11.0 → 0.13.0

package/README.md

@@ -32,8 +32,6 @@ Gunshi is designed to simplify the creation of modern command-line interfaces:
 
 ## 💿 Installation
 
-### 🐢 Node
-
 ```sh
 # npm
 npm install --save gunshi
@@ -43,41 +41,16 @@ pnpm add gunshi
 
 ## yarn
 yarn add gunshi
-```
-
-### 🦕 Deno
 
-```sh
+## deno
 deno add jsr:@kazupon/gunshi
-```
 
-### 🥟 Bun
-
-```sh
+## bun
 bun add gunshi
 ```
 
 ## 🚀 Usage
 
-### 📏 Simple API
-
-Gunshi has a simple API that is a facade:
-
-```js
-import { cli } from 'gunshi'
-
-const args = process.argv.slice(2)
-// run a simple command
-await cli(args, () => {
-  // something logic ...
-  console.log('Hello from Gunshi!', args)
-})
-```
-
-### ⚙️ Declarative Configuration
-
-Configure commands declaratively:
-
 ```js
 import { cli } from 'gunshi'
 
@@ -121,289 +94,7 @@ await 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 'type-safe' command 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
-
-// define '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
-
-Run a CLI with composable sub-commands:
-
-```js
-import { cli } from 'gunshi'
-
-// define 'create' command
-const createCommand = {
-  name: 'create',
-  description: 'Create a new resource',
-  options: {
-    name: { type: 'string', short: 'n' }
-  },
-  run: ctx => {
-    console.log(`Creating resource: ${ctx.values.name}`)
-  }
-}
-
-// define 'list' command
-const listCommand = {
-  name: 'list',
-  description: 'List all resources',
-  run: () => {
-    console.log('Listing all resources...')
-  }
-}
-
-// prepare a Map of sub-commands
-const subCommands = new Map()
-subCommands.set('create', createCommand)
-subCommands.set('list', listCommand)
-
-// define the main ('resource-manager') command
-const mainCommand = {
-  name: 'resource-manager',
-  description: 'Manage resources',
-  run: () => {
-    console.log('Use one of the sub-commands: create, list')
-  }
-}
-
-// run the CLI with composable sub-commands
-await cli(process.argv.slice(2), mainCommand, {
-  name: 'my-app',
-  version: '1.0.0',
-  subCommands
-})
-```
-
-For more detailed examples, check out the [playground/composable](https://github.com/kazupon/gunshi/tree/main/playground/composable) in the repository.
-
-### ⏳ Lazy & Async Command Loading
-
-Load commands lazily and execute them asynchronously:
-
-```js
-import { cli } from 'gunshi'
-
-// define a command that will be loaded lazily
-const lazyCommand = async () => {
-  // simulate async loading
-  await new Promise(resolve => setTimeout(resolve, 1000))
-
-  // return the actual command
-  return {
-    name: 'lazy',
-    description: 'A command that is loaded lazily',
-    run: async ctx => {
-      // async execution
-      await new Promise(resolve => setTimeout(resolve, 500))
-      console.log('Command executed!')
-    }
-  }
-}
-
-// prepare a Map of sub-commands with lazy-loaded commands
-const subCommands = new Map()
-subCommands.set('lazy', lazyCommand)
-
-// run the CLI with lazy-loaded commands
-await cli(
-  process.argv.slice(2),
-  { name: 'main', run: () => {} },
-  {
-    name: 'my-app',
-    subCommands
-  }
-)
-```
-
-For more detailed examples, check out the [playground/lazy-async](https://github.com/kazupon/gunshi/tree/main/playground/lazy-async) in the repository.
-
-### 📜 Auto Usage Generation
-
-Gunshi automatically generates usage information:
-
-```js
-import { cli } from 'gunshi'
-
-const command = {
-  name: 'app',
-  description: 'My application',
-  options: {
-    path: {
-      type: 'string',
-      short: 'p',
-      description: 'File or directory path'
-    },
-    recursive: {
-      type: 'boolean',
-      short: 'r',
-      description: 'Operate recursively on directories'
-    },
-    operation: {
-      type: 'string',
-      short: 'o',
-      required: true,
-      description: 'Operation to perform (list, copy, move, delete)'
-    }
-  },
-  // define examples
-  examples: '# Example\n$ my-app --operation list --path ./src',
-  run: ctx => {
-    // command implementation
-  }
-}
-
-// run with --help to see the automatically generated usage information
-await cli(process.argv.slice(2), command, {
-  name: 'my-app',
-  version: '1.0.0'
-})
-```
-
-For more detailed examples, check out the [playground/auto-usage](https://github.com/kazupon/gunshi/tree/main/playground/auto-usage) in the repository.
-
-### 🎨 Custom Usage Generation
-
-Customize the usage message generation:
-
-```js
-import { cli } from 'gunshi'
-
-// define custom header renderer
-const customHeaderRenderer = ctx => {
-  return Promise.resolve(`
-╔═══════════════════════╗
-║      ${ctx.env.name.toUpperCase()}      ║
-╚═══════════════════════╝
-${ctx.env.description}
-Version: ${ctx.env.version}
-`)
-}
-
-// define custom usage renderer
-const customUsageRenderer = ctx => {
-  const lines = []
-  lines.push('USAGE:')
-  lines.push(`  $ ${ctx.env.name} [options]`)
-  lines.push('')
-  lines.push('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.translate(key)}`)
-  }
-
-  return Promise.resolve(lines.join('\n'))
-}
-
-// run with custom renderers
-await cli(
-  process.argv.slice(2),
-  { name: 'app', run: () => {} },
-  {
-    name: 'my-app',
-    version: '1.0.0',
-    description: 'My application',
-    renderHeader: customHeaderRenderer,
-    renderUsage: customUsageRenderer
-  }
-)
-```
-
-For more detailed examples, check out the [playground/custom-usage](https://github.com/kazupon/gunshi/tree/main/playground/custom-usage) in the repository.
-
-### 🌍 Internationalization
-
-Support internationalization:
-
-```js
-import { cli } from 'gunshi'
-import enUS from './locales/en-US.json' with { type: 'json' }
-
-const command = {
-  name: 'greeter',
-  options: {
-    name: {
-      type: 'string',
-      short: 'n'
-    },
-    formal: {
-      type: 'boolean',
-      short: 'f'
-    }
-  },
-  // 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
-    return enUS
-  },
-  run: ctx => {
-    const { name = 'World', formal } = ctx.values
-    const greeting = formal ? ctx.translate('formal_greeting') : ctx.translate('informal_greeting')
-    console.log(`${greeting}, ${name}!`)
-  }
-}
-
-// run with locale support
-await 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)
-  locale: new Intl.Locale(process.env.MY_LOCALE || 'en-US')
-})
-```
-
-For more detailed examples, check out the [playground/i18n](https://github.com/kazupon/gunshi/tree/main/playground/i18n) in the repository.
+About more details and usage, see [documentations](https://gunshi.dev)
 
 ## 💁‍♀️ Showcases
 
@@ -423,6 +114,16 @@ This project is inspired and powered by:
 
 Thank you!
 
+## 🤝 Sponsors
+
+The development of Gunish is supported by my OSS sponsors!
+
+<p align="center">
+  <a href="https://cdn.jsdelivr.net/gh/kazupon/sponsors/sponsors.svg">
+    <img src='https://cdn.jsdelivr.net/gh/kazupon/sponsors/sponsors.svg'/>
+  </a>
+</p>
+
 ## ©️ License
 
 [MIT](http://opensource.org/licenses/MIT)

package/lib/{context-ZNBQwQKN.js → cli-D_4MqIMP.js}

@@ -1,4 +1,5 @@
-import { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, DEFAULT_LOCALE, NOOP, create, deepFreeze, log, mapResourceWithBuiltinKey, resolveLazyCommand } from "./utils-zZSVaYTy.js";
+import { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, COMMON_OPTIONS, DEFAULT_LOCALE, NOOP, create, deepFreeze, log, mapResourceWithBuiltinKey, renderHeader, renderUsage, renderValidationErrors, resolveLazyCommand } from "./renderer-DAUAIZxV.js";
+import { parseArgs, resolveArgs } from "args-tokens";
 
 //#region src/locales/en-US.json
 var COMMAND = "COMMAND";
@@ -29,10 +30,11 @@ function createTranslationAdapter(options) {
 }
 var DefaultTranslation = class {
 	#resources = new Map();
-	options;
+	#options;
 	constructor(options) {
-		this.options = options;
-		this.#resources = new Map();
+		this.#options = options;
+		this.#resources.set(options.locale, create());
+		if (options.locale !== options.fallbackLocale) this.#resources.set(options.fallbackLocale, create());
 	}
 	getResource(locale) {
 		return this.#resources.get(locale);
@@ -45,21 +47,20 @@ var DefaultTranslation = class {
 		if (resource) return resource[key];
 		return void 0;
 	}
-	translate(locale, key, _values = create()) {
-		/**
-		* NOTE:
-		* DefaultTranslation support static message only
-		* If you want to resolve message with values and use the complex message format,
-		* you should inherit this class or implement your own translation adapter.
-		*/
-		return this.getMessage(locale, key) || this.getMessage(this.options.fallbackLocale, key);
+	translate(locale, key, values = create()) {
+		let message = this.getMessage(locale, key);
+		if (message === void 0 && locale !== this.#options.fallbackLocale) message = this.getMessage(this.#options.fallbackLocale, key);
+		if (message === void 0) return;
+		return message.replaceAll(/\{\{(\w+)\}\}/g, (_, name) => {
+			return values[name] == null ? "" : values[name].toString();
+		});
 	}
 };
 
 //#endregion
 //#region src/context.ts
 const BUILT_IN_PREFIX_CODE = BUILT_IN_PREFIX.codePointAt(0);
-async function createCommandContext({ options, values, positionals, command, commandOptions, omitted = false }) {
+async function createCommandContext({ options, values, positionals, args, command, commandOptions, omitted = false }) {
 	/**
 	* normailize the options schema and values, to avoid prototype pollution
 	*/
@@ -120,6 +121,7 @@ async function createCommandContext({ options, values, positionals, command, com
 		options: _options,
 		values,
 		positionals,
+		_: args,
 		log: commandOptions.usageSilent ? NOOP : log,
 		loadCommands,
 		translate
@@ -164,4 +166,92 @@ async function loadCommandResource(ctx, command) {
 }
 
 //#endregion
-export { DefaultTranslation, createCommandContext };
+//#region src/cli.ts
+async function cli(args, entry, opts = {}) {
+	const tokens = parseArgs(args);
+	const subCommand = getSubCommand(tokens);
+	const resolvedCommandOptions = resolveCommandOptions(opts, entry);
+	const [name, command] = await resolveCommand(subCommand, entry, resolvedCommandOptions);
+	if (!command) throw new Error(`Command not found: ${name || ""}`);
+	const options = resolveArgOptions(command.options);
+	const { values, positionals, error } = resolveArgs(options, tokens);
+	const omitted = !subCommand;
+	const ctx = await createCommandContext({
+		options,
+		values,
+		positionals,
+		args,
+		omitted,
+		command,
+		commandOptions: resolvedCommandOptions
+	});
+	if (values.version) {
+		showVersion(ctx);
+		return;
+	}
+	const usageBuffer = [];
+	const header = await showHeader(ctx);
+	if (header) usageBuffer.push(header);
+	if (values.help) {
+		const usage = await showUsage(ctx);
+		if (usage) usageBuffer.push(usage);
+		return usageBuffer.join("\n");
+	}
+	if (error) {
+		await showValidationErrors(ctx, error);
+		return;
+	}
+	await command.run(ctx);
+}
+function resolveArgOptions(options) {
+	return Object.assign(create(), options, COMMON_OPTIONS);
+}
+function resolveCommandOptions(options, entry) {
+	const subCommands = new Map(options.subCommands);
+	if (typeof entry === "object" && entry.name) subCommands.set(entry.name, entry);
+	const resolvedOptions = Object.assign(create(), COMMAND_OPTIONS_DEFAULT, options, { subCommands });
+	return resolvedOptions;
+}
+function getSubCommand(tokens) {
+	const firstToken = tokens[0];
+	return firstToken && firstToken.kind === "positional" && firstToken.index === 0 && firstToken.value ? firstToken.value : "";
+}
+async function showUsage(ctx) {
+	if (ctx.env.renderUsage === null) return;
+	const usage = await (ctx.env.renderUsage || renderUsage)(ctx);
+	if (usage) {
+		ctx.log(usage);
+		return usage;
+	}
+}
+function showVersion(ctx) {
+	ctx.log(ctx.env.version);
+}
+async function showHeader(ctx) {
+	if (ctx.env.renderHeader === null) return;
+	const header = await (ctx.env.renderHeader || renderHeader)(ctx);
+	if (header) {
+		ctx.log(header);
+		ctx.log();
+		return header;
+	}
+}
+async function showValidationErrors(ctx, error) {
+	if (ctx.env.renderValidationErrors === null) return;
+	const render = ctx.env.renderValidationErrors || renderValidationErrors;
+	ctx.log(await render(ctx, error));
+}
+async function resolveCommand(sub, entry, options) {
+	const omitted = !sub;
+	if (typeof entry === "function") return [void 0, { run: entry }];
+	else if (omitted) return typeof entry === "object" ? [entry.name, await resolveLazyCommand(entry)] : [void 0, void 0];
+	else {
+		if (options.subCommands == null) return [sub, void 0];
+		const cmd = options.subCommands?.get(sub);
+		if (cmd == null) return [sub, void 0];
+		return [sub, await resolveLazyCommand(cmd, sub)];
+	}
+}
+
+//#endregion
+export { DefaultTranslation, cli };

package/lib/generator.d.ts

@@ -1,12 +1,12 @@
 import { ArgOptions } from 'args-tokens';
-import { C as Command, a as CommandOptions } from './types.d-VymWn7vz.js';
+import { C as Command, a as CommandOptions } from './types.d-DqtZy3HN.js';
 
 /**
-* Generate the command usage
+* Generate the command usage.
 * @param command - usage generate command, if you want to generate the usage of the default command where there are target commands and sub-commands, specify `null`.
 * @param entry - A {@link Command | entry command}
 * @param opts - A {@link CommandOptions | command options}
-* @returns A rendered usage
+* @returns A rendered usage.
 */
 declare function generate<Options extends ArgOptions = ArgOptions>(command: string | null, entry: Command<Options>, opts?: CommandOptions<Options>): Promise<string>;
 

package/lib/generator.js

@@ -1,7 +1,5 @@
-import { create } from "./utils-zZSVaYTy.js";
-import "./context-ZNBQwQKN.js";
-import "./renderer-Dm_6iF2f.js";
-import { cli } from "./cli-CKcZ5eWi.js";
+import { create } from "./renderer-DAUAIZxV.js";
+import { cli } from "./cli-D_4MqIMP.js";
 
 //#region src/generator.ts
 async function generate(command, entry, opts = {}) {

package/lib/index.d.ts

@@ -1,25 +1,24 @@
 import { ArgOptions } from 'args-tokens';
-export { ArgOptionSchema, ArgOptions, ArgValues } from 'args-tokens';
-import { C as Command, c as CommandRunner, a as CommandOptions, T as TranslationAdapter, d as TranslationAdapterFactoryOptions } from './types.d-VymWn7vz.js';
-export { g as CommandBuiltinKeys, e as CommandBuiltinOptionsKeys, f as CommandBuiltinResourceKeys, b as CommandContext, h as CommandEnvironment, i as CommandResource, j as CommandResourceFetcher, l as Commandable, G as GenerateNamespacedKey, L as LazyCommand, k as TranslationAdapterFactory } from './types.d-VymWn7vz.js';
+export { ArgOptionSchema, ArgOptions, ArgValues, parseArgs, resolveArgs } from 'args-tokens';
+import { C as Command, b as CommandRunner, a as CommandOptions, T as TranslationAdapter, c as TranslationAdapterFactoryOptions } from './types.d-DqtZy3HN.js';
+export { f as CommandBuiltinKeys, d as CommandBuiltinOptionsKeys, e as CommandBuiltinResourceKeys, h as CommandContext, g as CommandEnvironment, i as CommandResource, j as CommandResourceFetcher, l as Commandable, D as DEFAULT_LOCALE, G as GenerateNamespacedKey, L as LazyCommand, k as TranslationAdapterFactory } from './types.d-DqtZy3HN.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}
+* 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}
 * @returns A rendered usage or undefined. if you will use {@link CommandOptions.usageSilent} option, it will return rendered usage string.
 */
 declare function cli<Options extends ArgOptions = ArgOptions>(args: string[], entry: Command<Options> | CommandRunner<Options>, opts?: CommandOptions<Options>): Promise<string | undefined>;
 
 declare class DefaultTranslation implements TranslationAdapter {
 	#private;
-	options: TranslationAdapterFactoryOptions;
 	constructor(options: TranslationAdapterFactoryOptions);
 	getResource(locale: string): Record<string, string> | undefined;
 	setResource(locale: string, resource: Record<string, string>): void;
 	getMessage(locale: string, key: string): string | undefined;
-	translate(locale: string, key: string, _values?: Record<string, unknown>): string | undefined;
+	translate(locale: string, key: string, values?: Record<string, unknown>): string | undefined;
 }
 
 export { Command, CommandOptions, CommandRunner, DefaultTranslation, TranslationAdapter, TranslationAdapterFactoryOptions, cli };

package/lib/index.js

@@ -1,6 +1,5 @@
-import "./utils-zZSVaYTy.js";
-import { DefaultTranslation } from "./context-ZNBQwQKN.js";
-import "./renderer-Dm_6iF2f.js";
-import { cli } from "./cli-CKcZ5eWi.js";
+import { DEFAULT_LOCALE } from "./renderer-DAUAIZxV.js";
+import { DefaultTranslation, cli } from "./cli-D_4MqIMP.js";
+import { parseArgs, resolveArgs } from "args-tokens";
 
-export { DefaultTranslation, cli };
+export { DEFAULT_LOCALE, DefaultTranslation, cli, parseArgs, resolveArgs };

package/lib/renderer/index.d.ts

@@ -1,25 +1,25 @@
 import { ArgOptions } from 'args-tokens';
-import { b as CommandContext } from '../types.d-VymWn7vz.js';
+import { h as CommandContext } from '../types.d-DqtZy3HN.js';
 
 /**
-* Render the header
+* Render the header.
 * @param ctx A {@link CommandContext | command context}
-* @returns A rendered header
+* @returns A rendered header.
 */
 declare function renderHeader<Options extends ArgOptions = ArgOptions>(ctx: Readonly<CommandContext<Options>>): Promise<string>;
 
 /**
-* Render the usage
+* Render the usage.
 * @param ctx A {@link CommandContext | command context}
-* @returns A rendered usage
+* @returns A rendered usage.
 */
 declare function renderUsage<Options extends ArgOptions = ArgOptions>(ctx: Readonly<CommandContext<Options>>): Promise<string>;
 
 /**
-* Render the validation errors
+* 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
+* @returns A rendered validation error.
 */
 declare function renderValidationErrors<Options extends ArgOptions = ArgOptions>(_ctx: CommandContext<Options>, error: AggregateError): Promise<string>;
 

package/lib/renderer/index.js

@@ -1,4 +1,3 @@
-import "../utils-zZSVaYTy.js";
-import { renderHeader, renderUsage, renderValidationErrors } from "../renderer-Dm_6iF2f.js";
+import { renderHeader, renderUsage, renderValidationErrors } from "../renderer-DAUAIZxV.js";
 
 export { renderHeader, renderUsage, renderValidationErrors };