gunshi 0.19.0 → 0.20.0

package/README.md

@@ -99,6 +99,7 @@ About more details and usage, see [documentations](https://gunshi.dev)
 ## 💁‍♀️ Showcases
 
 - [pnpmc](https://github.com/kazupon/pnpmc): PNPM Catalogs Tooling
+- [sourcemap-publisher](https://github.com/es-tooling/sourcemap-publisher): A tool to publish sourcemaps externally and rewrite sourcemap URLs at pre-publish time
 
 ## 🙌 Contributing guidelines
 

package/lib/{cli-m93bHwFR.js → cli-rwwoCHjK.js}

@@ -1,6 +1,6 @@
-import { COMMAND_OPTIONS_DEFAULT, COMMON_ARGS, create, resolveLazyCommand } from "./utils-DWRmOGGa.js";
-import { createCommandContext } from "./context-CBDAvGDh.js";
-import { renderHeader, renderUsage, renderValidationErrors } from "./renderer-BDs5T_Z4.js";
+import { COMMAND_OPTIONS_DEFAULT, COMMON_ARGS, create, resolveLazyCommand } from "./utils-STQBqMtf.js";
+import { createCommandContext } from "./context-IwpAqLSL.js";
+import { renderHeader, renderUsage, renderValidationErrors } from "./renderer-BpwhGYRZ.js";
 import { parseArgs, resolveArgs } from "args-tokens";
 
 //#region src/cli.ts

package/lib/{context-CBDAvGDh.js → context-IwpAqLSL.js}

@@ -1,4 +1,4 @@
-import { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, DEFAULT_LOCALE$1 as DEFAULT_LOCALE, NOOP, create, deepFreeze, log, mapResourceWithBuiltinKey, resolveArgKey, resolveLazyCommand } from "./utils-DWRmOGGa.js";
+import { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, DEFAULT_LOCALE$1 as DEFAULT_LOCALE, NOOP, create, deepFreeze, log, mapResourceWithBuiltinKey, resolveArgKey, resolveExamples, resolveLazyCommand } from "./utils-STQBqMtf.js";
 
 //#region src/locales/en-US.json
 var COMMAND = "COMMAND";
@@ -152,14 +152,11 @@ async function createCommandContext({ args, values, positionals, rest, argv, tok
 		return res;
 	}, create());
 	defaultCommandResource.description = command.description || "";
-	defaultCommandResource.examples = command.examples || "";
+	defaultCommandResource.examples = await resolveExamples(ctx, command.examples);
 	adapter.setResource(DEFAULT_LOCALE, defaultCommandResource);
 	const originalResource = await loadCommandResource(ctx, command);
 	if (originalResource) {
-		const resource = Object.assign(create(), {
-			description: originalResource.description,
-			examples: originalResource.examples
-		}, originalResource);
+		const resource = Object.assign(create(), originalResource, { examples: await resolveExamples(ctx, originalResource.examples) });
 		if (builtInLoadedResources) {
 			resource.help = builtInLoadedResources.help;
 			resource.version = builtInLoadedResources.version;

package/lib/context.d.ts

@@ -1,4 +1,4 @@
-import { Command, CommandContext, CommandOptions } from "./types-BVZKXMbJ.js";
+import { Command, CommandContext, CommandOptions } from "./types-iztBdPY6.js";
 import { ArgToken, ArgValues, Args } from "args-tokens";
 
 //#region src/context.d.ts

package/lib/context.js

@@ -1,4 +1,4 @@
-import "./utils-DWRmOGGa.js";
-import { createCommandContext } from "./context-CBDAvGDh.js";
+import "./utils-STQBqMtf.js";
+import { createCommandContext } from "./context-IwpAqLSL.js";
 
 export { createCommandContext };

package/lib/{definition-Bdw7cMea.d.ts → definition-BrCD_SuG.d.ts}

@@ -1,4 +1,4 @@
-import { Command, CommandLoader, LazyCommand } from "./types-BVZKXMbJ.js";
+import { Command, CommandLoader, LazyCommand } from "./types-iztBdPY6.js";
 import { ArgSchema, ArgValues as ArgValues$1, Args, Args as Args$1 } from "args-tokens";
 
 //#region src/definition.d.ts

package/lib/definition.d.ts

@@ -1,3 +1,3 @@
-import "./types-BVZKXMbJ.js";
-import { ArgSchema, ArgValues, Args, define$1 as define, lazy$1 as lazy } from "./definition-Bdw7cMea.js";
+import "./types-iztBdPY6.js";
+import { ArgSchema, ArgValues, Args, define$1 as define, lazy$1 as lazy } from "./definition-BrCD_SuG.js";
 export { ArgSchema, ArgValues, Args, define, lazy };

package/lib/generator.d.ts

@@ -1,4 +1,4 @@
-import { Command, CommandOptions } from "./types-BVZKXMbJ.js";
+import { Command, CommandOptions } from "./types-iztBdPY6.js";
 import { Args } from "args-tokens";
 
 //#region src/generator.d.ts

package/lib/generator.js

@@ -1,7 +1,7 @@
-import { create } from "./utils-DWRmOGGa.js";
-import "./context-CBDAvGDh.js";
-import "./renderer-BDs5T_Z4.js";
-import { cli } from "./cli-m93bHwFR.js";
+import { create } from "./utils-STQBqMtf.js";
+import "./context-IwpAqLSL.js";
+import "./renderer-BpwhGYRZ.js";
+import { cli } from "./cli-rwwoCHjK.js";
 
 //#region src/generator.ts
 /**

package/lib/index.d.ts

@@ -1,5 +1,5 @@
-import { Command, CommandArgKeys, CommandBuiltinArgsKeys, CommandBuiltinKeys, CommandBuiltinResourceKeys, CommandContext, CommandEnvironment, CommandLoader, CommandOptions, CommandResource, CommandResourceFetcher, CommandRunner, Commandable, DEFAULT_LOCALE, GenerateNamespacedKey, KeyOfArgs, LazyCommand, RemovedIndex, TranslationAdapter, TranslationAdapterFactory, TranslationAdapterFactoryOptions } from "./types-BVZKXMbJ.js";
-import { define$1 as define, lazy$1 as lazy } from "./definition-Bdw7cMea.js";
+import { Command, CommandArgKeys, CommandBuiltinArgsKeys, CommandBuiltinKeys, CommandBuiltinResourceKeys, CommandContext, CommandEnvironment, CommandExamplesFetcher, CommandLoader, CommandOptions, CommandResource, CommandResourceFetcher, CommandRunner, Commandable, DEFAULT_LOCALE, GenerateNamespacedKey, KeyOfArgs, LazyCommand, RemovedIndex, TranslationAdapter, TranslationAdapterFactory, TranslationAdapterFactoryOptions } from "./types-iztBdPY6.js";
+import { define$1 as define, lazy$1 as lazy } from "./definition-BrCD_SuG.js";
 import { ArgSchema, ArgValues, Args, Args as Args$1, parseArgs, resolveArgs } from "args-tokens";
 
 //#region src/cli.d.ts
@@ -32,4 +32,4 @@ declare class DefaultTranslation implements TranslationAdapter {
 }
 
 //#endregion
-export { ArgSchema, ArgValues, Args, Command, CommandArgKeys, CommandBuiltinArgsKeys, CommandBuiltinKeys, CommandBuiltinResourceKeys, CommandContext, CommandEnvironment, CommandLoader, CommandOptions, CommandResource, CommandResourceFetcher, CommandRunner, Commandable, DEFAULT_LOCALE, DefaultTranslation, GenerateNamespacedKey, KeyOfArgs, LazyCommand, RemovedIndex, TranslationAdapter, TranslationAdapterFactory, TranslationAdapterFactoryOptions, cli, define, lazy, parseArgs, resolveArgs };
+export { ArgSchema, ArgValues, Args, Command, CommandArgKeys, CommandBuiltinArgsKeys, CommandBuiltinKeys, CommandBuiltinResourceKeys, CommandContext, CommandEnvironment, CommandExamplesFetcher, CommandLoader, CommandOptions, CommandResource, CommandResourceFetcher, CommandRunner, Commandable, DEFAULT_LOCALE, DefaultTranslation, GenerateNamespacedKey, KeyOfArgs, LazyCommand, RemovedIndex, TranslationAdapter, TranslationAdapterFactory, TranslationAdapterFactoryOptions, cli, define, lazy, parseArgs, resolveArgs };

package/lib/index.js

@@ -1,8 +1,8 @@
-import { DEFAULT_LOCALE$1 as DEFAULT_LOCALE } from "./utils-DWRmOGGa.js";
-import { DefaultTranslation } from "./context-CBDAvGDh.js";
+import { DEFAULT_LOCALE$1 as DEFAULT_LOCALE } from "./utils-STQBqMtf.js";
+import { DefaultTranslation } from "./context-IwpAqLSL.js";
 import { define, lazy } from "./definition-DyVBFqB7.js";
-import "./renderer-BDs5T_Z4.js";
-import { cli } from "./cli-m93bHwFR.js";
+import "./renderer-BpwhGYRZ.js";
+import { cli } from "./cli-rwwoCHjK.js";
 import { parseArgs, resolveArgs } from "args-tokens";
 
 export { DEFAULT_LOCALE, DefaultTranslation, cli, define, lazy, parseArgs, resolveArgs };

package/lib/{renderer-BDs5T_Z4.js → renderer-BpwhGYRZ.js}

@@ -1,4 +1,4 @@
-import { COMMON_ARGS, create, resolveArgKey, resolveBuiltInKey } from "./utils-DWRmOGGa.js";
+import { COMMON_ARGS, create, resolveArgKey, resolveBuiltInKey, resolveExamples } from "./utils-STQBqMtf.js";
 
 //#region src/renderer/header.ts
 /**
@@ -29,7 +29,7 @@ async function renderUsage(ctx) {
 	if (ctx.omitted && await hasCommands(ctx)) messages.push(...await renderCommandsSection(ctx), "");
 	if (hasPositionalArgs(ctx)) messages.push(...await renderPositionalArgsSection(ctx), "");
 	if (hasOptionalArgs(ctx)) messages.push(...await renderOptionalArgsSection(ctx), "");
-	const examples = renderExamplesSection(ctx);
+	const examples = await renderExamplesSection(ctx);
 	if (examples.length > 0) messages.push(...examples, "");
 	return messages.join("\n");
 }
@@ -60,9 +60,9 @@ async function renderOptionalArgsSection(ctx) {
 * @param ctx A {@link CommandContext | command context}
 * @returns A rendered examples section
 */
-function renderExamplesSection(ctx) {
+async function renderExamplesSection(ctx) {
 	const messages = [];
-	const resolvedExamples = resolveExamples(ctx);
+	const resolvedExamples = await resolveExamples$1(ctx);
 	if (resolvedExamples) {
 		const examples = resolvedExamples.split("\n").map((example) => example.padStart(ctx.env.leftMargin + example.length));
 		messages.push(`${ctx.translate(resolveBuiltInKey("EXAMPLES"))}:`, ...examples);
@@ -140,11 +140,11 @@ function resolveDescription(ctx) {
 * @param ctx A {@link CommandContext | command context}
 * @returns resolved command examples, if not resolved, return empty string
 */
-function resolveExamples(ctx) {
+async function resolveExamples$1(ctx) {
 	const ret = ctx.translate("examples");
 	if (ret) return ret;
 	const command = ctx.env.subCommands?.get(ctx.name || "");
-	return command?.examples ?? "";
+	return await resolveExamples(ctx, command?.examples);
 }
 /**
 * Check if the command has sub commands

package/lib/renderer.d.ts

@@ -1,4 +1,4 @@
-import { CommandContext } from "./types-BVZKXMbJ.js";
+import { CommandContext } from "./types-iztBdPY6.js";
 import { Args } from "args-tokens";
 
 //#region src/renderer/header.d.ts

package/lib/renderer.js

@@ -1,4 +1,4 @@
-import "./utils-DWRmOGGa.js";
-import { renderHeader, renderUsage, renderValidationErrors } from "./renderer-BDs5T_Z4.js";
+import "./utils-STQBqMtf.js";
+import { renderHeader, renderUsage, renderValidationErrors } from "./renderer-BpwhGYRZ.js";
 
 export { renderHeader, renderUsage, renderValidationErrors };

package/lib/{types-BVZKXMbJ.d.ts → types-iztBdPY6.d.ts}

@@ -34,29 +34,36 @@ type Awaitable<T> = T | Promise<T>;
 type RemoveIndexSignature<T> = { [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K] };
 /**
  * Remove index signature from object or record type.
+ * @internal
  */
 type RemovedIndex<T> = RemoveIndexSignature<{ [K in keyof T]: T[K] }>;
+/** @internal */
 type KeyOfArgs<A extends Args> = keyof A | { [K in keyof A]: A[K]['type'] extends 'boolean' ? A[K]['negatable'] extends true ? `no-${Extract<K, string>}` : never : never }[keyof A];
 /**
  * Generate a namespaced key.
+ * @internal
  */
 type GenerateNamespacedKey<Key extends string, Prefixed extends string = typeof BUILT_IN_PREFIX> = `${Prefixed}${typeof BUILT_IN_KEY_SEPARATOR}${Key}`;
 /**
  * Command i18n built-in arguments keys.
+ * @internal
  */
 type CommandBuiltinArgsKeys = keyof (typeof constants_d_exports)['COMMON_ARGS'];
 /**
  * Command i18n built-in resource keys.
+ * @internal
  */
 type CommandBuiltinResourceKeys = (typeof constants_d_exports)['COMMAND_BUILTIN_RESOURCE_KEYS'][number];
 /**
  * Command i18n built-in keys.
  * The command i18n built-in keys are used to {@link CommandContext.translate | translate} function.
+ * @internal
  */
 type CommandBuiltinKeys = GenerateNamespacedKey<CommandBuiltinArgsKeys> | GenerateNamespacedKey<CommandBuiltinResourceKeys> | 'description' | 'examples';
 /**
  * Command i18n option keys.
  * The command i18n option keys are used to {@link CommandContext.translate | translate} function.
+ * @internal
  */
 type CommandArgKeys<A extends Args> = GenerateNamespacedKey<KeyOfArgs<RemovedIndex<A>>, typeof ARG_PREFIX>;
 /**
@@ -298,7 +305,7 @@ interface Command<A extends Args = Args> {
    * Command examples.
    * examples of how to use the command.
    */
-  examples?: string;
+  examples?: string | CommandExamplesFetcher<A>;
   /**
    * Command runner. it's the command to be executed
    */
@@ -319,10 +326,16 @@ type CommandResource<A extends Args = Args> = {
   /**
    * Examples usage.
    */
-  examples: string;
+  examples: string | CommandExamplesFetcher<A>;
 } & { [Arg in GenerateNamespacedKey<KeyOfArgs<RemovedIndex<A>>, typeof ARG_PREFIX>]: string } & {
   [key: string]: string;
 };
+/**
+ * Command examples fetcher.
+ * @param ctx A {@link CommandContext | command context}
+ * @returns A fetched command examples.
+ */
+type CommandExamplesFetcher<A extends Args = Args, V = ArgValues<A>> = (ctx: Readonly<CommandContext<A, V>>) => Promise<string>;
 /**
  * Command resource fetcher.
  * @param ctx A {@link CommandContext | command context}
@@ -404,4 +417,4 @@ type LazyCommand<A extends Args = Args> = {
  * Define a command type.
  */
 type Commandable<A extends Args> = Command<A> | LazyCommand<A>; //#endregion
-export { Command, CommandArgKeys, CommandBuiltinArgsKeys, CommandBuiltinKeys, CommandBuiltinResourceKeys, CommandContext, CommandEnvironment, CommandLoader, CommandOptions, CommandResource, CommandResourceFetcher, CommandRunner, Commandable, DEFAULT_LOCALE, GenerateNamespacedKey, KeyOfArgs, LazyCommand, RemovedIndex, TranslationAdapter, TranslationAdapterFactory, TranslationAdapterFactoryOptions };
+export { Command, CommandArgKeys, CommandBuiltinArgsKeys, CommandBuiltinKeys, CommandBuiltinResourceKeys, CommandContext, CommandEnvironment, CommandExamplesFetcher, CommandLoader, CommandOptions, CommandResource, CommandResourceFetcher, CommandRunner, Commandable, DEFAULT_LOCALE, GenerateNamespacedKey, KeyOfArgs, LazyCommand, RemovedIndex, TranslationAdapter, TranslationAdapterFactory, TranslationAdapterFactoryOptions };

package/lib/{utils-DWRmOGGa.js → utils-STQBqMtf.js}

@@ -71,6 +71,9 @@ function resolveBuiltInKey(key) {
 function resolveArgKey(key) {
 	return `${ARG_PREFIX}${BUILT_IN_KEY_SEPARATOR}${key}`;
 }
+async function resolveExamples(ctx, examples) {
+	return typeof examples === "string" ? examples : typeof examples === "function" ? await examples(ctx) : "";
+}
 function mapResourceWithBuiltinKey(resource) {
 	return Object.entries(resource).reduce((acc, [key, value]) => {
 		acc[resolveBuiltInKey(key)] = value;
@@ -93,4 +96,4 @@ function deepFreeze(obj) {
 }
 
 //#endregion
-export { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, COMMON_ARGS, DEFAULT_LOCALE as DEFAULT_LOCALE$1, NOOP, create, deepFreeze, log, mapResourceWithBuiltinKey, resolveArgKey, resolveBuiltInKey, resolveLazyCommand };
+export { BUILT_IN_PREFIX, COMMAND_OPTIONS_DEFAULT, COMMON_ARGS, DEFAULT_LOCALE as DEFAULT_LOCALE$1, NOOP, create, deepFreeze, log, mapResourceWithBuiltinKey, resolveArgKey, resolveBuiltInKey, resolveExamples, resolveLazyCommand };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gunshi",
   "description": "Modern javascript command-line library",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -103,11 +103,13 @@
     "eslint-plugin-vue-composable": "^1.0.0",
     "eslint-plugin-yml": "^1.18.0",
     "gh-changelogen": "^0.2.8",
+    "gunshi019": "npm:gunshi@0.19.0",
     "jsr": "^0.13.4",
     "jsr-exports-lint": "^0.2.0",
     "knip": "^5.53.0",
     "lint-staged": "^15.5.1",
     "messageformat": "4.0.0-10",
+    "mitata": "^1.0.34",
     "pkg-pr-new": "^0.0.43",
     "prettier": "^3.5.3",
     "publint": "^0.3.12",
@@ -138,6 +140,8 @@
     ]
   },
   "scripts": {
+    "bench:mitata": "node --expose-gc bench/mitata.js",
+    "bench:vitest": "vitest bench --run",
     "build": "tsdown",
     "changelog": "gh-changelogen --repo=kazupon/gunshi",
     "clean": "git clean -df",
@@ -145,7 +149,7 @@
     "dev:eslint": "pnpx @eslint/config-inspector --config eslint.config.ts",
     "dev:typedoc": "typedoc --watch --preserveWatchOutput",
     "docs:build": "pnpm run docs:build:typedoc && pnpm docs:build:vitepress",
-    "docs:build:typedoc": "typedoc",
+    "docs:build:typedoc": "typedoc --excludeInternal",
     "docs:build:vitepress": "vitepress build docs",
     "docs:dev": "pnpm run docs:build:typedoc && pnpm docs:dev:vitepress",
     "docs:dev:vitepress": "vitepress dev docs",