@gunshi/plugin 0.32.0 → 0.33.0

package/lib/index.d.ts

@@ -581,15 +581,6 @@ type ArgExplicitlyProvided<A extends Args> = { [K in keyof A]: boolean };
  */
 //#endregion
 //#region ../gunshi/src/plugin/context.d.ts
-/**
- * Type helper to create GunshiParams from extracted args and extensions
- *
- * @internal
- */
-type ExtractedParams<G extends GunshiParamsConstraint, L extends Record<string, unknown> = {}> = {
-  args: ExtractArgs<G>;
-  extensions: ExtractExtensions<G> & L;
-};
 /**
  * Gunshi plugin context interface.
  *
@@ -638,7 +629,7 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
    *
    * @param decorator - A decorator function that wraps the base header renderer.
    */
-  decorateHeaderRenderer<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRenderer: (ctx: Readonly<CommandContext<ExtractedParams<G, L>>>) => Promise<string>, ctx: Readonly<CommandContext<ExtractedParams<G, L>>>) => Promise<string>): void;
+  decorateHeaderRenderer<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRenderer: (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Promise<string>, ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Promise<string>): void;
   /**
    * Decorate the usage renderer.
    *
@@ -646,7 +637,7 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
    *
    * @param decorator - A decorator function that wraps the base usage renderer.
    */
-  decorateUsageRenderer<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRenderer: (ctx: Readonly<CommandContext<ExtractedParams<G, L>>>) => Promise<string>, ctx: Readonly<CommandContext<ExtractedParams<G, L>>>) => Promise<string>): void;
+  decorateUsageRenderer<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRenderer: (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Promise<string>, ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Promise<string>): void;
   /**
    * Decorate the validation errors renderer.
    *
@@ -654,7 +645,7 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
    *
    * @param decorator - A decorator function that wraps the base validation errors renderer.
    */
-  decorateValidationErrorsRenderer<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRenderer: (ctx: Readonly<CommandContext<ExtractedParams<G, L>>>, error: AggregateError) => Promise<string>, ctx: Readonly<CommandContext<ExtractedParams<G, L>>>, error: AggregateError) => Promise<string>): void;
+  decorateValidationErrorsRenderer<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRenderer: (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>, error: AggregateError) => Promise<string>, ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>, error: AggregateError) => Promise<string>): void;
   /**
    * Decorate the command execution.
    *
@@ -664,7 +655,7 @@ interface PluginContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
    *
    * @param decorator - A decorator function that wraps the command runner
    */
-  decorateCommand<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRunner: (ctx: Readonly<CommandContext<ExtractedParams<G, L>>>) => Awaitable<void | string>) => (ctx: Readonly<CommandContext<ExtractedParams<G, L>>>) => Awaitable<void | string>): void;
+  decorateCommand<L extends Record<string, unknown> = DefaultGunshiParams['extensions']>(decorator: (baseRunner: (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Awaitable<void | string>) => (ctx: Readonly<CommandContext<MergeGunshiExtensions<G, L>>>) => Awaitable<void | string>): void;
 }
 //#endregion
 //#region ../gunshi/src/plugin/core.d.ts
@@ -730,6 +721,36 @@ type PluginExtension<T = Record<string, unknown>, G extends GunshiParams = Defau
 type OnPluginExtension<G extends GunshiParams = DefaultGunshiParams> = (ctx: Readonly<CommandContext<G>>, cmd: Readonly<Command<G>>) => Awaitable<void>;
 type IsStringLiteral<S extends string> = string extends S ? false : true;
 type MergeExtension<Id, ResolvedDepExt extends ExtendContext, PluginExt extends ExtendContext> = Id extends infer I ? I extends string ? IsStringLiteral<I> extends true ? ResolvedDepExt & { [K in I]: PluginExt } : ResolvedDepExt : ResolvedDepExt : ResolvedDepExt;
+/**
+ * Extensions resolved from the declared plugin dependencies.
+ *
+ * @internal
+ */
+type DependencyExtensions<Deps extends ReadonlyArray<PluginDependency | string>, Context extends ExtendContext> = InferDependencyExtensions<Deps, Context>;
+/**
+ * Gunshi params available while a plugin extension resolves its dependencies.
+ *
+ * @internal
+ */
+type DependencyParams<Deps extends ReadonlyArray<PluginDependency | string>, Context extends ExtendContext> = GunshiParams<{
+  args: Args;
+  extensions: DependencyExtensions<Deps, Context>;
+}>;
+/**
+ * Extensions available after applying the current plugin extension.
+ *
+ * @internal
+ */
+type MergedPluginExtensions<Id extends string, Deps extends ReadonlyArray<PluginDependency | string>, Context extends ExtendContext, Ext extends ExtendContext> = MergeExtension<Id, DependencyExtensions<Deps, Context>, Ext>;
+/**
+ * Gunshi params available after applying the current plugin extension.
+ *
+ * @internal
+ */
+type MergedPluginParams<Id extends string, Deps extends ReadonlyArray<PluginDependency | string>, Context extends ExtendContext, Ext extends ExtendContext> = GunshiParams<{
+  args: Args;
+  extensions: MergedPluginExtensions<Id, Deps, Context, Ext>;
+}>;
 /**
  * Plugin definition options
  *
@@ -743,13 +764,7 @@ Deps extends ReadonlyArray<PluginDependency | string> = (PluginDependency | stri
 // for plugin dependencies
 Ext extends Record<string, unknown> = {},
 // for plugin extension type
-ResolvedDepExt extends GunshiParams = GunshiParams<{
-  args: Args;
-  extensions: InferDependencyExtensions<Deps, DepExt>;
-}>, PluginExt extends PluginExtension<Ext, ResolvedDepExt> = PluginExtension<Ext, ResolvedDepExt>, MergedExt extends GunshiParams = GunshiParams<{
-  args: Args;
-  extensions: MergeExtension<Id, InferDependencyExtensions<Deps, DepExt>, Awaited<ReturnType<PluginExt>>>;
-}>> {
+ResolvedDepExt extends GunshiParams = DependencyParams<Deps, DepExt>, PluginExt extends PluginExtension<Ext, ResolvedDepExt> = PluginExtension<Ext, ResolvedDepExt>, MergedExt extends GunshiParams = MergedPluginParams<Id, Deps, DepExt, Awaited<ReturnType<PluginExt>>>> {
   /**
    * Plugin unique identifier
    */
@@ -858,20 +873,11 @@ Deps extends ReadonlyArray<PluginDependency | string> = [],
 // for plugin dependencies
 Extension extends {} = {},
 // for plugin extension type
-ResolvedDepExtensions extends GunshiParams = GunshiParams<{
-  args: Args;
-  extensions: InferDependencyExtensions<Deps, Context>;
-}>, PluginExt extends PluginExtension<Extension, DefaultGunshiParams> = PluginExtension<Extension, ResolvedDepExtensions>, MergedExtensions extends GunshiParams = GunshiParams<{
-  args: Args;
-  extensions: MergeExtension<Id, InferDependencyExtensions<Deps, Context>, Awaited<ReturnType<PluginExt>>>;
-}>>(options: {
+ResolvedDepExtensions extends GunshiParams = DependencyParams<Deps, Context>, PluginExt extends PluginExtension<Extension, DefaultGunshiParams> = PluginExtension<Extension, ResolvedDepExtensions>, MergedExtensions extends GunshiParams = MergedPluginParams<Id, Deps, Context, Awaited<ReturnType<PluginExt>>>>(options: {
   id: Id;
   name?: string;
   dependencies?: Deps;
-  setup?: (ctx: Readonly<PluginContext<GunshiParams<{
-    args: Args;
-    extensions: MergeExtension<Id, InferDependencyExtensions<Deps, Context>, Awaited<ReturnType<PluginExt>>>;
-  }>>>) => Awaitable<void>;
+  setup?: (ctx: Readonly<PluginContext<MergedPluginParams<Id, Deps, Context, Awaited<ReturnType<PluginExt>>>>>) => Awaitable<void>;
   extension: PluginExt;
   onExtension?: OnPluginExtension<MergedExtensions>;
 }): PluginWithExtension<Awaited<ReturnType<PluginExt>>>;
@@ -896,20 +902,11 @@ Deps extends ReadonlyArray<PluginDependency | string> = [],
 // for plugin dependencies
 Extension extends Record<string, unknown> = {},
 // for plugin extension type
-ResolvedDepExtensions extends GunshiParams = GunshiParams<{
-  args: Args;
-  extensions: InferDependencyExtensions<Deps, Context>;
-}>, PluginExt extends PluginExtension<Extension, DefaultGunshiParams> = PluginExtension<Extension, ResolvedDepExtensions>, MergedExtensions extends GunshiParams = GunshiParams<{
-  args: Args;
-  extensions: MergeExtension<Id, InferDependencyExtensions<Deps, Context>, Awaited<ReturnType<PluginExt>>>;
-}>>(options: {
+ResolvedDepExtensions extends GunshiParams = DependencyParams<Deps, Context>, PluginExt extends PluginExtension<Extension, DefaultGunshiParams> = PluginExtension<Extension, ResolvedDepExtensions>, MergedExtensions extends GunshiParams = MergedPluginParams<Id, Deps, Context, Awaited<ReturnType<PluginExt>>>>(options: {
   id: Id;
   name?: string;
   dependencies?: Deps;
-  setup?: (ctx: Readonly<PluginContext<GunshiParams<{
-    args: Args;
-    extensions: MergeExtension<Id, InferDependencyExtensions<Deps, Context>, Awaited<ReturnType<PluginExt>>>;
-  }>>>) => Awaitable<void>;
+  setup?: (ctx: Readonly<PluginContext<MergedPluginParams<Id, Deps, Context, Awaited<ReturnType<PluginExt>>>>>) => Awaitable<void>;
   onExtension?: OnPluginExtension<MergedExtensions>;
 }): PluginWithoutExtension<DefaultGunshiParams['extensions']>;
 //#endregion
@@ -1011,11 +1008,37 @@ type ExtractExtensions<G> = G extends GunshiParams<any> ? G['extensions'] : G ex
  * @internal
  */
 type NormalizeToGunshiParams<G> = G extends GunshiParams<any> ? G : G extends {
-  extensions: ExtendContext;
+  args: infer A extends Args;
+  extensions: infer E extends ExtendContext;
+} ? GunshiParams<{
+  args: A;
+  extensions: E;
+}> : G extends {
+  args: infer A extends Args;
+} ? GunshiParams<{
+  args: A;
+  extensions: {};
+}> : G extends {
+  extensions: infer E extends ExtendContext;
 } ? GunshiParams<{
   args: Args;
-  extensions: G['extensions'];
+  extensions: E;
 }> : DefaultGunshiParams;
+/**
+ * Type helper to merge command context extensions into G
+ *
+ * @internal
+ */
+type MergeGunshiExtensions<G extends GunshiParamsConstraint, E extends ExtendContext> = GunshiParams<{
+  /**
+   * Command argument definitions.
+   */
+  args: ExtractArgs<G>;
+  /**
+   * Merged command context extensions.
+   */
+  extensions: ExtractExtensions<G> & E;
+}>;
 /**
  * Command environment.
  *
@@ -1329,7 +1352,7 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
   validationError?: AggregateError;
 }
 /**
- * CommandContextCore type (base type without extensions)
+ * Readonly command context available to a command context extension factory.
  *
  * @typeParam G - A type extending {@linkcode GunshiParams} to specify the shape of command context.
  *
@@ -1605,7 +1628,16 @@ declare const CLI_OPTIONS_DEFAULT: CliOptions<DefaultGunshiParams>;
  *
  * @internal
  */
-type ExtractExtensions$1<E extends Record<string, CommandContextExtension>> = { [K in keyof E]: E[K] extends CommandContextExtension<infer T> ? T : never };
+type ExtractExtensionValues<E extends Record<string, CommandContextExtension>> = { [K in keyof E]: E[K] extends CommandContextExtension<infer T> ? T : never };
+/**
+ * Return type of {@link createCommandContext}
+ *
+ * @internal
+ */
+type CommandContextResult<G extends GunshiParamsConstraint, E extends Record<string, CommandContextExtension>> = {} extends ExtractExtensionValues<E> ? Readonly<CommandContext<G>> : Readonly<CommandContext<GunshiParams<{
+  args: ExtractArgs<G>;
+  extensions: ExtractExtensionValues<E>;
+}>>>;
 /**
  * Parameters of {@link createCommandContext}
  */
@@ -1692,10 +1724,7 @@ declare function createCommandContext<G extends GunshiParamsConstraint = Default
   commandPath,
   omitted,
   validationError
-}: CommandContextParams<G, V, C, E>): Promise<{} extends ExtractExtensions$1<E> ? Readonly<CommandContext<G>> : Readonly<CommandContext<GunshiParams<{
-  args: ExtractArgs<G>;
-  extensions: ExtractExtensions$1<E>;
-}>>>>;
+}: CommandContextParams<G, V, C, E>): Promise<CommandContextResult<G, E>>;
 //#endregion
 //#region src/index.d.ts
 /**
@@ -1704,4 +1733,4 @@ declare function createCommandContext<G extends GunshiParamsConstraint = Default
 */
 
 //#endregion
-export { ANONYMOUS_COMMAND_NAME, type ArgSchema, type ArgToken, type ArgValues, type Args, Awaitable, CLI_OPTIONS_DEFAULT, Command, CommandContext, CommandContextCore, CommandContextExtension, CommandContextParams, CommandDecorator, CommandExamplesFetcher, CommandRunner, DefaultGunshiParams, ExtendContext, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, LazyCommand, NormalizeToGunshiParams, OnPluginExtension, Plugin, PluginContext, PluginDependency, PluginExtension, PluginFunction, PluginOptions, PluginWithExtension, PluginWithoutExtension, Prettify, RendererDecorator, ValidationErrorsDecorator, createCommandContext, plugin };
+export { ANONYMOUS_COMMAND_NAME, type ArgSchema, type ArgToken, type ArgValues, type Args, Awaitable, CLI_OPTIONS_DEFAULT, Command, CommandContext, CommandContextCore, CommandContextExtension, CommandContextParams, CommandDecorator, CommandExamplesFetcher, CommandRunner, DefaultGunshiParams, ExtendContext, ExtractArgs, ExtractExtensions, GunshiParams, GunshiParamsConstraint, LazyCommand, MergeGunshiExtensions, NormalizeToGunshiParams, OnPluginExtension, Plugin, PluginContext, PluginDependency, PluginExtension, PluginFunction, PluginOptions, PluginWithExtension, PluginWithoutExtension, Prettify, RendererDecorator, ValidationErrorsDecorator, createCommandContext, plugin };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/plugin",
   "description": "plugin development kit for gunshi",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -56,7 +56,7 @@
     "jsr-exports-lint": "^0.4.2",
     "publint": "^0.3.20",
     "tsdown": "0.21.0",
-    "gunshi": "0.32.0"
+    "gunshi": "0.33.0"
   },
   "scripts": {
     "build": "tsdown",