@optique/config 1.4.0-dev.2600 → 1.4.0-dev.2603

package/dist/index.cjs

@@ -22,6 +22,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 //#endregion
 const node_fs = __toESM(require("node:fs"));
+const node_os = __toESM(require("node:os"));
 const node_path = __toESM(require("node:path"));
 const __optique_core_annotations = __toESM(require("@optique/core/annotations"));
 const __optique_core_extension = __toESM(require("@optique/core/extension"));
@@ -66,6 +67,19 @@ function isStandardSchema(value) {
 	if (standard == null || typeof standard !== "object" && typeof standard !== "function") return false;
 	return typeof standard.validate === "function";
 }
+/**
+* Expands a leading `~` in a config file path to the home directory.  Only
+* a bare `~` and `~/` (or `~\` on Windows) prefixes are expanded; any other
+* path is returned unchanged.
+* @throws {Error} If the home directory cannot be determined.
+*/
+function expandHomeDirectory(path) {
+	const hasHomePrefix = path === "~" || path.startsWith("~/") || node_path.sep === "\\" && path.startsWith("~\\");
+	if (!hasHomePrefix) return path;
+	const home = (0, node_os.homedir)();
+	if (!home) throw new Error("Cannot expand ~ in config path: the home directory could not be determined.");
+	return path === "~" ? home : (0, node_path.join)(home, path.slice(2));
+}
 function isErrnoException(error) {
 	return typeof error === "object" && error !== null && "code" in error;
 }
@@ -153,6 +167,7 @@ function createConfigContext(options) {
 			if (!opts || !opts.getConfigPath && !opts.load) throw new TypeError("Either getConfigPath or load must be provided in the runner options when using ConfigContext.");
 			if (opts.load !== void 0 && typeof opts.load !== "function") throw new TypeError(`Expected load to be a function, but got: ${getTypeName(opts.load)}.`);
 			if (!opts.load && opts.getConfigPath !== void 0 && typeof opts.getConfigPath !== "function") throw new TypeError(`Expected getConfigPath to be a function, but got: ${getTypeName(opts.getConfigPath)}.`);
+			if (opts.expandHome !== void 0 && typeof opts.expandHome !== "boolean") throw new TypeError(`Expected expandHome to be a boolean, but got: ${getTypeName(opts.expandHome)}.`);
 			const parsedPlaceholder = request.parsed;
 			const emptyAnnotations = () => ({});
 			const buildAnnotations = (configData, configMeta) => {
@@ -184,7 +199,7 @@ function createConfigContext(options) {
 				const configPath = opts.getConfigPath(parsedPlaceholder);
 				if (configPath !== void 0 && typeof configPath !== "string") throw new TypeError(`Expected getConfigPath() to return a string or undefined, but got: ${getTypeName(configPath)}.`);
 				if (!configPath) return emptyAnnotations();
-				const absoluteConfigPath = (0, node_path.resolve)(configPath);
+				const absoluteConfigPath = (0, node_path.resolve)(opts.expandHome ? expandHomeDirectory(configPath) : configPath);
 				const singleFileMeta = {
 					configDir: (0, node_path.dirname)(absoluteConfigPath),
 					configPath: absoluteConfigPath

package/dist/index.d.cts

@@ -103,6 +103,25 @@ interface ConfigContextRequiredOptions<TConfigMeta = ConfigMeta> {
    * @since 1.0.0
    */
   readonly load?: (parsed: ParserValuePlaceholder) => Promise<ConfigLoadResult<TConfigMeta> | undefined | null> | ConfigLoadResult<TConfigMeta> | undefined | null;
+  /**
+   * Whether to expand a leading `~` in the path returned by `getConfigPath()`
+   * to the current user's home directory.  Defaults to `false`, so the path
+   * is used as is, since `~` is a valid file name character on most
+   * platforms.
+   *
+   * When enabled, only a bare `~` and paths starting with `~/` (or `~\` on
+   * Windows) are expanded.  Other forms such as `~user/config.json` are left
+   * unchanged.  The expanded path is also what `ConfigMeta` reports.
+   *
+   * This option only affects single-file mode.  It has no effect when `load`
+   * is provided, although it is still validated.
+   *
+   * On Deno, looking up the home directory requires the
+   * `--allow-sys=homedir` permission.
+   *
+   * @since 1.4.0
+   */
+  readonly expandHome?: boolean;
 }
 /**
  * A config context that provides configuration data via annotations.

package/dist/index.d.ts

@@ -103,6 +103,25 @@ interface ConfigContextRequiredOptions<TConfigMeta = ConfigMeta> {
    * @since 1.0.0
    */
   readonly load?: (parsed: ParserValuePlaceholder) => Promise<ConfigLoadResult<TConfigMeta> | undefined | null> | ConfigLoadResult<TConfigMeta> | undefined | null;
+  /**
+   * Whether to expand a leading `~` in the path returned by `getConfigPath()`
+   * to the current user's home directory.  Defaults to `false`, so the path
+   * is used as is, since `~` is a valid file name character on most
+   * platforms.
+   *
+   * When enabled, only a bare `~` and paths starting with `~/` (or `~\` on
+   * Windows) are expanded.  Other forms such as `~user/config.json` are left
+   * unchanged.  The expanded path is also what `ConfigMeta` reports.
+   *
+   * This option only affects single-file mode.  It has no effect when `load`
+   * is provided, although it is still validated.
+   *
+   * On Deno, looking up the home directory requires the
+   * `--allow-sys=homedir` permission.
+   *
+   * @since 1.4.0
+   */
+  readonly expandHome?: boolean;
 }
 /**
  * A config context that provides configuration data via annotations.

package/dist/index.js

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { homedir } from "node:os";
+import { dirname, join, resolve, sep } from "node:path";
 import { getAnnotations } from "@optique/core/annotations";
 import { defineTraits, delegateSuggestNodes, inheritAnnotations, injectAnnotations, mapModeValue, mapSourceMetadata, withAnnotationView, wrapForMode } from "@optique/core/extension";
 import { fluent } from "@optique/core/fluent";
@@ -43,6 +44,19 @@ function isStandardSchema(value) {
 	if (standard == null || typeof standard !== "object" && typeof standard !== "function") return false;
 	return typeof standard.validate === "function";
 }
+/**
+* Expands a leading `~` in a config file path to the home directory.  Only
+* a bare `~` and `~/` (or `~\` on Windows) prefixes are expanded; any other
+* path is returned unchanged.
+* @throws {Error} If the home directory cannot be determined.
+*/
+function expandHomeDirectory(path) {
+	const hasHomePrefix = path === "~" || path.startsWith("~/") || sep === "\\" && path.startsWith("~\\");
+	if (!hasHomePrefix) return path;
+	const home = homedir();
+	if (!home) throw new Error("Cannot expand ~ in config path: the home directory could not be determined.");
+	return path === "~" ? home : join(home, path.slice(2));
+}
 function isErrnoException(error) {
 	return typeof error === "object" && error !== null && "code" in error;
 }
@@ -130,6 +144,7 @@ function createConfigContext(options) {
 			if (!opts || !opts.getConfigPath && !opts.load) throw new TypeError("Either getConfigPath or load must be provided in the runner options when using ConfigContext.");
 			if (opts.load !== void 0 && typeof opts.load !== "function") throw new TypeError(`Expected load to be a function, but got: ${getTypeName(opts.load)}.`);
 			if (!opts.load && opts.getConfigPath !== void 0 && typeof opts.getConfigPath !== "function") throw new TypeError(`Expected getConfigPath to be a function, but got: ${getTypeName(opts.getConfigPath)}.`);
+			if (opts.expandHome !== void 0 && typeof opts.expandHome !== "boolean") throw new TypeError(`Expected expandHome to be a boolean, but got: ${getTypeName(opts.expandHome)}.`);
 			const parsedPlaceholder = request.parsed;
 			const emptyAnnotations = () => ({});
 			const buildAnnotations = (configData, configMeta) => {
@@ -161,7 +176,7 @@ function createConfigContext(options) {
 				const configPath = opts.getConfigPath(parsedPlaceholder);
 				if (configPath !== void 0 && typeof configPath !== "string") throw new TypeError(`Expected getConfigPath() to return a string or undefined, but got: ${getTypeName(configPath)}.`);
 				if (!configPath) return emptyAnnotations();
-				const absoluteConfigPath = resolve(configPath);
+				const absoluteConfigPath = resolve(opts.expandHome ? expandHomeDirectory(configPath) : configPath);
 				const singleFileMeta = {
 					configDir: dirname(absoluteConfigPath),
 					configPath: absoluteConfigPath

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/config",
-  "version": "1.4.0-dev.2600",
+  "version": "1.4.0-dev.2603",
   "description": "Configuration file support for Optique with Standard Schema validation",
   "keywords": [
     "CLI",
@@ -65,10 +65,10 @@
     "@standard-schema/spec": "^1.1.0"
   },
   "dependencies": {
-    "@optique/core": "1.4.0-dev.2600+6c98c033"
+    "@optique/core": "1.4.0-dev.2603+d6d54fca"
   },
   "devDependencies": {
-    "@optique/env": "1.4.0-dev.2600+6c98c033",
+    "@optique/env": "1.4.0-dev.2603+d6d54fca",
     "@standard-schema/spec": "^1.1.0",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",