effect 3.12.3 → 3.12.5

package/src/Schema.ts

@@ -5008,30 +5008,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 +5176,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 +5553,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 +5572,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 +5674,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 +5706,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 +5931,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 +6029,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" }),
+  Number$.annotations({ description: "a number to be decoded into a bigint" }),
   BigIntFromSelf,
   {
     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)
@@ -6122,14 +6168,15 @@ export class DurationFromSelf extends declare(
  * @since 3.10.0
  */
 export class DurationFromNanos extends transformOrFail(
-  BigIntFromSelf.annotations({ description: "a bigint that will be parsed into a Duration" }),
+  BigIntFromSelf.annotations({ description: "a bigint to be decoded into a Duration" }),
   DurationFromSelf,
   {
     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)),
+        onNone: () =>
+          ParseResult.fail(new ParseResult.Type(ast, duration, `Unable to encode ${duration} into a bigint`)),
         onSome: (val) => ParseResult.succeed(val)
       })
   }
@@ -6143,7 +6190,7 @@ export class DurationFromNanos extends transformOrFail(
  * @since 3.10.0
  */
 export class DurationFromMillis extends transform(
-  Number$.annotations({ description: "a number that will be parsed into a Duration" }),
+  Number$.annotations({ description: "a number to be decoded into a Duration" }),
   DurationFromSelf,
   { strict: true, decode: (ms) => duration_.millis(ms), encode: (n) => duration_.toMillis(n) }
 ).annotations({ identifier: "DurationFromMillis" }) {}
@@ -6166,7 +6213,7 @@ const HRTime: Schema<readonly [seconds: number, nanos: number]> = Tuple(
  * @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.annotations({ description: "a tuple of seconds and nanos to be decoded into a Duration" }),
   DurationFromSelf,
   {
     strict: true,
@@ -6347,7 +6394,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 +6416,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 +6580,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 +6622,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 +6661,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 +6758,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 +6980,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 +7014,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 +7031,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 +7050,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 +7066,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 +7082,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 +7117,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 +7148,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 +7174,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 +7207,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 +7226,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 +7873,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 +7893,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 +8064,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 +8085,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 +10979,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"
+}) {}