effect 4.0.5 → 4.0.6

package/dist/Schema.js

@@ -69,6 +69,8 @@ import * as SchemaGetter from "./SchemaGetter.js";
 import * as SchemaIssue from "./SchemaIssue.js";
 import * as SchemaParser from "./SchemaParser.js";
 import * as SchemaTransformation from "./SchemaTransformation.js";
+import * as SemVer_ from "./SemVer.js";
+import * as SemVerRange_ from "./SemVerRange.js";
 import * as Struct_ from "./Struct.js";
 const TypeId = InternalMake.TypeId;
 /**
@@ -1677,8 +1679,8 @@ export function TemplateLiteralParser(parts) {
   });
 }
 /**
- * Creates a schema from a TypeScript enum object. Validates that the input is one of the enum's values.
- * Numeric enum values must be finite.
+ * Creates a schema from a TypeScript enum or an object mapping names to string or number values.
+ * Validates that the input is one of those values. Numeric values must be finite.
  *
  * **Gotchas**
  *
@@ -3211,10 +3213,9 @@ export function TaggedStruct(value, fields) {
  *
  * **Gotchas**
  *
- * Rejects overlapping discriminant types in known member tuples at compile
- * time, including nested unions. Numeric and string values such as `1` and
- * `"1"` count as duplicates. Also throws at runtime if multiple members use the
- * same discriminant property key.
+ * Throws when multiple members use the same discriminant property key,
+ * including members of nested unions. Numeric and string values such as `1`
+ * and `"1"` count as duplicates.
  *
  * **Example** (Adding tagged-union utilities to an existing union)
  *
@@ -3806,16 +3807,24 @@ export function isULID(annotations) {
  * @since 4.0.0
  */
 export function isBase64(annotations) {
-  const regExp = /^([0-9a-zA-Z+/]{4})*(([0-9a-zA-Z+/]{2}==)|([0-9a-zA-Z+/]{3}=))?$/;
-  return isPattern(regExp, {
+  const pattern = "^([0-9a-zA-Z+/]{4})*(([0-9a-zA-Z+/]{2}==)|([0-9a-zA-Z+/]{3}=))?$";
+  // `pattern` overflows the V8 stack on large inputs
+  const regExp = /^[0-9a-zA-Z+/]*={0,2}$/;
+  return makeFilter(s => s.length % 4 === 0 && regExp.test(s), {
     expected: "a base64 encoded string",
     representation: {
       id: "effect/schema/isBase64",
       payload: null
     },
     toJsonSchema: () => ({
-      pattern: regExp.source
+      pattern
     }),
+    arbitraryConstraint: {
+      patterns: [{
+        source: pattern,
+        flags: ""
+      }]
+    },
     toCode: () => ({
       runtime: "Schema.isBase64()"
     }),
@@ -3843,16 +3852,24 @@ export function isBase64(annotations) {
  * @since 4.0.0
  */
 export function isBase64Url(annotations) {
-  const regExp = /^([0-9a-zA-Z-_]{4})*(([0-9a-zA-Z-_]{2}(==)?)|([0-9a-zA-Z-_]{3}(=)?))?$/;
-  return isPattern(regExp, {
+  const pattern = "^([0-9a-zA-Z-_]{4})*(([0-9a-zA-Z-_]{2}(==)?)|([0-9a-zA-Z-_]{3}(=)?))?$";
+  // `pattern` overflows the V8 stack on large inputs
+  const regExp = /^[0-9a-zA-Z-_]*={0,2}$/;
+  return makeFilter(s => regExp.test(s) && (s.endsWith("=") ? s.length % 4 === 0 : s.length % 4 !== 1), {
     expected: "a base64url encoded string",
     representation: {
       id: "effect/schema/isBase64Url",
       payload: null
     },
     toJsonSchema: () => ({
-      pattern: regExp.source
+      pattern
     }),
+    arbitraryConstraint: {
+      patterns: [{
+        source: pattern,
+        flags: ""
+      }]
+    },
     toCode: () => ({
       runtime: "Schema.isBase64Url()"
     }),
@@ -6317,7 +6334,9 @@ export const File = /*#__PURE__*/instanceOf(globalThis.File, {
  * @category schemas
  * @since 4.0.0
  */
-export const FormData = /*#__PURE__*/instanceOf(globalThis.FormData, {
+// Read the global inside the guard: resolving globalThis.FormData at module
+// scope loads undici on Node.
+export const FormData = /*#__PURE__*/declare(u => u instanceof globalThis.FormData, {
   representation: {
     id: "effect/schema/FormData",
     payload: null
@@ -7237,7 +7256,7 @@ export function Cause(error, defect) {
       }
       return Effect.mapBothEager(SchemaParser.decodeUnknownEffect(failures)(input.reasons, options), {
         onSuccess: Cause_.fromReasons,
-        onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "failures", issue, input, options)
+        onFailure: issue => SchemaIssue.makeCompositeAtKey(ast, "reasons", issue, input, options)
       });
     };
   }, {
@@ -7494,6 +7513,43 @@ export const DateTimeUtcFromDate = /*#__PURE__*/Date.pipe(/*#__PURE__*/decodeTo(
 export const DateTimeUtcFromString = /*#__PURE__*/String.annotate({
   expected: "a string that will be decoded as a DateTime.Utc"
 }).pipe(/*#__PURE__*/decodeTo(DateTimeUtc, dateTimeUtcFromString));
+const dateTimeUtcFromHttpDate = /*#__PURE__*/SchemaTransformation.transformEffect({
+  decode: (s, options) => Result_.match(Headers_.parseHttpDate(s), {
+    onFailure: () => Effect.fail(new SchemaIssue.InvalidValue({
+      expected: "an HTTP date (RFC 9110 §5.6.7)"
+    }, s, options)),
+    onSuccess: Effect.succeed
+  }),
+  encode: utc => Effect.succeed(Headers_.formatHttpDate(utc))
+});
+/**
+ * Schema for HTTP date header values, such as `Date`, `Last-Modified` and
+ * `Expires`, decoded as `DateTime.Utc`.
+ *
+ * **When to use**
+ *
+ * Use with HTTP API header schemas that carry dates. Decoding accepts the
+ * three formats of RFC 9110 §5.6.7 and reads them as UTC; encoding emits the
+ * preferred IMF-fixdate form (`Sun, 06 Nov 1994 08:49:37 GMT`).
+ *
+ * **Example** (Decoding an HTTP date)
+ *
+ * ```ts
+ * import { DateTime, Schema } from "effect"
+ *
+ * const date = Schema.decodeSync(Schema.DateTimeUtcFromHttpDate)("Sun, 06 Nov 1994 08:49:37 GMT")
+ * const millis = DateTime.toEpochMillis(date) // => 784111777000
+ * ```
+ *
+ * @see {@link DateTimeUtcFromString} for ISO 8601 strings
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 4.0.0
+ */
+export const DateTimeUtcFromHttpDate = /*#__PURE__*/String.annotate({
+  expected: "an HTTP date string"
+}).pipe(/*#__PURE__*/decodeTo(DateTimeUtc, dateTimeUtcFromHttpDate));
 /**
  * Schema that decodes a number into a `DateTime.Utc`.
  *
@@ -9192,6 +9248,64 @@ export const Headers = /*#__PURE__*/declare(Headers_.isHeaders, {
     })
   }))
 });
+/**
+ * Schema for parsed `Retry-After` header values.
+ *
+ * **Details**
+ *
+ * Matches `Headers.RetryAfter`: either `{ _tag: "Duration", duration }` or
+ * `{ _tag: "DateTime", dateTime }`. The duration must be finite and
+ * non-negative. Use {@link RetryAfterFromString} for the header string form.
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 4.0.0
+ */
+export const RetryAfter = /*#__PURE__*/Union([/*#__PURE__*/Struct({
+  _tag: /*#__PURE__*/tag("Duration"),
+  duration: /*#__PURE__*/Duration.check(/*#__PURE__*/makeFilter(d => Duration_.isFinite(d) && !Duration_.isNegative(d), {
+    expected: "a finite, non-negative duration"
+  }))
+}), /*#__PURE__*/Struct({
+  _tag: /*#__PURE__*/tag("DateTime"),
+  dateTime: DateTimeUtc
+})]);
+const retryAfterFromString = /*#__PURE__*/SchemaTransformation.transformEffect({
+  decode: (s, options) => Result_.match(Headers_.parseRetryAfter(s), {
+    onFailure: () => Effect.fail(new SchemaIssue.InvalidValue({
+      expected: "whole non-negative seconds or an HTTP date (RFC 9110 §10.2.3)"
+    }, s, options)),
+    onSuccess: Effect.succeed
+  }),
+  encode: self => Effect.succeed(Headers_.formatRetryAfter(self))
+});
+/**
+ * Schema for `Retry-After` header values, decoded with
+ * `Headers.parseRetryAfter`.
+ *
+ * **When to use**
+ *
+ * Use with HTTP API header schemas that carry `Retry-After`. Decoding accepts
+ * whole non-negative seconds or an HTTP date and rejects anything else;
+ * encoding emits the delay as whole seconds, rounding a fractional second up,
+ * or the date as an IMF-fixdate.
+ *
+ * **Example** (Decoding a Retry-After header)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const value = Schema.decodeSync(Schema.RetryAfterFromString)("120")
+ * // => { _tag: "Duration", duration: Duration.seconds(120) }
+ * ```
+ *
+ * @stability unstable
+ * @category schemas
+ * @since 4.0.0
+ */
+export const RetryAfterFromString = /*#__PURE__*/String.annotate({
+  expected: "a Retry-After header value"
+}).pipe(/*#__PURE__*/decodeTo(RetryAfter, retryAfterFromString));
 /**
  * Schema for HTTP URL parameters.
  *
@@ -9497,6 +9611,123 @@ export function Result(success, failure) {
     failure
   });
 }
+// -----------------------------------------------------------------------------
+// SemVer schemas
+// -----------------------------------------------------------------------------
+const semVerStringTransformation = (parse, format) => SchemaTransformation.transformEffect({
+  decode: (input, options) => Effect.mapErrorEager(Effect.fromResult(parse(input)), error => new SchemaIssue.InvalidValue({
+    message: error.message
+  }, input, options)),
+  encode: value => Effect.succeed(format(value))
+});
+// Alphanumeric identifiers contain at least one non-digit.
+const SemVerCoreArbitrary = /*#__PURE__*/Struct({
+  major: Natural,
+  minor: Natural,
+  patch: Natural,
+  prerelease: /*#__PURE__*/ArraySchema(/*#__PURE__*/Union([Natural, /*#__PURE__*/String.check(/*#__PURE__*/isPattern(/^[0-9]*[A-Za-z-][0-9A-Za-z-]*$/))]))
+});
+const semVerFromString = /*#__PURE__*/semVerStringTransformation(SemVer_.parse, SemVer_.format);
+const SemVerString = /*#__PURE__*/String.annotate({
+  expected: "a string that will be decoded as a SemVer"
+});
+/**
+ * Schema for `SemVer` values.
+ *
+ * **Details**
+ *
+ * The JSON and StringTree codecs encode a version as its canonical string,
+ * including build metadata.
+ *
+ * @see {@link SemVerFromString} for parsing version strings
+ * @stability unstable
+ * @category schemas
+ * @since 4.0.6
+ */
+export const SemVer = /*#__PURE__*/declare(SemVer_.isSemVer, {
+  representation: {
+    id: "effect/schema/SemVer",
+    payload: null
+  },
+  toCode: () => ({
+    runtime: `Schema.SemVer`,
+    Type: `SemVer.SemVer`,
+    importDeclarations: [`import * as SemVer from "effect/SemVer"`]
+  }),
+  expected: "SemVer",
+  toCodecArbitrary: () => linkDecoding()(Struct({
+    ...SemVerCoreArbitrary.fields,
+    build: ArraySchema(String.check(isPattern(/^[0-9A-Za-z-]+$/)))
+  }), SchemaGetter.transform(SemVer_.make)),
+  toCodecJson: () => link()(SemVerString, semVerFromString),
+  toFormatter: () => SemVer_.format
+});
+/**
+ * Schema that parses a Semantic Versioning 2.0.0 string into a `SemVer`.
+ *
+ * **Details**
+ *
+ * Decodes with `SemVer.parse`, rejecting a `v` prefix, surrounding whitespace,
+ * partial versions, and leading zeros. Encodes with `SemVer.format`, including
+ * build metadata.
+ *
+ * @see {@link SemVer} for validating values that are already SemVer values
+ * @stability unstable
+ * @category schemas
+ * @since 4.0.6
+ */
+export const SemVerFromString = /*#__PURE__*/SemVerString.pipe(/*#__PURE__*/decodeTo(SemVer, semVerFromString));
+const semVerRangeFromString = /*#__PURE__*/semVerStringTransformation(SemVerRange_.parse, SemVerRange_.format);
+const SemVerRangeString = /*#__PURE__*/String.annotate({
+  expected: "a string that will be decoded as a SemVer range"
+});
+/**
+ * Schema for `SemVerRange` values.
+ *
+ * **Details**
+ *
+ * The JSON and StringTree codecs encode a range with `SemVerRange.format`.
+ *
+ * @see {@link SemVerRangeFromString} for parsing range strings
+ * @stability unstable
+ * @category schemas
+ * @since 4.0.6
+ */
+export const SemVerRange = /*#__PURE__*/declare(SemVerRange_.isSemVerRange, {
+  representation: {
+    id: "effect/schema/SemVerRange",
+    payload: null
+  },
+  toCode: () => ({
+    runtime: `Schema.SemVerRange`,
+    Type: `SemVerRange.SemVerRange`,
+    importDeclarations: [`import * as SemVerRange from "effect/SemVerRange"`]
+  }),
+  expected: "SemVerRange",
+  toCodecArbitrary: () => linkDecoding()(ArraySchema(ArraySchema(Struct({
+    operator: Literals(["", "=", "<", "<=", ">", ">=", "~", "^"]),
+    version: SemVerCoreArbitrary
+  })).check(isMinLength(1))), SchemaGetter.transform(sets => SemVerRange_.parseUnsafe(sets.map(set => set.map(({
+    operator,
+    version
+  }) => `${operator}${SemVer_.format(SemVer_.make(version))}`).join(" ")).join(" || ")))),
+  toCodecJson: () => link()(SemVerRangeString, semVerRangeFromString),
+  toFormatter: () => SemVerRange_.format
+});
+/**
+ * Schema that parses an npm-style version range string into a `SemVerRange`.
+ *
+ * **Details**
+ *
+ * Decodes with `SemVerRange.parse` and encodes with `SemVerRange.format`,
+ * preserving parsed operators and normalizing wildcard spellings.
+ *
+ * @see {@link SemVerRange} for validating values that are already ranges
+ * @stability unstable
+ * @category schemas
+ * @since 4.0.6
+ */
+export const SemVerRangeFromString = /*#__PURE__*/SemVerRangeString.pipe(/*#__PURE__*/decodeTo(SemVerRange, semVerRangeFromString));
 const immerable = /*#__PURE__*/globalThis.Symbol.for("immer-draftable");
 const payloadToken = {};
 function makeClass(Inherited, identifier, struct, annotations, proto) {
@@ -9572,13 +9803,22 @@ function makeClass(Inherited, identifier, struct, annotations, proto) {
   }
   return out;
 }
-function getClassTransformation(self) {
-  return new SchemaTransformation.Transformation(SchemaGetter.transform(input => new self(input, {
+/**
+ * Constructs a class instance from fields that were already validated against
+ * the class struct, without running the constructor's schema pass.
+ *
+ * @internal
+ */
+export function makeClassTrusted(self, fields) {
+  return new self(fields, {
     "~payload": {
       token: payloadToken,
-      value: input
+      value: fields
     }
-  })), SchemaGetter.passthrough());
+  });
+}
+function getClassTransformation(self) {
+  return new SchemaTransformation.Transformation(SchemaGetter.transform(input => makeClassTrusted(self, input)), SchemaGetter.passthrough());
 }
 function getClassTypeId(identifier) {
   return `~effect/Schema/Class/${identifier}`;
@@ -9639,7 +9879,9 @@ function isStruct(schema) {
  *
  * **Gotchas**
  *
- * Passing `disableChecks` in the options skips constructor validation.
+ * Passing `disableChecks: true` skips filters and checks, not parsing of types
+ * and structure. Wrong types and shapes are still rejected, and constructor
+ * defaults still apply.
  *
  * **Example** (Defining a basic class)
  *
@@ -10072,6 +10314,78 @@ export const toCodecStringTree = InternalToCodec.toCodecStringTree;
  * @since 4.0.0
  */
 export const toCodecArrayFromSingle = InternalToCodec.toCodecArrayFromSingle;
+/**
+ * Derives a JSON codec, like {@link toCodecJson}, that also accepts the
+ * `null` values Go's `encoding/json` writes for nil pointers, slices, and maps.
+ *
+ * **When to use**
+ *
+ * Use when decoding JSON produced by a Go service (for example the Docker
+ * Engine or Kubernetes APIs), where any field the API document describes as
+ * optional, or any slice or map, may arrive as `null`.
+ *
+ * **Details**
+ *
+ * Decoding applies these rules at every level of the schema:
+ *
+ * - An optional key that is `null` decodes as a missing key.
+ * - A required array (`Schema.Array`) that is `null` decodes as `[]`.
+ * - A required record (`Schema.Record`) that is `null` decodes as `{}`.
+ *
+ * Array and record rules also apply at the top level and to nested collection
+ * values. Tuples, non-empty arrays, and structs are not treated as collections;
+ * collection checks still apply to the empty value.
+ *
+ * Encoding is unchanged from {@link toCodecJson}: the added rules only decode
+ * `null` and do not emit it. A missing key stays missing.
+ *
+ * These rules also accept `encoding/json/v2` output. By default, v2 writes
+ * nil slices and maps as `[]` and `{}`, but it can be configured to emit
+ * `null` instead.
+ *
+ * **Gotchas**
+ *
+ * - Normalization deliberately discards the distinction between nil and empty
+ *   Go slices or maps. They are distinguishable in Go, and unmarshalling a
+ *   missing key, `null`, or an empty collection can affect existing values
+ *   differently. Use {@link toCodecJson} with explicit nullable schemas when
+ *   that distinction matters.
+ * - A key whose schema already accepts `null` (for example
+ *   `Schema.NullOr(X)`, `Schema.Unknown`, or `Schema.Json`) keeps `null` as a
+ *   value.
+ * - A required field that is not an array or a record (a nil pointer to a Go
+ *   struct, for example) still fails on `null`. Make it optional if the API
+ *   can omit it.
+ * - A nil `[]byte` is written as `null` by `encoding/json` (and as `""` by
+ *   version 2), but its schema is a base64 string, not an array. A required
+ *   `[]byte` field that is `null` fails; make it optional if the API can send
+ *   `null`.
+ * - Only these `null` rules are covered. Field formats such as durations,
+ *   base64 bytes, and numbers encoded as strings belong in the field schemas.
+ *
+ * **Example** (Decoding a Go response with nil fields)
+ *
+ * ```ts import.meta.vitest
+ * import { Schema } from "effect"
+ *
+ * const Container = Schema.Struct({
+ *   Id: Schema.String,
+ *   Names: Schema.Array(Schema.String),
+ *   Labels: Schema.Record(Schema.String, Schema.String),
+ *   Status: Schema.optionalKey(Schema.String)
+ * })
+ *
+ * const decode = Schema.decodeUnknownSync(Schema.toCodecGoJson(Container))
+ *
+ * decode({ Id: "a", Names: null, Labels: null, Status: null }) // => { Id: "a", Names: [], Labels: {} }
+ * ```
+ *
+ * @see {@link toCodecJson} for the canonical JSON codec
+ * @stability unstable
+ * @category converting
+ * @since 4.0.6
+ */
+export const toCodecGoJson = InternalToCodec.toCodecGoJson;
 /**
  * Derives an XML encoder from a codec.
  *