@optique/testing 1.3.0-dev.2488 → 1.3.0-dev.2491

package/README.md

@@ -18,6 +18,23 @@ visible from its import:
 The package root holds only the contracts that mean the same thing at more than
 one boundary.  It depends on no test framework and no assertion library.
 
+The parser layer is available through `parseArgs()` and `parseArgsSync()`:
+
+~~~~ typescript
+import { option } from "@optique/core/primitives";
+import { parseArgsSync } from "@optique/testing/parser";
+
+const result = parseArgsSync(option("--verbose"), ["--verbose"]);
+if (result.success) {
+  console.log(result.value);
+} else {
+  console.error(result.error, result.remainingArgs, result.commandPath);
+}
+~~~~
+
+The runner, discovery, and child-process entry points remain reserved while
+their helpers are developed.
+
 [Optique]: https://optique.dev/
 
 

package/dist/parser.cjs

@@ -0,0 +1,66 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const __optique_core_parser = __toESM(require("@optique/core/parser"));
+
+//#region src/parser.ts
+/**
+* Parses a complete argument list and always returns a promise.
+*
+* Parser failures are returned as structured values.  Exceptions thrown by a
+* parser, or rejections from an asynchronous parser, reject the returned
+* promise.
+*
+* @template TParser The parser type, including its inferred result value.
+* @param parser The parser to exercise.
+* @param args The complete argument list to parse.
+* @param options Optional parser annotations.
+* @returns A promise resolving to the parsed value or structured failure.
+* @since 1.3.0
+*/
+async function parseArgs(parser, args, options) {
+	return await (0, __optique_core_parser.parseDetailed)(parser, args, options);
+}
+/**
+* Parses a complete argument list with a synchronous parser.
+*
+* Parser failures are returned as structured values.  Exceptions thrown by a
+* parser propagate to the caller.
+*
+* @template TParser The synchronous parser type, including its inferred result
+*                   value.
+* @param parser The synchronous parser to exercise.
+* @param args The complete argument list to parse.
+* @param options Optional parser annotations.
+* @returns The parsed value or structured failure.
+* @throws {TypeError} When called with an asynchronous parser at runtime.
+* @since 1.3.0
+*/
+function parseArgsSync(parser, args, options) {
+	if (parser.mode !== "sync") throw new TypeError("Cannot use an async parser with parseArgsSync(). Use parseArgs() instead.");
+	return (0, __optique_core_parser.parseDetailed)(parser, args, options);
+}
+
+//#endregion
+exports.parseArgs = parseArgs;
+exports.parseArgsSync = parseArgsSync;

package/dist/parser.d.cts

@@ -1 +1,44 @@
-export { };
+import { DetailedParseResult, InferValue, Mode, ParseOptions, Parser } from "@optique/core/parser";
+
+//#region src/parser.d.ts
+
+/**
+ * The result of parsing a complete argument list in a parser-layer test.
+ *
+ * @template T The inferred parser value type.
+ * @since 1.3.0
+ */
+type ParseArgsResult<T> = DetailedParseResult<T>;
+/**
+ * Parses a complete argument list and always returns a promise.
+ *
+ * Parser failures are returned as structured values.  Exceptions thrown by a
+ * parser, or rejections from an asynchronous parser, reject the returned
+ * promise.
+ *
+ * @template TParser The parser type, including its inferred result value.
+ * @param parser The parser to exercise.
+ * @param args The complete argument list to parse.
+ * @param options Optional parser annotations.
+ * @returns A promise resolving to the parsed value or structured failure.
+ * @since 1.3.0
+ */
+declare function parseArgs<TParser extends Parser<Mode, unknown, unknown>>(parser: TParser, args: readonly string[], options?: ParseOptions): Promise<ParseArgsResult<InferValue<TParser>>>;
+/**
+ * Parses a complete argument list with a synchronous parser.
+ *
+ * Parser failures are returned as structured values.  Exceptions thrown by a
+ * parser propagate to the caller.
+ *
+ * @template TParser The synchronous parser type, including its inferred result
+ *                   value.
+ * @param parser The synchronous parser to exercise.
+ * @param args The complete argument list to parse.
+ * @param options Optional parser annotations.
+ * @returns The parsed value or structured failure.
+ * @throws {TypeError} When called with an asynchronous parser at runtime.
+ * @since 1.3.0
+ */
+declare function parseArgsSync<TParser extends Parser<"sync", unknown, unknown>>(parser: TParser, args: readonly string[], options?: ParseOptions): ParseArgsResult<InferValue<TParser>>;
+//#endregion
+export { ParseArgsResult, parseArgs, parseArgsSync };

package/dist/parser.d.ts

@@ -1 +1,44 @@
-export { };
+import { DetailedParseResult, InferValue, Mode, ParseOptions, Parser } from "@optique/core/parser";
+
+//#region src/parser.d.ts
+
+/**
+ * The result of parsing a complete argument list in a parser-layer test.
+ *
+ * @template T The inferred parser value type.
+ * @since 1.3.0
+ */
+type ParseArgsResult<T> = DetailedParseResult<T>;
+/**
+ * Parses a complete argument list and always returns a promise.
+ *
+ * Parser failures are returned as structured values.  Exceptions thrown by a
+ * parser, or rejections from an asynchronous parser, reject the returned
+ * promise.
+ *
+ * @template TParser The parser type, including its inferred result value.
+ * @param parser The parser to exercise.
+ * @param args The complete argument list to parse.
+ * @param options Optional parser annotations.
+ * @returns A promise resolving to the parsed value or structured failure.
+ * @since 1.3.0
+ */
+declare function parseArgs<TParser extends Parser<Mode, unknown, unknown>>(parser: TParser, args: readonly string[], options?: ParseOptions): Promise<ParseArgsResult<InferValue<TParser>>>;
+/**
+ * Parses a complete argument list with a synchronous parser.
+ *
+ * Parser failures are returned as structured values.  Exceptions thrown by a
+ * parser propagate to the caller.
+ *
+ * @template TParser The synchronous parser type, including its inferred result
+ *                   value.
+ * @param parser The synchronous parser to exercise.
+ * @param args The complete argument list to parse.
+ * @param options Optional parser annotations.
+ * @returns The parsed value or structured failure.
+ * @throws {TypeError} When called with an asynchronous parser at runtime.
+ * @since 1.3.0
+ */
+declare function parseArgsSync<TParser extends Parser<"sync", unknown, unknown>>(parser: TParser, args: readonly string[], options?: ParseOptions): ParseArgsResult<InferValue<TParser>>;
+//#endregion
+export { ParseArgsResult, parseArgs, parseArgsSync };

package/dist/parser.js

@@ -0,0 +1,42 @@
+import { parseDetailed } from "@optique/core/parser";
+
+//#region src/parser.ts
+/**
+* Parses a complete argument list and always returns a promise.
+*
+* Parser failures are returned as structured values.  Exceptions thrown by a
+* parser, or rejections from an asynchronous parser, reject the returned
+* promise.
+*
+* @template TParser The parser type, including its inferred result value.
+* @param parser The parser to exercise.
+* @param args The complete argument list to parse.
+* @param options Optional parser annotations.
+* @returns A promise resolving to the parsed value or structured failure.
+* @since 1.3.0
+*/
+async function parseArgs(parser, args, options) {
+	return await parseDetailed(parser, args, options);
+}
+/**
+* Parses a complete argument list with a synchronous parser.
+*
+* Parser failures are returned as structured values.  Exceptions thrown by a
+* parser propagate to the caller.
+*
+* @template TParser The synchronous parser type, including its inferred result
+*                   value.
+* @param parser The synchronous parser to exercise.
+* @param args The complete argument list to parse.
+* @param options Optional parser annotations.
+* @returns The parsed value or structured failure.
+* @throws {TypeError} When called with an asynchronous parser at runtime.
+* @since 1.3.0
+*/
+function parseArgsSync(parser, args, options) {
+	if (parser.mode !== "sync") throw new TypeError("Cannot use an async parser with parseArgsSync(). Use parseArgs() instead.");
+	return parseDetailed(parser, args, options);
+}
+
+//#endregion
+export { parseArgs, parseArgsSync };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/testing",
-  "version": "1.3.0-dev.2488",
+  "version": "1.3.0-dev.2491",
   "description": "Testing support for Optique command-line interfaces",
   "keywords": [
     "CLI",
@@ -85,6 +85,9 @@
     }
   },
   "sideEffects": false,
+  "dependencies": {
+    "@optique/core": "1.3.0-dev.2491+0b23bdcf"
+  },
   "devDependencies": {
     "@types/node": "^24.0.0",
     "tsdown": "^0.13.0",