@optique/config 1.0.0-dev.1828 → 1.0.0-dev.1840

package/dist/index.cjs

@@ -29,11 +29,7 @@ const __optique_core_message = __toESM(require("@optique/core/message"));
 const __optique_core_mode_dispatch = __toESM(require("@optique/core/mode-dispatch"));
 
 //#region src/index.ts
-const phase2UndefinedParsedValueKey = Symbol("@optique/config/phase2UndefinedParsedValue");
 const phase1ConfigAnnotationMarker = Symbol("@optique/config/phase1Annotation");
-function isPhase2UndefinedParsedValue(value) {
-	return value != null && typeof value === "object" && phase2UndefinedParsedValueKey in value;
-}
 function getTypeName(value) {
 	if (value === null) return "null";
 	if (Array.isArray(value)) return "array";
@@ -97,11 +93,13 @@ function validateWithSchema(schema, rawData) {
 * *@optique/run* to provide configuration file support. Each runner call
 * receives its own annotation snapshot, so the same `ConfigContext`
 * instance can be reused safely across independent or concurrent runs.
-* When calling `context.getAnnotations()` manually, pass the returned
-* annotations to low-level APIs such as `parse()`, `parseAsync()`,
-* `parser.complete()`, `suggest()`, or `getDocPage()`. Calling
-* `getAnnotations()` by itself does not affect later parses unless those
-* returned annotations are explicitly threaded into a low-level API call.
+* When calling `context.getAnnotations()` manually, omit the request for a
+* phase-1 snapshot or pass `{ phase: "phase2", parsed }` for a phase-two
+* snapshot, then thread the returned annotations into low-level APIs such
+* as `parse()`, `parseAsync()`, `parser.complete()`, `suggest()`, or
+* `getDocPage()`. Calling `getAnnotations()` by itself does not affect
+* later parses unless those returned annotations are explicitly threaded
+* into a low-level API call.
 *
 * @template T The output type of the config schema.
 * @template TConfigMeta The metadata type for config sources.
@@ -135,21 +133,19 @@ function createConfigContext(options) {
 		id: contextId,
 		schema: rawSchema,
 		phase: "two-pass",
-		getInternalAnnotations(parsed, annotations) {
-			if (parsed === void 0) return { [contextId]: phase1ConfigAnnotationMarker };
+		getInternalAnnotations(request, annotations) {
+			if (request.phase === "phase1") return { [contextId]: phase1ConfigAnnotationMarker };
 			return Object.getOwnPropertySymbols(annotations).includes(contextId) ? void 0 : { [contextId]: void 0 };
 		},
-		finalizeParsed(parsed) {
-			return parsed === void 0 ? { [phase2UndefinedParsedValueKey]: true } : parsed;
-		},
-		getAnnotations(parsed, runtimeOptions) {
-			if (parsed === void 0) return {};
+		getAnnotations(request, runtimeOptions) {
+			if (request === void 0) return {};
+			if (request === null || typeof request !== "object" || !("phase" in request) || request.phase !== "phase1" && request.phase !== "phase2" || request.phase === "phase2" && !("parsed" in request)) throw new TypeError(`Expected getAnnotations() to receive no request or a SourceContextRequest ({ phase: "phase1" } or { phase: "phase2", parsed }), but got: ${getTypeName(request)}.`);
+			if (request.phase === "phase1") return {};
 			const opts = runtimeOptions;
 			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)}.`);
-			const parsedValue = isPhase2UndefinedParsedValue(parsed) ? void 0 : parsed;
-			const parsedPlaceholder = parsedValue;
+			const parsedPlaceholder = request.parsed;
 			const emptyAnnotations = () => ({});
 			const buildAnnotations = (configData, configMeta) => {
 				if (configData === void 0 || configData === null) return emptyAnnotations();

package/dist/index.d.cts

@@ -129,11 +129,13 @@ interface ConfigContext<T, TConfigMeta = ConfigMeta> extends SourceContext<Confi
  * *@optique/run* to provide configuration file support. Each runner call
  * receives its own annotation snapshot, so the same `ConfigContext`
  * instance can be reused safely across independent or concurrent runs.
- * When calling `context.getAnnotations()` manually, pass the returned
- * annotations to low-level APIs such as `parse()`, `parseAsync()`,
- * `parser.complete()`, `suggest()`, or `getDocPage()`. Calling
- * `getAnnotations()` by itself does not affect later parses unless those
- * returned annotations are explicitly threaded into a low-level API call.
+ * When calling `context.getAnnotations()` manually, omit the request for a
+ * phase-1 snapshot or pass `{ phase: "phase2", parsed }` for a phase-two
+ * snapshot, then thread the returned annotations into low-level APIs such
+ * as `parse()`, `parseAsync()`, `parser.complete()`, `suggest()`, or
+ * `getDocPage()`. Calling `getAnnotations()` by itself does not affect
+ * later parses unless those returned annotations are explicitly threaded
+ * into a low-level API call.
  *
  * @template T The output type of the config schema.
  * @template TConfigMeta The metadata type for config sources.

package/dist/index.d.ts

@@ -129,11 +129,13 @@ interface ConfigContext<T, TConfigMeta = ConfigMeta> extends SourceContext<Confi
  * *@optique/run* to provide configuration file support. Each runner call
  * receives its own annotation snapshot, so the same `ConfigContext`
  * instance can be reused safely across independent or concurrent runs.
- * When calling `context.getAnnotations()` manually, pass the returned
- * annotations to low-level APIs such as `parse()`, `parseAsync()`,
- * `parser.complete()`, `suggest()`, or `getDocPage()`. Calling
- * `getAnnotations()` by itself does not affect later parses unless those
- * returned annotations are explicitly threaded into a low-level API call.
+ * When calling `context.getAnnotations()` manually, omit the request for a
+ * phase-1 snapshot or pass `{ phase: "phase2", parsed }` for a phase-two
+ * snapshot, then thread the returned annotations into low-level APIs such
+ * as `parse()`, `parseAsync()`, `parser.complete()`, `suggest()`, or
+ * `getDocPage()`. Calling `getAnnotations()` by itself does not affect
+ * later parses unless those returned annotations are explicitly threaded
+ * into a low-level API call.
  *
  * @template T The output type of the config schema.
  * @template TConfigMeta The metadata type for config sources.

package/dist/index.js

@@ -6,11 +6,7 @@ import { message } from "@optique/core/message";
 import { mapModeValue, wrapForMode } from "@optique/core/mode-dispatch";
 
 //#region src/index.ts
-const phase2UndefinedParsedValueKey = Symbol("@optique/config/phase2UndefinedParsedValue");
 const phase1ConfigAnnotationMarker = Symbol("@optique/config/phase1Annotation");
-function isPhase2UndefinedParsedValue(value) {
-	return value != null && typeof value === "object" && phase2UndefinedParsedValueKey in value;
-}
 function getTypeName(value) {
 	if (value === null) return "null";
 	if (Array.isArray(value)) return "array";
@@ -74,11 +70,13 @@ function validateWithSchema(schema, rawData) {
 * *@optique/run* to provide configuration file support. Each runner call
 * receives its own annotation snapshot, so the same `ConfigContext`
 * instance can be reused safely across independent or concurrent runs.
-* When calling `context.getAnnotations()` manually, pass the returned
-* annotations to low-level APIs such as `parse()`, `parseAsync()`,
-* `parser.complete()`, `suggest()`, or `getDocPage()`. Calling
-* `getAnnotations()` by itself does not affect later parses unless those
-* returned annotations are explicitly threaded into a low-level API call.
+* When calling `context.getAnnotations()` manually, omit the request for a
+* phase-1 snapshot or pass `{ phase: "phase2", parsed }` for a phase-two
+* snapshot, then thread the returned annotations into low-level APIs such
+* as `parse()`, `parseAsync()`, `parser.complete()`, `suggest()`, or
+* `getDocPage()`. Calling `getAnnotations()` by itself does not affect
+* later parses unless those returned annotations are explicitly threaded
+* into a low-level API call.
 *
 * @template T The output type of the config schema.
 * @template TConfigMeta The metadata type for config sources.
@@ -112,21 +110,19 @@ function createConfigContext(options) {
 		id: contextId,
 		schema: rawSchema,
 		phase: "two-pass",
-		getInternalAnnotations(parsed, annotations) {
-			if (parsed === void 0) return { [contextId]: phase1ConfigAnnotationMarker };
+		getInternalAnnotations(request, annotations) {
+			if (request.phase === "phase1") return { [contextId]: phase1ConfigAnnotationMarker };
 			return Object.getOwnPropertySymbols(annotations).includes(contextId) ? void 0 : { [contextId]: void 0 };
 		},
-		finalizeParsed(parsed) {
-			return parsed === void 0 ? { [phase2UndefinedParsedValueKey]: true } : parsed;
-		},
-		getAnnotations(parsed, runtimeOptions) {
-			if (parsed === void 0) return {};
+		getAnnotations(request, runtimeOptions) {
+			if (request === void 0) return {};
+			if (request === null || typeof request !== "object" || !("phase" in request) || request.phase !== "phase1" && request.phase !== "phase2" || request.phase === "phase2" && !("parsed" in request)) throw new TypeError(`Expected getAnnotations() to receive no request or a SourceContextRequest ({ phase: "phase1" } or { phase: "phase2", parsed }), but got: ${getTypeName(request)}.`);
+			if (request.phase === "phase1") return {};
 			const opts = runtimeOptions;
 			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)}.`);
-			const parsedValue = isPhase2UndefinedParsedValue(parsed) ? void 0 : parsed;
-			const parsedPlaceholder = parsedValue;
+			const parsedPlaceholder = request.parsed;
 			const emptyAnnotations = () => ({});
 			const buildAnnotations = (configData, configMeta) => {
 				if (configData === void 0 || configData === null) return emptyAnnotations();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/config",
-  "version": "1.0.0-dev.1828+b245a686",
+  "version": "1.0.0-dev.1840+c09a37a0",
   "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.1828+b245a686"
+    "@optique/core": "1.0.0-dev.1840+c09a37a0"
   },
   "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.1828+b245a686"
+    "@optique/env": "1.0.0-dev.1840+c09a37a0"
   },
   "scripts": {
     "build": "tsdown",