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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/dist/index.cjs +17 -18
  2. package/dist/index.d.cts +10 -5
  3. package/dist/index.d.ts +10 -5
  4. package/dist/index.js +17 -18
  5. package/package.json +3 -3
package/dist/index.cjs CHANGED
@@ -29,11 +29,7 @@ const __optique_core_message = __toESM(require("@optique/core/message"));
29
29
  const __optique_core_mode_dispatch = __toESM(require("@optique/core/mode-dispatch"));
30
30
 
31
31
  //#region src/index.ts
32
- const phase2UndefinedParsedValueKey = Symbol("@optique/config/phase2UndefinedParsedValue");
33
32
  const phase1ConfigAnnotationMarker = Symbol("@optique/config/phase1Annotation");
34
- function isPhase2UndefinedParsedValue(value) {
35
- return value != null && typeof value === "object" && phase2UndefinedParsedValueKey in value;
36
- }
37
33
  function getTypeName(value) {
38
34
  if (value === null) return "null";
39
35
  if (Array.isArray(value)) return "array";
@@ -94,11 +90,16 @@ function validateWithSchema(schema, rawData) {
94
90
  *
95
91
  * The config context implements the `SourceContext` interface and can be used
96
92
  * with `runWith()` from *@optique/core* or `run()`/`runAsync()` from
97
- * *@optique/run* to provide configuration file support.
98
- * When calling `context.getAnnotations()` manually, pass the returned
99
- * annotations to low-level APIs such as `parse()`, `parseAsync()`,
100
- * `parser.complete()`, `suggest()`, or `getDocPage()`. Calling
101
- * `getAnnotations()` by itself does not affect later parses.
93
+ * *@optique/run* to provide configuration file support. Each runner call
94
+ * receives its own annotation snapshot, so the same `ConfigContext`
95
+ * instance can be reused safely across independent or concurrent runs.
96
+ * When calling `context.getAnnotations()` manually, omit the request for a
97
+ * phase-1 snapshot or pass `{ phase: "phase2", parsed }` for a phase-two
98
+ * snapshot, then thread the returned annotations into low-level APIs such
99
+ * as `parse()`, `parseAsync()`, `parser.complete()`, `suggest()`, or
100
+ * `getDocPage()`. Calling `getAnnotations()` by itself does not affect
101
+ * later parses unless those returned annotations are explicitly threaded
102
+ * into a low-level API call.
102
103
  *
103
104
  * @template T The output type of the config schema.
104
105
  * @template TConfigMeta The metadata type for config sources.
@@ -132,21 +133,19 @@ function createConfigContext(options) {
132
133
  id: contextId,
133
134
  schema: rawSchema,
134
135
  phase: "two-pass",
135
- getInternalAnnotations(parsed, annotations) {
136
- if (parsed === void 0) return { [contextId]: phase1ConfigAnnotationMarker };
136
+ getInternalAnnotations(request, annotations) {
137
+ if (request.phase === "phase1") return { [contextId]: phase1ConfigAnnotationMarker };
137
138
  return Object.getOwnPropertySymbols(annotations).includes(contextId) ? void 0 : { [contextId]: void 0 };
138
139
  },
139
- finalizeParsed(parsed) {
140
- return parsed === void 0 ? { [phase2UndefinedParsedValueKey]: true } : parsed;
141
- },
142
- getAnnotations(parsed, runtimeOptions) {
143
- if (parsed === void 0) return {};
140
+ getAnnotations(request, runtimeOptions) {
141
+ if (request === void 0) return {};
142
+ 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)}.`);
143
+ if (request.phase === "phase1") return {};
144
144
  const opts = runtimeOptions;
145
145
  if (!opts || !opts.getConfigPath && !opts.load) throw new TypeError("Either getConfigPath or load must be provided in the runner options when using ConfigContext.");
146
146
  if (opts.load !== void 0 && typeof opts.load !== "function") throw new TypeError(`Expected load to be a function, but got: ${getTypeName(opts.load)}.`);
147
147
  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)}.`);
148
- const parsedValue = isPhase2UndefinedParsedValue(parsed) ? void 0 : parsed;
149
- const parsedPlaceholder = parsedValue;
148
+ const parsedPlaceholder = request.parsed;
150
149
  const emptyAnnotations = () => ({});
151
150
  const buildAnnotations = (configData, configMeta) => {
152
151
  if (configData === void 0 || configData === null) return emptyAnnotations();
package/dist/index.d.cts CHANGED
@@ -126,11 +126,16 @@ interface ConfigContext<T, TConfigMeta = ConfigMeta> extends SourceContext<Confi
126
126
  *
127
127
  * The config context implements the `SourceContext` interface and can be used
128
128
  * with `runWith()` from *@optique/core* or `run()`/`runAsync()` from
129
- * *@optique/run* to provide configuration file support.
130
- * When calling `context.getAnnotations()` manually, pass the returned
131
- * annotations to low-level APIs such as `parse()`, `parseAsync()`,
132
- * `parser.complete()`, `suggest()`, or `getDocPage()`. Calling
133
- * `getAnnotations()` by itself does not affect later parses.
129
+ * *@optique/run* to provide configuration file support. Each runner call
130
+ * receives its own annotation snapshot, so the same `ConfigContext`
131
+ * instance can be reused safely across independent or concurrent runs.
132
+ * When calling `context.getAnnotations()` manually, omit the request for a
133
+ * phase-1 snapshot or pass `{ phase: "phase2", parsed }` for a phase-two
134
+ * snapshot, then thread the returned annotations into low-level APIs such
135
+ * as `parse()`, `parseAsync()`, `parser.complete()`, `suggest()`, or
136
+ * `getDocPage()`. Calling `getAnnotations()` by itself does not affect
137
+ * later parses unless those returned annotations are explicitly threaded
138
+ * into a low-level API call.
134
139
  *
135
140
  * @template T The output type of the config schema.
136
141
  * @template TConfigMeta The metadata type for config sources.
package/dist/index.d.ts CHANGED
@@ -126,11 +126,16 @@ interface ConfigContext<T, TConfigMeta = ConfigMeta> extends SourceContext<Confi
126
126
  *
127
127
  * The config context implements the `SourceContext` interface and can be used
128
128
  * with `runWith()` from *@optique/core* or `run()`/`runAsync()` from
129
- * *@optique/run* to provide configuration file support.
130
- * When calling `context.getAnnotations()` manually, pass the returned
131
- * annotations to low-level APIs such as `parse()`, `parseAsync()`,
132
- * `parser.complete()`, `suggest()`, or `getDocPage()`. Calling
133
- * `getAnnotations()` by itself does not affect later parses.
129
+ * *@optique/run* to provide configuration file support. Each runner call
130
+ * receives its own annotation snapshot, so the same `ConfigContext`
131
+ * instance can be reused safely across independent or concurrent runs.
132
+ * When calling `context.getAnnotations()` manually, omit the request for a
133
+ * phase-1 snapshot or pass `{ phase: "phase2", parsed }` for a phase-two
134
+ * snapshot, then thread the returned annotations into low-level APIs such
135
+ * as `parse()`, `parseAsync()`, `parser.complete()`, `suggest()`, or
136
+ * `getDocPage()`. Calling `getAnnotations()` by itself does not affect
137
+ * later parses unless those returned annotations are explicitly threaded
138
+ * into a low-level API call.
134
139
  *
135
140
  * @template T The output type of the config schema.
136
141
  * @template TConfigMeta The metadata type for config sources.
package/dist/index.js CHANGED
@@ -6,11 +6,7 @@ import { message } from "@optique/core/message";
6
6
  import { mapModeValue, wrapForMode } from "@optique/core/mode-dispatch";
7
7
 
8
8
  //#region src/index.ts
9
- const phase2UndefinedParsedValueKey = Symbol("@optique/config/phase2UndefinedParsedValue");
10
9
  const phase1ConfigAnnotationMarker = Symbol("@optique/config/phase1Annotation");
11
- function isPhase2UndefinedParsedValue(value) {
12
- return value != null && typeof value === "object" && phase2UndefinedParsedValueKey in value;
13
- }
14
10
  function getTypeName(value) {
15
11
  if (value === null) return "null";
16
12
  if (Array.isArray(value)) return "array";
@@ -71,11 +67,16 @@ function validateWithSchema(schema, rawData) {
71
67
  *
72
68
  * The config context implements the `SourceContext` interface and can be used
73
69
  * with `runWith()` from *@optique/core* or `run()`/`runAsync()` from
74
- * *@optique/run* to provide configuration file support.
75
- * When calling `context.getAnnotations()` manually, pass the returned
76
- * annotations to low-level APIs such as `parse()`, `parseAsync()`,
77
- * `parser.complete()`, `suggest()`, or `getDocPage()`. Calling
78
- * `getAnnotations()` by itself does not affect later parses.
70
+ * *@optique/run* to provide configuration file support. Each runner call
71
+ * receives its own annotation snapshot, so the same `ConfigContext`
72
+ * instance can be reused safely across independent or concurrent runs.
73
+ * When calling `context.getAnnotations()` manually, omit the request for a
74
+ * phase-1 snapshot or pass `{ phase: "phase2", parsed }` for a phase-two
75
+ * snapshot, then thread the returned annotations into low-level APIs such
76
+ * as `parse()`, `parseAsync()`, `parser.complete()`, `suggest()`, or
77
+ * `getDocPage()`. Calling `getAnnotations()` by itself does not affect
78
+ * later parses unless those returned annotations are explicitly threaded
79
+ * into a low-level API call.
79
80
  *
80
81
  * @template T The output type of the config schema.
81
82
  * @template TConfigMeta The metadata type for config sources.
@@ -109,21 +110,19 @@ function createConfigContext(options) {
109
110
  id: contextId,
110
111
  schema: rawSchema,
111
112
  phase: "two-pass",
112
- getInternalAnnotations(parsed, annotations) {
113
- if (parsed === void 0) return { [contextId]: phase1ConfigAnnotationMarker };
113
+ getInternalAnnotations(request, annotations) {
114
+ if (request.phase === "phase1") return { [contextId]: phase1ConfigAnnotationMarker };
114
115
  return Object.getOwnPropertySymbols(annotations).includes(contextId) ? void 0 : { [contextId]: void 0 };
115
116
  },
116
- finalizeParsed(parsed) {
117
- return parsed === void 0 ? { [phase2UndefinedParsedValueKey]: true } : parsed;
118
- },
119
- getAnnotations(parsed, runtimeOptions) {
120
- if (parsed === void 0) return {};
117
+ getAnnotations(request, runtimeOptions) {
118
+ if (request === void 0) return {};
119
+ 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)}.`);
120
+ if (request.phase === "phase1") return {};
121
121
  const opts = runtimeOptions;
122
122
  if (!opts || !opts.getConfigPath && !opts.load) throw new TypeError("Either getConfigPath or load must be provided in the runner options when using ConfigContext.");
123
123
  if (opts.load !== void 0 && typeof opts.load !== "function") throw new TypeError(`Expected load to be a function, but got: ${getTypeName(opts.load)}.`);
124
124
  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)}.`);
125
- const parsedValue = isPhase2UndefinedParsedValue(parsed) ? void 0 : parsed;
126
- const parsedPlaceholder = parsedValue;
125
+ const parsedPlaceholder = request.parsed;
127
126
  const emptyAnnotations = () => ({});
128
127
  const buildAnnotations = (configData, configMeta) => {
129
128
  if (configData === void 0 || configData === null) return emptyAnnotations();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@optique/config",
3
- "version": "1.0.0-dev.1827+582707f5",
3
+ "version": "1.0.0-dev.1840+c09a37a0",
4
4
  "description": "Configuration file support for Optique with Standard Schema validation",
5
5
  "keywords": [
6
6
  "CLI",
@@ -59,7 +59,7 @@
59
59
  "@standard-schema/spec": "^1.1.0"
60
60
  },
61
61
  "dependencies": {
62
- "@optique/core": "1.0.0-dev.1827+582707f5"
62
+ "@optique/core": "1.0.0-dev.1840+c09a37a0"
63
63
  },
64
64
  "devDependencies": {
65
65
  "@standard-schema/spec": "^1.1.0",
@@ -67,7 +67,7 @@
67
67
  "tsdown": "^0.13.0",
68
68
  "typescript": "^5.8.3",
69
69
  "zod": "^3.25.0 || ^4.0.0",
70
- "@optique/env": "1.0.0-dev.1827+582707f5"
70
+ "@optique/env": "1.0.0-dev.1840+c09a37a0"
71
71
  },
72
72
  "scripts": {
73
73
  "build": "tsdown",