effect 4.0.5 → 4.0.6

package/src/Schema.ts

@@ -79,6 +79,8 @@ import * as SchemaIssue from "./SchemaIssue.ts"
 import * as SchemaParser from "./SchemaParser.ts"
 import type * as SchemaRepresentation from "./SchemaRepresentation.ts"
 import * as SchemaTransformation from "./SchemaTransformation.ts"
+import * as SemVer_ from "./SemVer.ts"
+import * as SemVerRange_ from "./SemVerRange.ts"
 import type { StandardJSONSchemaV1, StandardSchemaV1 } from "./StandardSchema.ts"
 import type { Assign, Lambda, Mutable, Simplify } from "./Struct.ts"
 import * as Struct_ from "./Struct.ts"
@@ -123,8 +125,8 @@ export type ConstructorDefault = "no-default" | "with-default"
  *
  * **When to use**
  *
- * Use when passing `disableChecks: true` to skip validation when you trust the
- * data. Pass `parseOptions` to control parsing behavior.
+ * Use when passing `disableChecks: true` to skip filters and checks while still
+ * parsing types and structure. Pass `parseOptions` to control parsing behavior.
  *
  * @see {@link BottomWithoutNew.makeEffect}
  * @see {@link BottomWithoutNew.make}
@@ -139,7 +141,8 @@ export interface MakeOptions {
    */
   readonly parseOptions?: SchemaAST.ParseOptions | undefined
   /**
-   * Whether to disable validation for the schema.
+   * Whether to skip filters and checks. Types and structure are still parsed,
+   * and constructor defaults still apply.
    */
   readonly disableChecks?: boolean | undefined
 
@@ -2961,8 +2964,8 @@ export interface Enum<A extends { [x: string]: string | number }>
   readonly enums: A
 }
 /**
- * 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**
  *
@@ -2986,7 +2989,7 @@ export interface Enum<A extends { [x: string]: string | number }>
  * @category constructors
  * @since 4.0.0
  */
-export function Enum<A extends { [x: string]: string | number }>(enums: A): Enum<A> {
+export function Enum<const A extends { [x: string]: string | number }>(enums: A): Enum<A> {
   return make(
     new SchemaAST.Enum(
       Object.keys(enums).filter(
@@ -5632,8 +5635,8 @@ export interface compose<To extends Constraint, From extends Constraint> extends
  * **Gotchas**
  *
  * In a custom transformation, `decode` maps `From["Type"]` to `To["Encoded"]`
- * and is used on the encoding path, while `encode` maps `To["Encoded"]` to
- * `From["Type"]` and is used on the decoding path.
+ * and is used on the decoding path, while `encode` maps `To["Encoded"]` to
+ * `From["Type"]` and is used on the encoding path.
  *
  * **Example** (Transforming strings to numbers with a schema transformation)
  *
@@ -6316,12 +6319,6 @@ type Flatten<Schemas> = Schemas extends readonly [infer Head, ...infer Tail]
   ? Head extends Union<infer Inner> ? [...Flatten<Inner>, ...Flatten<Tail>]
   : [Head, ...Flatten<Tail>]
   : []
-type DiscriminantKey<T extends PropertyKey> = T extends number ? `${T}` : T
-type EnsureUniqueDiscriminants<Tags extends ReadonlyArray<PropertyKey>, Seen = never> = Tags extends
-  readonly [infer Head extends PropertyKey, ...infer Tail extends ReadonlyArray<PropertyKey>]
-  ? [DiscriminantKey<Head> & Seen] extends [never] ? EnsureUniqueDiscriminants<Tail, Seen | DiscriminantKey<Head>>
-  : never
-  : unknown
 type MatchCasesResult<Cases> = {
   [K in keyof Cases]-?: NonNullable<Cases[K]> extends (...args: Array<any>) => infer R ? R : never
 }[keyof Cases]
@@ -6406,10 +6403,9 @@ export type toTaggedUnion<
  *
  * **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)
  *
@@ -6436,7 +6432,7 @@ export type toTaggedUnion<
  */
 export function toTaggedUnion<const Tag extends PropertyKey>(tag: Tag) {
   return <const Members extends ReadonlyArray<Constraint & { readonly Type: { readonly [K in Tag]: PropertyKey } }>>(
-    self: Union<Members> & NoInfer<EnsureUniqueDiscriminants<TaggedUnionUtils<Tag, Members>["discriminants"]>>
+    self: Union<Members>
   ): toTaggedUnion<Tag, Members> => {
     const cases: Record<PropertyKey, unknown> = {}
     const discriminants: Array<PropertyKey> = []
@@ -7137,16 +7133,21 @@ export function isULID(annotations?: Annotations.Filter) {
  * @since 4.0.0
  */
 export function isBase64(annotations?: Annotations.Filter) {
-  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: string) => s.length % 4 === 0 && regExp.test(s),
     {
       expected: "a base64 encoded string",
       representation: {
         id: "effect/schema/isBase64",
         payload: null
       },
-      toJsonSchema: () => ({ pattern: regExp.source }),
+      toJsonSchema: () => ({ pattern }),
+      arbitraryConstraint: {
+        patterns: [{ source: pattern, flags: "" }]
+      },
       toCode: () => ({ runtime: "Schema.isBase64()" }),
       ...annotations
     }
@@ -7173,16 +7174,21 @@ export function isBase64(annotations?: Annotations.Filter) {
  * @since 4.0.0
  */
 export function isBase64Url(annotations?: Annotations.Filter) {
-  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: string) => 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 }),
+      toJsonSchema: () => ({ pattern }),
+      arbitraryConstraint: {
+        patterns: [{ source: pattern, flags: "" }]
+      },
       toCode: () => ({ runtime: "Schema.isBase64Url()" }),
       ...annotations
     }
@@ -9939,7 +9945,9 @@ export interface FormData extends instanceOf<globalThis.FormData> {
  * @category schemas
  * @since 4.0.0
  */
-export const FormData: FormData = instanceOf(globalThis.FormData, {
+// Read the global inside the guard: resolving globalThis.FormData at module
+// scope loads undici on Node.
+export const FormData: FormData = declare((u): u is globalThis.FormData => u instanceof globalThis.FormData, {
   representation: {
     id: "effect/schema/FormData",
     payload: null
@@ -11277,7 +11285,7 @@ export function Cause<E extends Constraint, D extends Constraint>(error: E, defe
         }
         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)
         })
       }
     },
@@ -11680,6 +11688,65 @@ export const DateTimeUtcFromString: DateTimeUtcFromString = String.annotate({
     dateTimeUtcFromString
   )
 )
+const dateTimeUtcFromHttpDate: SchemaTransformation.Transformation<DateTime.Utc, string> = SchemaTransformation
+  .transformEffect<DateTime.Utc, string>({
+    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))
+  })
+/**
+ * Type-level representation of {@link DateTimeUtcFromHttpDate}.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface DateTimeUtcFromHttpDate extends decodeTo<DateTimeUtc, String> {
+  readonly "Rebuild": DateTimeUtcFromHttpDate
+}
+/**
+ * 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: DateTimeUtcFromHttpDate = String.annotate({
+  expected: "an HTTP date string"
+}).pipe(
+  decodeTo(
+    DateTimeUtc,
+    dateTimeUtcFromHttpDate
+  )
+)
 /**
  * Type-level representation of {@link DateTimeUtcFromMillis}.
  *
@@ -15190,6 +15257,110 @@ export const Headers: Headers = declare(
   }
 )
 
+/**
+ * Type-level representation of {@link RetryAfter}.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface RetryAfter extends
+  Union<
+    readonly [
+      Struct<{ readonly _tag: tag<"Duration">; readonly duration: Duration }>,
+      Struct<{ readonly _tag: tag<"DateTime">; readonly dateTime: DateTimeUtc }>
+    ]
+  >
+{
+  readonly "Rebuild": RetryAfter
+}
+
+/**
+ * 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: RetryAfter = Union([
+  Struct({
+    _tag: tag("Duration"),
+    duration: Duration.check(
+      makeFilter((d) => Duration_.isFinite(d) && !Duration_.isNegative(d), {
+        expected: "a finite, non-negative duration"
+      })
+    )
+  }),
+  Struct({ _tag: tag("DateTime"), dateTime: DateTimeUtc })
+])
+
+const retryAfterFromString: SchemaTransformation.Transformation<Headers_.RetryAfter, string> = SchemaTransformation
+  .transformEffect<Headers_.RetryAfter, string>({
+    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))
+  })
+
+/**
+ * Type-level representation of {@link RetryAfterFromString}.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface RetryAfterFromString extends decodeTo<RetryAfter, String> {
+  readonly "Rebuild": RetryAfterFromString
+}
+
+/**
+ * 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: RetryAfterFromString = String.annotate({
+  expected: "a Retry-After header value"
+}).pipe(
+  decodeTo(
+    RetryAfter,
+    retryAfterFromString
+  )
+)
+
 /**
  * Type-level representation of {@link UrlParams}.
  *
@@ -15743,6 +15914,198 @@ export function Result<A extends Constraint, E extends Constraint>(
   return make(schema.ast, { success, failure })
 }
 
+// -----------------------------------------------------------------------------
+// SemVer schemas
+// -----------------------------------------------------------------------------
+
+const semVerStringTransformation = <A>(
+  parse: (input: string) => Result_.Result<A, SemVer_.SemVerError>,
+  format: (value: A) => string
+): SchemaTransformation.Transformation<A, string> =>
+  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 = Struct({
+  major: Natural,
+  minor: Natural,
+  patch: Natural,
+  prerelease: ArraySchema(Union([Natural, String.check(isPattern(/^[0-9]*[A-Za-z-][0-9A-Za-z-]*$/))]))
+})
+const semVerFromString = semVerStringTransformation(SemVer_.parse, SemVer_.format)
+const SemVerString = String.annotate({ expected: "a string that will be decoded as a SemVer" })
+/**
+ * Type-level representation of {@link SemVer}.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.6
+ */
+export interface SemVer extends declare<SemVer_.SemVer> {
+  readonly "Rebuild": 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: SemVer = 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<SemVer_.SemVer>()(
+        Struct({
+          ...SemVerCoreArbitrary.fields,
+          build: ArraySchema(String.check(isPattern(/^[0-9A-Za-z-]+$/)))
+        }),
+        SchemaGetter.transform(SemVer_.make)
+      ),
+    toCodecJson: () =>
+      link<SemVer_.SemVer>()(
+        SemVerString,
+        semVerFromString
+      ),
+    toFormatter: () => SemVer_.format
+  }
+)
+/**
+ * Type-level representation of {@link SemVerFromString}.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.6
+ */
+export interface SemVerFromString extends decodeTo<SemVer, String> {
+  readonly "Rebuild": SemVerFromString
+}
+/**
+ * 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: SemVerFromString = SemVerString.pipe(
+  decodeTo(SemVer, semVerFromString)
+)
+const semVerRangeFromString = semVerStringTransformation(SemVerRange_.parse, SemVerRange_.format)
+const SemVerRangeString = String.annotate({ expected: "a string that will be decoded as a SemVer range" })
+/**
+ * Type-level representation of {@link SemVerRange}.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.6
+ */
+export interface SemVerRange extends declare<SemVerRange_.SemVerRange> {
+  readonly "Rebuild": SemVerRange
+}
+/**
+ * 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: SemVerRange = 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<SemVerRange_.SemVerRange>()(
+        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<SemVerRange_.SemVerRange>()(
+        SemVerRangeString,
+        semVerRangeFromString
+      ),
+    toFormatter: () => SemVerRange_.format
+  }
+)
+/**
+ * Type-level representation of {@link SemVerRangeFromString}.
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.6
+ */
+export interface SemVerRangeFromString extends decodeTo<SemVerRange, String> {
+  readonly "Rebuild": SemVerRangeFromString
+}
+/**
+ * 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: SemVerRangeFromString = SemVerRangeString.pipe(
+  decodeTo(SemVerRange, semVerRangeFromString)
+)
+
 /**
  * Type-level representation returned by {@link Class}.
  *
@@ -15958,16 +16321,19 @@ function makeClass<
   return out
 }
 
+/**
+ * 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>(self: new(input: any, options?: MakeOptions) => Self, fields: object): Self {
+  return new self(fields, { "~payload": { token: payloadToken, value: fields } })
+}
+
 function getClassTransformation(self: new(...args: ReadonlyArray<any>) => any) {
   return new SchemaTransformation.Transformation<any, any, never, never>(
-    SchemaGetter.transform((input) =>
-      new self(input, {
-        "~payload": {
-          token: payloadToken,
-          value: input
-        }
-      })
-    ),
+    SchemaGetter.transform((input) => makeClassTrusted(self, input)),
     SchemaGetter.passthrough()
   )
 }
@@ -16051,7 +16417,9 @@ function isStruct(schema: Struct.Fields | Struct<Struct.Fields>): schema is Stru
  *
  * **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)
  *
@@ -16122,7 +16490,9 @@ export const Class: {
    *
    * **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)
    *
@@ -16166,151 +16536,14 @@ export const Class: {
    * @since 3.10.0
    */
   <Self = never, Brand = {}>(identifier: string): {
-    /**
-     * Creates a schema-backed class whose constructor validates input against a
-     * {@link Struct} schema. Construction throws an `Error` with a
-     * `SchemaIssue.Issue` in its `cause` on invalid input.
-     *
-     * **When to use**
-     *
-     * Use when you need a schema-backed data class with validated construction,
-     * schema-derived decoding/encoding, and class-style methods or inheritance.
-     *
-     * **Details**
-     *
-     * Pass the desired class type as the first type parameter. The second optional
-     * type parameter can be used to add nominal brands.
-     *
-     * The `identifier` is the schema's stable runtime name. It is exposed on the
-     * class, stored in the schema AST, and used to label diagnostics and generated
-     * references as well as to format class instances.
-     *
-     * It also derives a runtime marker that recognizes instances across hot module
-     * reloads, where `instanceof` can fail because the constructor has been
-     * replaced. The identifier is explicit because the outer JavaScript class name
-     * is not available while the `extends` expression is evaluated and may change
-     * through renaming or minification.
-     *
-     * **Gotchas**
-     *
-     * Passing `disableChecks` in the options skips constructor validation.
-     *
-     * **Example** (Defining a basic class)
-     *
-     * ```ts import.meta.vitest
-     * import { Schema } from "effect"
-     *
-     * class Person extends Schema.Class<Person>("Person")({
-     *   name: Schema.String,
-     *   age: Schema.Number
-     * }) {}
-     *
-     * const alice = new Person({ name: "Alice", age: 30 })
-     * alice.name // => "Alice"
-     * String(alice) // => "Person({\"name\":\"Alice\",\"age\":30})"
-     * ```
-     *
-     * **Example** (Extending a class)
-     *
-     * ```ts import.meta.vitest
-     * import { Schema } from "effect"
-     *
-     * class Animal extends Schema.Class<Animal>("Animal")({
-     *   name: Schema.String
-     * }) {}
-     *
-     * class Dog extends Animal.extend<Dog>("Dog")({
-     *   breed: Schema.String
-     * }) {}
-     *
-     * const dog = new Dog({ name: "Rex", breed: "Labrador" })
-     * dog.name // => "Rex"
-     * dog.breed // => "Labrador"
-     * ```
-     *
-     * @see {@link TaggedClass} for adding a `_tag` literal field to the class schema
-     * @see {@link Error} for defining schema-backed error classes
-     * @see {@link TaggedError} for defining tagged schema-backed error classes
-     *
-     * @stability stable
-     * @category constructors
-     * @since 3.10.0
-     */
     <const Fields extends Struct.Fields>(
       fields: Fields,
       annotations?: Annotations.Declaration<Self, readonly [Struct<Fields>]>
     ): [Self] extends [never] ? MissingSelfGeneric<"Schema.Class"> : Class<Self, Struct<Fields>, Brand>
-    /**
-     * Creates a schema-backed class whose constructor validates input against a
-     * {@link Struct} schema. Construction throws an `Error` with a
-     * `SchemaIssue.Issue` in its `cause` on invalid input.
-     *
-     * **When to use**
-     *
-     * Use when you need a schema-backed data class with validated construction,
-     * schema-derived decoding/encoding, and class-style methods or inheritance.
-     *
-     * **Details**
-     *
-     * Pass the desired class type as the first type parameter. The second optional
-     * type parameter can be used to add nominal brands.
-     *
-     * The `identifier` is the schema's stable runtime name. It is exposed on the
-     * class, stored in the schema AST, and used to label diagnostics and generated
-     * references as well as to format class instances.
-     *
-     * It also derives a runtime marker that recognizes instances across hot module
-     * reloads, where `instanceof` can fail because the constructor has been
-     * replaced. The identifier is explicit because the outer JavaScript class name
-     * is not available while the `extends` expression is evaluated and may change
-     * through renaming or minification.
-     *
-     * **Gotchas**
-     *
-     * Passing `disableChecks` in the options skips constructor validation.
-     *
-     * **Example** (Defining a basic class)
-     *
-     * ```ts import.meta.vitest
-     * import { Schema } from "effect"
-     *
-     * class Person extends Schema.Class<Person>("Person")({
-     *   name: Schema.String,
-     *   age: Schema.Number
-     * }) {}
-     *
-     * const alice = new Person({ name: "Alice", age: 30 })
-     * alice.name // => "Alice"
-     * String(alice) // => "Person({\"name\":\"Alice\",\"age\":30})"
-     * ```
-     *
-     * **Example** (Extending a class)
-     *
-     * ```ts import.meta.vitest
-     * import { Schema } from "effect"
-     *
-     * class Animal extends Schema.Class<Animal>("Animal")({
-     *   name: Schema.String
-     * }) {}
-     *
-     * class Dog extends Animal.extend<Dog>("Dog")({
-     *   breed: Schema.String
-     * }) {}
-     *
-     * const dog = new Dog({ name: "Rex", breed: "Labrador" })
-     * dog.name // => "Rex"
-     * dog.breed // => "Labrador"
-     * ```
-     *
-     * @see {@link TaggedClass} for adding a `_tag` literal field to the class schema
-     * @see {@link Error} for defining schema-backed error classes
-     * @see {@link TaggedError} for defining tagged schema-backed error classes
-     *
-     * @stability stable
-     * @category constructors
-     * @since 3.10.0
-     */
-    <S extends Struct<Struct.Fields>>(schema: S, annotations?: Annotations.Declaration<Self, readonly [S]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.Class"> : Class<Self, S, Brand>
+    <S extends Struct<Struct.Fields>>(
+      schema: S,
+      annotations?: Annotations.Declaration<Self, readonly [S]>
+    ): [Self] extends [never] ? MissingSelfGeneric<"Schema.Class"> : Class<Self, S, Brand>
   }
 } = <Self, Brand = {}>(identifier: string) =>
 (
@@ -16394,73 +16627,11 @@ export const TaggedClass: {
    * @since 3.10.0
    */
   <Self = never, Brand = {}>(identifier?: string): {
-    /**
-     * Defines a schema-backed class with an automatically populated `_tag` field.
-     *
-     * **When to use**
-     *
-     * Use to define class instances that are validated by a schema and participate
-     * in tagged union matching.
-     *
-     * **Details**
-     *
-     * The optional `identifier` parameter overrides the schema identifier;
-     * it defaults to the `tag` value.
-     *
-     * **Example** (Defining a tagged class)
-     *
-     * ```ts import.meta.vitest
-     * import { Schema } from "effect"
-     *
-     * class Circle extends Schema.TaggedClass<Circle>()("Circle", {
-     *   radius: Schema.Number
-     * }) {}
-     *
-     * const c = new Circle({ radius: 5 })
-     * c._tag // => "Circle"
-     * c.radius // => 5
-     * ```
-     *
-     * @stability stable
-     * @category constructors
-     * @since 3.10.0
-     */
     <Tag extends string, const Fields extends Struct.Fields>(
       tag: Tag,
       fields: Fields,
       annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>
     ): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedClass"> : Class<Self, TaggedStruct<Tag, Fields>, Brand>
-    /**
-     * Defines a schema-backed class with an automatically populated `_tag` field.
-     *
-     * **When to use**
-     *
-     * Use to define class instances that are validated by a schema and participate
-     * in tagged union matching.
-     *
-     * **Details**
-     *
-     * The optional `identifier` parameter overrides the schema identifier;
-     * it defaults to the `tag` value.
-     *
-     * **Example** (Defining a tagged class)
-     *
-     * ```ts import.meta.vitest
-     * import { Schema } from "effect"
-     *
-     * class Circle extends Schema.TaggedClass<Circle>()("Circle", {
-     *   radius: Schema.Number
-     * }) {}
-     *
-     * const c = new Circle({ radius: 5 })
-     * c._tag // => "Circle"
-     * c.radius // => 5
-     * ```
-     *
-     * @stability stable
-     * @category constructors
-     * @since 3.10.0
-     */
     <Tag extends string, S extends Struct<Struct.Fields>>(
       tag: Tag,
       schema: S,
@@ -16542,64 +16713,15 @@ export const Error: {
    * @since 4.0.0
    */
   <Self = never, Brand = {}>(identifier: string): {
-    /**
-     * Creates a schema-backed error class that can be used as a typed,
-     * yieldable error in Effect programs. Combines {@link Class} validation with
-     * the `YieldableError` interface so instances can be yielded directly inside
-     * `Effect.gen`.
-     *
-     * **Example** (Schema-backed error)
-     *
-     * ```ts import.meta.vitest
-     * import { Effect, Schema } from "effect"
-     *
-     * class NotFound extends Schema.Error<NotFound>("NotFound")({
-     *   id: Schema.Number
-     * }) {}
-     *
-     * const program = Effect.gen(function*() {
-     *   yield* new NotFound({ id: 1 })
-     * })
-     * const error = await Effect.runPromise(Effect.flip(program))
-     * error.id // => 1
-     * ```
-     *
-     * @stability stable
-     * @category constructors
-     * @since 4.0.0
-     */
     <const Fields extends Struct.Fields>(
       fields: Fields,
       annotations?: Annotations.Declaration<Self, readonly [Struct<Fields>]>
     ): [Self] extends [never] ? MissingSelfGeneric<"Schema.Error">
       : Class<Self, Struct<Fields>, Cause_.YieldableError & Brand>
-    /**
-     * Creates a schema-backed error class that can be used as a typed,
-     * yieldable error in Effect programs. Combines {@link Class} validation with
-     * the `YieldableError` interface so instances can be yielded directly inside
-     * `Effect.gen`.
-     *
-     * **Example** (Schema-backed error)
-     *
-     * ```ts import.meta.vitest
-     * import { Effect, Schema } from "effect"
-     *
-     * class NotFound extends Schema.Error<NotFound>("NotFound")({
-     *   id: Schema.Number
-     * }) {}
-     *
-     * const program = Effect.gen(function*() {
-     *   yield* new NotFound({ id: 1 })
-     * })
-     * const error = await Effect.runPromise(Effect.flip(program))
-     * error.id // => 1
-     * ```
-     *
-     * @stability stable
-     * @category constructors
-     * @since 4.0.0
-     */
-    <S extends Struct<Struct.Fields>>(schema: S, annotations?: Annotations.Declaration<Self, readonly [S]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.Error"> : Class<Self, S, Cause_.YieldableError & Brand>
+    <S extends Struct<Struct.Fields>>(
+      schema: S,
+      annotations?: Annotations.Declaration<Self, readonly [S]>
+    ): [Self] extends [never] ? MissingSelfGeneric<"Schema.Error"> : Class<Self, S, Cause_.YieldableError & Brand>
   }
 } = <Self, Brand = {}>(identifier: string) =>
 (
@@ -16682,72 +16804,12 @@ export const TaggedError: {
    * @since 3.10.0
    */
   <Self = never, Brand = {}>(identifier?: string): {
-    /**
-     * Defines a schema-backed yieldable error class with an automatically populated
-     * `_tag` field.
-     *
-     * **When to use**
-     *
-     * Use to define typed errors that are schema validated, yielded in `Effect.gen`,
-     * and matched as tagged union members.
-     *
-     * **Example** (Defining a tagged error class)
-     *
-     * ```ts import.meta.vitest
-     * import { Effect, Schema } from "effect"
-     *
-     * class NotFound extends Schema.TaggedError<NotFound>()("NotFound", {
-     *   id: Schema.Number
-     * }) {}
-     *
-     * const program = Effect.gen(function*() {
-     *   yield* new NotFound({ id: 42 })
-     * })
-     * const error = await Effect.runPromise(Effect.flip(program))
-     * error._tag // => "NotFound"
-     * error.id // => 42
-     * ```
-     *
-     * @stability stable
-     * @category constructors
-     * @since 3.10.0
-     */
     <Tag extends string, const Fields extends Struct.Fields>(
       tag: Tag,
       fields: Fields,
       annotations?: Annotations.Declaration<Self, readonly [TaggedStruct<Tag, Fields>]>
     ): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedError">
       : Class<Self, TaggedStruct<Tag, Fields>, Cause_.YieldableError & Brand>
-    /**
-     * Defines a schema-backed yieldable error class with an automatically populated
-     * `_tag` field.
-     *
-     * **When to use**
-     *
-     * Use to define typed errors that are schema validated, yielded in `Effect.gen`,
-     * and matched as tagged union members.
-     *
-     * **Example** (Defining a tagged error class)
-     *
-     * ```ts import.meta.vitest
-     * import { Effect, Schema } from "effect"
-     *
-     * class NotFound extends Schema.TaggedError<NotFound>()("NotFound", {
-     *   id: Schema.Number
-     * }) {}
-     *
-     * const program = Effect.gen(function*() {
-     *   yield* new NotFound({ id: 42 })
-     * })
-     * const error = await Effect.runPromise(Effect.flip(program))
-     * error._tag // => "NotFound"
-     * error.id // => 42
-     * ```
-     *
-     * @stability stable
-     * @category constructors
-     * @since 3.10.0
-     */
     <Tag extends string, S extends Struct<Struct.Fields>>(
       tag: Tag,
       schema: S,
@@ -17317,6 +17379,179 @@ export const toCodecArrayFromSingle: {
    */
   <S extends Constraint>(schema: S): toCodecArrayFromSingle<S>
 } = InternalToCodec.toCodecArrayFromSingle
+/**
+ * Type-level representation returned by {@link toCodecGoJson}.
+ *
+ * @stability unstable
+ * @category converting
+ * @since 4.0.6
+ */
+export interface toCodecGoJson<S extends Constraint> extends
+  BottomLazy<
+    S["ast"],
+    toCodecGoJson<S>,
+    S["~type.parameters"],
+    S["~type.mutability"],
+    S["~type.optionality"],
+    S["~type.constructor.default"],
+    S["~encoded.mutability"],
+    S["~encoded.optionality"]
+  >
+{
+  readonly "Type": S["Type"]
+  readonly "Encoded": Json
+  readonly "DecodingServices": S["DecodingServices"]
+  readonly "EncodingServices": S["EncodingServices"]
+  readonly "~type.make.in": S["~type.make.in"]
+  readonly "~type.make": S["~type.make"]
+  readonly "Iso": S["Iso"]
+  readonly schema: S
+}
+/**
+ * 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: {
+  /**
+   * 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
+   */
+  <S extends Constraint>(schema: S): toCodecGoJson<S>
+} = InternalToCodec.toCodecGoJson
 type XmlEncoderOptions = {
   /** Root element name for the returned XML string. Default: "root" */
   readonly rootName?: string | undefined
@@ -17934,7 +18169,7 @@ export declare namespace Annotations {
     readonly "~sentinels"?: ReadonlyArray<SchemaAST.Sentinel> | undefined
   }
   /**
-   * Annotations for filter schema nodes (created via `Schema.filter`). Extends
+   * Annotations for filter checks (created via `Schema.makeFilter`). Extends
    * {@link Augment} with an optional error message, identifier, and metadata.
    * Filters are intentionally non-parametric to keep them covariant.
    *