effect 4.0.5 → 4.0.6

package/dist/Schema.d.ts

@@ -51,6 +51,8 @@ import * as SchemaGetter from "./SchemaGetter.ts";
 import * as SchemaIssue from "./SchemaIssue.ts";
 import * as SchemaParser from "./SchemaParser.ts";
 import type * as SchemaRepresentation from "./SchemaRepresentation.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";
@@ -94,8 +96,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}
@@ -110,7 +112,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;
 }
@@ -2424,8 +2427,8 @@ export interface Enum<A extends {
     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**
  *
@@ -2449,7 +2452,7 @@ export interface Enum<A extends {
  * @category constructors
  * @since 4.0.0
  */
-export declare function Enum<A extends {
+export declare function Enum<const A extends {
     [x: string]: string | number;
 }>(enums: A): Enum<A>;
 /**
@@ -4629,8 +4632,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)
  *
@@ -5145,8 +5148,6 @@ export declare function TaggedStruct<const Tag extends SchemaAST.LiteralValue, c
  * Recursively flatten any nested Schema.Union members into a single tuple of leaf schemas.
  */
 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];
@@ -5222,10 +5223,9 @@ export type toTaggedUnion<Tag extends PropertyKey, Members extends ReadonlyArray
  *
  * **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)
  *
@@ -5252,7 +5252,7 @@ export type toTaggedUnion<Tag extends PropertyKey, Members extends ReadonlyArray
  */
 export declare function toTaggedUnion<const Tag extends PropertyKey>(tag: Tag): <const Members extends ReadonlyArray<Constraint & {
     readonly Type: { readonly [K in Tag]: PropertyKey; };
-}>>(self: Union<Members> & NoInfer<EnsureUniqueDiscriminants<TaggedUnionUtils<Tag, Members>["discriminants"]>>) => toTaggedUnion<Tag, Members>;
+}>>(self: Union<Members>) => toTaggedUnion<Tag, Members>;
 /**
  * Type-level representation returned by {@link TaggedUnion}.
  *
@@ -8362,6 +8362,42 @@ export interface DateTimeUtcFromString extends decodeTo<DateTimeUtc, String> {
  * @since 4.0.0
  */
 export declare const DateTimeUtcFromString: DateTimeUtcFromString;
+/**
+ * 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 declare const DateTimeUtcFromHttpDate: DateTimeUtcFromHttpDate;
 /**
  * Type-level representation of {@link DateTimeUtcFromMillis}.
  *
@@ -10474,6 +10510,74 @@ export interface Headers extends declare<Headers_.Headers, {
  * @since 4.0.0
  */
 export declare const Headers: Headers;
+/**
+ * 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 declare const RetryAfter: RetryAfter;
+/**
+ * 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 declare const RetryAfterFromString: RetryAfterFromString;
 /**
  * Type-level representation of {@link UrlParams}.
  *
@@ -10755,6 +10859,102 @@ export type ResultIso<A extends Constraint, E extends Constraint> = {
  * @since 4.0.0
  */
 export declare function Result<A extends Constraint, E extends Constraint>(success: A, failure: E): Result<A, E>;
+/**
+ * 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 declare const SemVer: SemVer;
+/**
+ * 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 declare const SemVerFromString: SemVerFromString;
+/**
+ * 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 declare const SemVerRange: SemVerRange;
+/**
+ * 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 declare const SemVerRangeFromString: SemVerRangeFromString;
 /**
  * Type-level representation returned by {@link Class}.
  *
@@ -10857,7 +11057,9 @@ type MissingSelfGeneric<Usage extends string> = `Missing \`Self\` generic - use
  *
  * **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)
  *
@@ -10928,7 +11130,9 @@ export declare 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)
      *
@@ -10972,147 +11176,7 @@ export declare 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>;
     };
 };
@@ -11180,69 +11244,7 @@ export declare 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, annotations?: Annotations.Declaration<Self, readonly [Struct<Simplify<{
             readonly _tag: tag<Tag>;
         } & S["fields"]>>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedClass"> : Class<Self, Struct<Simplify<{
@@ -11304,59 +11306,7 @@ export declare 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>;
     };
 };
@@ -11422,67 +11372,7 @@ export declare 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, annotations?: Annotations.Declaration<Self, readonly [Struct<Simplify<{
             readonly _tag: tag<Tag>;
         } & S["fields"]>>]>): [Self] extends [never] ? MissingSelfGeneric<"Schema.TaggedError"> : Class<Self, Struct<Simplify<{
@@ -11975,6 +11865,168 @@ export declare const toCodecArrayFromSingle: {
      */
     <S extends Constraint>(schema: S): toCodecArrayFromSingle<S>;
 };
+/**
+ * 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 declare 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>;
+};
 type XmlEncoderOptions = {
     /** Root element name for the returned XML string. Default: "root" */
     readonly rootName?: string | undefined;
@@ -12510,7 +12562,7 @@ export declare namespace Annotations {
         readonly toCode?: SchemaRepresentation.Generation.Declaration | 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.
      *