@optique/run 0.9.0-dev.176 → 0.9.0-dev.178

package/dist/index.d.cts

@@ -1,4 +1,4 @@
 import { RunOptions, run } from "./run.cjs";
-import { PathOptions, path } from "./valueparser.cjs";
+import { PathErrorOptions, PathOptions, PathOptionsBase, PathOptionsMustExist, PathOptionsMustNotExist, PathOptionsNoExistenceCheck, path } from "./valueparser.cjs";
 import { PrintErrorOptions, PrintOptions, Printer, PrinterOptions, createPrinter, print, printError } from "./print.cjs";
-export { PathOptions, PrintErrorOptions, PrintOptions, Printer, PrinterOptions, RunOptions, createPrinter, path, print, printError, run };
+export { PathErrorOptions, PathOptions, PathOptionsBase, PathOptionsMustExist, PathOptionsMustNotExist, PathOptionsNoExistenceCheck, PrintErrorOptions, PrintOptions, Printer, PrinterOptions, RunOptions, createPrinter, path, print, printError, run };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 import { RunOptions, run } from "./run.js";
-import { PathOptions, path } from "./valueparser.js";
+import { PathErrorOptions, PathOptions, PathOptionsBase, PathOptionsMustExist, PathOptionsMustNotExist, PathOptionsNoExistenceCheck, path } from "./valueparser.js";
 import { PrintErrorOptions, PrintOptions, Printer, PrinterOptions, createPrinter, print, printError } from "./print.js";
-export { PathOptions, PrintErrorOptions, PrintOptions, Printer, PrinterOptions, RunOptions, createPrinter, path, print, printError, run };
+export { PathErrorOptions, PathOptions, PathOptionsBase, PathOptionsMustExist, PathOptionsMustNotExist, PathOptionsNoExistenceCheck, PrintErrorOptions, PrintOptions, Printer, PrinterOptions, RunOptions, createPrinter, path, print, printError, run };

package/dist/valueparser.cjs

@@ -40,7 +40,9 @@ const node_fs = require_rolldown_runtime.__toESM(require("node:fs"));
 * ```
 */
 function path(options = {}) {
-	const { metavar = "PATH", mustExist = false, type = "either", allowCreate = false, extensions } = options;
+	const { metavar = "PATH", type = "either", allowCreate = false, extensions } = options;
+	const mustExist = "mustExist" in options ? options.mustExist : false;
+	const mustNotExist = "mustNotExist" in options ? options.mustNotExist : false;
 	return {
 		metavar,
 		parse(input) {
@@ -54,6 +56,23 @@ function path(options = {}) {
 					};
 				}
 			}
+			if (mustNotExist) {
+				if ((0, node_fs.existsSync)(input)) return {
+					success: false,
+					error: options.errors?.pathAlreadyExists ? typeof options.errors.pathAlreadyExists === "function" ? options.errors.pathAlreadyExists(input) : options.errors.pathAlreadyExists : __optique_core_message.message`Path ${(0, __optique_core_message.text)(input)} already exists.`
+				};
+				if (allowCreate) {
+					const parentDir = (0, node_path.dirname)(input);
+					if (!(0, node_fs.existsSync)(parentDir)) return {
+						success: false,
+						error: options.errors?.parentNotFound ? typeof options.errors.parentNotFound === "function" ? options.errors.parentNotFound(parentDir) : options.errors.parentNotFound : __optique_core_message.message`Parent directory ${(0, __optique_core_message.text)(parentDir)} does not exist.`
+					};
+				}
+				return {
+					success: true,
+					value: input
+				};
+			}
 			if (mustExist) {
 				if (!(0, node_fs.existsSync)(input)) return {
 					success: false,

package/dist/valueparser.d.cts

@@ -4,28 +4,69 @@ import { ValueParser } from "@optique/core/valueparser";
 //#region src/valueparser.d.ts
 
 /**
- * Configuration options for the {@link path} value parser.
+ * Custom error messages for path validation failures.
+ * @since 0.5.0
  */
-interface PathOptions {
+interface PathErrorOptions {
+  /**
+   * Custom error message when file extension is invalid.
+   * Can be a static message or a function that receives input, expected
+   * extensions, and actual extension.
+   * @since 0.5.0
+   */
+  invalidExtension?: Message | ((input: string, extensions: readonly string[], actualExtension: string) => Message);
+  /**
+   * Custom error message when path does not exist.
+   * Can be a static message or a function that receives the input path.
+   * @since 0.5.0
+   */
+  pathNotFound?: Message | ((input: string) => Message);
+  /**
+   * Custom error message when path already exists (used with
+   * {@link PathOptions.mustNotExist}).
+   * Can be a static message or a function that receives the input path.
+   * @since 0.9.0
+   */
+  pathAlreadyExists?: Message | ((input: string) => Message);
+  /**
+   * Custom error message when path is expected to be a file but isn't.
+   * Can be a static message or a function that receives the input path.
+   * @since 0.5.0
+   */
+  notAFile?: Message | ((input: string) => Message);
+  /**
+   * Custom error message when path is expected to be a directory but isn't.
+   * Can be a static message or a function that receives the input path.
+   * @since 0.5.0
+   */
+  notADirectory?: Message | ((input: string) => Message);
+  /**
+   * Custom error message when parent directory does not exist for new files.
+   * Can be a static message or a function that receives the parent directory
+   * path.
+   * @since 0.5.0
+   */
+  parentNotFound?: Message | ((parentDir: string) => Message);
+}
+/**
+ * Base configuration options shared by all {@link PathOptions} variants.
+ */
+interface PathOptionsBase {
   /**
    * The metavariable name for this parser, e.g., `"FILE"`, `"DIR"`.
    * @default "PATH"
    */
   readonly metavar?: string;
-  /**
-   * Whether the path must exist on the filesystem.
-   * @default false
-   */
-  readonly mustExist?: boolean;
   /**
    * Expected type of path (file, directory, or either).
-   * Only checked when {@link mustExist} is true.
+   * Only checked when {@link PathOptionsMustExist.mustExist} is `true`.
    * @default "either"
    */
   readonly type?: "file" | "directory" | "either";
   /**
    * Whether to allow creating new files/directories.
-   * When true and mustExist is false, validates that parent directory exists.
+   * When `true` and {@link PathOptionsMustExist.mustExist} is `false`,
+   * validates that parent directory exists.
    * @default false
    */
   readonly allowCreate?: boolean;
@@ -38,39 +79,60 @@ interface PathOptions {
    * Custom error messages for path validation failures.
    * @since 0.5.0
    */
-  readonly errors?: {
-    /**
-     * Custom error message when file extension is invalid.
-     * Can be a static message or a function that receives input, expected extensions, and actual extension.
-     * @since 0.5.0
-     */
-    invalidExtension?: Message | ((input: string, extensions: readonly string[], actualExtension: string) => Message);
-    /**
-     * Custom error message when path does not exist.
-     * Can be a static message or a function that receives the input path.
-     * @since 0.5.0
-     */
-    pathNotFound?: Message | ((input: string) => Message);
-    /**
-     * Custom error message when path is expected to be a file but isn't.
-     * Can be a static message or a function that receives the input path.
-     * @since 0.5.0
-     */
-    notAFile?: Message | ((input: string) => Message);
-    /**
-     * Custom error message when path is expected to be a directory but isn't.
-     * Can be a static message or a function that receives the input path.
-     * @since 0.5.0
-     */
-    notADirectory?: Message | ((input: string) => Message);
-    /**
-     * Custom error message when parent directory does not exist for new files.
-     * Can be a static message or a function that receives the parent directory path.
-     * @since 0.5.0
-     */
-    parentNotFound?: Message | ((parentDir: string) => Message);
-  };
+  readonly errors?: PathErrorOptions;
 }
+/**
+ * Configuration options for when the path must exist.
+ */
+interface PathOptionsMustExist extends PathOptionsBase {
+  /**
+   * When `true`, the path must exist on the filesystem.
+   */
+  readonly mustExist: true;
+  /**
+   * Cannot be used together with {@link mustExist}.
+   */
+  readonly mustNotExist?: never;
+}
+/**
+ * Configuration options for when the path must not exist.
+ * @since 0.9.0
+ */
+interface PathOptionsMustNotExist extends PathOptionsBase {
+  /**
+   * Cannot be used together with {@link mustNotExist}.
+   */
+  readonly mustExist?: never;
+  /**
+   * When `true`, the path must not exist on the filesystem.
+   * Useful for output files to prevent accidental overwrites.
+   * @since 0.9.0
+   */
+  readonly mustNotExist: true;
+}
+/**
+ * Configuration options when no existence check is required.
+ */
+interface PathOptionsNoExistenceCheck extends PathOptionsBase {
+  /**
+   * Whether the path must exist on the filesystem.
+   * @default false
+   */
+  readonly mustExist?: false;
+  /**
+   * Whether the path must not exist on the filesystem.
+   * @default false
+   */
+  readonly mustNotExist?: false;
+}
+/**
+ * Configuration options for the {@link path} value parser.
+ *
+ * Note that {@link PathOptionsMustExist.mustExist} and
+ * {@link PathOptionsMustNotExist.mustNotExist} are mutually exclusive;
+ * you cannot set both to `true` at the same time.
+ */
+type PathOptions = PathOptionsMustExist | PathOptionsMustNotExist | PathOptionsNoExistenceCheck;
 /**
  * Creates a ValueParser for file system paths with validation options.
  *
@@ -108,4 +170,4 @@ interface PathOptions {
  */
 declare function path(options?: PathOptions): ValueParser<string>;
 //#endregion
-export { PathOptions, path };
+export { PathErrorOptions, PathOptions, PathOptionsBase, PathOptionsMustExist, PathOptionsMustNotExist, PathOptionsNoExistenceCheck, path };

package/dist/valueparser.d.ts

@@ -4,28 +4,69 @@ import { ValueParser } from "@optique/core/valueparser";
 //#region src/valueparser.d.ts
 
 /**
- * Configuration options for the {@link path} value parser.
+ * Custom error messages for path validation failures.
+ * @since 0.5.0
  */
-interface PathOptions {
+interface PathErrorOptions {
+  /**
+   * Custom error message when file extension is invalid.
+   * Can be a static message or a function that receives input, expected
+   * extensions, and actual extension.
+   * @since 0.5.0
+   */
+  invalidExtension?: Message | ((input: string, extensions: readonly string[], actualExtension: string) => Message);
+  /**
+   * Custom error message when path does not exist.
+   * Can be a static message or a function that receives the input path.
+   * @since 0.5.0
+   */
+  pathNotFound?: Message | ((input: string) => Message);
+  /**
+   * Custom error message when path already exists (used with
+   * {@link PathOptions.mustNotExist}).
+   * Can be a static message or a function that receives the input path.
+   * @since 0.9.0
+   */
+  pathAlreadyExists?: Message | ((input: string) => Message);
+  /**
+   * Custom error message when path is expected to be a file but isn't.
+   * Can be a static message or a function that receives the input path.
+   * @since 0.5.0
+   */
+  notAFile?: Message | ((input: string) => Message);
+  /**
+   * Custom error message when path is expected to be a directory but isn't.
+   * Can be a static message or a function that receives the input path.
+   * @since 0.5.0
+   */
+  notADirectory?: Message | ((input: string) => Message);
+  /**
+   * Custom error message when parent directory does not exist for new files.
+   * Can be a static message or a function that receives the parent directory
+   * path.
+   * @since 0.5.0
+   */
+  parentNotFound?: Message | ((parentDir: string) => Message);
+}
+/**
+ * Base configuration options shared by all {@link PathOptions} variants.
+ */
+interface PathOptionsBase {
   /**
    * The metavariable name for this parser, e.g., `"FILE"`, `"DIR"`.
    * @default "PATH"
    */
   readonly metavar?: string;
-  /**
-   * Whether the path must exist on the filesystem.
-   * @default false
-   */
-  readonly mustExist?: boolean;
   /**
    * Expected type of path (file, directory, or either).
-   * Only checked when {@link mustExist} is true.
+   * Only checked when {@link PathOptionsMustExist.mustExist} is `true`.
    * @default "either"
    */
   readonly type?: "file" | "directory" | "either";
   /**
    * Whether to allow creating new files/directories.
-   * When true and mustExist is false, validates that parent directory exists.
+   * When `true` and {@link PathOptionsMustExist.mustExist} is `false`,
+   * validates that parent directory exists.
    * @default false
    */
   readonly allowCreate?: boolean;
@@ -38,39 +79,60 @@ interface PathOptions {
    * Custom error messages for path validation failures.
    * @since 0.5.0
    */
-  readonly errors?: {
-    /**
-     * Custom error message when file extension is invalid.
-     * Can be a static message or a function that receives input, expected extensions, and actual extension.
-     * @since 0.5.0
-     */
-    invalidExtension?: Message | ((input: string, extensions: readonly string[], actualExtension: string) => Message);
-    /**
-     * Custom error message when path does not exist.
-     * Can be a static message or a function that receives the input path.
-     * @since 0.5.0
-     */
-    pathNotFound?: Message | ((input: string) => Message);
-    /**
-     * Custom error message when path is expected to be a file but isn't.
-     * Can be a static message or a function that receives the input path.
-     * @since 0.5.0
-     */
-    notAFile?: Message | ((input: string) => Message);
-    /**
-     * Custom error message when path is expected to be a directory but isn't.
-     * Can be a static message or a function that receives the input path.
-     * @since 0.5.0
-     */
-    notADirectory?: Message | ((input: string) => Message);
-    /**
-     * Custom error message when parent directory does not exist for new files.
-     * Can be a static message or a function that receives the parent directory path.
-     * @since 0.5.0
-     */
-    parentNotFound?: Message | ((parentDir: string) => Message);
-  };
+  readonly errors?: PathErrorOptions;
 }
+/**
+ * Configuration options for when the path must exist.
+ */
+interface PathOptionsMustExist extends PathOptionsBase {
+  /**
+   * When `true`, the path must exist on the filesystem.
+   */
+  readonly mustExist: true;
+  /**
+   * Cannot be used together with {@link mustExist}.
+   */
+  readonly mustNotExist?: never;
+}
+/**
+ * Configuration options for when the path must not exist.
+ * @since 0.9.0
+ */
+interface PathOptionsMustNotExist extends PathOptionsBase {
+  /**
+   * Cannot be used together with {@link mustNotExist}.
+   */
+  readonly mustExist?: never;
+  /**
+   * When `true`, the path must not exist on the filesystem.
+   * Useful for output files to prevent accidental overwrites.
+   * @since 0.9.0
+   */
+  readonly mustNotExist: true;
+}
+/**
+ * Configuration options when no existence check is required.
+ */
+interface PathOptionsNoExistenceCheck extends PathOptionsBase {
+  /**
+   * Whether the path must exist on the filesystem.
+   * @default false
+   */
+  readonly mustExist?: false;
+  /**
+   * Whether the path must not exist on the filesystem.
+   * @default false
+   */
+  readonly mustNotExist?: false;
+}
+/**
+ * Configuration options for the {@link path} value parser.
+ *
+ * Note that {@link PathOptionsMustExist.mustExist} and
+ * {@link PathOptionsMustNotExist.mustNotExist} are mutually exclusive;
+ * you cannot set both to `true` at the same time.
+ */
+type PathOptions = PathOptionsMustExist | PathOptionsMustNotExist | PathOptionsNoExistenceCheck;
 /**
  * Creates a ValueParser for file system paths with validation options.
  *
@@ -108,4 +170,4 @@ interface PathOptions {
  */
 declare function path(options?: PathOptions): ValueParser<string>;
 //#endregion
-export { PathOptions, path };
+export { PathErrorOptions, PathOptions, PathOptionsBase, PathOptionsMustExist, PathOptionsMustNotExist, PathOptionsNoExistenceCheck, path };

package/dist/valueparser.js

@@ -39,7 +39,9 @@ import { existsSync, statSync } from "node:fs";
 * ```
 */
 function path(options = {}) {
-	const { metavar = "PATH", mustExist = false, type = "either", allowCreate = false, extensions } = options;
+	const { metavar = "PATH", type = "either", allowCreate = false, extensions } = options;
+	const mustExist = "mustExist" in options ? options.mustExist : false;
+	const mustNotExist = "mustNotExist" in options ? options.mustNotExist : false;
 	return {
 		metavar,
 		parse(input) {
@@ -53,6 +55,23 @@ function path(options = {}) {
 					};
 				}
 			}
+			if (mustNotExist) {
+				if (existsSync(input)) return {
+					success: false,
+					error: options.errors?.pathAlreadyExists ? typeof options.errors.pathAlreadyExists === "function" ? options.errors.pathAlreadyExists(input) : options.errors.pathAlreadyExists : message`Path ${text(input)} already exists.`
+				};
+				if (allowCreate) {
+					const parentDir = dirname(input);
+					if (!existsSync(parentDir)) return {
+						success: false,
+						error: options.errors?.parentNotFound ? typeof options.errors.parentNotFound === "function" ? options.errors.parentNotFound(parentDir) : options.errors.parentNotFound : message`Parent directory ${text(parentDir)} does not exist.`
+					};
+				}
+				return {
+					success: true,
+					value: input
+				};
+			}
 			if (mustExist) {
 				if (!existsSync(input)) return {
 					success: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/run",
-  "version": "0.9.0-dev.176+1350294a",
+  "version": "0.9.0-dev.178+732cc3ad",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -70,7 +70,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "0.9.0-dev.176+1350294a"
+    "@optique/core": "0.9.0-dev.178+732cc3ad"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",