@gunshi/definition 0.32.0 → 0.34.0

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.25.0/node_modules/args-tokens/lib/parser-D95CJBHr.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.26.1/node_modules/args-tokens/lib/parser-DT7Ztcch.d.ts
 //#region src/parser.d.ts
 /**
  * Entry point of argument parser.
@@ -55,7 +55,7 @@ interface ArgToken {
  * Parser Options.
  */
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.25.0/node_modules/args-tokens/lib/resolver.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.26.1/node_modules/args-tokens/lib/resolver.d.ts
 //#region src/resolver.d.ts
 /**
  * An argument schema definition for command-line argument parsing.
@@ -172,7 +172,10 @@ interface ArgSchema {
    * When `true`, the argument must be provided by the user.
    * If missing, an `ArgResolveError` with type 'required' will be thrown.
    *
-   * Note: Only `true` is allowed (not `false`) to make intent explicit.
+   * For single-value positional arguments, omitting `required` keeps the argument
+   * required for compatibility. Set `required: false` to make a positional argument
+   * optional. Optional positional arguments leave enough input values for later
+   * required positional arguments before consuming a value.
    *
    * @example
    * Required arguments:
@@ -196,7 +199,8 @@ interface ArgSchema {
    *
    * When `true`, the resolved value becomes an array.
    * For options: can be specified multiple times (--tag foo --tag bar)
-   * For positional: collects remaining positional arguments
+   * For positional: collects remaining positional arguments after preserving values for
+   * later required positional arguments.
    *
    * Note: Only `true` is allowed (not `false`) to make intent explicit.
    *
@@ -276,7 +280,11 @@ interface ArgSchema {
    * - `boolean` type: boolean default
    * - `number` type: number default
    * - `enum` type: must be one of the `choices` values
-   * - `positional`/`custom` type: any appropriate default
+   * - `positional`/`custom` type: string, boolean, or number default
+   *
+   * For single-value positional arguments, the default is used when the positional
+   * value is missing or when the value is preserved for later required positional
+   * arguments, unless `required: true` is set.
    *
    * @example
    * Default values by type:
@@ -533,7 +541,8 @@ type FilterArgs<A extends Args, V extends Record<keyof A, unknown>, K extends ke
  *
  * @internal
  */
-type FilterPositionalArgs<A extends Args, V extends Record<keyof A, unknown>> = { [Arg in keyof A as A[Arg]['type'] extends 'positional' ? Arg : never]: V[Arg] };
+type FilterPositionalArgs<A extends Args, V extends Record<keyof A, unknown>> = { [Arg in keyof A as IsRequiredPositionalArg<A[Arg]> extends true ? Arg : never]: V[Arg] };
+type IsRequiredPositionalArg<A extends ArgSchema> = A['type'] extends 'positional' ? A['multiple'] extends true ? A['required'] extends true ? true : false : A['required'] extends false ? A['default'] extends {} ? true : false : true : false;
 /**
  * An arguments for {@link resolveArgs | resolve arguments}.
  */
@@ -581,15 +590,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$1<G> & L;
-};
 /**
  * Gunshi plugin context interface.
  *
@@ -638,7 +638,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 +646,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 +654,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 +664,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
@@ -798,9 +798,46 @@ type ExtractArgExplicitlyProvided<G> = ArgExplicitlyProvided<ExtractArgs<G>>;
  *
  * @internal
  */
-type ExtractExtensions$1<G> = G extends GunshiParams<any> ? G['extensions'] : G extends {
+type ExtractExtensions<G> = G extends GunshiParams<any> ? G['extensions'] : G extends {
   extensions: infer E;
 } ? E : {};
+/**
+ * Type helper to normalize G to GunshiParams
+ *
+ * @internal
+ */
+type NormalizeToGunshiParams<G> = G extends GunshiParams<any> ? G : G extends {
+  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: 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.
  *
@@ -1106,7 +1143,7 @@ interface CommandContext<G extends GunshiParamsConstraint = DefaultGunshiParams>
    *
    * @since v0.27.0
    */
-  extensions: keyof ExtractExtensions$1<G> extends never ? any : ExtractExtensions$1<G>;
+  extensions: keyof ExtractExtensions<G> extends never ? any : ExtractExtensions<G>;
   /**
    * Validation error from argument parsing.
    * This will be set if argument validation fails during CLI execution.
@@ -1114,7 +1151,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.
  *
@@ -1355,7 +1392,16 @@ type CommandLoader<G extends GunshiParamsConstraint = DefaultGunshiParams> = ()
  *
  * @internal
  */
-type ExtractExtensions<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}
  */
@@ -1442,24 +1488,27 @@ declare function createCommandContext<G extends GunshiParamsConstraint = Default
   commandPath,
   omitted,
   validationError
-}: CommandContextParams<G, V, C, E>): Promise<{} extends ExtractExtensions<E> ? Readonly<CommandContext<G>> : Readonly<CommandContext<GunshiParams<{
-  args: ExtractArgs<G>;
-  extensions: ExtractExtensions<E>;
-}>>>>;
+}: CommandContextParams<G, V, C, E>): Promise<CommandContextResult<G, E>>;
 //#endregion
 //#region ../gunshi/src/definition.d.ts
 /**
- * Infer command properties excluding for {@link define} function
+ * The result type of the {@link define} function
  *
  * @internal
  */
-type InferCommandProps<G extends GunshiParamsConstraint = DefaultGunshiParams> = Pick<Command<G>, Exclude<keyof Command<G>, keyof Command<G>>>;
+type CommandDefinitionResult<G extends GunshiParamsConstraint = DefaultGunshiParams, C = {}> = Prettify<Pick<C, keyof C> & Partial<Pick<Command<G>, Exclude<keyof Command<G>, keyof C>>>>;
 /**
- * The result type of the {@link define} function
+ * The command definition accepted by {@link define} helpers.
  *
  * @internal
  */
-type CommandDefinitionResult<G extends GunshiParamsConstraint = DefaultGunshiParams, C extends Command<G> = Command<G>> = Prettify<Pick<C, keyof C> & Partial<Pick<Command<G>, Exclude<keyof Command<G>, keyof C>>>>;
+type CommandDefinition<A extends Args, E extends ExtendContext, C extends Partial<Command<{
+  args: A;
+  extensions: E;
+}>>> = C & Command<{
+  args: A;
+  extensions: E;
+}>;
 /**
  * Define a {@link Command | command}.
  *
@@ -1490,10 +1539,10 @@ type CommandDefinitionResult<G extends GunshiParamsConstraint = DefaultGunshiPar
  * @param definition - A {@link Command | command} definition
  * @returns A defined {@link Command | command}
  */
-declare function define<G extends GunshiParamsConstraint = DefaultGunshiParams, A extends Args = ExtractArgs<G>, C extends InferCommandProps<G> = InferCommandProps<G>>(definition: C & Command<{
+declare function define<G extends GunshiParamsConstraint = DefaultGunshiParams, A extends Args = ExtractArgs<G>, C extends Partial<Command<{
   args: A;
-  extensions: ExtractExtensions$1<G>;
-}>): CommandDefinitionResult<G, C>;
+  extensions: ExtractExtensions<G>;
+}>> = {}>(definition: CommandDefinition<A, ExtractExtensions<G>, C>): CommandDefinitionResult<G, C>;
 /**
  * Return type for defineWithTypes
  *
@@ -1504,10 +1553,7 @@ declare function define<G extends GunshiParamsConstraint = DefaultGunshiParams,
 type DefineWithTypesReturn<DefaultExtensions extends ExtendContext, DefaultArgs extends Args> = <A extends DefaultArgs = DefaultArgs, C extends Partial<Command<{
   args: A;
   extensions: DefaultExtensions;
-}>> = {}>(definition: C & Command<{
-  args: A;
-  extensions: DefaultExtensions;
-}>) => CommandDefinitionResult<{
+}>> = {}>(definition: CommandDefinition<A, DefaultExtensions, C>) => CommandDefinitionResult<{
   args: A;
   extensions: DefaultExtensions;
 }, C>;
@@ -1540,7 +1586,7 @@ type DefineWithTypesReturn<DefaultExtensions extends ExtendContext, DefaultArgs
  *
  * @since v0.27.0
  */
-declare function defineWithTypes<G extends GunshiParamsConstraint>(): DefineWithTypesReturn<ExtractExtensions$1<G>, ExtractArgs<G>>;
+declare function defineWithTypes<G extends GunshiParamsConstraint>(): DefineWithTypesReturn<ExtractExtensions<G>, ExtractArgs<G>>;
 /**
  * Define a {@link LazyCommand | lazy command}.
  *
@@ -1610,30 +1656,6 @@ declare function lazy<G extends GunshiParamsConstraint = DefaultGunshiParams, A
   args: A;
   extensions: {};
 }, D>;
-/**
- * Normalize G to a full GunshiParams type
- *
- * @typeParam G - A {@link GunshiParamsConstraint} type
- *
- * @internal
- */
-type NormalizeGunshiParams<G extends GunshiParamsConstraint> = G extends GunshiParams<any> ? G : G extends {
-  args: infer A;
-  extensions: infer E;
-} ? {
-  args: A;
-  extensions: E;
-} : G extends {
-  args: infer A;
-} ? {
-  args: A;
-  extensions: {};
-} : G extends {
-  extensions: infer E;
-} ? {
-  args: Args;
-  extensions: E;
-} : DefaultGunshiParams;
 /**
  * Return type for lazyWithTypes
  *
@@ -1676,7 +1698,7 @@ type LazyWithTypesReturn<FullG extends GunshiParamsConstraint> = <D extends Part
  *
  * @since v0.27.0
  */
-declare function lazyWithTypes<G extends GunshiParamsConstraint>(): LazyWithTypesReturn<NormalizeGunshiParams<G>>;
+declare function lazyWithTypes<G extends GunshiParamsConstraint>(): LazyWithTypesReturn<NormalizeToGunshiParams<G>>;
 //#endregion
 //#region src/index.d.ts
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/definition",
   "description": "utilities for gunshi command definition",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "author": {
     "name": "kazuya kawaguchi",
     "email": "kawakazu80@gmail.com"
@@ -57,7 +57,7 @@
     "jsr-exports-lint": "^0.4.2",
     "publint": "^0.3.20",
     "tsdown": "0.21.0",
-    "gunshi": "0.32.0"
+    "gunshi": "0.34.0"
   },
   "scripts": {
     "build": "tsdown",