paramour 0.9.0 → 0.10.0

package/dist/codec.d.ts

@@ -30,7 +30,7 @@ export type Arity = "many" | "single";
  * `Out` (which is an array type).
  */
 export interface Codec<Out, P extends Presence = "required", C extends boolean = false, A extends Arity = "single", E extends boolean = boolean> {
-    readonly catch: C extends false ? (fallback: (() => Out) | Out) => Codec<Out, P, true, A, E> : never;
+    readonly catch: C extends false ? (fallback: (() => CatchFallback<Out, P>) | CatchFallback<Out, P>) => Codec<Out, P, true, A, E> : never;
     /**
      * Overloaded so the value/factory split is visible in type-state: the
      * factory overload comes FIRST and must stay first. The runtime
@@ -48,8 +48,13 @@ export interface Codec<Out, P extends Presence = "required", C extends boolean =
     } : never : never;
     readonly optional: A extends "single" ? P extends "required" ? () => Codec<Out, "optional", C, A, E> : never : never;
     readonly "~arity": A;
-    /** Stored as a thunk regardless of the form passed to `.catch()`. */
-    readonly "~catchValue": (() => Out) | undefined;
+    /**
+     * Stored as a thunk regardless of the form passed to `.catch()`. The thunk
+     * may return `undefined` only on an `.optional()` codec (see
+     * {@link CatchFallback}); typed uniformly so every codec stays assignable
+     * to {@link AnyCodec}.
+     */
+    readonly "~catchValue": (() => Out | undefined) | undefined;
     readonly "~caught": C;
     /**
      * True when `.default()` received a value (not a factory). Value defaults
@@ -104,6 +109,17 @@ export type ParamCodec = Codec<any, "required", boolean>;
  */
 export type Presence = "defaulted" | "optional" | "required";
 export type PresenceOf<C extends AnyCodec> = C["~presence"];
+/**
+ * What `.catch()` may recover to. An `.optional()` codec already decodes to
+ * `Out | undefined`, so it may also recover a failed parse to *absent* —
+ * `undefined` — which is the honest fallback when no in-domain value means
+ * "nothing selected". This does not blur D2: the INPUT `.catch()` handles is
+ * still a present-but-malformed value, never absence. Every other presence
+ * keeps an `Out`-only fallback: a required or defaulted key must decode to a
+ * value. Non-distributive so the `Presence` union inside {@link AnyCodec}
+ * reads as `Out`, keeping concrete optional codecs assignable to it.
+ */
+type CatchFallback<Out, P extends Presence> = [P] extends ["optional"] ? Out | undefined : Out;
 /**
  * Rejects value-form `.default()` arguments whose static type includes any
  * function member: runtime {@link isFactory} would treat them as factories,

package/dist/codec.js

@@ -22,7 +22,28 @@ function build(state) {
             if (state.catchValue !== undefined) {
                 throw new ParamourError(".catch() may only be applied once");
             }
-            return build({ ...state, catchValue: toThunk(fallback, "catch") });
+            if (state.presence === "optional") {
+                return build({ ...state, catchValue: toThunk(fallback, "catch") });
+            }
+            // Only an optional key may recover to absent (CatchFallback). The
+            // value form fails here, at definition time; a factory's result is
+            // only knowable per decode, so it is checked there.
+            if (fallback === undefined) {
+                throw new ParamourError(".catch(undefined) requires .optional() first: only an optional key can recover to absent");
+            }
+            const thunk = toThunk(fallback, "catch");
+            return build({
+                ...state,
+                catchValue: isFactory(fallback)
+                    ? () => {
+                        const value = thunk();
+                        if (value === undefined) {
+                            throw new ParamourError(".catch() factory returned undefined on a non-optional codec: only an optional key can recover to absent");
+                        }
+                        return value;
+                    }
+                    : thunk,
+            });
         },
         default(value) {
             if (state.arity === "many") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paramour",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "exports": {
     ".": {