@gunshi/combinators 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/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
 /**
@@ -116,7 +116,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:
@@ -140,7 +143,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.
    *
@@ -220,7 +224,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:
@@ -439,7 +447,7 @@ interface Args {
  * @typeParam T - {@link Args | Arguments} which is an object that defines the command line arguments.
  */
 //#endregion
-//#region ../../node_modules/.pnpm/args-tokens@0.25.0/node_modules/args-tokens/lib/combinators.d.ts
+//#region ../../node_modules/.pnpm/args-tokens@0.26.1/node_modules/args-tokens/lib/combinators.d.ts
 //#region src/combinators.d.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
@@ -676,6 +684,7 @@ type ArgSchemaPositionalType = {
  * const args = {
  *   command: positional(),           // resolves to string
  *   port: positional(integer()),     // resolves to number
+ *   query: unrequired(positional())  // optional positional
  * }
  * ```
  *
@@ -696,6 +705,7 @@ declare function positional<T>(parser: CombinatorSchema<T>): CombinatorSchema<T>
  * const args = {
  *   command: positional(),           // resolves to string
  *   port: positional(integer()),     // resolves to number
+ *   query: unrequired(positional())  // optional positional
  * }
  * ```
  *
@@ -945,10 +955,11 @@ type CombinatorUnrequired = {
 /**
  * Mark a combinator schema as not required.
  *
- * Useful for overriding a base combinator that was created with `required: true`.
+ * Useful for overriding a base combinator that was created with `required: true`,
+ * or for making a positional argument explicitly optional.
  * The original schema is not modified.
  *
- * @typeParam T - The schema's parsed type.
+ * @typeParam T - The schema type.
  *
  * @param schema - The base combinator schema.
  * @returns A new schema with `required: false`.
@@ -956,13 +967,14 @@ type CombinatorUnrequired = {
  * @example
  * ```ts
  * const args = {
- *   name: unrequired(string({ required: true }))
+ *   name: unrequired(string({ required: true })),
+ *   query: unrequired(positional())
  * }
  * ```
  *
  * @experimental
  */
-declare function unrequired<T>(schema: CombinatorSchema<T>): CombinatorSchema<T> & CombinatorUnrequired;
+declare function unrequired<T extends ArgSchema>(schema: T): Omit<T, 'required'> & CombinatorUnrequired;
 /**
  * Recursively merge a tuple of {@link Args} types.
  * Later types override earlier ones on key conflicts.

package/lib/index.js

@@ -1,4 +1,4 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.25.0/node_modules/args-tokens/lib/combinators.js
+//#region ../../node_modules/.pnpm/args-tokens@0.26.1/node_modules/args-tokens/lib/combinators.js
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
@@ -179,7 +179,8 @@ function positional(parser) {
 		parse: parser.parse,
 		metavar: parser.metavar,
 		...parser.description != null ? { description: parser.description } : {},
-		...parser.required != null ? { required: parser.required } : {}
+		...parser.required != null ? { required: parser.required } : {},
+		...parser.default != null ? { default: parser.default } : {}
 	};
 	const opts = parser;
 	return {
@@ -437,10 +438,11 @@ function describe(schema, text) {
 /**
 * Mark a combinator schema as not required.
 *
-* Useful for overriding a base combinator that was created with `required: true`.
+* Useful for overriding a base combinator that was created with `required: true`,
+* or for making a positional argument explicitly optional.
 * The original schema is not modified.
 *
-* @typeParam T - The schema's parsed type.
+* @typeParam T - The schema type.
 *
 * @param schema - The base combinator schema.
 * @returns A new schema with `required: false`.
@@ -448,7 +450,8 @@ function describe(schema, text) {
 * @example
 * ```ts
 * const args = {
-*   name: unrequired(string({ required: true }))
+*   name: unrequired(string({ required: true })),
+*   query: unrequired(positional())
 * }
 * ```
 *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gunshi/combinators",
   "description": "parser combinators for gunshi argument schema",
-  "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",