@optique/core 1.0.0-dev.921 → 1.0.0

package/dist/modifiers.d.cts

@@ -1,5 +1,5 @@
 import { Message } from "./message.cjs";
-import { Mode, Parser } from "./parser.cjs";
+import { Mode, Parser } from "./internal/parser.cjs";
 
 //#region src/modifiers.d.ts
 
@@ -123,6 +123,47 @@ declare function withDefault<M extends Mode, TValue, TState, const TDefault = TV
  * @param transform A function that transforms the parsed value from type T to type U.
  * @returns A {@link Parser} that produces the transformed value of type U
  *          while preserving the original parser's state type and parsing behavior.
+ * @throws Any exception thrown by `transform` when completing a non-deferred
+ *   value.  Errors from deferred placeholder transforms are caught and the
+ *   mapped result falls back to `undefined` with `deferred: true`.
+ *
+ * ### Deferred prompt interaction
+ *
+ * During two-phase parsing, `map()` propagates the `deferred` flag from
+ * inner results but intentionally drops per-field `deferredKeys`.  The
+ * inner key set describes the *input* shape, but `transform` produces an
+ * arbitrary *output* shape where keys may be renamed, dropped, or reused
+ * with different semantics.  For `object()` results that are *not*
+ * wrapped in `map()`, per-field deferred stripping works normally.
+ *
+ * Because the `deferred` flag is propagated conservatively, mapped scalar
+ * results are treated as missing (`undefined`) during phase-two context
+ * collection — even when `transform` only used non-deferred fields.
+ * For example, `map(object({ apiKey: prompt(...), mode: option(...) }),
+ * v => v.mode)` makes phase-two contexts see `undefined` instead of the
+ * real `mode` value.  This is the intentional trade-off: the alternative
+ * (not propagating `deferred`) would leak placeholder values into context
+ * resolution when `transform` *does* use deferred fields.  The final
+ * parse always produces the correct result regardless.
+ *
+ * If the transform throws on a deferred placeholder value, the mapped
+ * result falls back to `undefined` with `deferred: true`, so the first
+ * pass does not abort.
+ *
+ * ### Transform purity
+ *
+ * The `transform` function must not mutate its input.  Object and array
+ * values may be shared placeholder references during deferred prompt
+ * resolution, and in-place mutations would corrupt the placeholder for
+ * subsequent parses.  Always return a new value:
+ *
+ * ```typescript
+ * // ✅ Correct — creates a new object
+ * map(parser, v => ({ ...v, host: "override" }))
+ *
+ * // ❌ Wrong — mutates the input in place
+ * map(parser, v => { v.host = "override"; return v; })
+ * ```
  *
  * @example
  * ```typescript

package/dist/modifiers.d.ts

@@ -1,5 +1,5 @@
 import { Message } from "./message.js";
-import { Mode, Parser } from "./parser.js";
+import { Mode, Parser } from "./internal/parser.js";
 
 //#region src/modifiers.d.ts
 
@@ -123,6 +123,47 @@ declare function withDefault<M extends Mode, TValue, TState, const TDefault = TV
  * @param transform A function that transforms the parsed value from type T to type U.
  * @returns A {@link Parser} that produces the transformed value of type U
  *          while preserving the original parser's state type and parsing behavior.
+ * @throws Any exception thrown by `transform` when completing a non-deferred
+ *   value.  Errors from deferred placeholder transforms are caught and the
+ *   mapped result falls back to `undefined` with `deferred: true`.
+ *
+ * ### Deferred prompt interaction
+ *
+ * During two-phase parsing, `map()` propagates the `deferred` flag from
+ * inner results but intentionally drops per-field `deferredKeys`.  The
+ * inner key set describes the *input* shape, but `transform` produces an
+ * arbitrary *output* shape where keys may be renamed, dropped, or reused
+ * with different semantics.  For `object()` results that are *not*
+ * wrapped in `map()`, per-field deferred stripping works normally.
+ *
+ * Because the `deferred` flag is propagated conservatively, mapped scalar
+ * results are treated as missing (`undefined`) during phase-two context
+ * collection — even when `transform` only used non-deferred fields.
+ * For example, `map(object({ apiKey: prompt(...), mode: option(...) }),
+ * v => v.mode)` makes phase-two contexts see `undefined` instead of the
+ * real `mode` value.  This is the intentional trade-off: the alternative
+ * (not propagating `deferred`) would leak placeholder values into context
+ * resolution when `transform` *does* use deferred fields.  The final
+ * parse always produces the correct result regardless.
+ *
+ * If the transform throws on a deferred placeholder value, the mapped
+ * result falls back to `undefined` with `deferred: true`, so the first
+ * pass does not abort.
+ *
+ * ### Transform purity
+ *
+ * The `transform` function must not mutate its input.  Object and array
+ * values may be shared placeholder references during deferred prompt
+ * resolution, and in-place mutations would corrupt the placeholder for
+ * subsequent parses.  Always return a new value:
+ *
+ * ```typescript
+ * // ✅ Correct — creates a new object
+ * map(parser, v => ({ ...v, host: "override" }))
+ *
+ * // ❌ Wrong — mutates the input in place
+ * map(parser, v => { v.host = "override"; return v; })
+ * ```
  *
  * @example
  * ```typescript