effect 4.0.0-beta.85 → 4.0.0-beta.87

package/dist/Schema.js

@@ -87,7 +87,7 @@ const TypeId = InternalSchema.TypeId;
  * const isBox = (u: unknown): u is Box<unknown> =>
  *   typeof u === "object" && u !== null && "value" in u
  *
- * const Box = <A extends Schema.Top>(item: A) =>
+ * const Box = <A extends Schema.Constraint>(item: A) =>
  *   Schema.declareConstructor<Box<A["Type"]>, Box<A["Encoded"]>>()(
  *     [item],
  *     ([itemCodec]) =>
@@ -813,7 +813,7 @@ export const decodeUnknownOption = SchemaParser.decodeUnknownOption;
  * @category decoding
  * @since 3.10.0
  */
-export const decodeOption = decodeUnknownOption;
+export const decodeOption = SchemaParser.decodeOption;
 /**
  * Decodes an `unknown` input against a schema, returning a `Result` that
  * succeeds with the decoded value or fails with a {@link SchemaError} for schema
@@ -1194,7 +1194,7 @@ export const encodeUnknownOption = SchemaParser.encodeUnknownOption;
  * @category encoding
  * @since 3.10.0
  */
-export const encodeOption = encodeUnknownOption;
+export const encodeOption = SchemaParser.encodeOption;
 /**
  * Encodes an `unknown` input against a schema, returning a `Result` that
  * succeeds with the encoded value or fails with a {@link SchemaError} for schema
@@ -2064,6 +2064,13 @@ export function Record(key, value, options) {
  * Extends a struct schema with one or more record (index-signature) schemas,
  * producing a schema whose decoded type intersects the struct and all records.
  *
+ * **Gotchas**
+ *
+ * TypeScript index signatures also apply to fixed keys. `StructWithRest` does
+ * not reject incompatible fixed fields at the call site; use
+ * `StructWithRest.ValidateRecords` when you want an explicit type-level
+ * compatibility check.
+ *
  * **Example** (Defining structs with string-indexed extra keys)
  *
  * ```ts
@@ -2568,7 +2575,7 @@ export function catchDecoding(f) {
  * @since 4.0.0
  */
 export function catchDecodingWithContext(f) {
-  return self => self.pipe(middlewareDecoding(Effect.catchEager(f)));
+  return self => middlewareDecoding(Effect.catchEager(f))(self);
 }
 /**
  * Recovers from an encoding error by providing a fallback value.
@@ -2606,7 +2613,7 @@ export function catchEncoding(f) {
  * @since 4.0.0
  */
 export function catchEncodingWithContext(f) {
-  return self => self.pipe(middlewareEncoding(Effect.catchEager(f)));
+  return self => middlewareEncoding(Effect.catchEager(f))(self);
 }
 export function decodeTo(to, transformation) {
   return from => {
@@ -2661,12 +2668,12 @@ export function decodeTo(to, transformation) {
  */
 export function decode(transformation) {
   return self => {
-    return self.pipe(decodeTo(toType(self), transformation));
+    return decodeTo(toType(self), transformation)(self);
   };
 }
 export function encodeTo(to, transformation) {
   return from => {
-    return transformation ? to.pipe(decodeTo(from, transformation)) : to.pipe(decodeTo(from));
+    return transformation ? decodeTo(from, transformation)(to) : decodeTo(from)(to);
   };
 }
 /**
@@ -2696,7 +2703,7 @@ export function encodeTo(to, transformation) {
  */
 export function encode(transformation) {
   return self => {
-    return toEncoded(self).pipe(decodeTo(self, transformation));
+    return decodeTo(self, transformation)(toEncoded(self));
   };
 }
 /**
@@ -5228,6 +5235,7 @@ export function Result(success, failure) {
  *   into JSON, it will fail with an error. This is useful when the wrapped schema is
  *   sensitive and should not be exposed in JSON.
  *
+ * @see {@link RedactedFromValue} for decoding raw values and wrapping them in `Redacted`.
  * @category Redacted
  * @since 3.10.0
  */
@@ -5286,13 +5294,14 @@ export function Redacted(value, options) {
  * @since 4.0.0
  */
 export function redact(schema) {
-  return schema.pipe(middlewareDecoding(Effect.mapErrorEager(SchemaIssue.redact)));
+  return middlewareDecoding(Effect.mapErrorEager(SchemaIssue.redact))(schema);
 }
 /**
  * Decodes a value and wraps it in `Redacted<A>`. Unlike {@link Redacted} which
  * expects the input to already be a `Redacted` instance, this schema decodes
  * the raw value and wraps it.
  *
+ * @see {@link Redacted} for schemas whose input is already a `Redacted` value.
  * @category Redacted
  * @since 4.0.0
  */
@@ -6654,10 +6663,8 @@ export const FormData = /*#__PURE__*/instanceOf(globalThis.FormData, {
  *
  * You can express nested values using bracket notation.
  *
- * If you want to decode values that are not strings, use
- * `Schema.toCodecStringTree` with the `keepDeclarations: true` option.
- * This serializer preserves values such as numbers and `Blob` objects when
- * compatible with the schema.
+ * If you want to decode string fields into non-string primitive values, use
+ * `Schema.toCodecStringTree`.
  *
  * **Example** (Decoding a flat structure)
  *
@@ -6711,8 +6718,7 @@ export const FormData = /*#__PURE__*/instanceOf(globalThis.FormData, {
  *   Schema.toCodecStringTree(
  *     Schema.Struct({
  *       a: Schema.Int
- *     }),
- *     { keepDeclarations: true }
+ *     })
  *   )
  * )
  *
@@ -7530,25 +7536,25 @@ function getClassTypeId(identifier) {
 function getClassSchemaFactory(from, identifier, annotations) {
   let memo;
   return self => {
-    if (memo === undefined) {
-      const transformation = getClassTransformation(self);
-      const to = make(new SchemaAST.Declaration([from.ast], () => (input, ast) => {
-        return input instanceof self || Predicate.hasProperty(input, getClassTypeId(identifier)) ? Effect.succeed(input) : Effect.fail(new SchemaIssue.InvalidType(ast, Option_.some(input)));
-      }, {
-        identifier,
-        [SchemaAST.ClassTypeId]: ([from]) => new SchemaAST.Link(from, transformation),
-        toCodec: ([from]) => new SchemaAST.Link(from.ast, transformation),
-        toArbitrary: ([from]) => () => ({
-          arbitrary: from.arbitrary.map(args => new self(args)),
-          terminal: from.terminal?.map(args => new self(args))
-        }),
-        toFormatter: ([from]) => t => `${self.identifier}(${from(t)})`,
-        "~sentinels": SchemaAST.collectSentinels(from.ast),
-        ...annotations
-      }));
-      memo = from.pipe(decodeTo(to, transformation));
+    if (memo !== undefined) {
+      return memo;
     }
-    return memo;
+    const transformation = getClassTransformation(self);
+    const to = make(new SchemaAST.Declaration([from.ast], () => (input, ast) => {
+      return input instanceof self || Predicate.hasProperty(input, getClassTypeId(identifier)) ? Effect.succeed(input) : Effect.fail(new SchemaIssue.InvalidType(ast, Option_.some(input)));
+    }, {
+      identifier,
+      [SchemaAST.ClassTypeId]: ([from]) => new SchemaAST.Link(from, transformation),
+      toCodec: ([from]) => new SchemaAST.Link(from.ast, transformation),
+      toArbitrary: ([from]) => () => ({
+        arbitrary: from.arbitrary.map(args => new self(args)),
+        terminal: from.terminal?.map(args => new self(args))
+      }),
+      toFormatter: ([from]) => t => `${self.identifier}(${from(t)})`,
+      "~sentinels": SchemaAST.collectSentinels(from.ast),
+      ...annotations
+    }));
+    return memo = decodeTo(to, transformation)(from);
   };
 }
 function isStruct(schema) {
@@ -8011,9 +8017,6 @@ export function toJsonSchemaDocument(schema, options) {
     definitions: jd.definitions
   };
 }
-// -----------------------------------------------------------------------------
-// Canonical Codecs
-// -----------------------------------------------------------------------------
 /**
  * Derives a canonical JSON codec from a schema. The encoded form is `Json`, and
  * decoding produces the schema's `Type`.
@@ -8022,9 +8025,11 @@ export function toJsonSchemaDocument(schema, options) {
  * @since 4.0.0
  */
 export function toCodecJson(schema) {
-  return make(toCodecJsonTop(schema.ast));
+  return make(toCodecJsonTop(schema.ast), {
+    schema
+  });
 }
-const toCodecJsonTop = /*#__PURE__*/SchemaAST.toCodec(ast => {
+const toCodecJsonTop = /*#__PURE__*/SchemaAST.applyToSelfOrLastLinkEncoding(ast => {
   const out = toCodecJsonBase(ast, toCodecJsonTop);
   return out !== ast && SchemaAST.isOptional(ast) ? SchemaAST.optionalKeyLastLink(out) : out;
 });
@@ -8111,8 +8116,43 @@ function toCodecIsoBase(ast, recur) {
   }
   return ast;
 }
-export function toCodecStringTree(schema, options) {
-  return make(toCodecEnsureArray(options?.keepDeclarations === true ? serializerStringTreeKeepDeclarations(schema.ast) : serializerStringTree(schema.ast)));
+/**
+ * Converts a schema to the StringTree canonical codec, where every leaf value
+ * becomes a string while preserving the original structure.
+ *
+ * **Details**
+ *
+ * Declarations are converted to `undefined` (unless they have a
+ * `toCodecJson` or `toCodec` annotation).
+ *
+ * @category Canonical Codecs
+ * @since 4.0.0
+ */
+export function toCodecStringTree(schema) {
+  return make(serializerStringTree(schema.ast), {
+    schema
+  });
+}
+/**
+ * Allows array schemas to decode from either an array input or a single value
+ * input.
+ *
+ * **When to use**
+ *
+ * Use when you need to accept transport formats that may represent a
+ * single-item array as a bare value, such as query-string or form-data adapters.
+ *
+ * **Gotchas**
+ *
+ * This combinator is intentionally not part of `toCodecStringTree`; it adds a
+ * decoding convenience rather than a canonical StringTree representation. It
+ * does not parse comma-separated strings.
+ *
+ * @category Canonical Codecs
+ * @since 4.0.0
+ */
+export function toCodecArrayFromSingle(schema) {
+  return make(toCodecArrayFromSingleTop(schema.ast));
 }
 /**
  * Derives an XML encoder from a codec.
@@ -8290,7 +8330,12 @@ function serializerTree(ast, recur, onMissingAnnotation) {
 }
 const nullToString = /*#__PURE__*/new SchemaAST.Link(/*#__PURE__*/new SchemaAST.Literal("null"), /*#__PURE__*/new SchemaTransformation.Transformation(/*#__PURE__*/SchemaGetter.transform(() => null), /*#__PURE__*/SchemaGetter.transform(() => "null")));
 const booleanToString = /*#__PURE__*/new SchemaAST.Link(/*#__PURE__*/new SchemaAST.Union([/*#__PURE__*/new SchemaAST.Literal("true"), /*#__PURE__*/new SchemaAST.Literal("false")], "anyOf"), /*#__PURE__*/new SchemaTransformation.Transformation(/*#__PURE__*/SchemaGetter.transform(s => s === "true"), /*#__PURE__*/SchemaGetter.String()));
-const serializerStringTree = /*#__PURE__*/SchemaAST.toCodec(ast => {
+const SERIALIZER_ENSURE_ARRAY = "~effect/Schema/SERIALIZER_ENSURE_ARRAY";
+const isSerializerArrayFromSingle = ast => SchemaAST.isUnion(ast) && ast.annotations?.[SERIALIZER_ENSURE_ARRAY] === true;
+const serializerStringTree = /*#__PURE__*/SchemaAST.applyToSelfOrLastLinkEncoding(ast => {
+  if (isSerializerArrayFromSingle(ast)) {
+    return ast;
+  }
   const out = serializerTree(ast, serializerStringTree, ast => SchemaAST.replaceEncoding(ast, [unknownToUndefined]));
   if (out !== ast && SchemaAST.isOptional(ast)) {
     return SchemaAST.optionalKeyLastLink(out);
@@ -8298,38 +8343,23 @@ const serializerStringTree = /*#__PURE__*/SchemaAST.toCodec(ast => {
   return out;
 });
 const unknownToUndefined = /*#__PURE__*/new SchemaAST.Link(SchemaAST.undefined, /*#__PURE__*/new SchemaTransformation.Transformation(/*#__PURE__*/SchemaGetter.passthrough(), /*#__PURE__*/SchemaGetter.transform(() => undefined)));
-const serializerStringTreeKeepDeclarations = /*#__PURE__*/SchemaAST.toCodec(ast => {
-  const out = serializerTree(ast, serializerStringTreeKeepDeclarations, identity);
-  if (out !== ast && SchemaAST.isOptional(ast)) {
-    return SchemaAST.optionalKeyLastLink(out);
-  }
-  return out;
-});
-const SERIALIZER_ENSURE_ARRAY = "~effect/Schema/SERIALIZER_ENSURE_ARRAY";
-const toCodecEnsureArray = /*#__PURE__*/SchemaAST.toCodec(ast => {
-  if (SchemaAST.isUnion(ast) && ast.annotations?.[SERIALIZER_ENSURE_ARRAY]) {
+const toArrayFromSingleInputElement = ast => SchemaAST.isOptional(ast) ? SchemaAST.optionalKey(SchemaAST.unknown) : SchemaAST.unknown;
+const arrayFromSingleTransformation = /*#__PURE__*/new SchemaTransformation.Transformation(/*#__PURE__*/SchemaGetter.transform(input => typeof input === "string" ? [input] : input), /*#__PURE__*/SchemaGetter.passthrough());
+const toCodecArrayFromSingleTop = /*#__PURE__*/SchemaAST.applyToSelfOrLastLinkEncoding(ast => {
+  if (isSerializerArrayFromSingle(ast)) {
     return ast;
   }
-  const out = onSerializerEnsureArray(ast);
+  const out = onSerializerArrayFromSingle(ast);
   if (SchemaAST.isArrays(out)) {
-    const ensure = new SchemaAST.Union([out, SchemaAST.decodeTo(SchemaAST.string, out, new SchemaTransformation.Transformation(SchemaGetter.split(), SchemaGetter.passthrough()))], "anyOf", {
+    const ensure = SchemaAST.decodeTo(new SchemaAST.Union([new SchemaAST.Arrays(out.isMutable, out.elements.map(toArrayFromSingleInputElement), out.rest.map(toArrayFromSingleInputElement)), SchemaAST.string], "anyOf", {
       [SERIALIZER_ENSURE_ARRAY]: true
-    });
+    }), out, arrayFromSingleTransformation);
     return SchemaAST.isOptional(ast) ? SchemaAST.optionalKey(ensure) : ensure;
   }
   return out;
 });
-function onSerializerEnsureArray(ast) {
-  switch (ast._tag) {
-    default:
-      return ast;
-    case "Declaration":
-    case "Arrays":
-    case "Objects":
-    case "Union":
-    case "Suspend":
-      return ast.recur(toCodecEnsureArray);
-  }
+function onSerializerArrayFromSingle(ast) {
+  return ast._tag === "Declaration" || ast._tag === "Arrays" || ast._tag === "Objects" || ast._tag === "Union" || ast._tag === "Suspend" ? ast.recur(toCodecArrayFromSingleTop) : ast;
 }
 // -----------------------------------------------------------------------------
 // Optic APIs