@optique/core 1.0.0-dev.1228 → 1.0.0-dev.1239

package/dist/facade.cjs

@@ -1104,9 +1104,12 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 * @param args The command-line arguments to parse.
 * @param options Configuration options for customizing behavior.
 * @returns The parsed result if successful.
+* @throws {TypeError} If an async parser is passed at runtime.  Use
+* {@link runParser} or {@link runParserAsync} for async parsers.
 * @since 0.9.0
 */
 function runParserSync(parser, programName, args, options) {
+	if (parser.$mode !== "sync") throw new TypeError("Cannot use an async parser with runParserSync(). Use runParser() or runParserAsync() instead.");
 	return runParser(parser, programName, args, options);
 }
 /**
@@ -1465,11 +1468,14 @@ async function runWith(parser, programName, contexts, options) {
 * @param contexts Source contexts to use (priority: earlier overrides later).
 * @param options Run options including args, help, version, etc.
 * @returns The parsed result.
-* @throws Error if any context returns a Promise or if a context's
+* @throws {TypeError} If an async parser is passed at runtime.  Use
+* {@link runWith} or {@link runWithAsync} for async parsers.
+* @throws {Error} If any context returns a Promise or if a context's
 * `[Symbol.asyncDispose]` returns a Promise.
 * @since 0.10.0
 */
 function runWithSync(parser, programName, contexts, options) {
+	if (parser.$mode !== "sync") throw new TypeError("Cannot use an async parser with runWithSync(). Use runWith() or runWithAsync() instead.");
 	const args = options?.args ?? [];
 	if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 	if (contexts.length === 0) return runParser(parser, programName, args, options);

package/dist/facade.d.cts

@@ -301,6 +301,8 @@ declare function runParser<TParser extends Parser<Mode, unknown, unknown>, THelp
  * @param args The command-line arguments to parse.
  * @param options Configuration options for customizing behavior.
  * @returns The parsed result if successful.
+ * @throws {TypeError} If an async parser is passed at runtime.  Use
+ * {@link runParser} or {@link runParserAsync} for async parsers.
  * @since 0.9.0
  */
 declare function runParserSync<TParser extends Parser<"sync", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): InferValue<TParser>;
@@ -461,7 +463,9 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
  * @returns The parsed result.
- * @throws Error if any context returns a Promise or if a context's
+ * @throws {TypeError} If an async parser is passed at runtime.  Use
+ * {@link runWith} or {@link runWithAsync} for async parsers.
+ * @throws {Error} If any context returns a Promise or if a context's
  * `[Symbol.asyncDispose]` returns a Promise.
  * @since 0.10.0
  */

package/dist/facade.d.ts

@@ -301,6 +301,8 @@ declare function runParser<TParser extends Parser<Mode, unknown, unknown>, THelp
  * @param args The command-line arguments to parse.
  * @param options Configuration options for customizing behavior.
  * @returns The parsed result if successful.
+ * @throws {TypeError} If an async parser is passed at runtime.  Use
+ * {@link runParser} or {@link runParserAsync} for async parsers.
  * @since 0.9.0
  */
 declare function runParserSync<TParser extends Parser<"sync", unknown, unknown>, THelp = void, TError = never>(parser: TParser, programName: string, args: readonly string[], options?: RunOptions<THelp, TError>): InferValue<TParser>;
@@ -461,7 +463,9 @@ declare function runWith<TParser extends Parser<Mode, unknown, unknown>, TContex
  * @param contexts Source contexts to use (priority: earlier overrides later).
  * @param options Run options including args, help, version, etc.
  * @returns The parsed result.
- * @throws Error if any context returns a Promise or if a context's
+ * @throws {TypeError} If an async parser is passed at runtime.  Use
+ * {@link runWith} or {@link runWithAsync} for async parsers.
+ * @throws {Error} If any context returns a Promise or if a context's
  * `[Symbol.asyncDispose]` returns a Promise.
  * @since 0.10.0
  */

package/dist/facade.js

@@ -1104,9 +1104,12 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 * @param args The command-line arguments to parse.
 * @param options Configuration options for customizing behavior.
 * @returns The parsed result if successful.
+* @throws {TypeError} If an async parser is passed at runtime.  Use
+* {@link runParser} or {@link runParserAsync} for async parsers.
 * @since 0.9.0
 */
 function runParserSync(parser, programName, args, options) {
+	if (parser.$mode !== "sync") throw new TypeError("Cannot use an async parser with runParserSync(). Use runParser() or runParserAsync() instead.");
 	return runParser(parser, programName, args, options);
 }
 /**
@@ -1465,11 +1468,14 @@ async function runWith(parser, programName, contexts, options) {
 * @param contexts Source contexts to use (priority: earlier overrides later).
 * @param options Run options including args, help, version, etc.
 * @returns The parsed result.
-* @throws Error if any context returns a Promise or if a context's
+* @throws {TypeError} If an async parser is passed at runtime.  Use
+* {@link runWith} or {@link runWithAsync} for async parsers.
+* @throws {Error} If any context returns a Promise or if a context's
 * `[Symbol.asyncDispose]` returns a Promise.
 * @since 0.10.0
 */
 function runWithSync(parser, programName, contexts, options) {
+	if (parser.$mode !== "sync") throw new TypeError("Cannot use an async parser with runWithSync(). Use runWith() or runWithAsync() instead.");
 	const args = options?.args ?? [];
 	if (needsEarlyExit(args, options)) return runParser(parser, programName, args, options);
 	if (contexts.length === 0) return runParser(parser, programName, args, options);

package/dist/valueparser.cjs

@@ -810,6 +810,10 @@ function locale(options = {}) {
 * @param options Configuration options for the UUID parser.
 * @returns A {@link ValueParser} that converts string input to {@link Uuid}
 *          strings.
+* @throws {TypeError} If any element of
+*   {@link UuidOptions.allowedVersions} is not an integer.
+* @throws {RangeError} If any element of
+*   {@link UuidOptions.allowedVersions} is outside the range 1 to 8.
 */
 function uuid(options = {}) {
 	const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -817,7 +821,15 @@ function uuid(options = {}) {
 	require_nonempty.ensureNonEmptyString(metavar);
 	checkBooleanOption(options, "strict");
 	const strict = options.strict !== false;
-	const allowedVersions = options.allowedVersions != null ? Object.freeze([...options.allowedVersions]) : null;
+	const allowedVersions = options.allowedVersions != null ? (() => {
+		const unique = /* @__PURE__ */ new Set();
+		for (const v of options.allowedVersions) {
+			if (!Number.isInteger(v)) throw new TypeError(`Expected every element of allowedVersions to be an integer, but got value "${typeof v === "symbol" ? v.toString() : String(v)}" of type "${Array.isArray(v) ? "array" : v === null ? "null" : typeof v}".`);
+			if (v < 1 || v > 8) throw new RangeError(`Expected every element of allowedVersions to be between 1 and 8, but got: ${v}.`);
+			unique.add(v);
+		}
+		return Object.freeze([...unique]);
+	})() : null;
 	const invalidUuid = options.errors?.invalidUuid;
 	const disallowedVersion = options.errors?.disallowedVersion;
 	const invalidVariant = options.errors?.invalidVariant;

package/dist/valueparser.d.cts

@@ -562,9 +562,13 @@ interface UuidOptions {
   readonly metavar?: NonEmptyString;
   /**
    * List of allowed UUID versions (e.g., `[4, 5]` for UUIDs version 4 and 5).
+   * Each version must be an integer between 1 and 8 (the standardized
+   * [RFC 9562] versions).  Duplicate entries are automatically removed.
    * If specified, the parser will validate that the UUID matches one of the
    * allowed versions.  If not specified, the accepted versions depend on
    * the {@link strict} option.
+   *
+   * [RFC 9562]: https://www.rfc-editor.org/rfc/rfc9562
    */
   readonly allowedVersions?: readonly number[];
   /**
@@ -633,6 +637,10 @@ interface UuidOptions {
  * @param options Configuration options for the UUID parser.
  * @returns A {@link ValueParser} that converts string input to {@link Uuid}
  *          strings.
+ * @throws {TypeError} If any element of
+ *   {@link UuidOptions.allowedVersions} is not an integer.
+ * @throws {RangeError} If any element of
+ *   {@link UuidOptions.allowedVersions} is outside the range 1 to 8.
  */
 declare function uuid(options?: UuidOptions): ValueParser<"sync", Uuid>;
 /**

package/dist/valueparser.d.ts

@@ -562,9 +562,13 @@ interface UuidOptions {
   readonly metavar?: NonEmptyString;
   /**
    * List of allowed UUID versions (e.g., `[4, 5]` for UUIDs version 4 and 5).
+   * Each version must be an integer between 1 and 8 (the standardized
+   * [RFC 9562] versions).  Duplicate entries are automatically removed.
    * If specified, the parser will validate that the UUID matches one of the
    * allowed versions.  If not specified, the accepted versions depend on
    * the {@link strict} option.
+   *
+   * [RFC 9562]: https://www.rfc-editor.org/rfc/rfc9562
    */
   readonly allowedVersions?: readonly number[];
   /**
@@ -633,6 +637,10 @@ interface UuidOptions {
  * @param options Configuration options for the UUID parser.
  * @returns A {@link ValueParser} that converts string input to {@link Uuid}
  *          strings.
+ * @throws {TypeError} If any element of
+ *   {@link UuidOptions.allowedVersions} is not an integer.
+ * @throws {RangeError} If any element of
+ *   {@link UuidOptions.allowedVersions} is outside the range 1 to 8.
  */
 declare function uuid(options?: UuidOptions): ValueParser<"sync", Uuid>;
 /**

package/dist/valueparser.js

@@ -810,6 +810,10 @@ function locale(options = {}) {
 * @param options Configuration options for the UUID parser.
 * @returns A {@link ValueParser} that converts string input to {@link Uuid}
 *          strings.
+* @throws {TypeError} If any element of
+*   {@link UuidOptions.allowedVersions} is not an integer.
+* @throws {RangeError} If any element of
+*   {@link UuidOptions.allowedVersions} is outside the range 1 to 8.
 */
 function uuid(options = {}) {
 	const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -817,7 +821,15 @@ function uuid(options = {}) {
 	ensureNonEmptyString(metavar);
 	checkBooleanOption(options, "strict");
 	const strict = options.strict !== false;
-	const allowedVersions = options.allowedVersions != null ? Object.freeze([...options.allowedVersions]) : null;
+	const allowedVersions = options.allowedVersions != null ? (() => {
+		const unique = /* @__PURE__ */ new Set();
+		for (const v of options.allowedVersions) {
+			if (!Number.isInteger(v)) throw new TypeError(`Expected every element of allowedVersions to be an integer, but got value "${typeof v === "symbol" ? v.toString() : String(v)}" of type "${Array.isArray(v) ? "array" : v === null ? "null" : typeof v}".`);
+			if (v < 1 || v > 8) throw new RangeError(`Expected every element of allowedVersions to be between 1 and 8, but got: ${v}.`);
+			unique.add(v);
+		}
+		return Object.freeze([...unique]);
+	})() : null;
 	const invalidUuid = options.errors?.invalidUuid;
 	const disallowedVersion = options.errors?.disallowedVersion;
 	const invalidVariant = options.errors?.invalidVariant;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.0.0-dev.1228+2971180c",
+  "version": "1.0.0-dev.1239+e5c4f6ba",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",