@gunshi/definition 0.33.0 → 0.35.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.27.0/node_modules/args-tokens/lib/parser-DT7Ztcch.d.ts
 //#region src/parser.d.ts
 /**
  * Entry point of argument parser.
@@ -55,13 +55,13 @@ 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.27.0/node_modules/args-tokens/lib/resolver.d.ts
 //#region src/resolver.d.ts
 /**
  * An argument schema definition for command-line argument parsing.
  *
  * This schema is similar to the schema of Node.js `util.parseArgs` but with extended features:
- * - Additional `required` and `description` properties
+ * - Additional `required`, `description`, and `hidden` properties
  * - Extended `type` support: 'string', 'boolean', 'number', 'enum', 'positional', 'custom'
  * - Simplified `default` property (single type, not union types)
  *
@@ -166,13 +166,35 @@ interface ArgSchema {
    * ```
    */
   description?: string;
+  /**
+   * Hide the argument from generated help or usage output.
+   *
+   * This is metadata for renderers. It does not affect parsing, validation,
+   * required checks, defaults, conflicts, or resolved values.
+   *
+   * @example
+   * Hidden compatibility option:
+   * ```ts
+   * {
+   *   legacy: {
+   *     type: 'string',
+   *     hidden: true,
+   *     description: 'Deprecated compatibility option'
+   *   }
+   * }
+   * ```
+   */
+  hidden?: boolean;
   /**
    * Marks the argument as required.
    *
    * 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 +218,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 +299,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 +560,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}.
  */
@@ -1551,7 +1579,7 @@ type DefineWithTypesReturn<DefaultExtensions extends ExtendContext, DefaultArgs
 /**
  * Define a {@link Command | command} with types
  *
- * This helper function allows specifying the type parameter of {@link GunshiParams}
+ * This helper function allows specifying the type parameter of {@link GunshiParamsConstraint}
  * while inferring the {@link Args} type, {@link ExtendContext} type from the definition.
  *
  * @example
@@ -1571,7 +1599,7 @@ type DefineWithTypesReturn<DefaultExtensions extends ExtendContext, DefaultArgs
  * })
  * ```
  *
- * @typeParam G - A {@link GunshiParams} type
+ * @typeParam G - A {@link GunshiParamsConstraint} type
  *
  * @returns A function that takes a command definition via {@link define}
  *
@@ -1627,30 +1655,39 @@ declare function lazy<A extends Args>(loader: CommandLoader<{
  * }, testDefinition)
  * ```
  *
- * @typeParam A - An {@link Args} type
- * @typeParam D - A partial {@link Command} definition type
+ * @typeParam D - A partial {@link Command} definition type with required `args`
  *
  * @param loader - A {@link CommandLoader | command loader} function that returns a command definition
- * @param definition - An optional {@link Command | command} definition
+ * @param definition - A {@link Command | command} definition
  * @returns A {@link LazyCommand | lazy command} that can be executed later
  */
-declare function lazy<G extends GunshiParamsConstraint = DefaultGunshiParams, A extends ExtractArgs<G> = ExtractArgs<G>, D extends Partial<Command<{
-  args: A;
-  extensions: {};
-}>> = Partial<Command<{
-  args: A;
+declare function lazy<D extends {
+  args: Args;
+} & Partial<Command<{
+  args: D['args'];
   extensions: {};
 }>>>(loader: CommandLoader<{
-  args: A;
+  args: D['args'];
   extensions: {};
 }>, definition: D): LazyCommand<{
-  args: A;
+  args: D['args'];
   extensions: {};
 }, D>;
+/**
+ * Define a {@link LazyCommand | lazy command} with explicit Gunshi parameters and optional definition.
+ *
+ * @typeParam G - A {@link GunshiParamsConstraint}
+ * @typeParam D - A partial {@link Command} definition type
+ *
+ * @param loader - A {@link CommandLoader | command loader} function that returns a command definition
+ * @param definition - An optional {@link Command | command} definition
+ * @returns A {@link LazyCommand | lazy command} that can be executed later
+ */
+declare function lazy<G extends GunshiParamsConstraint = DefaultGunshiParams, D extends Partial<Command<G>> = Partial<Command<G>>>(loader: CommandLoader<G>, definition?: D): LazyCommand<G, D>;
 /**
  * Return type for lazyWithTypes
  *
- * @typeParam FullG - The normalized {@link GunshiParams} type
+ * @typeParam FullG - The normalized {@link GunshiParamsConstraint} type
  *
  * @internal
  */
@@ -1658,7 +1695,7 @@ type LazyWithTypesReturn<FullG extends GunshiParamsConstraint> = <D extends Part
 /**
  * Define a {@link LazyCommand | lazy command} with specific type parameters.
  *
- * This helper function allows specifying the type parameter of {@link GunshiParams}
+ * This helper function allows specifying the type parameter of {@link GunshiParamsConstraint}
  * while inferring the {@link Args} type, {@link ExtendContext} type from the definition.
  *
  * @example
@@ -1683,7 +1720,7 @@ type LazyWithTypesReturn<FullG extends GunshiParamsConstraint> = <D extends Part
  * )
  * ```
  *
- * @typeParam G - A {@link GunshiParams} type
+ * @typeParam G - A {@link GunshiParamsConstraint} type
  *
  * @returns A function that takes a lazy command definition via {@link lazy}
  *

package/lib/index.js

@@ -181,7 +181,7 @@ function define(definition) {
 /**
 * Define a {@link Command | command} with types
 *
-* This helper function allows specifying the type parameter of {@link GunshiParams}
+* This helper function allows specifying the type parameter of {@link GunshiParamsConstraint}
 * while inferring the {@link Args} type, {@link ExtendContext} type from the definition.
 *
 * @example
@@ -201,7 +201,7 @@ function define(definition) {
 * })
 * ```
 *
-* @typeParam G - A {@link GunshiParams} type
+* @typeParam G - A {@link GunshiParamsConstraint} type
 *
 * @returns A function that takes a command definition via {@link define}
 *
@@ -237,7 +237,7 @@ function lazy(loader, definition) {
 /**
 * Define a {@link LazyCommand | lazy command} with specific type parameters.
 *
-* This helper function allows specifying the type parameter of {@link GunshiParams}
+* This helper function allows specifying the type parameter of {@link GunshiParamsConstraint}
 * while inferring the {@link Args} type, {@link ExtendContext} type from the definition.
 *
 * @example
@@ -262,7 +262,7 @@ function lazy(loader, definition) {
 * )
 * ```
 *
-* @typeParam G - A {@link GunshiParams} type
+* @typeParam G - A {@link GunshiParamsConstraint} type
 *
 * @returns A function that takes a lazy command definition via {@link lazy}
 *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/definition",
   "description": "utilities for gunshi command definition",
-  "version": "0.33.0",
+  "version": "0.35.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.33.0"
+    "gunshi": "0.35.0"
   },
   "scripts": {
     "build": "tsdown",