Mark .optional(() => ...) as non-experimental

Author: jviide

.changeset/calm-bugs-fail.md

@@ -0,0 +1,5 @@
+---
+"@badrap/valita": patch
+---
+
+Mark `.optional(() => ...)` as non-experimental and recommend it over the now-deprecated `.default(x)`

README.md

@@ -299,13 +299,13 @@ const t = v.string().optional();
 t.parse("Hello, World!");
 ```
 
-The `.default(...)` method can be used to set a default value for a missing or undefined value.
+An optional function can be used to replace a missing or undefined values with some other default value:
 
 ```ts
 const person = v.object({
   name: v.string(),
   // Set a sensible default for those unwilling to fill in their theme song
-  themeSong: v.string().default("Tribute"),
+  themeSong: v.string().optional(() => "Tribute"),
 });
 
 person.parse({ name: "Jane Doe", themeSong: "Never gonna give you up" });
@@ -316,6 +316,8 @@ person.parse({ name: "Jane Doe", themeSong: undefined });
 // { name: "Jane Doe", themeSong: "Tribute" }
 ```
 
+The default function is re-evaluated every for every missing or undefined value to avoid accidentally sharing mutable default values like objects or arrays between different parsed values.
+
 ### Array Types
 
 The `v.array(...)` combinator can be used to check that the value is an array, and that its items have a specific type. The validated arrays may be of arbitrary length, including empty arrays.

src/index.ts

@@ -437,7 +437,17 @@ abstract class AbstractType<Output = unknown> {
   abstract toTerminals(func: (t: TerminalType) => void): void;
   abstract func(v: unknown, flags: number): RawResult<Output>;
 
-  /** @experimental */
+  /**
+   * Return new optional type that can not be used as a standalone
+   * validator. Rather, it's meant to be used as a with object validators,
+   * to mark one of the object's properties as _optional_. Optional property
+   * types accept both the original type, `undefined` and missing properties.
+   *
+   * The optional `defaultFn` function, if provided, will be called each
+   * time a value that is missing or `undefined` is parsed.
+   *
+   * @param [defaultFn] - An optional function returning the default value.
+   */
   // Use `<X extends T>() => X` instead of `() => T` to make literal
   // inference work when an optionals with defaultFn is used as a
   // ObjectType property.
@@ -455,12 +465,6 @@ abstract class AbstractType<Output = unknown> {
     defaultFn: () => Exclude<Output, undefined>,
   ): Type<Exclude<Output, undefined>>;
   optional<T>(defaultFn: () => T): Type<Exclude<Output, undefined> | T>;
-  /**
-   * Return new optional type that can not be used as a standalone
-   * validator. Rather, it's meant to be used as a with object validators,
-   * to mark one of the object's properties as _optional_. Optional property
-   * types accept both the original type, `undefined` and missing properties.
-   */
   optional(): Optional<Output>;
   optional<T>(
     defaultFn?: () => T,
@@ -474,6 +478,9 @@ abstract class AbstractType<Output = unknown> {
     });
   }
 
+  /**
+   * @deprecated Instead of `.default(x)` use `.optional(() => x)`.
+   */
   default<T extends Literal>(
     defaultValue: T,
   ): Type<Exclude<Output, undefined> | T>;