effect 4.0.0-beta.84 → 4.0.0-beta.86

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
@@ -1600,14 +1600,20 @@ function templateLiteralFromParts(parts) {
   return new SchemaAST.TemplateLiteral(parts.map(part => isSchema(part) ? part.ast : new SchemaAST.Literal(part)));
 }
 /**
- * Creates a schema that validates strings matching a template literal pattern. Each part can be
- * a literal string/number/bigint or a schema whose encoded type is a string, number, or bigint.
+ * Creates a schema that validates strings by matching ordered template literal
+ * parts.
  *
  * **When to use**
  *
  * Use when the decoded value should remain the matched string and you do not
  * need the individual template parts parsed into a tuple.
  *
+ * **Details**
+ *
+ * Each part can be a literal `string`, `number`, or `bigint`, or a schema whose
+ * encoded type is `string`, `number`, or `bigint`. Checks on string, number,
+ * and bigint schema parts are applied while matching each segment.
+ *
  * **Example** (Defining a URL path pattern)
  *
  * ```ts
@@ -1627,7 +1633,7 @@ export function TemplateLiteral(parts) {
   });
 }
 /**
- * Schema for parsing template literal matches into typed tuple parts.
+ * Schema for parsing matched template literal strings into typed tuple parts.
  *
  * **When to use**
  *
@@ -1637,7 +1643,8 @@ export function TemplateLiteral(parts) {
  * **Details**
  *
  * Unlike {@link TemplateLiteral}, this schema decodes the matched string into a
- * readonly tuple with one element per schema part.
+ * readonly tuple with one element per schema part. Checks on string, number,
+ * and bigint schema parts are applied while matching each segment.
  *
  * **Example** (Parsing path parameters)
  *
@@ -2015,7 +2022,18 @@ derive) {
   };
 }
 /**
- * Defines a record (dictionary) schema with typed keys and values.
+ * Defines a record schema whose dynamic properties are selected by a key schema
+ * and decoded with a value schema.
+ *
+ * **Details**
+ *
+ * For dynamic keys, the key schema selects matching own properties and the
+ * value schema decodes or encodes only those selected properties. Checks on
+ * string, number, symbol, and template literal key schemas narrow which
+ * properties are selected.
+ *
+ * For transformed key schemas, property selection is based on encoded property
+ * names before the selected key is decoded.
  *
  * **Example** (Defining a string-keyed record of numbers)
  *
@@ -2046,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
@@ -2550,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.
@@ -2588,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 => {
@@ -2643,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);
   };
 }
 /**
@@ -2678,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));
   };
 }
 /**
@@ -5210,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
  */
@@ -5268,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
  */
@@ -6636,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)
  *
@@ -6693,8 +6718,7 @@ export const FormData = /*#__PURE__*/instanceOf(globalThis.FormData, {
  *   Schema.toCodecStringTree(
  *     Schema.Struct({
  *       a: Schema.Int
- *     }),
- *     { keepDeclarations: true }
+ *     })
  *   )
  * )
  *
@@ -7482,14 +7506,16 @@ function makeClass(Inherited, identifier, struct, annotations, proto) {
       return this.rebuild(SchemaAST.appendChecks(this.ast, checks));
     }
     static extend(identifier) {
-      return (newFields, annotations) => {
+      return (schema, annotations) => {
+        const extension = isStruct(schema) ? schema : Struct(schema);
         const fields = {
           ...struct.fields,
-          ...newFields
+          ...extension.fields
         };
-        return makeClass(this, identifier, makeStruct(SchemaAST.struct(fields, struct.ast.checks, {
+        const ast = SchemaAST.struct(fields, struct.ast.checks, {
           identifier
-        }), fields), annotations, proto);
+        });
+        return makeClass(this, identifier, makeStruct(SchemaAST.appendChecks(ast, extension.ast.checks), fields), annotations, proto);
       };
     }
     static mapFields(f, options) {
@@ -7510,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) {
@@ -7991,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`.
@@ -8004,7 +8027,7 @@ export function toJsonSchemaDocument(schema, options) {
 export function toCodecJson(schema) {
   return make(toCodecJsonTop(schema.ast));
 }
-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;
 });
@@ -8040,7 +8063,7 @@ function toCodecJsonBase(ast, recur) {
             cause: ast
           });
         }
-        return ast.recur(recur);
+        return ast.recur(recur, SchemaAST.parameterFromString);
       }
     case "Union":
       {
@@ -8091,8 +8114,41 @@ 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));
+}
+/**
+ * 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.
@@ -8251,7 +8307,7 @@ function serializerTree(ast, recur, onMissingAnnotation) {
             cause: ast
           });
         }
-        return ast.recur(recur);
+        return ast.recur(recur, SchemaAST.parameterFromString);
       }
     case "Union":
       {
@@ -8270,7 +8326,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);
@@ -8278,38 +8339,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