effect 4.0.0-beta.70 → 4.0.0-beta.71

package/dist/Schema.js

@@ -1351,6 +1351,12 @@ export const Number = /*#__PURE__*/make(AST.number);
 /**
  * Schema for `boolean` values. Validates that the input is `typeof` `"boolean"`.
  *
+ * **When to use**
+ *
+ * Use to validate values that are already JavaScript booleans.
+ *
+ * @see {@link BooleanFromBit} for a schema that decodes bit literals `0` or `1` into a boolean
+ *
  * @category Boolean
  * @since 4.0.0
  */
@@ -1366,6 +1372,13 @@ export const Symbol = /*#__PURE__*/make(AST.symbol);
 /**
  * Schema for `bigint` values. Validates that the input is `typeof` `"bigint"`.
  *
+ * **When to use**
+ *
+ * Use when the input is already a bigint and the schema should validate and
+ * preserve bigint values without parsing from another representation.
+ *
+ * @see {@link BigIntFromString} for parsing string input into a bigint
+ *
  * @category schemas
  * @since 4.0.0
  */
@@ -1708,7 +1721,7 @@ export function TupleWithRest(schema, rest) {
  * @since 4.0.0
  */
 const ArraySchema = /*#__PURE__*/Struct_.lambda(schema => make(new AST.Arrays(false, [], [schema.ast]), {
-  schema
+  value: schema
 }));
 export {
 /**
@@ -1749,22 +1762,32 @@ ArraySchema as Array };
  * @since 3.10.0
  */
 export const NonEmptyArray = /*#__PURE__*/Struct_.lambda(schema => make(new AST.Arrays(false, [schema.ast], [schema.ast]), {
-  schema
+  value: schema
 }));
 /**
  * Creates a schema that accepts either a value decoded by `schema` or an array
  * decoded by `Schema.Array(schema)`, then returns an array.
  *
+ * **When to use**
+ *
+ * Use to accept input that may be provided either as one item or as an array,
+ * while normalizing decoded values to a readonly array.
+ *
  * **Details**
  *
+ * During encoding, one-element arrays are encoded as the single element. Empty
+ * arrays and arrays with two or more elements are encoded as arrays.
+ *
+ * **Gotchas**
+ *
  * The single-value branch is tried before the array branch. If `schema` itself
  * accepts arrays, an array input can be treated as one value and wrapped in a
  * one-element array.
  *
- * During encoding, one-element arrays are encoded as the single element. Empty
- * arrays and arrays with two or more elements are encoded as arrays.
+ * @see {@link Array} for accepting only array input
+ * @see {@link NonEmptyArray} for requiring at least one decoded element
  *
- * @category Arrays
+ * @category constructors
  * @since 3.10.0
  */
 export function ArrayEnsure(schema) {
@@ -1969,6 +1992,18 @@ export function refine(refinement, annotations) {
  * Adds a nominal brand to a schema, intersecting the output type with
  * `Brand.Brand<B>` to prevent accidental mixing of structurally identical types.
  *
+ * **When to use**
+ *
+ * Use to make values decoded by an existing schema nominally distinct when the
+ * schema already carries the runtime validation you need.
+ *
+ * **Gotchas**
+ *
+ * `brand` adds brand metadata and narrows the TypeScript output type, but it
+ * does not add runtime checks.
+ *
+ * @see {@link fromBrand} for applying a Brand constructor's checks along with the brand tag
+ *
  * @category branding
  * @since 3.10.0
  */
@@ -2078,6 +2113,19 @@ export function catchDecoding(f) {
 /**
  * Like {@link catchDecoding}, but the handler may require Effect services (`R`).
  *
+ * **When to use**
+ *
+ * Use when decoding fallback logic needs services from the Effect context.
+ *
+ * **Details**
+ *
+ * The handler receives the `Issue` and returns an `Effect` that either succeeds
+ * with a fallback value or re-fails with a (possibly different) issue. The
+ * handler's services are added to the schema's decoding services.
+ *
+ * @see {@link catchDecoding} for recovery handlers that do not require services
+ * @see {@link middlewareDecoding} for intercepting or replacing the full decoding pipeline
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -2102,6 +2150,19 @@ export function catchEncoding(f) {
 /**
  * Like {@link catchEncoding}, but the handler may require Effect services (`R`).
  *
+ * **When to use**
+ *
+ * Use when encoding fallback logic needs services from the Effect context.
+ *
+ * **Details**
+ *
+ * The handler receives the `Issue` and returns an `Effect` that either succeeds
+ * with a fallback encoded value or re-fails with a (possibly different) issue.
+ * The handler's services are added to the schema's encoding services.
+ *
+ * @see {@link catchEncoding} for recovery handlers that do not require services
+ * @see {@link middlewareEncoding} for intercepting or replacing the full encoding pipeline
+ *
  * @category error handling
  * @since 4.0.0
  */
@@ -3623,6 +3684,8 @@ export function isDateValid(annotations) {
     ...annotations
   });
 }
+const nextDate = date => new globalThis.Date(date.getTime() + 1);
+const previousDate = date => new globalThis.Date(date.getTime() - 1);
 /**
  * Validates that a Date is greater than the specified value (exclusive).
  *
@@ -3630,9 +3693,9 @@ export function isDateValid(annotations) {
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies a `min` constraint
- * with `minExcluded: true` to ensure generated Date objects are greater than the
- * specified value.
+ * When generating test data with fast-check, this applies a `min` constraint of
+ * one millisecond after the specified value to ensure generated Date objects are
+ * greater than it.
  *
  * @category Date checks
  * @since 4.0.0
@@ -3646,8 +3709,7 @@ export const isGreaterThanDate = /*#__PURE__*/makeIsGreaterThan({
     },
     toArbitraryConstraint: {
       date: {
-        min: exclusiveMinimum,
-        minExcluded: true
+        min: nextDate(exclusiveMinimum)
       }
     }
   })
@@ -3693,9 +3755,9 @@ export const isGreaterThanOrEqualToDate = /*#__PURE__*/makeIsGreaterThanOrEqualT
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies a `max` constraint
- * with `maxExcluded: true` to ensure generated Date objects are less than the
- * specified value.
+ * When generating test data with fast-check, this applies a `max` constraint of
+ * one millisecond before the specified value to ensure generated Date objects
+ * are less than it.
  *
  * @category Date checks
  * @since 4.0.0
@@ -3709,8 +3771,7 @@ export const isLessThanDate = /*#__PURE__*/makeIsLessThan({
     },
     toArbitraryConstraint: {
       date: {
-        max: exclusiveMaximum,
-        maxExcluded: true
+        max: previousDate(exclusiveMaximum)
       }
     }
   })
@@ -3763,7 +3824,8 @@ export const isLessThanOrEqualToDate = /*#__PURE__*/makeIsLessThanOrEqualTo({
  * Arbitrary:
  *
  * When generating test data with fast-check, this applies `min` and `max`
- * constraints to ensure generated Date objects fall within the specified range.
+ * constraints to ensure generated Date objects fall within the specified range,
+ * shifting exclusive bounds by one millisecond.
  *
  * @category Date checks
  * @since 4.0.0
@@ -3777,12 +3839,14 @@ export const isBetweenDate = /*#__PURE__*/makeIsBetween({
     },
     toArbitraryConstraint: {
       date: {
-        min: options.minimum,
-        max: options.maximum
+        min: options.exclusiveMinimum ? nextDate(options.minimum) : options.minimum,
+        max: options.exclusiveMaximum ? previousDate(options.maximum) : options.maximum
       }
     }
   })
 });
+const nextBigInt = n => n + globalThis.BigInt(1);
+const previousBigInt = n => n - globalThis.BigInt(1);
 /**
  * Validates that a BigInt is greater than the specified value (exclusive).
  *
@@ -3790,8 +3854,8 @@ export const isBetweenDate = /*#__PURE__*/makeIsBetween({
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies a `min` constraint
- * with `minExcluded: true` to ensure generated BigInts are greater than the
+ * When generating test data with fast-check, this applies a `min` constraint of
+ * `exclusiveMinimum + 1n` to ensure generated BigInts are greater than the
  * specified value.
  *
  * @category BigInt checks
@@ -3806,8 +3870,7 @@ export const isGreaterThanBigInt = /*#__PURE__*/makeIsGreaterThan({
     },
     toArbitraryConstraint: {
       bigint: {
-        min: exclusiveMinimum,
-        minExcluded: true
+        min: nextBigInt(exclusiveMinimum)
       }
     }
   })
@@ -3848,8 +3911,8 @@ export const isGreaterThanOrEqualToBigInt = /*#__PURE__*/makeIsGreaterThanOrEqua
  *
  * Arbitrary:
  *
- * When generating test data with fast-check, this applies a `max` constraint
- * with `maxExcluded: true` to ensure generated BigInts are less than the
+ * When generating test data with fast-check, this applies a `max` constraint of
+ * `exclusiveMaximum - 1n` to ensure generated BigInts are less than the
  * specified value.
  *
  * @category BigInt checks
@@ -3864,8 +3927,7 @@ export const isLessThanBigInt = /*#__PURE__*/makeIsLessThan({
     },
     toArbitraryConstraint: {
       bigint: {
-        max: exclusiveMaximum,
-        maxExcluded: true
+        max: previousBigInt(exclusiveMaximum)
       }
     }
   })
@@ -3923,8 +3985,8 @@ export const isBetweenBigInt = /*#__PURE__*/makeIsBetween({
     },
     toArbitraryConstraint: {
       bigint: {
-        min: options.minimum,
-        max: options.maximum
+        min: options.exclusiveMinimum ? nextBigInt(options.minimum) : options.minimum,
+        max: options.exclusiveMaximum ? previousBigInt(options.maximum) : options.maximum
       }
     }
   })
@@ -4452,7 +4514,20 @@ export function isUnique(annotations) {
  */
 export const NonEmptyString = /*#__PURE__*/String.check(/*#__PURE__*/isNonEmpty());
 /**
- * A schema representing a single character.
+ * A schema for strings whose JavaScript `length` is exactly `1`.
+ *
+ * **When to use**
+ *
+ * Use to validate string values that must have `length === 1`.
+ *
+ * **Gotchas**
+ *
+ * This schema uses JavaScript `String.length`, so visible characters made from
+ * multiple UTF-16 code units do not satisfy `length === 1`.
+ *
+ * @see {@link String} for unconstrained string values
+ * @see {@link NonEmptyString} for strings with length greater than zero
+ * @see {@link isLengthBetween} for the underlying length check
  *
  * @category String
  * @since 3.10.0
@@ -4724,11 +4799,9 @@ export function Result(success, failure) {
  *   - The default JSON serializer will deserialize into a `Redacted` instance with the label
  *   - The arbitrary generator will produce a `Redacted` instance with the label
  *   - The formatter will return the label
- *
- * Default JSON serializer:
- *
- * The default JSON serializer will fail when attempting to serialize a `Redacted` value,
- * but it will deserialize a value into a `Redacted` instance.
+ * - `disallowJsonEncode`: When set to `true`, when attempting to encode a `Redacted` instance
+ *   into JSON, it will fail with an error. This is useful when the wrapped schema is
+ *   sensitive and should not be exposed in JSON.
  *
  * @category Redacted
  * @since 3.10.0
@@ -4762,7 +4835,7 @@ export function Redacted(value, options) {
       decode: Getter.transform(e => Redacted_.make(e, {
         label: options?.label
       })),
-      encode: Getter.forbidden(oe => "Cannot serialize Redacted" + (Option_.isSome(oe) && typeof oe.value.label === "string" ? ` with label: "${oe.value.label}"` : ""))
+      encode: options?.disallowJsonEncode ? Getter.forbidden(oe => "Cannot serialize Redacted" + (Option_.isSome(oe) && typeof oe.value.label === "string" ? ` with label: "${oe.value.label}"` : "")) : Getter.transform(Redacted_.value)
     }),
     toArbitrary: ([value]) => () => value.map(a => Redacted_.make(a, {
       label: options?.label
@@ -4793,17 +4866,33 @@ export function redact(schema) {
  * @since 4.0.0
  */
 export function RedactedFromValue(value, options) {
-  return redact(value).pipe(decodeTo(Redacted(toType(value), options), {
+  return redact(value).pipe(decodeTo(Redacted(toType(value), {
+    label: options?.label,
+    disallowJsonEncode: options?.disallowEncode
+  }), {
     decode: Getter.transform(t => Redacted_.make(t, {
       label: options?.label
     })),
-    encode: Getter.forbidden(oe => "Cannot encode Redacted" + (Option_.isSome(oe) && typeof oe.value.label === "string" ? ` with label: "${oe.value.label}"` : ""))
+    encode: options?.disallowEncode ? Getter.forbidden(oe => "Cannot encode Redacted" + (Option_.isSome(oe) && typeof oe.value.label === "string" ? ` with label: "${oe.value.label}"` : "")) : Getter.transform(Redacted_.value)
   }));
 }
 /**
  * Creates a schema for `Cause.Reason` values using separate schemas for typed
  * failures and unexpected defects.
  *
+ * **When to use**
+ *
+ * Use to validate, transform, or serialize individual `Cause.Reason` values
+ * when typed failures and unexpected defects need separate schemas.
+ *
+ * **Details**
+ *
+ * `Fail` reasons use the `error` schema, `Die` reasons use the `defect` schema,
+ * and `Interrupt` reasons carry only an optional fiber id.
+ *
+ * @see {@link Cause} for constructing schemas for full Cause values
+ * @see {@link CauseReasonIso} for the ISO shape of each cause reason
+ *
  * @category CauseReason
  * @since 4.0.0
  */
@@ -4906,6 +4995,20 @@ function causeReasonToFormatter(error, defect) {
  * Creates a schema for `Cause` values using separate schemas for typed failures
  * and unexpected defects.
  *
+ * **When to use**
+ *
+ * Use to validate, transform, or serialize Effect failure causes when typed
+ * failures and unexpected defects need separate schemas.
+ *
+ * **Details**
+ *
+ * The `error` schema is applied to `Fail` reasons and the `defect` schema is
+ * applied to `Die` reasons. Interrupt reasons do not use either schema and
+ * carry only an optional fiber id.
+ *
+ * @see {@link CauseReason} for the schema used by each individual cause reason
+ * @see {@link CauseIso} for the ordered array representation used by the schema ISO
+ *
  * @category Cause
  * @since 3.10.0
  */
@@ -5493,12 +5596,16 @@ const DateString = /*#__PURE__*/String.annotate({
 /**
  * A schema for JavaScript `Date` objects.
  *
+ * **When to use**
+ *
+ * Use to validate in-memory values that must already be JavaScript `Date`
+ * instances.
+ *
  * **Details**
  *
- * This schema accepts any `Date` instance, including invalid dates. For
- * validating only valid dates, use `DateValid` instead. The default JSON
- * serializer encodes valid dates as ISO 8601 strings; invalid dates encode as
- * `"Invalid Date"`.
+ * This schema accepts any `Date` instance, including invalid dates. The default
+ * JSON serializer encodes valid dates as ISO 8601 strings; invalid dates encode
+ * as `"Invalid Date"`.
  *
  * **Example** (Date schema)
  *
@@ -5509,6 +5616,8 @@ const DateString = /*#__PURE__*/String.annotate({
  * // => Date { 2024-01-01T00:00:00.000Z }
  * ```
  *
+ * @see {@link DateValid} for accepting only valid Date instances
+ *
  * @category Date
  * @since 4.0.0
  */
@@ -5527,16 +5636,27 @@ export const Date = /*#__PURE__*/instanceOf(globalThis.Date, {
 /**
  * A transformation schema that decodes a string into a JavaScript `Date`.
  *
+ * **When to use**
+ *
+ * Use to model string-encoded dates that decode to JavaScript `Date` objects
+ * and encode back to strings.
+ *
  * **Details**
  *
  * Decoding:
- * The string is passed to JavaScript `Date` construction and may decode to an
- * invalid `Date`. Compose with `DateValid` when invalid dates should be rejected.
+ * The string is passed to JavaScript `Date` construction.
  *
  * Encoding:
  * A valid `Date` is encoded as an ISO string; an invalid `Date` is encoded as
  * `"Invalid Date"`.
  *
+ * **Gotchas**
+ *
+ * Invalid date strings can decode to invalid `Date` instances.
+ *
+ * @see {@link Date} for accepting Date instances directly
+ * @see {@link DateValid} for rejecting invalid Date instances
+ *
  * @category Date
  * @since 3.10.0
  */
@@ -5697,12 +5817,19 @@ const BigDecimalString = /*#__PURE__*/String.annotate({
 /**
  * A schema for `BigDecimal` values.
  *
+ * **When to use**
+ *
+ * Use when values are already `BigDecimal` instances and need schema validation,
+ * formatting, equivalence, and JSON string serialization.
+ *
  * **Details**
  *
  * Default JSON serializer:
  *
  * - encodes `BigDecimal` as a `string`
  *
+ * @see {@link BigDecimalFromString} for parsing string input into a BigDecimal
+ *
  * @category BigDecimal
  * @since 3.10.0
  */
@@ -5727,13 +5854,26 @@ export const BigDecimal = /*#__PURE__*/declare(BigDecimal_.isBigDecimal, {
 /**
  * A transformation schema that parses a string into a `BigDecimal`.
  *
+ * **When to use**
+ *
+ * Use to parse decimal or exponent-notation strings into arbitrary-precision
+ * BigDecimal values while encoding them back to strings.
+ *
  * **Details**
  *
  * Decoding:
- * - A `string` is decoded as a `BigDecimal`.
+ * - A `string` is decoded with `BigDecimal.fromString`.
  *
  * Encoding:
- * - A `BigDecimal` is encoded as a `string`.
+ * - A `BigDecimal` is encoded with `BigDecimal.format`.
+ *
+ * **Gotchas**
+ *
+ * An empty string decodes as zero.
+ *
+ * @see {@link BigDecimal} for validating values that are already BigDecimal values
+ * @see {@link BigIntFromString} for parsing base-10 integer strings into bigint values
+ * @see {@link NumberFromString} for parsing JavaScript number strings
  *
  * @category BigDecimal
  * @since 4.0.0
@@ -6194,6 +6334,11 @@ export const FiniteFromString = /*#__PURE__*/String.annotate({
 /**
  * A transformation schema that parses a string into a `bigint`.
  *
+ * **When to use**
+ *
+ * Use to parse signed base-10 integer strings into bigint values while encoding
+ * bigint values back to decimal strings.
+ *
  * **Details**
  *
  * Decoding:
@@ -6202,6 +6347,15 @@ export const FiniteFromString = /*#__PURE__*/String.annotate({
  * Encoding:
  * - A `bigint` is encoded as a `string`.
  *
+ * **Gotchas**
+ *
+ * Decoding accepts only strings matching `^-?\d+$`.
+ *
+ * @see {@link isStringBigInt} for the string predicate used by this schema
+ * @see {@link BigInt} for validating values that are already bigint values
+ * @see {@link NumberFromString} for parsing JavaScript number strings, including non-finite values
+ * @see {@link BigDecimalFromString} for parsing decimal number strings
+ *
  * @category BigInt
  * @since 4.0.0
  */
@@ -6347,6 +6501,19 @@ export const StandardSchemaV1FailureResult = /*#__PURE__*/Struct({
 /**
  * A boolean parsed from 0 or 1.
  *
+ * **When to use**
+ *
+ * Use when decoding data sources that represent booleans as `0 | 1` while
+ * keeping boolean values in the decoded model.
+ *
+ * **Details**
+ *
+ * Decoding accepts only `0 | 1`, maps `1` to `true`, and maps `0` to `false`.
+ * Encoding maps `true` to `1` and `false` to `0`.
+ *
+ * @see {@link Boolean} for validating values that are already booleans
+ * @see {@link Literals} for keeping bit literals instead of decoding them
+ *
  * @category Boolean
  * @since 4.0.0
  */
@@ -6444,11 +6611,20 @@ export const Uint8ArrayFromHex = /*#__PURE__*/String.annotate({
 /**
  * A schema for `DateTime.Utc` values.
  *
+ * **When to use**
+ *
+ * Use to validate existing `DateTime.Utc` schema values and use the default JSON
+ * codec that represents them as UTC ISO strings.
+ *
  * **Details**
  *
- * Default JSON serializer:
+ * The default JSON codec decodes UTC ISO strings into `DateTime.Utc` values and
+ * encodes `DateTime.Utc` values as UTC ISO strings.
  *
- * - encodes `DateTime.Utc` as a UTC ISO string
+ * @see {@link DateTimeUtcFromString} for decoding date-time strings into UTC values
+ * @see {@link DateTimeUtcFromDate} for decoding JavaScript Date values into UTC values
+ * @see {@link DateTimeUtcFromMillis} for decoding epoch milliseconds into UTC values
+ * @see {@link DateTimeZoned} for preserving zoned DateTime values
  *
  * @category DateTime
  * @since 3.10.0
@@ -6474,6 +6650,11 @@ export const DateTimeUtc = /*#__PURE__*/declare(u => DateTime.isDateTime(u) && D
 /**
  * A transformation schema that decodes a `Date` into a `DateTime.Utc`.
  *
+ * **When to use**
+ *
+ * Use when a boundary provides valid JavaScript `Date` objects but the decoded
+ * model should use `DateTime.Utc`.
+ *
  * **Details**
  *
  * Decoding:
@@ -6482,6 +6663,11 @@ export const DateTimeUtc = /*#__PURE__*/declare(u => DateTime.isDateTime(u) && D
  * Encoding:
  * - A `DateTime.Utc` is encoded as a `Date`
  *
+ * @see {@link DateTimeUtc} for validating values that are already `DateTime.Utc`
+ * @see {@link DateTimeUtcFromString} for decoding date-time strings into UTC values
+ * @see {@link DateTimeUtcFromMillis} for decoding epoch milliseconds into UTC values
+ * @see {@link DateValid} for validating Date instances without converting them
+ *
  * @category DateTime
  * @since 3.12.0
  */
@@ -6809,13 +6995,23 @@ function isStruct(schema) {
 /**
  * Creates a schema-backed class whose constructor validates input against a
  * {@link Struct} schema. Construction throws a {@link SchemaError} on invalid
- * input (unless `disableChecks` is set in the options).
+ * input.
+ *
+ * **When to use**
+ *
+ * Use to define a schema-backed data class when you want 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.
  *
+ * **Gotchas**
+ *
+ * Passing `disableChecks` in the options skips constructor validation.
+ *
  * **Example** (Basic class)
  *
  * ```ts
@@ -6849,6 +7045,10 @@ function isStruct(schema) {
  * console.log(dog.breed) // "Labrador"
  * ```
  *
+ * @see {@link TaggedClass} for adding a `_tag` literal field to the class schema
+ * @see {@link ErrorClass} for defining schema-backed error classes
+ * @see {@link TaggedErrorClass} for defining tagged schema-backed error classes
+ *
  * @category constructors
  * @since 3.10.0
  */