@optique/config 1.0.0-dev.1673 → 1.0.0-dev.1677

package/dist/index.cjs

@@ -109,7 +109,8 @@ function isPromise(value) {
 	return isPromiseLike(value) && value[Symbol.toStringTag] === "Promise";
 }
 function validateLoadResult(loaded) {
-	if (loaded == null || typeof loaded !== "object" || Array.isArray(loaded)) throw new TypeError(`Expected load() to return an object, but got: ${getTypeName(loaded)}.`);
+	if (loaded == null) return void 0;
+	if (typeof loaded !== "object" || Array.isArray(loaded)) throw new TypeError(`Expected load() to return an object, but got: ${getTypeName(loaded)}.`);
 	if (!("config" in loaded)) throw new TypeError("Expected load() result to have a config property.");
 	const result = loaded;
 	if (isPromise(result.config)) throw new TypeError("Expected config in load() result to not be a Promise. Resolve the Promise before returning.");
@@ -196,8 +197,13 @@ function createConfigContext(options) {
 			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)}.`);
 			const parsedValue = isPhase2UndefinedParsedValue(parsed) ? void 0 : parsed;
 			const parsedPlaceholder = parsedValue;
+			const emptyAnnotations = () => {
+				clearActiveConfig(contextId);
+				clearActiveConfigMeta(contextId);
+				return {};
+			};
 			const buildAnnotations = (configData, configMeta) => {
-				if (configData === void 0 || configData === null) return {};
+				if (configData === void 0 || configData === null) return emptyAnnotations();
 				setActiveConfig(contextId, configData);
 				if (configMeta !== void 0) {
 					setActiveConfigMeta(contextId, configMeta);
@@ -217,16 +223,18 @@ function createConfigContext(options) {
 				const loaded = opts.load(parsedPlaceholder);
 				if (isPromise(loaded)) return Promise.resolve(loaded).then((resolved) => {
 					const validated$1 = validateLoadResult(resolved);
+					if (validated$1 === void 0) return emptyAnnotations();
 					return validateAndBuildAnnotations(validated$1.config, validated$1.meta);
 				});
 				if (isPromiseLike(loaded)) throw new TypeError("Expected load() to return a plain object or Promise, but got a thenable. Use a real Promise instead.");
 				const validated = validateLoadResult(loaded);
+				if (validated === void 0) return emptyAnnotations();
 				return validateAndBuildAnnotations(validated.config, validated.meta);
 			}
 			if (opts.getConfigPath) {
 				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 {};
+				if (!configPath) return emptyAnnotations();
 				const absoluteConfigPath = (0, node_path.resolve)(configPath);
 				const singleFileMeta = {
 					configDir: (0, node_path.dirname)(absoluteConfigPath),
@@ -242,12 +250,12 @@ function createConfigContext(options) {
 					}
 					return validateAndBuildAnnotations(rawData, singleFileMeta);
 				} catch (error) {
-					if (isErrnoException(error) && error.code === "ENOENT") return {};
+					if (isErrnoException(error) && error.code === "ENOENT") return emptyAnnotations();
 					if (error instanceof SyntaxError) throw new Error(`Failed to parse config file ${absoluteConfigPath}: ${error.message}`);
 					throw error;
 				}
 			}
-			return {};
+			return emptyAnnotations();
 		},
 		[Symbol.dispose]() {
 			clearActiveConfig(contextId);

package/dist/index.d.cts

@@ -82,7 +82,10 @@ interface ConfigContextOptions<T> {
  */
 interface ConfigLoadResult<TConfigMeta = ConfigMeta> {
   /**
-   * Raw config data to validate against the schema.
+   * Raw config data to validate against the schema.  The value is always
+   * passed to the schema validator, even when `undefined` or `null`.
+   * To signal "no config found" without validation, return `undefined`
+   * or `null` directly from `load()` instead of wrapping it in an object.
    */
   readonly config: unknown;
   /**
@@ -117,15 +120,18 @@ interface ConfigContextRequiredOptions<TConfigMeta = ConfigMeta> {
    * returns the config data (or a Promise of it).  This allows full control
    * over file discovery, loading, merging, and error handling.
    *
-   * The returned data will be validated against the schema.
+   * The returned `ConfigLoadResult.config` is always validated against the
+   * schema.  Return `undefined` or `null` directly (not wrapped in a
+   * `ConfigLoadResult`) to signal that no config data was found;
+   * `bindConfig()` will fall back to its defaults.
    *
    * When `load` is provided, `getConfigPath` is ignored.
    *
    * @param parsed The result from the first parse pass.
-   * @returns Config data and metadata (config is validated by schema).
+   * @returns Config data and metadata, or `undefined`/`null` for no config.
    * @since 1.0.0
    */
-  readonly load?: (parsed: ParserValuePlaceholder) => Promise<ConfigLoadResult<TConfigMeta>> | ConfigLoadResult<TConfigMeta>;
+  readonly load?: (parsed: ParserValuePlaceholder) => Promise<ConfigLoadResult<TConfigMeta> | undefined | null> | ConfigLoadResult<TConfigMeta> | undefined | null;
 }
 /**
  * A config context that provides configuration data via annotations.

package/dist/index.d.ts

@@ -82,7 +82,10 @@ interface ConfigContextOptions<T> {
  */
 interface ConfigLoadResult<TConfigMeta = ConfigMeta> {
   /**
-   * Raw config data to validate against the schema.
+   * Raw config data to validate against the schema.  The value is always
+   * passed to the schema validator, even when `undefined` or `null`.
+   * To signal "no config found" without validation, return `undefined`
+   * or `null` directly from `load()` instead of wrapping it in an object.
    */
   readonly config: unknown;
   /**
@@ -117,15 +120,18 @@ interface ConfigContextRequiredOptions<TConfigMeta = ConfigMeta> {
    * returns the config data (or a Promise of it).  This allows full control
    * over file discovery, loading, merging, and error handling.
    *
-   * The returned data will be validated against the schema.
+   * The returned `ConfigLoadResult.config` is always validated against the
+   * schema.  Return `undefined` or `null` directly (not wrapped in a
+   * `ConfigLoadResult`) to signal that no config data was found;
+   * `bindConfig()` will fall back to its defaults.
    *
    * When `load` is provided, `getConfigPath` is ignored.
    *
    * @param parsed The result from the first parse pass.
-   * @returns Config data and metadata (config is validated by schema).
+   * @returns Config data and metadata, or `undefined`/`null` for no config.
    * @since 1.0.0
    */
-  readonly load?: (parsed: ParserValuePlaceholder) => Promise<ConfigLoadResult<TConfigMeta>> | ConfigLoadResult<TConfigMeta>;
+  readonly load?: (parsed: ParserValuePlaceholder) => Promise<ConfigLoadResult<TConfigMeta> | undefined | null> | ConfigLoadResult<TConfigMeta> | undefined | null;
 }
 /**
  * A config context that provides configuration data via annotations.

package/dist/index.js

@@ -86,7 +86,8 @@ function isPromise(value) {
 	return isPromiseLike(value) && value[Symbol.toStringTag] === "Promise";
 }
 function validateLoadResult(loaded) {
-	if (loaded == null || typeof loaded !== "object" || Array.isArray(loaded)) throw new TypeError(`Expected load() to return an object, but got: ${getTypeName(loaded)}.`);
+	if (loaded == null) return void 0;
+	if (typeof loaded !== "object" || Array.isArray(loaded)) throw new TypeError(`Expected load() to return an object, but got: ${getTypeName(loaded)}.`);
 	if (!("config" in loaded)) throw new TypeError("Expected load() result to have a config property.");
 	const result = loaded;
 	if (isPromise(result.config)) throw new TypeError("Expected config in load() result to not be a Promise. Resolve the Promise before returning.");
@@ -173,8 +174,13 @@ function createConfigContext(options) {
 			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)}.`);
 			const parsedValue = isPhase2UndefinedParsedValue(parsed) ? void 0 : parsed;
 			const parsedPlaceholder = parsedValue;
+			const emptyAnnotations = () => {
+				clearActiveConfig(contextId);
+				clearActiveConfigMeta(contextId);
+				return {};
+			};
 			const buildAnnotations = (configData, configMeta) => {
-				if (configData === void 0 || configData === null) return {};
+				if (configData === void 0 || configData === null) return emptyAnnotations();
 				setActiveConfig(contextId, configData);
 				if (configMeta !== void 0) {
 					setActiveConfigMeta(contextId, configMeta);
@@ -194,16 +200,18 @@ function createConfigContext(options) {
 				const loaded = opts.load(parsedPlaceholder);
 				if (isPromise(loaded)) return Promise.resolve(loaded).then((resolved) => {
 					const validated$1 = validateLoadResult(resolved);
+					if (validated$1 === void 0) return emptyAnnotations();
 					return validateAndBuildAnnotations(validated$1.config, validated$1.meta);
 				});
 				if (isPromiseLike(loaded)) throw new TypeError("Expected load() to return a plain object or Promise, but got a thenable. Use a real Promise instead.");
 				const validated = validateLoadResult(loaded);
+				if (validated === void 0) return emptyAnnotations();
 				return validateAndBuildAnnotations(validated.config, validated.meta);
 			}
 			if (opts.getConfigPath) {
 				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 {};
+				if (!configPath) return emptyAnnotations();
 				const absoluteConfigPath = resolve(configPath);
 				const singleFileMeta = {
 					configDir: dirname(absoluteConfigPath),
@@ -219,12 +227,12 @@ function createConfigContext(options) {
 					}
 					return validateAndBuildAnnotations(rawData, singleFileMeta);
 				} catch (error) {
-					if (isErrnoException(error) && error.code === "ENOENT") return {};
+					if (isErrnoException(error) && error.code === "ENOENT") return emptyAnnotations();
 					if (error instanceof SyntaxError) throw new Error(`Failed to parse config file ${absoluteConfigPath}: ${error.message}`);
 					throw error;
 				}
 			}
-			return {};
+			return emptyAnnotations();
 		},
 		[Symbol.dispose]() {
 			clearActiveConfig(contextId);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/config",
-  "version": "1.0.0-dev.1673+06c72d11",
+  "version": "1.0.0-dev.1677+8109f98c",
   "description": "Configuration file support for Optique with Standard Schema validation",
   "keywords": [
     "CLI",
@@ -59,7 +59,7 @@
     "@standard-schema/spec": "^1.1.0"
   },
   "dependencies": {
-    "@optique/core": "1.0.0-dev.1673+06c72d11"
+    "@optique/core": "1.0.0-dev.1677+8109f98c"
   },
   "devDependencies": {
     "@standard-schema/spec": "^1.1.0",
@@ -67,7 +67,7 @@
     "tsdown": "^0.13.0",
     "typescript": "^5.8.3",
     "zod": "^3.25.0 || ^4.0.0",
-    "@optique/env": "1.0.0-dev.1673+06c72d11"
+    "@optique/env": "1.0.0-dev.1677+8109f98c"
   },
   "scripts": {
     "build": "tsdown",