@gunshi/combinators 0.34.0 → 0.35.1

package/lib/index.d.ts

@@ -1,11 +1,11 @@
-//#region ../../node_modules/.pnpm/args-tokens@0.26.1/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,6 +110,25 @@ 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.
    *
@@ -447,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.26.1/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)
@@ -488,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.
    */
@@ -946,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.
  */
@@ -1089,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.26.1/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,13 +177,14 @@ 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.hidden != null ? { hidden: parser.hidden } : {},
 		...parser.required != null ? { required: parser.required } : {},
 		...parser.default != null ? { default: parser.default } : {}
 	};
@@ -186,6 +192,7 @@ function positional(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 } : {}
 	};
@@ -211,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) {
@@ -256,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
@@ -289,7 +298,7 @@ function combinator(config) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function map(schema, transform) {
 	const baseParse = schema.parse;
 	return {
@@ -319,7 +328,7 @@ function map(schema, transform) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function withDefault(schema, defaultValue) {
 	return {
 		...schema,
@@ -345,7 +354,7 @@ function withDefault(schema, defaultValue) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function multiple(schema) {
 	return {
 		...schema,
@@ -371,7 +380,7 @@ function multiple(schema) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function required(schema) {
 	return {
 		...schema,
@@ -400,7 +409,7 @@ function required(schema) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function short(schema, alias) {
 	return {
 		...schema,
@@ -428,7 +437,7 @@ function short(schema, alias) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function describe(schema, text) {
 	return {
 		...schema,
@@ -436,6 +445,33 @@ 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`,
@@ -457,7 +493,7 @@ function describe(schema, text) {
 *
 * @experimental
 */
-/* @__NO_SIDE_EFFECTS__ */
+// @__NO_SIDE_EFFECTS__
 function unrequired(schema) {
 	return {
 		...schema,
@@ -485,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];
@@ -516,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];
@@ -530,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.34.0",
+  "version": "0.35.1",
   "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.34.0"
+    "gunshi": "0.35.1"
   },
   "scripts": {
     "build": "tsdown",