effect 4.0.0-beta.46 → 4.0.0-beta.48

package/dist/Schema.js

@@ -233,7 +233,7 @@ export function declare(is, annotations) {
  * const bottom = Schema.revealBottom(schema)
  *
  * // `bottom` now exposes Type, Encoded, DecodingServices, EncodingServices,
- * // ast, ~rebuild.out, ~type.make.in, Iso, ~type.parameters, etc.
+ * // ast, Rebuild, ~type.make.in, Iso, ~type.parameters, etc.
  * type T = typeof bottom["Type"]     // string
  * type E = typeof bottom["Encoded"]  // string
  * ```
@@ -264,13 +264,44 @@ export function revealBottom(bottom) {
  * )
  * ```
  *
+ * @see {@link annotateEncoded} to annotate the encoded side instead.
+ *
  * @category Annotations
  * @since 4.0.0
  */
 export function annotate(annotations) {
-  return self => {
-    return self.annotate(annotations);
-  };
+  return self => self.annotate(annotations);
+}
+/**
+ * Adds metadata annotations to the **encoded** side of a schema without
+ * changing its runtime behavior. This is the encoded-side counterpart of
+ * `annotate`, which targets the decoded (Type) side.
+ *
+ * Internally the schema is flipped so that `Encoded` becomes `Type`,
+ * annotated, and then flipped back.
+ *
+ * **Example** (Adding a title to the encoded representation)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const schema = Schema.NumberFromString.pipe(
+ *   Schema.annotateEncoded({
+ *     title: "my title"
+ *   })
+ * )
+ *
+ * console.log(Schema.toEncoded(schema).ast.annotations?.title)
+ * // "my title"
+ * ```
+ *
+ * @see {@link annotate} to annotate the type side instead.
+ *
+ * @category Annotations
+ * @since 4.0.0
+ */
+export function annotateEncoded(annotations) {
+  return self => flip(flip(self).annotate(annotations));
 }
 /**
  * Adds key-level annotations to a schema field. This is the pipeable
@@ -2017,18 +2048,18 @@ defaultValue) {
   });
 }
 /**
- * **Options**
+ * Makes a struct key optional on the `Encoded` side and provides a default
+ * `Encoded` value when the key is missing during decoding.
  *
- * - `encodingStrategy`: The strategy to use when encoding.
- *   - `passthrough`: (default) Pass the default value through to the output.
- *   - `omit`: Omit the value from the output.
+ * The key uses `optionalKey` on the encoded side, so it may be absent from the
+ * input object but **not** `undefined`. The default value is specified in terms
+ * of the `Encoded` type (before any decoding transformations).
  *
- * Provides a default value for a missing key during decoding.
+ * **Options**
  *
- * When the key is absent from the input, `defaultValue()` is called to supply a value.
- * During encoding, the behavior is controlled by `options.encodingStrategy`:
- * - `"passthrough"` (default): include the value in the output
- * - `"omit"`: omit the key from the output
+ * - `encodingStrategy`:
+ *   - `"passthrough"` (default): include the value in the encoded output.
+ *   - `"omit"`: omit the key from the encoded output.
  *
  * **Example** (Default for a missing struct key)
  *
@@ -2043,7 +2074,8 @@ defaultValue) {
  * // result: { name: "anonymous" }
  * ```
  *
- * @see {@link withDecodingDefault} for the `optional` (value-level) variant
+ * @see {@link withDecodingDefault} for the value-level variant (key absent **or** `undefined`)
+ * @see {@link withDecodingDefaultTypeKey} for the variant where the default is a `Type` value
  * @since 4.0.0
  */
 export function withDecodingDefaultKey(defaultValue, options) {
@@ -2056,21 +2088,42 @@ export function withDecodingDefaultKey(defaultValue, options) {
   };
 }
 /**
+ * Makes a struct key optional on the `Encoded` side (`optionalKey`, so the
+ * key may be absent but **not** `undefined`) and provides a default `Type`
+ * value when the key is missing during decoding.
+ *
+ * Unlike {@link withDecodingDefaultKey}, the default value is specified in
+ * terms of the `Type` (decoded) representation, so it does not need to go
+ * through the decoding transformation.
+ *
  * **Options**
  *
- * - `encodingStrategy`: The strategy to use when encoding.
- *   - `passthrough`: (default) Pass the default value through to the output.
- *   - `omit`: Omit the value from the output.
+ * - `encodingStrategy`:
+ *   - `"passthrough"` (default): include the value in the encoded output.
+ *   - `"omit"`: omit the key from the encoded output.
  *
- * Provides a default value for an `optional` field during decoding.
+ * @see {@link withDecodingDefaultKey} for the variant where the default is an `Encoded` value
+ * @see {@link withDecodingDefaultType} for the value-level variant
+ * @since 4.0.0
+ */
+export function withDecodingDefaultTypeKey(defaultValue, options) {
+  return self => {
+    return toType(self).pipe(withDecodingDefaultKey(defaultValue, options), encodeTo(optionalKey(self)));
+  };
+}
+/**
+ * Wraps the `Encoded` side with `optional` (key absent **or** `undefined`)
+ * and provides a default `Encoded` value when the field is missing or
+ * `undefined` during decoding.
  *
- * Similar to {@link withDecodingDefaultKey} but works on `optional` (value-level optional)
- * rather than `optionalKey` (key-level optional).
+ * The default value is specified in terms of the `Encoded` type (before any
+ * decoding transformations).
  *
- * When the value is `undefined` or absent, `defaultValue()` is called to supply a value.
- * During encoding, the behavior is controlled by `options.encodingStrategy`:
- * - `"passthrough"` (default): include the value in the output
- * - `"omit"`: omit the value from the output
+ * **Options**
+ *
+ * - `encodingStrategy`:
+ *   - `"passthrough"` (default): include the value in the encoded output.
+ *   - `"omit"`: omit the key from the encoded output.
  *
  * **Example** (Default for an optional field value)
  *
@@ -2085,7 +2138,8 @@ export function withDecodingDefaultKey(defaultValue, options) {
  * // result: { name: "anonymous" }
  * ```
  *
- * @see {@link withDecodingDefaultKey} for the key-level variant
+ * @see {@link withDecodingDefaultKey} for the key-level variant (key absent only, not `undefined`)
+ * @see {@link withDecodingDefaultType} for the variant where the default is a `Type` value
  * @since 4.0.0
  */
 export function withDecodingDefault(defaultValue, options) {
@@ -2097,6 +2151,30 @@ export function withDecodingDefault(defaultValue, options) {
     }));
   };
 }
+/**
+ * Wraps the `Encoded` side with `optional` (key absent **or** `undefined`)
+ * and provides a default `Type` value when the field is missing or
+ * `undefined` during decoding.
+ *
+ * Unlike {@link withDecodingDefault}, the default value is specified in terms
+ * of the `Type` (decoded) representation, so it does not need to go through
+ * the decoding transformation.
+ *
+ * **Options**
+ *
+ * - `encodingStrategy`:
+ *   - `"passthrough"` (default): include the value in the encoded output.
+ *   - `"omit"`: omit the key from the encoded output.
+ *
+ * @see {@link withDecodingDefault} for the variant where the default is an `Encoded` value
+ * @see {@link withDecodingDefaultTypeKey} for the key-level variant
+ * @since 4.0.0
+ */
+export function withDecodingDefaultType(defaultValue, options) {
+  return self => {
+    return toType(self).pipe(withDecodingDefault(defaultValue, options), encodeTo(optional(self)));
+  };
+}
 /**
  * Combines a {@link Literal} schema with {@link withConstructorDefault}, making it ideal
  * for discriminator fields in tagged unions. When constructing via `make`, the
@@ -6180,10 +6258,10 @@ function makeClass(Inherited, identifier, struct, annotations, proto) {
   const ClassTypeId = getClassTypeId(identifier); // HMR support
   const out = class extends Inherited {
     constructor(...[input, options]) {
-      const props = input ?? {};
-      const validated = struct.make(props, options);
+      input = input ?? {};
+      const validated = struct.make(input, options);
       super({
-        ...props,
+        ...input,
         ...validated
       }, {
         ...options,
@@ -6209,11 +6287,11 @@ function makeClass(Inherited, identifier, struct, annotations, proto) {
     static make(input, options) {
       return new this(input, options);
     }
-    static makeEffect(input, options) {
-      return Effect.mapErrorEager(Parser.makeEffect(getClassSchema(this))(input, options), issue => new SchemaError(issue));
-    }
     static makeOption(input, options) {
-      return Parser.makeOption(getClassSchema(this))(input, options);
+      return Parser.makeOption(getClassSchema(this))(input ?? {}, options);
+    }
+    static makeEffect(input, options) {
+      return Effect.mapErrorEager(Parser.makeEffect(getClassSchema(this))(input ?? {}, options), issue => new SchemaError(issue));
     }
     static annotate(annotations) {
       return this.rebuild(AST.annotate(this.ast, annotations));