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

package/lib/index.d.ts

@@ -278,12 +278,12 @@ type PluginFunction<G extends GunshiParams = DefaultGunshiParams> = (ctx: Readon
  * Plugin extension for CommandContext
  * @since v0.27.0
  */
-type PluginExtension<T = Record<string, unknown>, G extends GunshiParams = DefaultGunshiParams> = (ctx: CommandContextCore<G>, cmd: Command<G>) => T;
+type PluginExtension<T = Record<string, unknown>, G extends GunshiParams = DefaultGunshiParams> = (ctx: CommandContextCore<G>, cmd: Command<G>) => Awaitable<T>;
 /**
  * Plugin extension callback type
  * @since v0.27.0
  */
-type OnPluginExtension<G extends GunshiParams = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>, cmd: Readonly<Command<G>>) => void;
+type OnPluginExtension<G extends GunshiParams = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>, cmd: Readonly<Command<G>>) => Awaitable<void>;
 /**
  * Plugin definition options
  * @since v0.27.0
@@ -357,14 +357,14 @@ declare function plugin<I extends string, P extends PluginExtension<any, Default
   dependencies?: (PluginDependency | string)[];
   setup?: (ctx: Readonly<PluginContext<GunshiParams<{
     args: Args;
-    extensions: { [K in I]: ReturnType<P> };
+    extensions: { [K in I]: Awaited<ReturnType<P>> };
   }>>>) => Awaitable<void>;
   extension: P;
   onExtension?: OnPluginExtension<{
     args: Args;
-    extensions: { [K in I]: ReturnType<P> };
+    extensions: { [K in I]: Awaited<ReturnType<P>> };
   }>;
-}): PluginWithExtension<ReturnType<P>>;
+}): PluginWithExtension<Awaited<ReturnType<P>>>;
 /**
  * Define a plugin without extension capabilities
  * @param options - {@link PluginOptions | plugin options} without extension
@@ -376,6 +376,7 @@ declare function plugin(options: {
   name?: string;
   dependencies?: (PluginDependency | string)[];
   setup?: (ctx: Readonly<PluginContext<DefaultGunshiParams>>) => Awaitable<void>;
+  onExtension?: OnPluginExtension<DefaultGunshiParams>;
 }): PluginWithoutExtension<DefaultGunshiParams['extensions']>;
 //#endregion
 //#region ../gunshi/src/types.d.ts
@@ -732,6 +733,33 @@ interface CommandContextExtension<E extends GunshiParams['extensions'] = Default
   readonly factory: (ctx: CommandContextCore, cmd: Command) => Awaitable<E>;
   readonly onFactory?: (ctx: Readonly<CommandContext>, cmd: Readonly<Command>) => Awaitable<void>;
 }
+/**
+ * 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.
  */
@@ -778,6 +806,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.
@@ -845,6 +878,7 @@ type RendererDecorator<T, G extends GunshiParamsConstraint = DefaultGunshiParams
 type ValidationErrorsDecorator<G extends GunshiParamsConstraint = DefaultGunshiParams> = (baseRenderer: (ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>, ctx: Readonly<CommandContext<G>>, error: AggregateError) => Promise<string>;
 //#endregion
 //#region ../gunshi/src/constants.d.ts
+declare const ANONYMOUS_COMMAND_NAME = "(anonymous)";
 declare const CLI_OPTIONS_DEFAULT: CliOptions<DefaultGunshiParams>;
 //#endregion
 //#region ../gunshi/src/context.d.ts
@@ -936,4 +970,4 @@ declare function createCommandContext<G extends GunshiParamsConstraint = Default
   extensions: ExtractExtensions<E>;
 }>>>>;
 //#endregion
-export { ArgSchema, ArgToken, ArgValues, Args, Awaitable, CLI_OPTIONS_DEFAULT, Command, CommandContext, CommandContextCore, CommandDecorator, CommandExamplesFetcher, CommandRunner, DefaultGunshiParams, ExtendContext, ExtractArgs, GunshiParams, GunshiParamsConstraint, LazyCommand, NormalizeToGunshiParams, OnPluginExtension, Plugin, PluginContext, PluginDependency, PluginExtension, PluginFunction, PluginOptions, PluginWithExtension, PluginWithoutExtension, RendererDecorator, ValidationErrorsDecorator, createCommandContext, plugin };
+export { ANONYMOUS_COMMAND_NAME, type ArgSchema, type ArgToken, type ArgValues, type Args, Awaitable, CLI_OPTIONS_DEFAULT, Command, CommandContext, CommandContextCore, CommandContextExtension, CommandDecorator, CommandExamplesFetcher, CommandRunner, DefaultGunshiParams, ExtendContext, ExtractArgs, GunshiParams, GunshiParamsConstraint, LazyCommand, NormalizeToGunshiParams, OnPluginExtension, Plugin, PluginContext, PluginDependency, PluginExtension, PluginFunction, PluginOptions, PluginWithExtension, PluginWithoutExtension, RendererDecorator, ValidationErrorsDecorator, createCommandContext, plugin };

package/lib/index.js

@@ -59,6 +59,15 @@ async function createCommandContext({ args, explicit, values, positionals, rest,
 	*/
 	const env = Object.assign(create(), CLI_OPTIONS_DEFAULT, cliOptions);
 	/**
+	* apply Command definition's rendering option with highest priority
+	*/
+	if (command.rendering) {
+		const { header, usage, validationErrors } = command.rendering;
+		if (header !== void 0) env.renderHeader = header;
+		if (usage !== void 0) env.renderUsage = usage;
+		if (validationErrors !== void 0) env.renderValidationErrors = validationErrors;
+	}
+	/**
 	* create the command context
 	*/
 	const core = Object.assign(create(), {
@@ -105,6 +114,9 @@ function getCommandName(cmd) {
 
 //#endregion
 //#region ../gunshi/src/plugin/core.ts
+const NOOP_EXTENSION = () => {
+	return Object.create(null);
+};
 /**
 * Define a plugin
 * @param options - {@link PluginOptions | plugin options}
@@ -112,7 +124,8 @@ function getCommandName(cmd) {
 * @since v0.27.0
 */
 function plugin(options) {
-	const { id, name, setup, extension, onExtension, dependencies } = options;
+	const { id, name, setup, onExtension, dependencies } = options;
+	const extension = options.extension || NOOP_EXTENSION;
 	const pluginFn = async (ctx) => {
 		if (setup) await setup(ctx);
 	};
@@ -149,4 +162,4 @@ function plugin(options) {
 }
 
 //#endregion
-export { CLI_OPTIONS_DEFAULT, createCommandContext, plugin };
+export { ANONYMOUS_COMMAND_NAME, CLI_OPTIONS_DEFAULT, createCommandContext, plugin };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/plugin",
   "description": "utilities for gunshi plugin",
-  "version": "0.27.0-alpha.8",
+  "version": "0.27.0-alpha.9",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -51,12 +51,12 @@
     }
   },
   "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": "0.27.0-alpha.8"
+    "tsdown": "^0.13.0",
+    "gunshi": "0.27.0-alpha.9"
   },
   "scripts": {
     "build": "tsdown",