effect 3.12.4 → 3.12.6

package/src/Schema.ts

@@ -3016,9 +3016,7 @@ export const pluck: {
    * @category struct transformations
    * @since 3.10.0
    */
-  <A, I, K extends keyof A & keyof I>(
-    key: K
-  ): <R>(schema: Schema<A, I, R>) => Schema<A[K], { readonly [P in K]: I[P] }, R>
+  <A, I, K extends keyof A & keyof I>(key: K): <R>(schema: Schema<A, I, R>) => Schema<A[K], Simplify<Pick<I, K>>, R>
   /**
    * Given a schema `Schema<A, I, R>` and a key `key: K`, this function extracts a specific field from the `A` type,
    * producing a new schema that represents a transformation from the `{ readonly [key]: I[K] }` type to `A[K]`.
@@ -3049,7 +3047,7 @@ export const pluck: {
    * @category struct transformations
    * @since 3.10.0
    */
-  <A, I, R, K extends keyof A & keyof I>(schema: Schema<A, I, R>, key: K): Schema<A[K], { readonly [P in K]: I[P] }, R>
+  <A, I, R, K extends keyof A & keyof I>(schema: Schema<A, I, R>, key: K): Schema<A[K], Simplify<Pick<I, K>>, R>
 } = dual(
   2,
   <A, I, R, K extends keyof A & keyof I>(
@@ -3722,7 +3720,8 @@ export type RefineSchemaId = typeof RefineSchemaId
 export interface refine<A, From extends Schema.Any>
   extends AnnotableClass<refine<A, From>, A, Schema.Encoded<From>, Schema.Context<From>>
 {
-  readonly [RefineSchemaId]: From // required for `type HasFields = ...`
+  /** The following is required for {@link HasFields} to work */
+  readonly [RefineSchemaId]: From
   readonly from: From
   readonly filter: (
     a: Schema.Type<From>,
@@ -5008,30 +5007,31 @@ export type ParseJsonOptions = {
   readonly space?: Parameters<typeof JSON.stringify>[2]
 }
 
-const JsonString = String$.annotations({
-  [AST.IdentifierAnnotationId]: "JsonString",
-  [AST.TitleAnnotationId]: "JsonString",
-  [AST.DescriptionAnnotationId]: "a string that will be parsed as JSON"
-})
+const getErrorMessage = (e: unknown): string => e instanceof Error ? e.message : String(e)
 
 const getParseJsonTransformation = (options?: ParseJsonOptions) =>
   transformOrFail(
-    JsonString,
+    String$.annotations({
+      [AST.DescriptionAnnotationId]: "a string to be decoded into JSON"
+    }),
     Unknown,
     {
       strict: true,
       decode: (s, _, ast) =>
         ParseResult.try({
           try: () => JSON.parse(s, options?.reviver),
-          catch: (e: any) => new ParseResult.Type(ast, s, e.message)
+          catch: (e) => new ParseResult.Type(ast, s, getErrorMessage(e))
         }),
       encode: (u, _, ast) =>
         ParseResult.try({
           try: () => JSON.stringify(u, options?.replacer, options?.space),
-          catch: (e: any) => new ParseResult.Type(ast, u, e.message)
+          catch: (e) => new ParseResult.Type(ast, u, getErrorMessage(e))
         })
     }
-  ).annotations({ schemaId: AST.ParseJsonSchemaId })
+  ).annotations({
+    title: "parseJson",
+    schemaId: AST.ParseJsonSchemaId
+  })
 
 /**
  * The `ParseJson` combinator provides a method to convert JSON strings into the `unknown` type using the underlying
@@ -5175,14 +5175,19 @@ export class URLFromSelf extends instanceOf(URL, {
 
 /** @ignore */
 class URL$ extends transformOrFail(
-  String$.annotations({ description: "a string that will be parsed into a URL" }),
+  String$.annotations({ description: "a string to be decoded into a URL" }),
   URLFromSelf,
   {
     strict: true,
-    decode: (str, _, ast) =>
+    decode: (s, _, ast) =>
       ParseResult.try({
-        try: () => new URL(str),
-        catch: () => new ParseResult.Type(ast, str)
+        try: () => new URL(s),
+        catch: (e) =>
+          new ParseResult.Type(
+            ast,
+            s,
+            `Unable to decode ${JSON.stringify(s)} into a URL. ${getErrorMessage(e)}`
+          )
       }),
     encode: (url) => ParseResult.succeed(url.toString())
   }
@@ -5547,8 +5552,11 @@ export const parseNumber = <A extends string, I, R>(
     Number$,
     {
       strict: false,
-      decode: (s, _, ast) => ParseResult.fromOption(number_.parse(s), () => new ParseResult.Type(ast, s)),
-      encode: (n) => ParseResult.succeed(String(n))
+      decode: (s, _, ast) =>
+        ParseResult.fromOption(number_.parse(s), () =>
+          new ParseResult.Type(ast, s, `Unable to decode ${JSON.stringify(s)} into a number`)),
+      encode: (n) =>
+        ParseResult.succeed(String(n))
     }
   )
 
@@ -5563,7 +5571,7 @@ export const parseNumber = <A extends string, I, R>(
  * @since 3.10.0
  */
 export class NumberFromString extends parseNumber(String$.annotations({
-  description: "a string that will be parsed into a number"
+  description: "a string to be decoded into a number"
 })).annotations({ identifier: "NumberFromString" }) {}
 
 /**
@@ -5665,16 +5673,31 @@ export class Not extends transform(Boolean$.annotations({ description: "a boolea
   encode: boolean_.not
 }) {}
 
+const encodeSymbol = (sym: symbol, _: AST.ParseOptions, ast: AST.AST) => {
+  const key = Symbol.keyFor(sym)
+  return key === undefined
+    ? ParseResult.fail(
+      new ParseResult.Type(ast, sym, `Unable to encode a unique symbol ${String(sym)} into a string`)
+    )
+    : ParseResult.succeed(key)
+}
+
+const decodeSymbol = (s: string) => ParseResult.succeed(Symbol.for(s))
+
 /** @ignore */
-class Symbol$ extends transform(
-  String$.annotations({ description: "a string that will be converted to a symbol" }),
+class Symbol$ extends transformOrFail(
+  String$.annotations({ description: "a string to be decoded into a globally shared symbol" }),
   SymbolFromSelf,
-  { strict: false, decode: (s) => Symbol.for(s), encode: (sym) => sym.description }
-).annotations({ identifier: "symbol" }) {}
+  {
+    strict: false,
+    decode: decodeSymbol,
+    encode: encodeSymbol
+  }
+).annotations({ identifier: "Symbol" }) {}
 
 export {
   /**
-   * This schema transforms a `string` into a `symbol`.
+   * Converts a string key into a globally shared symbol.
    *
    * @category symbol transformations
    * @since 3.10.0
@@ -5682,6 +5705,20 @@ export {
   Symbol$ as Symbol
 }
 
+const SymbolStruct = TaggedStruct("symbol", {
+  key: String$
+}).annotations({ description: "an object to be decoded into a globally shared symbol" })
+
+const SymbolFromStruct = transformOrFail(
+  SymbolStruct,
+  SymbolFromSelf,
+  {
+    strict: true,
+    decode: ({ key }) => decodeSymbol(key),
+    encode: (sym, _, ast) => ParseResult.map(encodeSymbol(sym, _, ast), (key) => SymbolStruct.make({ key }))
+  }
+)
+
 /**
  * @category schema id
  * @since 3.10.0
@@ -5893,14 +5930,18 @@ export const clampBigInt =
 
 /** @ignore */
 class BigInt$ extends transformOrFail(
-  String$.annotations({ description: "a string that will be parsed into a bigint" }),
+  String$.annotations({ description: "a string to be decoded into a bigint" }),
   BigIntFromSelf,
   {
     strict: true,
-    decode: (s, _, ast) => ParseResult.fromOption(bigInt_.fromString(s), () => new ParseResult.Type(ast, s)),
+    decode: (s, _, ast) =>
+      ParseResult.fromOption(
+        bigInt_.fromString(s),
+        () => new ParseResult.Type(ast, s, `Unable to decode ${JSON.stringify(s)} into a bigint`)
+      ),
     encode: (n) => ParseResult.succeed(String(n))
   }
-).annotations({ identifier: "bigint" }) {}
+).annotations({ identifier: "BigInt" }) {}
 
 export {
   /**
@@ -5987,18 +6028,22 @@ export const NonNegativeBigInt: filter<Schema<bigint, string>> = BigInt$.pipe(
  * @since 3.10.0
  */
 export class BigIntFromNumber extends transformOrFail(
-  Number$.annotations({ description: "a number that will be parsed into a bigint" }),
-  BigIntFromSelf,
+  Number$.annotations({ description: "a number to be decoded into a bigint" }),
+  BigIntFromSelf.pipe(betweenBigInt(BigInt(Number.MIN_SAFE_INTEGER), BigInt(Number.MAX_SAFE_INTEGER))),
   {
     strict: true,
     decode: (n, _, ast) =>
       ParseResult.fromOption(
         bigInt_.fromNumber(n),
-        () => new ParseResult.Type(ast, n)
+        () => new ParseResult.Type(ast, n, `Unable to decode ${n} into a bigint`)
       ),
-    encode: (b, _, ast) => ParseResult.fromOption(bigInt_.toNumber(b), () => new ParseResult.Type(ast, b))
+    encode: (b, _, ast) =>
+      ParseResult.fromOption(
+        bigInt_.toNumber(b),
+        () => new ParseResult.Type(ast, b, `Unable to encode ${b}n into a number`)
+      )
   }
-).annotations({ identifier: "BigintFromNumber" }) {}
+).annotations({ identifier: "BigIntFromNumber" }) {}
 
 const redactedArbitrary = <A>(value: LazyArbitrary<A>): LazyArbitrary<redacted_.Redacted<A>> => (fc) =>
   value(fc).map(redacted_.make)
@@ -6101,77 +6146,90 @@ export class DurationFromSelf extends declare(
     arbitrary: (): LazyArbitrary<duration_.Duration> => (fc) =>
       fc.oneof(
         fc.constant(duration_.infinity),
-        fc.bigUint().map((_) => duration_.nanos(_)),
-        fc.bigUint().map((_) => duration_.micros(_)),
-        fc.maxSafeNat().map((_) => duration_.millis(_)),
-        fc.maxSafeNat().map((_) => duration_.seconds(_)),
-        fc.maxSafeNat().map((_) => duration_.minutes(_)),
-        fc.maxSafeNat().map((_) => duration_.hours(_)),
-        fc.maxSafeNat().map((_) => duration_.days(_)),
-        fc.maxSafeNat().map((_) => duration_.weeks(_))
+        fc.bigInt({ min: 0n }).map((_) => duration_.nanos(_)),
+        fc.maxSafeNat().map((_) => duration_.millis(_))
       ),
     equivalence: (): Equivalence.Equivalence<duration_.Duration> => duration_.Equivalence
   }
 ) {}
 
 /**
- * A schema that transforms a `bigint` tuple into a `Duration`.
- * Treats the value as the number of nanoseconds.
+ * A schema that transforms a non negative `bigint` into a `Duration`. Treats
+ * the value as the number of nanoseconds.
  *
  * @category Duration transformations
  * @since 3.10.0
  */
 export class DurationFromNanos extends transformOrFail(
-  BigIntFromSelf.annotations({ description: "a bigint that will be parsed into a Duration" }),
-  DurationFromSelf,
+  NonNegativeBigIntFromSelf.annotations({ description: "a bigint to be decoded into a Duration" }),
+  DurationFromSelf.pipe(filter((duration) => duration_.isFinite(duration), { description: "a finite duration" })),
   {
     strict: true,
     decode: (nanos) => ParseResult.succeed(duration_.nanos(nanos)),
     encode: (duration, _, ast) =>
       option_.match(duration_.toNanos(duration), {
-        onNone: () => ParseResult.fail(new ParseResult.Type(ast, duration)),
-        onSome: (val) => ParseResult.succeed(val)
+        onNone: () =>
+          ParseResult.fail(new ParseResult.Type(ast, duration, `Unable to encode ${duration} into a bigint`)),
+        onSome: (nanos) => ParseResult.succeed(nanos)
       })
   }
 ).annotations({ identifier: "DurationFromNanos" }) {}
 
 /**
- * A schema that transforms a `number` tuple into a `Duration`.
- * Treats the value as the number of milliseconds.
+ * A non-negative integer. +Infinity is excluded.
+ *
+ * @category number constructors
+ * @since 3.11.10
+ */
+export const NonNegativeInt = NonNegative.pipe(int()).annotations({ identifier: "NonNegativeInt" })
+
+/**
+ * A schema that transforms a (possibly Infinite) non negative number into a
+ * `Duration`. Treats the value as the number of milliseconds.
  *
  * @category Duration transformations
  * @since 3.10.0
  */
 export class DurationFromMillis extends transform(
-  Number$.annotations({ description: "a number that will be parsed into a Duration" }),
+  NonNegative.annotations({
+    description: "a non-negative number to be decoded into a Duration"
+  }),
   DurationFromSelf,
-  { strict: true, decode: (ms) => duration_.millis(ms), encode: (n) => duration_.toMillis(n) }
+  {
+    strict: true,
+    decode: (ms) => duration_.millis(ms),
+    encode: (duration) => duration_.toMillis(duration)
+  }
 ).annotations({ identifier: "DurationFromMillis" }) {}
 
-/**
- * @category number constructors
- * @since 3.11.10
- */
-export const NonNegativeInt = NonNegative.pipe(int()).annotations({ identifier: "NonNegativeInt" })
-
-const HRTime: Schema<readonly [seconds: number, nanos: number]> = Tuple(
+const FiniteHRTime = Tuple(
   element(NonNegativeInt).annotations({ title: "seconds" }),
   element(NonNegativeInt).annotations({ title: "nanos" })
-).annotations({ identifier: "HRTime" })
+).annotations({ identifier: "FiniteHRTime" })
+
+const InfiniteHRTime = Tuple(Literal(-1), Literal(0)).annotations({ identifier: "InfiniteHRTime" })
+
+const HRTime: Schema<readonly [seconds: number, nanos: number]> = Union(FiniteHRTime, InfiniteHRTime).annotations({
+  identifier: "HRTime",
+  description: "a tuple of seconds and nanos to be decoded into a Duration"
+})
 
 /**
  * A schema that transforms a `[number, number]` tuple into a `Duration`.
  *
+ * Infinite durations are encoded as `[-1, 0]`.
+ *
  * @category Duration transformations
  * @since 3.10.0
  */
 export class Duration extends transform(
-  HRTime.annotations({ description: "a tuple of seconds and nanos that will be parsed into a Duration" }),
+  HRTime,
   DurationFromSelf,
   {
     strict: true,
-    decode: ([seconds, nanos]) => duration_.nanos(BigInt(seconds) * BigInt(1e9) + BigInt(nanos)),
-    encode: (duration) => duration_.toHrTime(duration)
+    decode: ([seconds, nanos]) =>
+      seconds === -1 ? duration_.infinity : duration_.nanos(BigInt(seconds) * BigInt(1e9) + BigInt(nanos)),
+    encode: (duration) => duration.value._tag === "Infinity" ? [-1, 0] as const : duration_.toHrTime(duration)
   }
 ).annotations({ identifier: "Duration" }) {}
 
@@ -6347,7 +6405,7 @@ export const Uint8 = Number$.pipe(
 
 const Uint8Array$: Schema<Uint8Array, ReadonlyArray<number>> = transform(
   Array$(Uint8).annotations({
-    description: "an array of 8-bit unsigned integers that will be parsed into a Uint8Array"
+    description: "an array of 8-bit unsigned integers to be decoded into a Uint8Array"
   }),
   Uint8ArrayFromSelf,
   { strict: true, decode: (numbers) => Uint8Array.from(numbers), encode: (uint8Array) => Array.from(uint8Array) }
@@ -6369,7 +6427,7 @@ const makeUint8ArrayTransformation = (
   encode: (u: Uint8Array) => string
 ) =>
   transformOrFail(
-    String$.annotations({ description: "a string that will be parsed into a Uint8Array" }),
+    String$.annotations({ description: "a string to be decoded into a Uint8Array" }),
     Uint8ArrayFromSelf,
     {
       strict: true,
@@ -6533,11 +6591,11 @@ export type MinItemsSchemaId = typeof MinItemsSchemaId
  * @category ReadonlyArray filters
  * @since 3.10.0
  */
-export const minItems = <A>(
+export const minItems = <A extends ReadonlyArray<any>>(
   n: number,
-  annotations?: Annotations.Filter<ReadonlyArray<A>>
+  annotations?: Annotations.Filter<A>
 ) =>
-<I, R>(self: Schema<ReadonlyArray<A>, I, R>): filter<Schema<ReadonlyArray<A>, I, R>> => {
+<I, R>(self: Schema<A, I, R>): filter<Schema<A, I, R>> => {
   const minItems = Math.floor(n)
   if (minItems < 1) {
     throw new Error(
@@ -6575,21 +6633,28 @@ export type MaxItemsSchemaId = typeof MaxItemsSchemaId
  * @category ReadonlyArray filters
  * @since 3.10.0
  */
-export const maxItems = <A>(
+export const maxItems = <A extends ReadonlyArray<any>>(
   n: number,
-  annotations?: Annotations.Filter<ReadonlyArray<A>>
+  annotations?: Annotations.Filter<A>
 ) =>
-<I, R>(self: Schema<ReadonlyArray<A>, I, R>): filter<Schema<ReadonlyArray<A>, I, R>> =>
-  self.pipe(
-    filter((a) => a.length <= n, {
+<I, R>(self: Schema<A, I, R>): filter<Schema<A, I, R>> => {
+  const maxItems = Math.floor(n)
+  if (maxItems < 1) {
+    throw new Error(
+      errors_.getInvalidArgumentErrorMessage(`Expected an integer greater than or equal to 1, actual ${n}`)
+    )
+  }
+  return self.pipe(
+    filter((a) => a.length <= maxItems, {
       schemaId: MaxItemsSchemaId,
-      title: `maxItems(${n})`,
-      description: `an array of at most ${n} item(s)`,
-      jsonSchema: { maxItems: n },
+      title: `maxItems(${maxItems})`,
+      description: `an array of at most ${maxItems} item(s)`,
+      jsonSchema: { maxItems },
       [AST.StableFilterAnnotationId]: true,
       ...annotations
     })
   )
+}
 
 /**
  * @category schema id
@@ -6607,21 +6672,28 @@ export type ItemsCountSchemaId = typeof ItemsCountSchemaId
  * @category ReadonlyArray filters
  * @since 3.10.0
  */
-export const itemsCount = <A>(
+export const itemsCount = <A extends ReadonlyArray<any>>(
   n: number,
-  annotations?: Annotations.Filter<ReadonlyArray<A>>
+  annotations?: Annotations.Filter<A>
 ) =>
-<I, R>(self: Schema<ReadonlyArray<A>, I, R>): filter<Schema<ReadonlyArray<A>, I, R>> =>
-  self.pipe(
-    filter((a) => a.length === n, {
+<I, R>(self: Schema<A, I, R>): filter<Schema<A, I, R>> => {
+  const itemsCount = Math.floor(n)
+  if (itemsCount < 1) {
+    throw new Error(
+      errors_.getInvalidArgumentErrorMessage(`Expected an integer greater than or equal to 1, actual ${n}`)
+    )
+  }
+  return self.pipe(
+    filter((a) => a.length === itemsCount, {
       schemaId: ItemsCountSchemaId,
-      title: `itemsCount(${n})`,
-      description: `an array of exactly ${n} item(s)`,
-      jsonSchema: { minItems: n, maxItems: n },
+      title: `itemsCount(${itemsCount})`,
+      description: `an array of exactly ${itemsCount} item(s)`,
+      jsonSchema: { minItems: itemsCount, maxItems: itemsCount },
       [AST.StableFilterAnnotationId]: true,
       ...annotations
     })
   )
+}
 
 /**
  * @category ReadonlyArray transformations
@@ -6697,7 +6769,7 @@ export const headOrElse: {
             ? ParseResult.succeed(as[0])
             : fallback
             ? ParseResult.succeed(fallback())
-            : ParseResult.fail(new ParseResult.Type(ast, as)),
+            : ParseResult.fail(new ParseResult.Type(ast, as, "Unable to retrieve the first element of an empty array")),
         encode: (a) => ParseResult.succeed(array_.of(a))
       }
     )
@@ -6919,7 +6991,7 @@ export class ValidDateFromSelf extends DateFromSelf.pipe(
  * @since 3.10.0
  */
 export class DateFromString extends transform(
-  String$.annotations({ description: "a string that will be parsed into a Date" }),
+  String$.annotations({ description: "a string to be decoded into a Date" }),
   DateFromSelf,
   { strict: true, decode: (s) => new Date(s), encode: (d) => util_.formatDate(d) }
 ).annotations({ identifier: "DateFromString" }) {}
@@ -6953,7 +7025,7 @@ export {
  * @since 3.10.0
  */
 export class DateFromNumber extends transform(
-  Number$.annotations({ description: "a number that will be parsed into a Date" }),
+  Number$.annotations({ description: "a number to be decoded into a Date" }),
   DateFromSelf,
   { strict: true, decode: (n) => new Date(n), encode: (d) => d.getTime() }
 ).annotations({ identifier: "DateFromNumber" }) {}
@@ -6970,15 +7042,16 @@ export class DateTimeUtcFromSelf extends declare(
     identifier: "DateTimeUtcFromSelf",
     description: "a DateTime.Utc instance",
     pretty: (): pretty_.Pretty<dateTime.Utc> => (dateTime) => dateTime.toString(),
-    arbitrary: (): LazyArbitrary<dateTime.Utc> => (fc) => fc.date().map((date) => dateTime.unsafeFromDate(date)),
+    arbitrary: (): LazyArbitrary<dateTime.Utc> => (fc) =>
+      fc.date({ noInvalidDate: true }).map((date) => dateTime.unsafeFromDate(date)),
     equivalence: () => dateTime.Equivalence
   }
 ) {}
 
-const decodeDateTime = <A extends dateTime.DateTime.Input>(input: A, _: ParseOptions, ast: AST.AST) =>
+const decodeDateTimeUtc = <A extends dateTime.DateTime.Input>(input: A, _: ParseOptions, ast: AST.AST) =>
   ParseResult.try({
     try: () => dateTime.unsafeMake(input),
-    catch: () => new ParseResult.Type(ast, input)
+    catch: () => new ParseResult.Type(ast, input, `Unable to decode ${util_.formatUnknown(input)} into a DateTime.Utc`)
   })
 
 /**
@@ -6988,11 +7061,11 @@ const decodeDateTime = <A extends dateTime.DateTime.Input>(input: A, _: ParseOpt
  * @since 3.10.0
  */
 export class DateTimeUtcFromNumber extends transformOrFail(
-  Number$.annotations({ description: "a number that will be parsed into a DateTime.Utc" }),
+  Number$.annotations({ description: "a number to be decoded into a DateTime.Utc" }),
   DateTimeUtcFromSelf,
   {
     strict: true,
-    decode: decodeDateTime,
+    decode: decodeDateTimeUtc,
     encode: (dt) => ParseResult.succeed(dateTime.toEpochMillis(dt))
   }
 ).annotations({ identifier: "DateTimeUtcFromNumber" }) {}
@@ -7004,11 +7077,11 @@ export class DateTimeUtcFromNumber extends transformOrFail(
  * @since 3.12.0
  */
 export class DateTimeUtcFromDate extends transformOrFail(
-  DateFromSelf.annotations({ description: "a Date that will be parsed into a DateTime.Utc" }),
+  DateFromSelf.annotations({ description: "a Date to be decoded into a DateTime.Utc" }),
   DateTimeUtcFromSelf,
   {
     strict: true,
-    decode: decodeDateTime,
+    decode: decodeDateTimeUtc,
     encode: (dt) => ParseResult.succeed(dateTime.toDateUtc(dt))
   }
 ).annotations({ identifier: "DateTimeUtcFromDate" }) {}
@@ -7020,17 +7093,17 @@ export class DateTimeUtcFromDate extends transformOrFail(
  * @since 3.10.0
  */
 export class DateTimeUtc extends transformOrFail(
-  String$.annotations({ description: "a string that will be parsed into a DateTime.Utc" }),
+  String$.annotations({ description: "a string to be decoded into a DateTime.Utc" }),
   DateTimeUtcFromSelf,
   {
     strict: true,
-    decode: decodeDateTime,
+    decode: decodeDateTimeUtc,
     encode: (dt) => ParseResult.succeed(dateTime.formatIso(dt))
   }
 ).annotations({ identifier: "DateTimeUtc" }) {}
 
 const timeZoneOffsetArbitrary = (): LazyArbitrary<dateTime.TimeZone.Offset> => (fc) =>
-  fc.integer({ min: -12 * 60 * 60 * 1000, max: 12 * 60 * 60 * 1000 }).map(dateTime.zoneMakeOffset)
+  fc.integer({ min: -12 * 60 * 60 * 1000, max: 14 * 60 * 60 * 1000 }).map(dateTime.zoneMakeOffset)
 
 /**
  * Describes a schema that represents a `TimeZone.Offset` instance.
@@ -7055,7 +7128,7 @@ export class TimeZoneOffsetFromSelf extends declare(
  * @since 3.10.0
  */
 export class TimeZoneOffset extends transform(
-  Number$.annotations({ description: "a number that will be parsed into a TimeZone.Offset" }),
+  Number$.annotations({ description: "a number to be decoded into a TimeZone.Offset" }),
   TimeZoneOffsetFromSelf,
   { strict: true, decode: dateTime.zoneMakeOffset, encode: (tz) => tz.offset }
 ).annotations({ identifier: "TimeZoneOffset" }) {}
@@ -7086,32 +7159,24 @@ export class TimeZoneNamedFromSelf extends declare(
  * @since 3.10.0
  */
 export class TimeZoneNamed extends transformOrFail(
-  String$.annotations({ description: "a string that will be parsed into a TimeZone.Named" }),
+  String$.annotations({ description: "a string to be decoded into a TimeZone.Named" }),
   TimeZoneNamedFromSelf,
   {
     strict: true,
     decode: (s, _, ast) =>
       ParseResult.try({
         try: () => dateTime.zoneUnsafeMakeNamed(s),
-        catch: () => new ParseResult.Type(ast, s)
+        catch: () => new ParseResult.Type(ast, s, `Unable to decode ${JSON.stringify(s)} into a TimeZone.Named`)
       }),
     encode: (tz) => ParseResult.succeed(tz.id)
   }
 ).annotations({ identifier: "TimeZoneNamed" }) {}
 
-/**
- * @category api interface
- * @since 3.10.0
- */
-export interface TimeZoneFromSelf extends Union<[typeof TimeZoneOffsetFromSelf, typeof TimeZoneNamedFromSelf]> {
-  annotations(annotations: Annotations.Schema<dateTime.TimeZone>): TimeZoneFromSelf
-}
-
 /**
  * @category TimeZone constructors
  * @since 3.10.0
  */
-export const TimeZoneFromSelf: TimeZoneFromSelf = Union(TimeZoneOffsetFromSelf, TimeZoneNamedFromSelf)
+export class TimeZoneFromSelf extends Union(TimeZoneOffsetFromSelf, TimeZoneNamedFromSelf) {}
 
 /**
  * Defines a schema that attempts to convert a `string` to a `TimeZone` using the `DateTime.zoneFromString` constructor.
@@ -7120,13 +7185,14 @@ export const TimeZoneFromSelf: TimeZoneFromSelf = Union(TimeZoneOffsetFromSelf,
  * @since 3.10.0
  */
 export class TimeZone extends transformOrFail(
-  String$.annotations({ description: "a string that will be parsed into a TimeZone" }),
+  String$.annotations({ description: "a string to be decoded into a TimeZone" }),
   TimeZoneFromSelf,
   {
     strict: true,
     decode: (s, _, ast) =>
       option_.match(dateTime.zoneFromString(s), {
-        onNone: () => ParseResult.fail(new ParseResult.Type(ast, s)),
+        onNone: () =>
+          ParseResult.fail(new ParseResult.Type(ast, s, `Unable to decode ${JSON.stringify(s)} into a TimeZone`)),
         onSome: ParseResult.succeed
       }),
     encode: (tz) => ParseResult.succeed(dateTime.zoneToString(tz))
@@ -7152,7 +7218,14 @@ export class DateTimeZonedFromSelf extends declare(
     description: "a DateTime.Zoned instance",
     pretty: (): pretty_.Pretty<dateTime.Zoned> => (dateTime) => dateTime.toString(),
     arbitrary: (): LazyArbitrary<dateTime.Zoned> => (fc) =>
-      fc.date().chain((date) => timeZoneArbitrary(fc).map((timeZone) => dateTime.unsafeMakeZoned(date, { timeZone }))),
+      fc.tuple(
+        fc.integer({
+          // time zone db supports +/- 1000 years or so
+          min: -31536000000000,
+          max: 31536000000000
+        }),
+        timeZoneArbitrary(fc)
+      ).map(([millis, timeZone]) => dateTime.unsafeMakeZoned(millis, { timeZone })),
     equivalence: () => dateTime.Equivalence
   }
 ) {}
@@ -7164,13 +7237,14 @@ export class DateTimeZonedFromSelf extends declare(
  * @since 3.10.0
  */
 export class DateTimeZoned extends transformOrFail(
-  String$.annotations({ description: "a string that will be parsed into a DateTime.Zoned" }),
+  String$.annotations({ description: "a string to be decoded into a DateTime.Zoned" }),
   DateTimeZonedFromSelf,
   {
     strict: true,
     decode: (s, _, ast) =>
       option_.match(dateTime.makeZonedFromString(s), {
-        onNone: () => ParseResult.fail(new ParseResult.Type(ast, s)),
+        onNone: () =>
+          ParseResult.fail(new ParseResult.Type(ast, s, `Unable to decode ${JSON.stringify(s)} into a DateTime.Zoned`)),
         onSome: ParseResult.succeed
       }),
     encode: (dt) => ParseResult.succeed(dateTime.formatIsoZoned(dt))
@@ -7810,7 +7884,7 @@ export const ReadonlyMapFromRecord = <KA, KR, VA, VI, VR>({ key, value }: {
 }): Schema<ReadonlyMap<KA, VA>, { readonly [x: string]: VI }, KR | VR> =>
   transform(
     Record({ key: encodedBoundSchema(key), value }).annotations({
-      description: "a record that will be parsed into a ReadonlyMap"
+      description: "a record to be decoded into a ReadonlyMap"
     }),
     ReadonlyMapFromSelf({ key, value: typeSchema(value) }),
     {
@@ -7830,7 +7904,7 @@ export const MapFromRecord = <KA, KR, VA, VI, VR>({ key, value }: {
 }): Schema<Map<KA, VA>, { readonly [x: string]: VI }, KR | VR> =>
   transform(
     Record({ key: encodedBoundSchema(key), value }).annotations({
-      description: "a record that will be parsed into a Map"
+      description: "a record to be decoded into a Map"
     }),
     MapFromSelf({ key, value: typeSchema(value) }),
     {
@@ -8001,13 +8075,14 @@ export class BigDecimalFromSelf extends declare(
  * @since 3.10.0
  */
 export class BigDecimal extends transformOrFail(
-  String$.annotations({ description: "a string that will be parsed into a BigDecimal" }),
+  String$.annotations({ description: "a string to be decoded into a BigDecimal" }),
   BigDecimalFromSelf,
   {
     strict: true,
-    decode: (num, _, ast) =>
-      bigDecimal_.fromString(num).pipe(option_.match({
-        onNone: () => ParseResult.fail(new ParseResult.Type(ast, num)),
+    decode: (s, _, ast) =>
+      bigDecimal_.fromString(s).pipe(option_.match({
+        onNone: () =>
+          ParseResult.fail(new ParseResult.Type(ast, s, `Unable to decode ${JSON.stringify(s)} into a BigDecimal`)),
         onSome: (val) => ParseResult.succeed(bigDecimal_.normalize(val))
       })),
     encode: (val) => ParseResult.succeed(bigDecimal_.format(bigDecimal_.normalize(val)))
@@ -8021,13 +8096,13 @@ export class BigDecimal extends transformOrFail(
  * @category BigDecimal transformations
  * @since 3.10.0
  */
-export class BigDecimalFromNumber extends transformOrFail(
-  Number$.annotations({ description: "a number that will be parsed into a BigDecimal" }),
+export class BigDecimalFromNumber extends transform(
+  Number$.annotations({ description: "a number to be decoded into a BigDecimal" }),
   BigDecimalFromSelf,
   {
     strict: true,
-    decode: (num) => ParseResult.succeed(bigDecimal_.unsafeFromNumber(num)),
-    encode: (val) => ParseResult.succeed(bigDecimal_.unsafeToNumber(val))
+    decode: bigDecimal_.unsafeFromNumber,
+    encode: bigDecimal_.unsafeToNumber
   }
 ).annotations({ identifier: "BigDecimalFromNumber" }) {}
 
@@ -10915,3 +10990,37 @@ const go = (ast: AST.AST, path: ReadonlyArray<PropertyKey>): Equivalence.Equival
     }
   }
 }
+
+/** @ignore */
+class PropertyKey$ extends Union(String$, Number$, SymbolFromStruct).annotations({ identifier: "PropertyKey" }) {}
+
+export {
+  /**
+   * @since 3.12.5
+   */
+  PropertyKey$ as PropertyKey
+}
+
+/**
+ * @category ArrayFormatter
+ * @since 3.12.5
+ */
+export class ArrayFormatterIssue extends Struct({
+  _tag: propertySignature(Literal(
+    "Pointer",
+    "Unexpected",
+    "Missing",
+    "Composite",
+    "Refinement",
+    "Transformation",
+    "Type",
+    "Forbidden"
+  )).annotations({ description: "The tag identifying the type of parse issue" }),
+  path: propertySignature(Array$(PropertyKey$)).annotations({
+    description: "The path to the property where the issue occurred"
+  }),
+  message: propertySignature(String$).annotations({ description: "A descriptive message explaining the issue" })
+}).annotations({
+  identifier: "ArrayFormatterIssue",
+  description: "Represents an issue returned by the ArrayFormatter formatter"
+}) {}