@gunshi/combinators 0.33.0 → 0.35.0

package/lib/index.d.ts

@@ -1,11 +1,11 @@
-//#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)
  *
@@ -110,13 +110,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:
@@ -140,7 +162,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 +243,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 +466,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.27.0/node_modules/args-tokens/lib/combinators.d.ts
 //#region src/combinators.d.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
@@ -480,6 +507,10 @@ interface BaseOptions {
    * Human-readable description for help text generation.
    */
   description?: string;
+  /**
+   * Hide from generated help or usage output.
+   */
+  hidden?: boolean;
   /**
    * Single character short alias.
    */
@@ -676,6 +707,7 @@ type ArgSchemaPositionalType = {
  * const args = {
  *   command: positional(),           // resolves to string
  *   port: positional(integer()),     // resolves to number
+ *   query: unrequired(positional())  // optional positional
  * }
  * ```
  *
@@ -696,6 +728,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
  * }
  * ```
  *
@@ -936,6 +969,33 @@ type CombinatorDescribe<D extends string> = {
  * @experimental
  */
 declare function describe<T, D extends string>(schema: CombinatorSchema<T>, text: D): CombinatorSchema<T> & CombinatorDescribe<D>;
+/**
+ * Options for the {@link hidden} combinator.
+ */
+type CombinatorHidden = {
+  hidden: true;
+};
+/**
+ * Hide a combinator schema from generated help or usage output.
+ *
+ * The original schema is not modified. This only marks renderer metadata and
+ * does not change parsing, validation, defaults, conflicts, or resolved values.
+ *
+ * @typeParam T - The schema type.
+ *
+ * @param schema - The base combinator schema.
+ * @returns A new schema with `hidden: true`.
+ *
+ * @example
+ * ```ts
+ * const args = {
+ *   legacy: hidden(string())
+ * }
+ * ```
+ *
+ * @experimental
+ */
+declare function hidden<T extends ArgSchema>(schema: T): Omit<T, 'hidden'> & CombinatorHidden;
 /**
  * Options for the {@link unrequired} combinator.
  */
@@ -945,10 +1005,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 +1017,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.
@@ -1077,4 +1139,4 @@ declare function extend<T extends Args, U extends Args>(base: T, overrides: U):
 */
 
 //#endregion
-export { BaseOptions, BooleanOptions, Combinator, CombinatorOptions, CombinatorSchema, FloatOptions, IntegerOptions, NumberOptions, StringOptions, args, boolean, choice, combinator, describe, extend, float, integer, map, merge, multiple, number, positional, required, short, string, unrequired, withDefault };
+export { BaseOptions, BooleanOptions, Combinator, CombinatorOptions, CombinatorSchema, FloatOptions, IntegerOptions, NumberOptions, StringOptions, args, boolean, choice, combinator, describe, extend, float, hidden, integer, map, merge, multiple, number, positional, required, short, string, unrequired, withDefault };

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.27.0/node_modules/args-tokens/lib/combinators.js
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
@@ -18,12 +18,13 @@
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function string(opts) {
 	return {
 		type: "string",
 		metavar: "string",
 		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.hidden != null ? { hidden: opts.hidden } : {},
 		...opts?.short != null ? { short: opts.short } : {},
 		...opts?.required != null ? { required: opts.required } : {},
 		parse(value) {
@@ -51,12 +52,13 @@ function string(opts) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function number(opts) {
 	return {
 		type: "number",
 		metavar: "number",
 		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.hidden != null ? { hidden: opts.hidden } : {},
 		...opts?.short != null ? { short: opts.short } : {},
 		...opts?.required != null ? { required: opts.required } : {},
 		parse(value) {
@@ -85,12 +87,13 @@ function number(opts) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function integer(opts) {
 	return {
 		type: "custom",
 		metavar: "integer",
 		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.hidden != null ? { hidden: opts.hidden } : {},
 		...opts?.short != null ? { short: opts.short } : {},
 		...opts?.required != null ? { required: opts.required } : {},
 		parse(value) {
@@ -120,12 +123,13 @@ function integer(opts) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function float(opts) {
 	return {
 		type: "custom",
 		metavar: "float",
 		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.hidden != null ? { hidden: opts.hidden } : {},
 		...opts?.short != null ? { short: opts.short } : {},
 		...opts?.required != null ? { required: opts.required } : {},
 		parse(value) {
@@ -158,13 +162,14 @@ function float(opts) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function boolean(opts) {
 	return {
 		type: "boolean",
 		...opts?.negatable != null ? { negatable: opts.negatable } : {},
 		metavar: "boolean",
 		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.hidden != null ? { hidden: opts.hidden } : {},
 		...opts?.short != null ? { short: opts.short } : {},
 		...opts?.required != null ? { required: opts.required } : {},
 		parse(value) {
@@ -172,19 +177,22 @@ function boolean(opts) {
 		}
 	};
 }
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function positional(parser) {
 	if (parser && "parse" in parser) return {
 		type: "positional",
 		parse: parser.parse,
 		metavar: parser.metavar,
 		...parser.description != null ? { description: parser.description } : {},
-		...parser.required != null ? { required: parser.required } : {}
+		...parser.hidden != null ? { hidden: parser.hidden } : {},
+		...parser.required != null ? { required: parser.required } : {},
+		...parser.default != null ? { default: parser.default } : {}
 	};
 	const opts = parser;
 	return {
 		type: "positional",
 		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.hidden != null ? { hidden: opts.hidden } : {},
 		...opts?.short != null ? { short: opts.short } : {},
 		...opts?.required != null ? { required: opts.required } : {}
 	};
@@ -210,13 +218,14 @@ function positional(parser) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function choice(values, opts) {
 	return {
 		type: "enum",
 		metavar: values.join("|"),
 		choices: values,
 		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.hidden != null ? { hidden: opts.hidden } : {},
 		...opts?.short != null ? { short: opts.short } : {},
 		...opts?.required != null ? { required: opts.required } : {},
 		parse(value) {
@@ -255,12 +264,13 @@ function choice(values, opts) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function combinator(config) {
 	return {
 		type: "custom",
 		metavar: config.metavar ?? "custom",
 		...config.description != null ? { description: config.description } : {},
+		...config.hidden != null ? { hidden: config.hidden } : {},
 		...config.short != null ? { short: config.short } : {},
 		...config.required != null ? { required: config.required } : {},
 		parse: config.parse
@@ -288,7 +298,7 @@ function combinator(config) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function map(schema, transform) {
 	const baseParse = schema.parse;
 	return {
@@ -318,7 +328,7 @@ function map(schema, transform) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function withDefault(schema, defaultValue) {
 	return {
 		...schema,
@@ -344,7 +354,7 @@ function withDefault(schema, defaultValue) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function multiple(schema) {
 	return {
 		...schema,
@@ -370,7 +380,7 @@ function multiple(schema) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function required(schema) {
 	return {
 		...schema,
@@ -399,7 +409,7 @@ function required(schema) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function short(schema, alias) {
 	return {
 		...schema,
@@ -427,7 +437,7 @@ function short(schema, alias) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function describe(schema, text) {
 	return {
 		...schema,
@@ -435,12 +445,40 @@ function describe(schema, text) {
 	};
 }
 /**
+* Hide a combinator schema from generated help or usage output.
+*
+* The original schema is not modified. This only marks renderer metadata and
+* does not change parsing, validation, defaults, conflicts, or resolved values.
+*
+* @typeParam T - The schema type.
+*
+* @param schema - The base combinator schema.
+* @returns A new schema with `hidden: true`.
+*
+* @example
+* ```ts
+* const args = {
+*   legacy: hidden(string())
+* }
+* ```
+*
+* @experimental
+*/
+// @__NO_SIDE_EFFECTS__
+function hidden(schema) {
+	return {
+		...schema,
+		hidden: true
+	};
+}
+/**
 * 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,13 +486,14 @@ function describe(schema, text) {
 * @example
 * ```ts
 * const args = {
-*   name: unrequired(string({ required: true }))
+*   name: unrequired(string({ required: true })),
+*   query: unrequired(positional())
 * }
 * ```
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function unrequired(schema) {
 	return {
 		...schema,
@@ -482,11 +521,11 @@ function unrequired(schema) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function args(fields) {
 	return fields;
 }
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function merge(...schemas) {
 	const result = Object.create(null);
 	for (const schema of schemas) for (const key of Object.keys(schema)) result[key] = schema[key];
@@ -513,7 +552,7 @@ function merge(...schemas) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function extend(base, overrides) {
 	const result = Object.create(null);
 	for (const key of Object.keys(base)) result[key] = base[key];
@@ -527,4 +566,4 @@ function extend(base, overrides) {
 * @license MIT
 */
 //#endregion
-export { args, boolean, choice, combinator, describe, extend, float, integer, map, merge, multiple, number, positional, required, short, string, unrequired, withDefault };
+export { args, boolean, choice, combinator, describe, extend, float, hidden, integer, map, merge, multiple, number, positional, required, short, string, unrequired, withDefault };

package/package.json

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