@gunshi/shared 0.27.0-alpha.8 → 0.27.0-alpha.9

package/lib/index.d.ts

@@ -448,6 +448,33 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
  * @since v0.27.0
  */
 
+/**
+ * Rendering control options
+ * @since v0.27.0
+ */
+interface RenderingOptions<G extends GunshiParamsConstraint = DefaultGunshiParams> {
+  /**
+   * Header rendering configuration
+   * - `null`: Disable rendering
+   * - `function`: Use custom renderer
+   * - `undefined` (when omitted): Use default renderer
+   */
+  header?: ((ctx: Readonly<CommandContext<G>>) => Promise<string>) | null;
+  /**
+   * Usage rendering configuration
+   * - `null`: Disable rendering
+   * - `function`: Use custom renderer
+   * - `undefined` (when omitted): Use default renderer
+   */
+  usage?: ((ctx: Readonly<CommandContext<G>>) => Promise<string>) | null;
+  /**
+   * Validation errors rendering configuration
+   * - `null`: Disable rendering
+   * - `function`: Use custom renderer
+   * - `undefined` (when omitted): Use default renderer
+   */
+  validationErrors?: ((ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>) | null;
+}
 /**
  * Command interface.
  */
@@ -494,6 +521,11 @@ interface Command<G extends GunshiParamsConstraint = DefaultGunshiParams> {
    * @since v0.27.0
    */
   entry?: boolean;
+  /**
+   * Rendering control options
+   * @since v0.27.0
+   */
+  rendering?: RenderingOptions<G>;
 }
 /**
  * Lazy command interface.
@@ -603,37 +635,88 @@ type CommandBuiltinArgsKeys = keyof (typeof constants_d_exports)['COMMON_ARGS'];
  */
 type CommandBuiltinResourceKeys = (typeof constants_d_exports)['COMMAND_BUILTIN_RESOURCE_KEYS'][number];
 /**
- * i18n built-in resource keys.
+ * Built-in resource keys.
  */
 type BuiltinResourceKeys = CommandBuiltinArgsKeys | CommandBuiltinResourceKeys;
 /**
- * Command i18n built-in keys.
- * The command i18n built-in keys are used by the i18n plugin for translation.
+ * Command built-in keys.
  */
-type CommandBuiltinKeys = GenerateNamespacedKey<BuiltinResourceKeys> | 'description' | 'examples';
+type CommandBuiltinKeys = GenerateNamespacedKey<BuiltinResourceKeys>;
 /**
  * Command i18n option keys.
  * The command i18n option keys are used by the i18n plugin for translation.
  */
-type CommandArgKeys<A extends Args> = GenerateNamespacedKey<KeyOfArgs<RemovedIndex<A>>, typeof ARG_PREFIX>;
+type CommandArgKeys<A extends Args, C = {}, K extends string = GenerateNamespacedKey<Extract<KeyOfArgs<RemovedIndex<A>>, string>, typeof ARG_PREFIX>> = C extends {
+  name: infer N;
+} ? (N extends string ? GenerateNamespacedKey<K, N> : K) : K;
+/**
+ * Resolve translation keys for command context.
+ */
+type ResolveTranslationKeys<A extends Args, C = {},
+// for CommandContext
+E extends Record<string, string> = {},
+// for extended resources
+R extends string = keyof RemovedIndex<E>, T extends string = (C extends {
+  name: infer N;
+} ? N extends string ? GenerateNamespacedKey<R, N> : R : R | CommandBuiltinKeys), O = CommandArgKeys<A, C>> = CommandBuiltinKeys | O | T;
 /**
  * Translation function interface
  */
-interface Translation<T extends string = CommandBuiltinKeys, G extends GunshiParams<any> = DefaultGunshiParams> {
-  <O = CommandArgKeys<G['args']>, K = CommandBuiltinKeys | O | T>(key: K, values?: Record<string, unknown>): string;
+interface Translation<A extends Args, C = {},
+// for CommandContext
+E extends Record<string, string> = {},
+// for extended resources
+K = ResolveTranslationKeys<A, C, E>> {
+  (key: K, values?: Record<string, unknown>): string;
 }
 //#endregion
-//#region src/localize.d.ts
-interface Localization<T extends string = CommandBuiltinKeys, G extends GunshiParams<any> = DefaultGunshiParams> {
-  <O = CommandArgKeys<G['args']>, K = CommandBuiltinKeys | O | T>(key: K, values?: Record<string, unknown>): Promise<string>;
+//#region src/localization.d.ts
+interface Localization<A extends Args, C = {},
+// for CommandContext
+E extends Record<string, string> = {}> {
+  <K = ResolveTranslationKeys<A, C, E>>(key: K, values?: Record<string, unknown>): string;
 }
-declare function localizable<T extends string = CommandBuiltinKeys>(ctx: CommandContext, cmd: Command, translate?: Translation<T>): Localization<T>;
+/**
+ * Create a localizable function for a command.
+ * This function will resolve the translation key based on the command context and the provided translation function.
+ * @param ctx Command context
+ * @param cmd Command
+ * @param translate Translation function
+ * @returns Localizable function
+ */
+declare function localizable<A extends Args, C = {},
+// for CommandContext
+E extends Record<string, string> = {},
+// for extended resources
+K = ResolveTranslationKeys<A, C, E>>(ctx: CommandContext, cmd: Command, translate?: Translation<A, C, E, K>): Localization<A, C, E>;
 //#endregion
 //#region src/utils.d.ts
+/**
+ * Resolve a namespaced key for built-in resources.
+ * Built-in keys are prefixed with "_:".
+ * @param key The built-in key to resolve.
+ * @returns Prefixed built-in key.
+ */
 declare function resolveBuiltInKey<K extends string = CommandBuiltinArgsKeys | CommandBuiltinResourceKeys>(key: K): GenerateNamespacedKey<K>;
-declare function resolveArgKey<A extends Args = DefaultGunshiParams['args'], K extends string = KeyOfArgs<RemovedIndex<A>>>(key: K): GenerateNamespacedKey<K, typeof ARG_PREFIX>;
+/**
+ * Resolve a namespaced key for argument resources.
+ * Argument keys are prefixed with "arg:".
+ * If the command name is provided, it will be prefixed with the command name (e.g. "cmd1:arg:foo").
+ * @param key The argument key to resolve.
+ * @param ctx The command context.
+ * @returns Prefixed argument key.
+ */
+declare function resolveArgKey<A extends Args = DefaultGunshiParams['args'], K extends string = KeyOfArgs<RemovedIndex<A>>>(key: K, ctx?: Readonly<CommandContext>): string;
+/**
+ * Resolve a namespaced key for non-built-in resources.
+ * Non-built-in keys are not prefixed with any special characters. If the command name is provided, it will be prefixed with the command name (e.g. "cmd1:foo").
+ * @param key The non-built-in key to resolve.
+ * @param ctx The command context.
+ * @returns Prefixed non-built-in key.
+ */
+declare function resolveKey<T extends Record<string, string> = {}, K = (keyof T extends string ? keyof T : string)>(key: K, ctx?: Readonly<CommandContext>): string;
 declare function resolveExamples<G extends GunshiParamsConstraint = DefaultGunshiParams>(ctx: Readonly<CommandContext<G>>, examples?: string | CommandExamplesFetcher<G>): Promise<string>;
 declare function namespacedId<K extends string>(id: K): GenerateNamespacedKey<K, typeof PLUGIN_PREFIX>;
 declare function makeShortLongOptionPair(schema: ArgSchema, name: string, toKebab?: boolean): string;
 //#endregion
-export { ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, BuiltinResourceKeys, COMMAND_BUILTIN_RESOURCE_KEYS, COMMON_ARGS, CommandArgKeys, CommandBuiltinArgsKeys, CommandBuiltinKeys, CommandBuiltinResourceKeys, en_US_default as DefaultResource, GenerateNamespacedKey, KeyOfArgs, Localization, PLUGIN_PREFIX, RemovedIndex, Translation, create, deepFreeze, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveExamples, resolveLazyCommand };
+export { ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, BuiltinResourceKeys, COMMAND_BUILTIN_RESOURCE_KEYS, COMMON_ARGS, CommandArgKeys, CommandBuiltinArgsKeys, CommandBuiltinKeys, CommandBuiltinResourceKeys, en_US_default as DefaultResource, GenerateNamespacedKey, KeyOfArgs, Localization, PLUGIN_PREFIX, RemovedIndex, ResolveTranslationKeys, Translation, create, deepFreeze, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveExamples, resolveKey, resolveLazyCommand };

package/lib/index.js

@@ -139,11 +139,35 @@ var en_US_default = {
 
 //#endregion
 //#region src/utils.ts
+/**
+* Resolve a namespaced key for built-in resources.
+* Built-in keys are prefixed with "_:".
+* @param key The built-in key to resolve.
+* @returns Prefixed built-in key.
+*/
 function resolveBuiltInKey(key) {
 	return `${BUILT_IN_PREFIX}${BUILT_IN_KEY_SEPARATOR}${key}`;
 }
-function resolveArgKey(key) {
-	return `${ARG_PREFIX}${BUILT_IN_KEY_SEPARATOR}${key}`;
+/**
+* Resolve a namespaced key for argument resources.
+* Argument keys are prefixed with "arg:".
+* If the command name is provided, it will be prefixed with the command name (e.g. "cmd1:arg:foo").
+* @param key The argument key to resolve.
+* @param ctx The command context.
+* @returns Prefixed argument key.
+*/
+function resolveArgKey(key, ctx) {
+	return `${ctx?.name ? `${ctx.name}${BUILT_IN_KEY_SEPARATOR}` : ""}${ARG_PREFIX}${BUILT_IN_KEY_SEPARATOR}${key}`;
+}
+/**
+* Resolve a namespaced key for non-built-in resources.
+* Non-built-in keys are not prefixed with any special characters. If the command name is provided, it will be prefixed with the command name (e.g. "cmd1:foo").
+* @param key The non-built-in key to resolve.
+* @param ctx The command context.
+* @returns Prefixed non-built-in key.
+*/
+function resolveKey(key, ctx) {
+	return `${ctx?.name ? `${ctx.name}${BUILT_IN_KEY_SEPARATOR}` : ""}${key}`;
 }
 async function resolveExamples(ctx, examples) {
 	return typeof examples === "string" ? examples : typeof examples === "function" ? await examples(ctx) : "";
@@ -159,15 +183,25 @@ function makeShortLongOptionPair(schema, name, toKebab) {
 }
 
 //#endregion
-//#region src/localize.ts
+//#region src/localization.ts
+/**
+* Create a localizable function for a command.
+* This function will resolve the translation key based on the command context and the provided translation function.
+* @param ctx Command context
+* @param cmd Command
+* @param translate Translation function
+* @returns Localizable function
+*/
 function localizable(ctx, cmd, translate) {
 	async function localize(key, values) {
 		if (translate) return translate(key, values);
-		else if (key.startsWith(BUILD_IN_PREFIX_AND_KEY_SEPARATOR)) {
+		if (key.startsWith(BUILD_IN_PREFIX_AND_KEY_SEPARATOR)) {
 			const resKey = key.slice(BUILD_IN_PREFIX_AND_KEY_SEPARATOR.length);
 			return en_US_default[resKey] || key;
-		} else if (key.startsWith(ARG_PREFIX_AND_KEY_SEPARATOR)) {
-			let argKey = key.slice(ARG_PREFIX_AND_KEY_SEPARATOR.length);
+		}
+		const namaspacedArgKey = resolveKey(ARG_PREFIX_AND_KEY_SEPARATOR, ctx);
+		if (key.startsWith(namaspacedArgKey)) {
+			let argKey = key.slice(namaspacedArgKey.length);
 			let negatable = false;
 			if (argKey.startsWith(ARG_NEGATABLE_PREFIX)) {
 				argKey = argKey.slice(ARG_NEGATABLE_PREFIX.length);
@@ -176,12 +210,13 @@ function localizable(ctx, cmd, translate) {
 			const schema = ctx.args[argKey];
 			if (!schema) return argKey;
 			return negatable && schema.type === "boolean" && schema.negatable ? `${en_US_default["NEGATABLE"]} ${makeShortLongOptionPair(schema, argKey, ctx.toKebab)}` : schema.description || "";
-		} else if (key === "description") return "";
-		else if (key === "examples") return await resolveExamples(ctx, cmd.examples);
+		}
+		if (key === resolveKey("description", ctx)) return "";
+		else if (key === resolveKey("examples", ctx)) return await resolveExamples(ctx, cmd.examples);
 		else return key;
 	}
 	return localize;
 }
 
 //#endregion
-export { ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, COMMAND_BUILTIN_RESOURCE_KEYS, COMMON_ARGS, en_US_default as DefaultResource, PLUGIN_PREFIX, create, deepFreeze, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveExamples, resolveLazyCommand };
+export { ARG_NEGATABLE_PREFIX, ARG_PREFIX, ARG_PREFIX_AND_KEY_SEPARATOR, BUILD_IN_PREFIX_AND_KEY_SEPARATOR, BUILT_IN_KEY_SEPARATOR, BUILT_IN_PREFIX, COMMAND_BUILTIN_RESOURCE_KEYS, COMMON_ARGS, en_US_default as DefaultResource, PLUGIN_PREFIX, create, deepFreeze, isLazyCommand, kebabnize, localizable, log, makeShortLongOptionPair, namespacedId, resolveArgKey, resolveBuiltInKey, resolveExamples, resolveKey, resolveLazyCommand };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/shared",
   "description": "shared utils for gunshi",
-  "version": "0.27.0-alpha.8",
+  "version": "0.27.0-alpha.9",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -50,13 +50,13 @@
     }
   },
   "devDependencies": {
-    "deno": "^2.4.0",
+    "deno": "^2.4.2",
     "jsr": "^0.13.5",
     "jsr-exports-lint": "^0.4.1",
     "publint": "^0.3.12",
-    "tsdown": "^0.12.9",
-    "@gunshi/resources": "0.27.0-alpha.8",
-    "gunshi": "0.27.0-alpha.8"
+    "tsdown": "^0.13.0",
+    "@gunshi/resources": "0.27.0-alpha.9",
+    "gunshi": "0.27.0-alpha.9"
   },
   "scripts": {
     "build": "tsdown",