@optique/run 0.10.7-dev.485 → 1.0.0-dev.1109

package/dist/valueparser.d.cts

@@ -9,6 +9,12 @@ import { ValueParser } from "@optique/core/valueparser";
  * @since 0.5.0
  */
 interface PathErrorOptions {
+  /**
+   * Custom error message when the path is empty or contains only whitespace.
+   * Can be a static message or a function that receives the raw input string.
+   * @since 1.0.0
+   */
+  emptyPath?: Message | ((input: string) => Message);
   /**
    * Custom error message when file extension is invalid.
    * Can be a static message or a function that receives input, expected
@@ -143,6 +149,17 @@ type PathOptions = PathOptionsMustExist | PathOptionsMustNotExist | PathOptionsN
  *
  * @param options Configuration options for path validation.
  * @returns A ValueParser that validates and returns string paths.
+ * @throws {TypeError} If {@link PathOptionsBase.type} is not one of
+ *   `"file"`, `"directory"`, or `"either"`.
+ * @throws {TypeError} If any entry in {@link PathOptionsBase.extensions} does
+ *   not start with a dot (e.g., `"json"` instead of `".json"`).
+ * @throws {TypeError} If {@link PathOptionsMustExist.mustExist} is not a
+ *   boolean.
+ * @throws {TypeError} If {@link PathOptionsMustNotExist.mustNotExist} is not a
+ *   boolean.
+ * @throws {TypeError} If {@link PathOptionsBase.allowCreate} is not a boolean.
+ * @throws {TypeError} If both {@link PathOptionsMustExist.mustExist} and
+ *   {@link PathOptionsMustNotExist.mustNotExist} are `true`.
  *
  * @example
  * ```typescript

package/dist/valueparser.d.ts

@@ -9,6 +9,12 @@ import { ValueParser } from "@optique/core/valueparser";
  * @since 0.5.0
  */
 interface PathErrorOptions {
+  /**
+   * Custom error message when the path is empty or contains only whitespace.
+   * Can be a static message or a function that receives the raw input string.
+   * @since 1.0.0
+   */
+  emptyPath?: Message | ((input: string) => Message);
   /**
    * Custom error message when file extension is invalid.
    * Can be a static message or a function that receives input, expected
@@ -143,6 +149,17 @@ type PathOptions = PathOptionsMustExist | PathOptionsMustNotExist | PathOptionsN
  *
  * @param options Configuration options for path validation.
  * @returns A ValueParser that validates and returns string paths.
+ * @throws {TypeError} If {@link PathOptionsBase.type} is not one of
+ *   `"file"`, `"directory"`, or `"either"`.
+ * @throws {TypeError} If any entry in {@link PathOptionsBase.extensions} does
+ *   not start with a dot (e.g., `"json"` instead of `".json"`).
+ * @throws {TypeError} If {@link PathOptionsMustExist.mustExist} is not a
+ *   boolean.
+ * @throws {TypeError} If {@link PathOptionsMustNotExist.mustNotExist} is not a
+ *   boolean.
+ * @throws {TypeError} If {@link PathOptionsBase.allowCreate} is not a boolean.
+ * @throws {TypeError} If both {@link PathOptionsMustExist.mustExist} and
+ *   {@link PathOptionsMustNotExist.mustNotExist} are `true`.
  *
  * @example
  * ```typescript

package/dist/valueparser.js

@@ -1,4 +1,4 @@
-import { dirname, extname } from "node:path";
+import { basename, dirname, extname } from "node:path";
 import { message, text } from "@optique/core/message";
 import { ensureNonEmptyString } from "@optique/core/nonempty";
 import { existsSync, statSync } from "node:fs";
@@ -13,6 +13,17 @@ import { existsSync, statSync } from "node:fs";
 *
 * @param options Configuration options for path validation.
 * @returns A ValueParser that validates and returns string paths.
+* @throws {TypeError} If {@link PathOptionsBase.type} is not one of
+*   `"file"`, `"directory"`, or `"either"`.
+* @throws {TypeError} If any entry in {@link PathOptionsBase.extensions} does
+*   not start with a dot (e.g., `"json"` instead of `".json"`).
+* @throws {TypeError} If {@link PathOptionsMustExist.mustExist} is not a
+*   boolean.
+* @throws {TypeError} If {@link PathOptionsMustNotExist.mustNotExist} is not a
+*   boolean.
+* @throws {TypeError} If {@link PathOptionsBase.allowCreate} is not a boolean.
+* @throws {TypeError} If both {@link PathOptionsMustExist.mustExist} and
+*   {@link PathOptionsMustNotExist.mustNotExist} are `true`.
 *
 * @example
 * ```typescript
@@ -42,16 +53,30 @@ import { existsSync, statSync } from "node:fs";
 function path(options = {}) {
 	const { metavar = "PATH", type = "either", allowCreate = false, extensions } = options;
 	ensureNonEmptyString(metavar);
+	if (type !== "file" && type !== "directory" && type !== "either") throw new TypeError(`Unsupported path type: ${JSON.stringify(type)}. Expected "file", "directory", or "either".`);
+	if (extensions) {
+		for (const ext of extensions) if (!ext.startsWith(".")) throw new TypeError(`Each extension must start with a dot, got: ${JSON.stringify(ext)}`);
+	}
+	if (options.allowCreate !== void 0 && typeof options.allowCreate !== "boolean") throw new TypeError(`Expected allowCreate to be a boolean, but got ${typeof options.allowCreate}: ${String(options.allowCreate)}.`);
+	const rawOptions = options;
+	if ("mustExist" in options && rawOptions.mustExist !== void 0 && typeof rawOptions.mustExist !== "boolean") throw new TypeError(`Expected mustExist to be a boolean, but got ${typeof rawOptions.mustExist}: ${String(rawOptions.mustExist)}.`);
+	if ("mustNotExist" in options && rawOptions.mustNotExist !== void 0 && typeof rawOptions.mustNotExist !== "boolean") throw new TypeError(`Expected mustNotExist to be a boolean, but got ${typeof rawOptions.mustNotExist}: ${String(rawOptions.mustNotExist)}.`);
 	const mustExist = "mustExist" in options ? options.mustExist : false;
 	const mustNotExist = "mustNotExist" in options ? options.mustNotExist : false;
+	if (mustExist && mustNotExist) throw new TypeError("Options mustExist and mustNotExist are mutually exclusive.");
 	return {
 		$mode: "sync",
 		metavar,
 		parse(input) {
-			if (extensions && extensions.length > 0) {
-				const ext = extname(input);
-				if (!extensions.includes(ext)) {
-					const actualExt = ext || "no extension";
+			if (input.trim() === "") return {
+				success: false,
+				error: options.errors?.emptyPath ? typeof options.errors.emptyPath === "function" ? options.errors.emptyPath(input) : options.errors.emptyPath : message`Path must not be empty.`
+			};
+			if (type !== "directory" && extensions && extensions.length > 0) {
+				const base = /[/\\]$/.test(input) ? "" : basename(input);
+				if (!extensions.some((ext) => base.endsWith(ext))) {
+					const ext = extname(input);
+					const actualExt = ext || (base.startsWith(".") ? base : "no extension");
 					return {
 						success: false,
 						error: options.errors?.invalidExtension ? typeof options.errors.invalidExtension === "function" ? options.errors.invalidExtension(input, extensions, actualExt) : options.errors.invalidExtension : message`Expected file with extension ${text(extensions.join(", "))}, got ${text(actualExt)}.`
@@ -111,7 +136,7 @@ function path(options = {}) {
 				pattern: prefix,
 				type: type === "either" ? "any" : type,
 				extensions,
-				includeHidden: prefix.startsWith("."),
+				includeHidden: basename(prefix).startsWith("."),
 				description: type === "directory" ? message`Directory` : type === "file" ? message`File` : message`File or directory`
 			};
 		}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/run",
-  "version": "0.10.7-dev.485+0a30b635",
+  "version": "1.0.0-dev.1109+fa132665",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -70,7 +70,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "0.10.7-dev.485+0a30b635"
+    "@optique/core": "1.0.0-dev.1109+fa132665"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",