effect 4.0.5 → 4.0.7

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**
  *
@@ -2125,11 +2127,18 @@ export function extendTo(fields, derive) {
  *
  * **Gotchas**
  *
+ * Dynamic records reject value schemas wrapped with {@link optionalKey} or
+ * {@link optional}. Index signatures already allow keys to be absent; use
+ * {@link UndefinedOr} when existing entries may contain `undefined`. Optional
+ * value schemas remain valid for finite literal keys, which become declared
+ * properties.
+ *
  * When decoded or encoded key transformations produce the same property key,
  * sequential parsing applies selected own properties in selection order, so
  * the later selected property overwrites the earlier value. Dynamic key
- * selection always examines own properties. Finite literal keys are declared
- * fields and may therefore be inherited. Output key order is not guaranteed.
+ * selection always examines own properties. Finite literal and enum keys are
+ * declared fields and may therefore be inherited. Output key order is not
+ * guaranteed.
  *
  * **Example** (Defining a string-keyed record of numbers)
  *
@@ -3211,10 +3220,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)
  *
@@ -3456,9 +3464,8 @@ export function link() {
  * )
  *
  * const result = Schema.decodeUnknownResult(schema)({ password: "123456", confirmPassword: "1234567" })
- * if (Result.isFailure(result) && result.failure.issue._tag === "Filter" && result.failure.issue.issue._tag === "Pointer") {
- *   result.failure.issue.issue.path // => ["password"]
- * }
+ * const message = Result.isFailure(result) ? result.failure.message : ""
+ * message // => "password and confirmPassword must match\n  at [\"password\"]"
  * ```
  *
  * **Example** (Reporting multiple failures at once)
@@ -3478,9 +3485,8 @@ export function link() {
  * )
  *
  * const result = Schema.decodeUnknownResult(schema)({ a: 1, b: 0, c: 0 })
- * if (Result.isFailure(result) && result.failure.issue._tag === "Filter" && result.failure.issue.issue._tag === "Composite") {
- *   result.failure.issue.issue.issues.map((issue) => issue._tag === "Pointer" ? issue.path : []) // => [["b"], ["c"]]
- * }
+ * const message = Result.isFailure(result) ? result.failure.message : ""
+ * message // => "b must be greater than 0\n  at [\"b\"]\nc must be greater than 0\n  at [\"c\"]"
  * ```
  *
  * @stability stable
@@ -3566,7 +3572,7 @@ export function isPattern(regExp, annotations) {
   const source = regExp.source;
   const flags = regExp.flags;
   const canExport = /^[dg]*uy?$/.test(flags);
-  const runtimeRegExp = flags === "" ? `new RegExp(${format(source)})` : `new RegExp(${format(source)}, ${format(flags)})`;
+  const runtimeRegExp = flags === "" ? `new globalThis.RegExp(${format(source)})` : `new globalThis.RegExp(${format(source)}, ${format(flags)})`;
   return SchemaAST.isPattern(regExp, {
     toJsonSchema: () => canExport ? {
       pattern: flags.endsWith("y") ? `^(?:${source})` : source
@@ -3708,7 +3714,7 @@ export function isUUID(version, annotations) {
     ...annotations
   });
 }
-const GUID_REGEXP = /^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$/;
+const GUID_REGEXP = /^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$/u;
 /**
  * Validates that a string has the GUID / UUID textual shape.
  *
@@ -3741,21 +3747,22 @@ export function isGUID(annotations) {
       id: "effect/schema/isGUID",
       payload: null
     },
-    toJsonSchema: () => ({
-      pattern: GUID_REGEXP.source
-    }),
     toCode: () => ({
       runtime: "Schema.isGUID()"
     }),
     ...annotations
   });
 }
+const ULID_REGEXP = /^[0-7][0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{25}$/u;
 /**
  * Validates that a string is a valid ULID (Universally Unique Lexicographically
  * Sortable Identifier).
  *
  * **Details**
  *
+ * Accepts uppercase and lowercase characters. The first character must be
+ * between `0` and `7` so the value fits in 128 bits.
+ *
  * JSON Schema:
  *
  * This check corresponds to a `pattern` constraint in JSON Schema that matches
@@ -3771,15 +3778,11 @@ export function isGUID(annotations) {
  * @since 4.0.0
  */
 export function isULID(annotations) {
-  const regExp = /^[0-9A-HJKMNP-TV-Za-hjkmnp-tv-z]{26}$/;
-  return isPattern(regExp, {
+  return isPattern(ULID_REGEXP, {
     representation: {
       id: "effect/schema/isULID",
       payload: null
     },
-    toJsonSchema: () => ({
-      pattern: regExp.source
-    }),
     toCode: () => ({
       runtime: "Schema.isULID()"
     }),
@@ -3806,16 +3809,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 +3854,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()"
     }),
@@ -4070,15 +4089,17 @@ const CAPITALIZED_PATTERN = "^(?:[^a-z][\\s\\S]*)?$";
  * @since 4.0.0
  */
 export function isCapitalized(annotations) {
-  const regExp = new globalThis.RegExp(CAPITALIZED_PATTERN);
-  return makeFilter(s => s.charAt(0).toUpperCase() === s.charAt(0), {
+  return makeFilter(s => {
+    const [first = ""] = s;
+    return first.toUpperCase() === first;
+  }, {
     expected: "a string with the first character in uppercase",
     representation: {
       id: "effect/schema/isCapitalized",
       payload: null
     },
     toJsonSchema: () => [{
-      pattern: regExp.source
+      pattern: CAPITALIZED_PATTERN
     }, true],
     toCode: () => ({
       runtime: "Schema.isCapitalized()"
@@ -4107,15 +4128,17 @@ const UNCAPITALIZED_PATTERN = "^(?:[^A-Z][\\s\\S]*)?$";
  * @since 4.0.0
  */
 export function isUncapitalized(annotations) {
-  const regExp = new globalThis.RegExp(UNCAPITALIZED_PATTERN);
-  return makeFilter(s => s.charAt(0).toLowerCase() === s.charAt(0), {
+  return makeFilter(s => {
+    const [first = ""] = s;
+    return first.toLowerCase() === first;
+  }, {
     expected: "a string with the first character in lowercase",
     representation: {
       id: "effect/schema/isUncapitalized",
       payload: null
     },
     toJsonSchema: () => [{
-      pattern: regExp.source
+      pattern: UNCAPITALIZED_PATTERN
     }, true],
     toCode: () => ({
       runtime: "Schema.isUncapitalized()"
@@ -4673,7 +4696,7 @@ function encodeDatePayload(date) {
   return date.toISOString();
 }
 function formatDateRuntime(date) {
-  return `new Date(${format(date.getTime())})`;
+  return `new globalThis.Date(${format(date.getTime())})`;
 }
 /**
  * Validates that a Date is greater than the specified value (exclusive).
@@ -6211,8 +6234,7 @@ export const DateFromString = /*#__PURE__*/DateString.pipe(/*#__PURE__*/decodeTo
  */
 export const DateFromMillis = /*#__PURE__*/Int.pipe(/*#__PURE__*/decodeTo(Date, SchemaTransformation.dateFromMillis));
 const JsonString = /*#__PURE__*/String.annotate({
-  expected: "a string that will be decoded as JSON",
-  contentMediaType: "application/json"
+  expected: "a string that will be decoded as JSON"
 });
 /**
  * Returns a schema that decodes a JSON string and then decodes the parsed value
@@ -6317,7 +6339,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 +7261,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 +7518,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 +9253,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 +9616,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) {
@@ -9533,7 +9769,7 @@ function makeClass(Inherited, identifier, struct, annotations, proto) {
       return getClassSchema(this).rebuild(ast);
     }
     static make(input, options) {
-      return SchemaParser.make(getClassSchema(this))(input ?? {}, options);
+      return SchemaParser.makeClassSync(SchemaAST.toType(getClassSchema(this).ast), input ?? {}, options, fields => makeClassTrusted(this, fields));
     }
     static makeOption(input, options) {
       return SchemaParser.makeOption(getClassSchema(this))(input ?? {}, options);
@@ -9572,13 +9808,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 +9884,13 @@ function isStruct(schema) {
  *
  * **Gotchas**
  *
- * Passing `disableChecks` in the options skips constructor validation.
+ * To subclass a `Schema.Class`, use `Base.extend<Self>(...)`, even when only
+ * adding methods or getters. Pass `{}` for the fields when none are added.
+ * Plain `class Child extends Base` is unsupported.
+ *
+ * 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 +10323,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.
  *