@optique/env 1.1.0-dev.1998 → 1.1.0-dev.2053

package/dist/index.cjs

@@ -36,6 +36,14 @@ function defaultEnvSource(key) {
 /**
 * Creates an environment context for use with Optique runners.
 *
+* Pass the returned context to `run()`'s `contexts` option so that
+* `bindEnv()` can read environment variables during parsing:
+*
+* ```typescript
+* const envContext = createEnvContext({ prefix: "MYAPP_" });
+* run(parser, { contexts: [envContext] });
+* ```
+*
 * When calling `context.getAnnotations()` manually, pass the returned
 * annotations to low-level APIs such as `parse()`, `parseAsync()`,
 * `parser.complete()`, `suggest()`, or `getDocPage()`. Since environment
@@ -81,6 +89,18 @@ function createEnvContext(options = {}) {
 *  3. Default value
 *  4. Error
 *
+* > **Important:** `bindEnv()` only reads environment variables when its
+* > `EnvContext` is registered with the runner via the `contexts` option:
+* >
+* > ```typescript
+* > run(parser, { contexts: [envContext] });
+* > ```
+* >
+* > Omitting `contexts` causes `bindEnv()` to skip the env lookup and fall
+* > through to the default or an error.  When other contexts are registered
+* > but this env context is not, the error explicitly names the `contexts`
+* > option to aid diagnosis.
+*
 * @param parser Parser that reads CLI values.
 * @param options Environment binding options.
 * @returns A parser with environment fallback behavior.
@@ -294,10 +314,23 @@ function getEnvOrDefault(state, options, mode, innerParser, innerState, exec) {
 		success: true,
 		value: options.default
 	}));
+	const envContextAbsent = annotations != null && !(options.context.id in annotations);
 	if (innerParser != null) {
 		const completeState = innerState ?? (annotations != null && innerParser.initialState == null && (0, __optique_core_extension.getTraits)(innerParser).inheritsAnnotations === true ? (0, __optique_core_extension.injectAnnotations)(innerParser.initialState, annotations) : innerParser.initialState);
-		return (0, __optique_core_extension.wrapForMode)(mode, innerParser.complete(completeState, exec));
+		const innerResult = innerParser.complete(completeState, exec);
+		if (envContextAbsent) {
+			const unregisteredError = {
+				success: false,
+				error: __optique_core_message.message`Environment variable ${(0, __optique_core_message.envVar)(fullKey)} could not be read: the env context was not passed to run()'s contexts option.`
+			};
+			return (0, __optique_core_extension.mapModeValue)(mode, innerResult, (r) => r.success ? r : unregisteredError);
+		}
+		return (0, __optique_core_extension.wrapForMode)(mode, innerResult);
 	}
+	if (envContextAbsent) return (0, __optique_core_extension.wrapForMode)(mode, {
+		success: false,
+		error: __optique_core_message.message`Environment variable ${(0, __optique_core_message.envVar)(fullKey)} could not be read: the env 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 environment variable: ${(0, __optique_core_message.envVar)(fullKey)}`

package/dist/index.d.cts

@@ -48,6 +48,14 @@ interface EnvContextOptions {
 /**
  * Creates an environment context for use with Optique runners.
  *
+ * Pass the returned context to `run()`'s `contexts` option so that
+ * `bindEnv()` can read environment variables during parsing:
+ *
+ * ```typescript
+ * const envContext = createEnvContext({ prefix: "MYAPP_" });
+ * run(parser, { contexts: [envContext] });
+ * ```
+ *
  * When calling `context.getAnnotations()` manually, pass the returned
  * annotations to low-level APIs such as `parse()`, `parseAsync()`,
  * `parser.complete()`, `suggest()`, or `getDocPage()`. Since environment
@@ -99,6 +107,18 @@ interface BindEnvOptions<M extends Mode, TValue> {
  *  3. Default value
  *  4. Error
  *
+ * > **Important:** `bindEnv()` only reads environment variables when its
+ * > `EnvContext` is registered with the runner via the `contexts` option:
+ * >
+ * > ```typescript
+ * > run(parser, { contexts: [envContext] });
+ * > ```
+ * >
+ * > Omitting `contexts` causes `bindEnv()` to skip the env lookup and fall
+ * > through to the default or an error.  When other contexts are registered
+ * > but this env context is not, the error explicitly names the `contexts`
+ * > option to aid diagnosis.
+ *
  * @param parser Parser that reads CLI values.
  * @param options Environment binding options.
  * @returns A parser with environment fallback behavior.

package/dist/index.d.ts

@@ -48,6 +48,14 @@ interface EnvContextOptions {
 /**
  * Creates an environment context for use with Optique runners.
  *
+ * Pass the returned context to `run()`'s `contexts` option so that
+ * `bindEnv()` can read environment variables during parsing:
+ *
+ * ```typescript
+ * const envContext = createEnvContext({ prefix: "MYAPP_" });
+ * run(parser, { contexts: [envContext] });
+ * ```
+ *
  * When calling `context.getAnnotations()` manually, pass the returned
  * annotations to low-level APIs such as `parse()`, `parseAsync()`,
  * `parser.complete()`, `suggest()`, or `getDocPage()`. Since environment
@@ -99,6 +107,18 @@ interface BindEnvOptions<M extends Mode, TValue> {
  *  3. Default value
  *  4. Error
  *
+ * > **Important:** `bindEnv()` only reads environment variables when its
+ * > `EnvContext` is registered with the runner via the `contexts` option:
+ * >
+ * > ```typescript
+ * > run(parser, { contexts: [envContext] });
+ * > ```
+ * >
+ * > Omitting `contexts` causes `bindEnv()` to skip the env lookup and fall
+ * > through to the default or an error.  When other contexts are registered
+ * > but this env context is not, the error explicitly names the `contexts`
+ * > option to aid diagnosis.
+ *
  * @param parser Parser that reads CLI values.
  * @param options Environment binding options.
  * @returns A parser with environment fallback behavior.

package/dist/index.js

@@ -13,6 +13,14 @@ function defaultEnvSource(key) {
 /**
 * Creates an environment context for use with Optique runners.
 *
+* Pass the returned context to `run()`'s `contexts` option so that
+* `bindEnv()` can read environment variables during parsing:
+*
+* ```typescript
+* const envContext = createEnvContext({ prefix: "MYAPP_" });
+* run(parser, { contexts: [envContext] });
+* ```
+*
 * When calling `context.getAnnotations()` manually, pass the returned
 * annotations to low-level APIs such as `parse()`, `parseAsync()`,
 * `parser.complete()`, `suggest()`, or `getDocPage()`. Since environment
@@ -58,6 +66,18 @@ function createEnvContext(options = {}) {
 *  3. Default value
 *  4. Error
 *
+* > **Important:** `bindEnv()` only reads environment variables when its
+* > `EnvContext` is registered with the runner via the `contexts` option:
+* >
+* > ```typescript
+* > run(parser, { contexts: [envContext] });
+* > ```
+* >
+* > Omitting `contexts` causes `bindEnv()` to skip the env lookup and fall
+* > through to the default or an error.  When other contexts are registered
+* > but this env context is not, the error explicitly names the `contexts`
+* > option to aid diagnosis.
+*
 * @param parser Parser that reads CLI values.
 * @param options Environment binding options.
 * @returns A parser with environment fallback behavior.
@@ -271,10 +291,23 @@ function getEnvOrDefault(state, options, mode, innerParser, innerState, exec) {
 		success: true,
 		value: options.default
 	}));
+	const envContextAbsent = annotations != null && !(options.context.id in annotations);
 	if (innerParser != null) {
 		const completeState = innerState ?? (annotations != null && innerParser.initialState == null && getTraits(innerParser).inheritsAnnotations === true ? injectAnnotations(innerParser.initialState, annotations) : innerParser.initialState);
-		return wrapForMode(mode, innerParser.complete(completeState, exec));
+		const innerResult = innerParser.complete(completeState, exec);
+		if (envContextAbsent) {
+			const unregisteredError = {
+				success: false,
+				error: message`Environment variable ${envVar(fullKey)} could not be read: the env context was not passed to run()'s contexts option.`
+			};
+			return mapModeValue(mode, innerResult, (r) => r.success ? r : unregisteredError);
+		}
+		return wrapForMode(mode, innerResult);
 	}
+	if (envContextAbsent) return wrapForMode(mode, {
+		success: false,
+		error: message`Environment variable ${envVar(fullKey)} could not be read: the env context was not passed to run()'s contexts option.`
+	});
 	return wrapForMode(mode, {
 		success: false,
 		error: message`Missing required environment variable: ${envVar(fullKey)}`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/env",
-  "version": "1.1.0-dev.1998+3e697633",
+  "version": "1.1.0-dev.2053",
   "description": "Environment variable support for Optique",
   "keywords": [
     "CLI",
@@ -54,7 +54,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "1.1.0-dev.1998+3e697633"
+    "@optique/core": "1.1.0-dev.2053+ed892f45"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",