@gunshi/combinators 0.28.2

package/lib/index.js

@@ -0,0 +1,503 @@
+//#region ../../node_modules/.pnpm/args-tokens@0.24.1/node_modules/args-tokens/lib/combinators.js
+/**
+* Create a string argument schema with optional validation.
+*
+* @param opts - Validation options.
+* @returns A combinator schema that resolves to string.
+*
+* @example
+* ```ts
+* const args = {
+*   name: string({ minLength: 1, maxLength: 50 })
+* }
+* ```
+*
+* @experimental
+*/
+function string(opts) {
+	return {
+		type: "string",
+		metavar: "string",
+		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.short != null ? { short: opts.short } : {},
+		...opts?.required != null ? { required: opts.required } : {},
+		parse(value) {
+			if (opts?.minLength != null && value.length < opts.minLength) throw new RangeError(`String must be at least ${opts.minLength} characters`);
+			if (opts?.maxLength != null && value.length > opts.maxLength) throw new RangeError(`String must be at most ${opts.maxLength} characters`);
+			if (opts?.pattern != null && !opts.pattern.test(value)) throw new Error(`String must match pattern ${opts.pattern}`);
+			return value;
+		}
+	};
+}
+/**
+* Create a number argument schema with optional range validation.
+*
+* Accepts any numeric value (integer or float).
+*
+* @param opts - Range options.
+* @returns A combinator schema that resolves to number.
+*
+* @example
+* ```ts
+* const args = {
+*   timeout: number({ min: 0, max: 30000 })
+* }
+* ```
+*
+* @experimental
+*/
+function number(opts) {
+	return {
+		type: "number",
+		metavar: "number",
+		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.short != null ? { short: opts.short } : {},
+		...opts?.required != null ? { required: opts.required } : {},
+		parse(value) {
+			const n = Number(value);
+			if (value.trim() === "" || isNaN(n)) throw new TypeError(`Expected a number, got '${value}'`);
+			if (opts?.min != null && n < opts.min) throw new RangeError(`Number must be >= ${opts.min}, got ${n}`);
+			if (opts?.max != null && n > opts.max) throw new RangeError(`Number must be <= ${opts.max}, got ${n}`);
+			return n;
+		}
+	};
+}
+/**
+* Create an integer argument schema with optional range validation.
+*
+* Only accepts integer values (no decimals).
+*
+* @param opts - Range options.
+* @returns A combinator schema that resolves to number (integer).
+*
+* @example
+* ```ts
+* const args = {
+*   retries: integer({ min: 0, max: 10 })
+* }
+* ```
+*
+* @experimental
+*/
+function integer(opts) {
+	return {
+		type: "custom",
+		metavar: "integer",
+		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.short != null ? { short: opts.short } : {},
+		...opts?.required != null ? { required: opts.required } : {},
+		parse(value) {
+			if (!/^-?\d+$/.test(value)) throw new TypeError(`Expected an integer, got '${value}'`);
+			const n = Number.parseInt(value, 10);
+			if (isNaN(n)) throw new TypeError(`Expected an integer, got '${value}'`);
+			if (opts?.min != null && n < opts.min) throw new RangeError(`Integer must be >= ${opts.min}, got ${n}`);
+			if (opts?.max != null && n > opts.max) throw new RangeError(`Integer must be <= ${opts.max}, got ${n}`);
+			return n;
+		}
+	};
+}
+/**
+* Create a floating-point argument schema with optional range validation.
+*
+* Rejects `NaN` and `Infinity` values.
+*
+* @param opts - Range options.
+* @returns A combinator schema that resolves to number (float).
+*
+* @example
+* ```ts
+* const args = {
+*   ratio: float({ min: 0, max: 1 })
+* }
+* ```
+*
+* @experimental
+*/
+function float(opts) {
+	return {
+		type: "custom",
+		metavar: "float",
+		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.short != null ? { short: opts.short } : {},
+		...opts?.required != null ? { required: opts.required } : {},
+		parse(value) {
+			const trimmed = value.trim();
+			if (!/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i.test(trimmed)) throw new TypeError(`Expected a finite float, got '${value}'`);
+			const n = Number.parseFloat(trimmed);
+			if (isNaN(n) || !isFinite(n)) throw new TypeError(`Expected a finite float, got '${value}'`);
+			if (opts?.min != null && n < opts.min) throw new RangeError(`Float must be >= ${opts.min}, got ${n}`);
+			if (opts?.max != null && n > opts.max) throw new RangeError(`Float must be <= ${opts.max}, got ${n}`);
+			return n;
+		}
+	};
+}
+/**
+* Create a boolean argument schema.
+*
+* Boolean arguments are existence-based. The resolver passes `"true"` or `"false"`
+* to the parse function based on the presence or negation of the flag.
+*
+* @param opts - Boolean options.
+* @returns A combinator schema for boolean flags.
+*
+* @example
+* ```ts
+* const args = {
+*   color: boolean({ negatable: true })
+* }
+* // Usage: --color (true), --no-color (false)
+* ```
+*
+* @experimental
+*/
+function boolean(opts) {
+	return {
+		type: "boolean",
+		...opts?.negatable != null ? { negatable: opts.negatable } : {},
+		metavar: "boolean",
+		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.short != null ? { short: opts.short } : {},
+		...opts?.required != null ? { required: opts.required } : {},
+		parse(value) {
+			return value === "true";
+		}
+	};
+}
+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 } : {}
+	};
+	const opts = parser;
+	return {
+		type: "positional",
+		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.short != null ? { short: opts.short } : {},
+		...opts?.required != null ? { required: opts.required } : {}
+	};
+}
+/**
+* Create an enum-like argument schema with literal type inference.
+*
+* Uses `const T` generic to infer literal union types from the values array.
+*
+* @typeParam T - The readonly array of allowed string values.
+*
+* @param values - Allowed values.
+* @param opts - Common options (description, short, required).
+* @returns A combinator schema that resolves to a union of the allowed values.
+*
+* @example
+* ```ts
+* const args = {
+*   level: choice(['debug', 'info', 'warn', 'error'] as const)
+* }
+* // typeof values.level === 'debug' | 'info' | 'warn' | 'error'
+* ```
+*
+* @experimental
+*/
+function choice(values, opts) {
+	return {
+		type: "enum",
+		metavar: values.join("|"),
+		choices: values,
+		...opts?.description != null ? { description: opts.description } : {},
+		...opts?.short != null ? { short: opts.short } : {},
+		...opts?.required != null ? { required: opts.required } : {},
+		parse(value) {
+			if (!values.includes(value)) throw new Error(`Value must be one of: ${values.join(", ")}`);
+			return value;
+		}
+	};
+}
+/**
+* Create a custom argument schema with a user-defined parse function.
+*
+* This is the most general custom combinator. Use it when none of the built-in
+* base combinators ({@link string}, {@link number}, {@link integer},
+* {@link float}, {@link boolean}, {@link choice}) fit your needs.
+*
+* The returned schema has `type: 'custom'`.
+*
+* @typeParam T - The parsed value type.
+*
+* @param config - Configuration with a parse function and optional metavar.
+* @returns A combinator schema that resolves to the parse function's return type.
+*
+* @example
+* ```ts
+* const date = combinator({
+*   parse: (value) => {
+*     const d = new Date(value)
+*     if (isNaN(d.getTime())) {
+*       throw new Error('Invalid date format')
+*     }
+*     return d
+*   },
+*   metavar: 'date'
+* })
+* ```
+*
+* @experimental
+*/
+function combinator(config) {
+	return {
+		type: "custom",
+		metavar: config.metavar ?? "custom",
+		...config.description != null ? { description: config.description } : {},
+		...config.short != null ? { short: config.short } : {},
+		...config.required != null ? { required: config.required } : {},
+		parse: config.parse
+	};
+}
+/**
+* Transform the output of a combinator schema.
+*
+* Creates a new schema that applies `transform` to the result of `schema.parse`.
+* The original schema is not modified.
+*
+* @typeParam T - The input schema's parsed type.
+* @typeParam U - The transformed type.
+*
+* @param schema - The base combinator schema.
+* @param transform - The transformation function.
+* @returns A new combinator schema that resolves to the transformed type.
+*
+* @example
+* ```ts
+* const args = {
+*   doubled: map(integer(), n => n * 2)
+* }
+* ```
+*
+* @experimental
+*/
+function map(schema, transform) {
+	const baseParse = schema.parse;
+	return {
+		...schema,
+		parse(value) {
+			return transform(baseParse(value));
+		}
+	};
+}
+/**
+* Set a default value on a combinator schema.
+*
+* The original schema is not modified.
+*
+* @typeParam T - The schema's parsed type.
+*
+* @param schema - The base combinator schema.
+* @param defaultValue - The default value.
+* @returns A new schema with the default value set.
+*
+* @example
+* ```ts
+* const args = {
+*   port: withDefault(integer({ min: 1, max: 65535 }), 8080)
+* }
+* ```
+*
+* @experimental
+*/
+function withDefault(schema, defaultValue) {
+	return {
+		...schema,
+		default: defaultValue
+	};
+}
+/**
+* Mark a combinator schema as accepting multiple values.
+*
+* The resolved value becomes an array. The original schema is not modified.
+*
+* @typeParam T - The schema's parsed type.
+* @param schema - The base combinator schema.
+* @returns A new schema with `multiple: true`.
+*
+* @example
+* ```ts
+* const args = {
+*   tags: multiple(string())
+* }
+* // typeof values.tags === string[]
+* ```
+*
+* @experimental
+*/
+function multiple(schema) {
+	return {
+		...schema,
+		multiple: true
+	};
+}
+/**
+* Mark a combinator schema as required.
+*
+* The original schema is not modified.
+*
+* @typeParam T - The schema's parsed type.
+*
+* @param schema - The base combinator schema.
+* @returns A new schema with `required: true`.
+*
+* @example
+* ```ts
+* const args = {
+*   name: required(string())
+* }
+* ```
+*
+* @experimental
+*/
+function required(schema) {
+	return {
+		...schema,
+		required: true
+	};
+}
+/**
+* Set a short alias on a combinator schema.
+*
+* The original schema is not modified.
+*
+* @typeParam T - The schema's parsed type.
+* @typeParam S - The short alias string literal type.
+*
+* @param schema - The base combinator schema.
+* @param alias - Single character short alias.
+* @returns A new schema with the short alias set.
+*
+* @example
+* ```ts
+* const args = {
+*   verbose: short(boolean(), 'v')
+* }
+* // Usage: -v or --verbose
+* ```
+*
+* @experimental
+*/
+function short(schema, alias) {
+	return {
+		...schema,
+		short: alias
+	};
+}
+/**
+* Set a description on a combinator schema for help text generation.
+*
+* The original schema is not modified.
+*
+* @typeParam T - The schema's parsed type.
+* @typeParam D - The description string literal type.
+*
+* @param schema - The base combinator schema.
+* @param text - Human-readable description.
+* @returns A new schema with the description set.
+*
+* @example
+* ```ts
+* const args = {
+*   port: describe(integer(), 'Port number to listen on')
+* }
+* ```
+*
+* @experimental
+*/
+function describe(schema, text) {
+	return {
+		...schema,
+		description: text
+	};
+}
+/**
+* Mark a combinator schema as not required.
+*
+* Useful for overriding a base combinator that was created with `required: true`.
+* The original schema is not modified.
+*
+* @typeParam T - The schema's parsed type.
+*
+* @param schema - The base combinator schema.
+* @returns A new schema with `required: false`.
+*
+* @example
+* ```ts
+* const args = {
+*   name: unrequired(string({ required: true }))
+* }
+* ```
+*
+* @experimental
+*/
+function unrequired(schema) {
+	return {
+		...schema,
+		required: false
+	};
+}
+/**
+* Type-safe schema factory.
+*
+* Returns the input unchanged at runtime, but provides type inference
+* so that `satisfies Args` is not needed.
+*
+* @typeParam T - The exact schema type.
+*
+* @param fields - The argument schema object.
+* @returns The same schema object with its type inferred.
+*
+* @example
+* ```ts
+* const common = args({
+*   verbose: boolean(),
+*   help: short(boolean(), 'h')
+* })
+* ```
+*
+* @experimental
+*/
+function args(fields) {
+	return fields;
+}
+function merge(...schemas) {
+	const result = Object.create(null);
+	for (const schema of schemas) for (const key of Object.keys(schema)) result[key] = schema[key];
+	return result;
+}
+/**
+* Extend a schema by overriding or adding fields.
+*
+* Equivalent to `merge(base, overrides)` but communicates the intent of
+* intentional overrides rather than general composition.
+*
+* @typeParam T - Base schema type.
+* @typeParam U - Overrides schema type.
+*
+* @param base - The base schema to extend.
+* @param overrides - Fields to override or add.
+* @returns A new schema with overrides applied.
+*
+* @example
+* ```ts
+* const base = args({ port: withDefault(integer(), 8080) })
+* const strict = extend(base, { port: required(integer({ min: 1, max: 65535 })) })
+* ```
+*
+* @experimental
+*/
+function extend(base, overrides) {
+	const result = Object.create(null);
+	for (const key of Object.keys(base)) result[key] = base[key];
+	for (const key of Object.keys(overrides)) result[key] = overrides[key];
+	return result;
+}
+
+//#endregion
+export { args, boolean, choice, combinator, describe, extend, float, integer, map, merge, multiple, number, positional, required, short, string, unrequired, withDefault };

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@gunshi/combinators",
+  "description": "parser combinators for gunshi argument schema",
+  "version": "0.28.2",
+  "author": {
+    "name": "kazuya kawaguchi",
+    "email": "kawakazu80@gmail.com"
+  },
+  "license": "MIT",
+  "funding": "https://github.com/sponsors/kazupon",
+  "bugs": {
+    "url": "https://github.com/kazupon/gunshi/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kazupon/gunshi.git",
+    "directory": "packages/combinators"
+  },
+  "keywords": [
+    "gunshi",
+    "combinators",
+    "parser",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">= 20"
+  },
+  "type": "module",
+  "files": [
+    "lib"
+  ],
+  "module": "lib/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "require": "./lib/index.js",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "lib/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "*": [
+        "./lib/*",
+        "./*"
+      ]
+    }
+  },
+  "devDependencies": {
+    "deno": "^2.6.3",
+    "jsr": "^0.13.5",
+    "jsr-exports-lint": "^0.4.1",
+    "publint": "^0.3.16",
+    "tsdown": "0.15.12",
+    "gunshi": "0.28.2"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint:jsr": "jsr publish --dry-run --allow-dirty",
+    "typecheck:deno": "deno check --import-map=../../importmap.json ./src"
+  }
+}