@optique/config 1.1.0-dev.2006 → 1.1.0-dev.2053

package/dist/index.cjs

@@ -87,6 +87,14 @@ function validateWithSchema(schema, rawData) {
 /**
 * Creates a config context for use with Optique parsers.
 *
+* Pass the returned context to `run()`'s `contexts` option so that
+* `bindConfig()` can read configuration values during parsing:
+*
+* ```typescript
+* const configContext = createConfigContext({ schema });
+* run(parser, { contexts: [configContext], contextOptions: { load } });
+* ```
+*
 * The config context implements the `SourceContext` interface and can be used
 * with `runWith()` from *@optique/core* or `run()`/`runAsync()` from
 * *@optique/run* to provide configuration file support. Each runner call
@@ -210,6 +218,18 @@ function createConfigContext(options) {
 * 3. Default value (if specified)
 * 4. Error (if none of the above)
 *
+* > **Important:** `bindConfig()` only reads configuration values when its
+* > `ConfigContext` is registered with the runner via the `contexts` option:
+* >
+* > ```typescript
+* > run(parser, { contexts: [configContext], contextOptions: { load } });
+* > ```
+* >
+* > Omitting `contexts` causes `bindConfig()` to skip the config lookup and
+* > fall through to the default or an error.  When other contexts are
+* > registered but this config context is not, the error explicitly names the
+* > `contexts` option to aid diagnosis.
+*
 * @template M The parser mode (sync or async).
 * @template TValue The parser value type.
 * @template TState The parser state type.
@@ -396,6 +416,7 @@ function bindConfig(parser, options) {
 function getConfigOrDefault(state, options, mode, innerParser) {
 	const annotations = (0, __optique_core_annotations.getAnnotations)(state);
 	const contextId = options.context.id;
+	const configContextAbsent = annotations != null && !(contextId in annotations);
 	const annotationValue = annotations?.[contextId];
 	const configData = annotationValue?.data;
 	const configMeta = annotationValue?.meta;
@@ -406,6 +427,10 @@ function getConfigOrDefault(state, options, mode, innerParser) {
 	} else configValue = configData[options.key];
 	if (configValue !== void 0) return validateFallbackValue(mode, innerParser, configValue);
 	if (options.default !== void 0) return validateFallbackValue(mode, innerParser, options.default);
+	if (configContextAbsent) return (0, __optique_core_extension.wrapForMode)(mode, {
+		success: false,
+		error: __optique_core_message.message`Configuration value could not be read: the config context was not passed to run()'s contexts option.`
+	});
 	return (0, __optique_core_extension.wrapForMode)(mode, {
 		success: false,
 		error: __optique_core_message.message`Missing required configuration value.`

package/dist/index.d.cts

@@ -124,6 +124,14 @@ interface ConfigContext<T, TConfigMeta = ConfigMeta> extends SourceContext<Confi
 /**
  * Creates a config context for use with Optique parsers.
  *
+ * Pass the returned context to `run()`'s `contexts` option so that
+ * `bindConfig()` can read configuration values during parsing:
+ *
+ * ```typescript
+ * const configContext = createConfigContext({ schema });
+ * run(parser, { contexts: [configContext], contextOptions: { load } });
+ * ```
+ *
  * The config context implements the `SourceContext` interface and can be used
  * with `runWith()` from *@optique/core* or `run()`/`runAsync()` from
  * *@optique/run* to provide configuration file support. Each runner call
@@ -194,6 +202,18 @@ interface BindConfigOptions<T, TValue, TConfigMeta = ConfigMeta> {
  * 3. Default value (if specified)
  * 4. Error (if none of the above)
  *
+ * > **Important:** `bindConfig()` only reads configuration values when its
+ * > `ConfigContext` is registered with the runner via the `contexts` option:
+ * >
+ * > ```typescript
+ * > run(parser, { contexts: [configContext], contextOptions: { load } });
+ * > ```
+ * >
+ * > Omitting `contexts` causes `bindConfig()` to skip the config lookup and
+ * > fall through to the default or an error.  When other contexts are
+ * > registered but this config context is not, the error explicitly names the
+ * > `contexts` option to aid diagnosis.
+ *
  * @template M The parser mode (sync or async).
  * @template TValue The parser value type.
  * @template TState The parser state type.

package/dist/index.d.ts

@@ -124,6 +124,14 @@ interface ConfigContext<T, TConfigMeta = ConfigMeta> extends SourceContext<Confi
 /**
  * Creates a config context for use with Optique parsers.
  *
+ * Pass the returned context to `run()`'s `contexts` option so that
+ * `bindConfig()` can read configuration values during parsing:
+ *
+ * ```typescript
+ * const configContext = createConfigContext({ schema });
+ * run(parser, { contexts: [configContext], contextOptions: { load } });
+ * ```
+ *
  * The config context implements the `SourceContext` interface and can be used
  * with `runWith()` from *@optique/core* or `run()`/`runAsync()` from
  * *@optique/run* to provide configuration file support. Each runner call
@@ -194,6 +202,18 @@ interface BindConfigOptions<T, TValue, TConfigMeta = ConfigMeta> {
  * 3. Default value (if specified)
  * 4. Error (if none of the above)
  *
+ * > **Important:** `bindConfig()` only reads configuration values when its
+ * > `ConfigContext` is registered with the runner via the `contexts` option:
+ * >
+ * > ```typescript
+ * > run(parser, { contexts: [configContext], contextOptions: { load } });
+ * > ```
+ * >
+ * > Omitting `contexts` causes `bindConfig()` to skip the config lookup and
+ * > fall through to the default or an error.  When other contexts are
+ * > registered but this config context is not, the error explicitly names the
+ * > `contexts` option to aid diagnosis.
+ *
  * @template M The parser mode (sync or async).
  * @template TValue The parser value type.
  * @template TState The parser state type.

package/dist/index.js

@@ -64,6 +64,14 @@ function validateWithSchema(schema, rawData) {
 /**
 * Creates a config context for use with Optique parsers.
 *
+* Pass the returned context to `run()`'s `contexts` option so that
+* `bindConfig()` can read configuration values during parsing:
+*
+* ```typescript
+* const configContext = createConfigContext({ schema });
+* run(parser, { contexts: [configContext], contextOptions: { load } });
+* ```
+*
 * The config context implements the `SourceContext` interface and can be used
 * with `runWith()` from *@optique/core* or `run()`/`runAsync()` from
 * *@optique/run* to provide configuration file support. Each runner call
@@ -187,6 +195,18 @@ function createConfigContext(options) {
 * 3. Default value (if specified)
 * 4. Error (if none of the above)
 *
+* > **Important:** `bindConfig()` only reads configuration values when its
+* > `ConfigContext` is registered with the runner via the `contexts` option:
+* >
+* > ```typescript
+* > run(parser, { contexts: [configContext], contextOptions: { load } });
+* > ```
+* >
+* > Omitting `contexts` causes `bindConfig()` to skip the config lookup and
+* > fall through to the default or an error.  When other contexts are
+* > registered but this config context is not, the error explicitly names the
+* > `contexts` option to aid diagnosis.
+*
 * @template M The parser mode (sync or async).
 * @template TValue The parser value type.
 * @template TState The parser state type.
@@ -373,6 +393,7 @@ function bindConfig(parser, options) {
 function getConfigOrDefault(state, options, mode, innerParser) {
 	const annotations = getAnnotations(state);
 	const contextId = options.context.id;
+	const configContextAbsent = annotations != null && !(contextId in annotations);
 	const annotationValue = annotations?.[contextId];
 	const configData = annotationValue?.data;
 	const configMeta = annotationValue?.meta;
@@ -383,6 +404,10 @@ function getConfigOrDefault(state, options, mode, innerParser) {
 	} else configValue = configData[options.key];
 	if (configValue !== void 0) return validateFallbackValue(mode, innerParser, configValue);
 	if (options.default !== void 0) return validateFallbackValue(mode, innerParser, options.default);
+	if (configContextAbsent) return wrapForMode(mode, {
+		success: false,
+		error: message`Configuration value could not be read: the config context was not passed to run()'s contexts option.`
+	});
 	return wrapForMode(mode, {
 		success: false,
 		error: message`Missing required configuration value.`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/config",
-  "version": "1.1.0-dev.2006+b336c042",
+  "version": "1.1.0-dev.2053",
   "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.1.0-dev.2006+b336c042"
+    "@optique/core": "1.1.0-dev.2053+ed892f45"
   },
   "devDependencies": {
     "@standard-schema/spec": "^1.1.0",
@@ -68,7 +68,7 @@
     "tsdown": "^0.13.0",
     "typescript": "^5.8.3",
     "zod": "^3.25.0 || ^4.0.0",
-    "@optique/env": "1.1.0-dev.2006+b336c042"
+    "@optique/env": "1.1.0-dev.2053+ed892f45"
   },
   "scripts": {
     "build": "tsdown",