effect 4.0.0-beta.99 → 4.0.0-rc.108

package/src/SchemaTransformation.ts

@@ -52,13 +52,15 @@ import * as SchemaIssue from "./SchemaIssue.ts"
  *
  * **Example** (Creating a middleware that falls back on decode failure)
  *
- * ```ts
- * import { Effect, Option, SchemaTransformation } from "effect"
+ * ```ts import.meta.vitest
+ * import { Effect, Option, SchemaIssue, SchemaTransformation } from "effect"
  *
- * const fallback = new SchemaTransformation.Middleware(
+ * const fallback = new SchemaTransformation.Middleware<string, string, never, never, never, never>(
  *   (effect) => Effect.catch(effect, () => Effect.succeed(Option.some("fallback"))),
  *   (effect) => effect
  * )
+ * const issue = new SchemaIssue.InvalidValue({ message: "Missing value" })
+ * await Effect.runPromise(fallback.decode(Effect.fail(issue), {})) // => Option.some("fallback")
  * ```
  *
  * @see {@link Transformation} — value-level bidirectional transformation
@@ -121,14 +123,13 @@ const TypeId = "~effect/SchemaTransformation/Transformation"
  *
  * **Example** (Composing two transformations)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { SchemaTransformation } from "effect"
  *
  * const trimAndLower = SchemaTransformation.trim().compose(
  *   SchemaTransformation.toLowerCase()
  * )
- * // decode: trim then lowercase
- * // encode: passthrough (both directions)
+ * trimAndLower._tag // => "Transformation"
  * ```
  *
  * @see {@link make} — construct from `{ decode, encode }` getters
@@ -178,14 +179,11 @@ export class Transformation<in out T, in out E, RD = never, RE = never> {
  *
  * **Example** (Checking a value)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { SchemaTransformation } from "effect"
  *
- * SchemaTransformation.isTransformation(SchemaTransformation.trim())
- * // true
- *
- * SchemaTransformation.isTransformation({ decode: null, encode: null })
- * // false
+ * SchemaTransformation.isTransformation(SchemaTransformation.trim()) // => true
+ * SchemaTransformation.isTransformation({ decode: null, encode: null }) // => false
  * ```
  *
  * @see {@link Transformation}
@@ -195,7 +193,7 @@ export class Transformation<in out T, in out E, RD = never, RE = never> {
  * @since 4.0.0
  */
 export function isTransformation(u: unknown): u is Transformation<any, any, unknown, unknown> {
-  return Predicate.hasProperty(u, TypeId)
+  return Predicate.hasProperty(u, TypeId) && u[TypeId] === TypeId
 }
 
 /**
@@ -214,13 +212,14 @@ export function isTransformation(u: unknown): u is Transformation<any, any, unkn
  *
  * **Example** (Wrapping existing getters)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { SchemaGetter, SchemaTransformation } from "effect"
  *
  * const t = SchemaTransformation.make({
  *   decode: SchemaGetter.transform<number, string>((s) => Number(s)),
  *   encode: SchemaGetter.transform<string, number>((n) => String(n))
  * })
+ * t._tag // => "Transformation"
  * ```
  *
  * @see {@link transform} — simpler constructor from pure functions
@@ -257,30 +256,31 @@ export const make = <T, E, RD = never, RE = never>(options: {
  *
  * **Example** (Parsing a date string that can fail)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Effect, Option, Schema, SchemaIssue, SchemaTransformation } from "effect"
  *
  * const DateFromString = Schema.String.pipe(
  *   Schema.decodeTo(
  *     Schema.Date,
  *     SchemaTransformation.transformOrFail({
- *       decode: (s) => {
+ *       decode: (s, options) => {
  *         const d = new Date(s)
  *         return isNaN(d.getTime())
- *           ? Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), { message: "Invalid date" }))
+ *           ? Effect.fail(new SchemaIssue.InvalidValue({ message: "Invalid date" }, s, options))
  *           : Effect.succeed(d)
  *       },
  *       encode: (d) => Effect.succeed(d.toISOString())
  *     })
  *   )
  * )
+ * Schema.decodeSync(DateFromString)("2024-01-01").toISOString() // => "2024-01-01T00:00:00.000Z"
  * ```
  *
  * @see {@link transform} — for infallible, pure transformations
  * @see {@link transformOptional} — for transformations that handle missing keys
  * @see {@link make} — for transformations from existing Getters
  *
- * @category constructors
+ * @category transforming
  * @since 3.10.0
  */
 export function transformOrFail<T, E, RD = never, RE = never>(options: {
@@ -310,7 +310,7 @@ export function transformOrFail<T, E, RD = never, RE = never>(options: {
  *
  * **Example** (Converting between cents and dollars)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const CentsFromDollars = Schema.Number.pipe(
@@ -322,13 +322,14 @@ export function transformOrFail<T, E, RD = never, RE = never>(options: {
  *     })
  *   )
  * )
+ * Schema.decodeSync(CentsFromDollars)(2.5) // => 250
  * ```
  *
  * @see {@link transformOrFail} — for fallible or effectful transformations
  * @see {@link transformOptional} — for transformations that handle missing keys
  * @see {@link passthrough} — when no conversion is needed
  *
- * @category constructors
+ * @category transforming
  * @since 3.10.0
  */
 export function transform<T, E>(options: {
@@ -360,7 +361,7 @@ export function transform<T, E>(options: {
  *
  * **Example** (Converting an optional key to Option)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Option, Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.Struct({
@@ -374,13 +375,14 @@ export function transform<T, E>(options: {
  *     )
  *   )
  * })
+ * Schema.decodeSync(schema)({}).a // => Option.none()
  * ```
  *
  * @see {@link transform} — when you don't need Option-level control
  * @see {@link optionFromOptionalKey} — built-in for the common optional-key-to-Option pattern
  * @see {@link optionFromOptional} — built-in for optional (undefined) to Option
  *
- * @category constructors
+ * @category transforming
  * @since 4.0.0
  */
 export function transformOptional<T, E>(options: {
@@ -410,19 +412,20 @@ export function transformOptional<T, E>(options: {
  *
  * **Example** (Trimming on decode)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const Trimmed = Schema.String.pipe(
  *   Schema.decode(SchemaTransformation.trim())
  * )
+ * Schema.decodeSync(Trimmed)("  hello  ") // => "hello"
  * ```
  *
  * @see {@link toLowerCase}
  * @see {@link toUpperCase}
  * @see {@link snakeToCamel}
  *
- * @category String transformations
+ * @category transforming
  * @since 4.0.0
  */
 export function trim(): Transformation<string, string> {
@@ -449,18 +452,19 @@ export function trim(): Transformation<string, string> {
  *
  * **Example** (Converting snake case to camel case)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const SnakeToCamel = Schema.String.pipe(
  *   Schema.decode(SchemaTransformation.snakeToCamel())
  * )
+ * Schema.decodeSync(SnakeToCamel)("user_name") // => "userName"
  * ```
  *
  * @see {@link trim}
  * @see {@link toLowerCase}
  *
- * @category String transformations
+ * @category transforming
  * @since 4.0.0
  */
 export function snakeToCamel(): Transformation<string, string> {
@@ -486,18 +490,19 @@ export function snakeToCamel(): Transformation<string, string> {
  *
  * **Example** (Lowercasing on decode)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const Lowered = Schema.String.pipe(
  *   Schema.decode(SchemaTransformation.toLowerCase())
  * )
+ * Schema.decodeSync(Lowered)("HELLO") // => "hello"
  * ```
  *
  * @see {@link toUpperCase}
  * @see {@link trim}
  *
- * @category String transformations
+ * @category transforming
  * @since 4.0.0
  */
 export function toLowerCase(): Transformation<string, string> {
@@ -523,18 +528,19 @@ export function toLowerCase(): Transformation<string, string> {
  *
  * **Example** (Uppercasing on decode)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const Uppered = Schema.String.pipe(
  *   Schema.decode(SchemaTransformation.toUpperCase())
  * )
+ * Schema.decodeSync(Uppered)("hello") // => "HELLO"
  * ```
  *
  * @see {@link toLowerCase}
  * @see {@link trim}
  *
- * @category String transformations
+ * @category transforming
  * @since 4.0.0
  */
 export function toUpperCase(): Transformation<string, string> {
@@ -560,18 +566,19 @@ export function toUpperCase(): Transformation<string, string> {
  *
  * **Example** (Capitalizing on decode)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const Capitalized = Schema.String.pipe(
  *   Schema.decode(SchemaTransformation.capitalize())
  * )
+ * Schema.decodeSync(Capitalized)("hello") // => "Hello"
  * ```
  *
  * @see {@link uncapitalize}
  * @see {@link toUpperCase}
  *
- * @category String transformations
+ * @category transforming
  * @since 4.0.0
  */
 export function capitalize(): Transformation<string, string> {
@@ -597,18 +604,19 @@ export function capitalize(): Transformation<string, string> {
  *
  * **Example** (Uncapitalizing on decode)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const Uncapitalized = Schema.String.pipe(
  *   Schema.decode(SchemaTransformation.uncapitalize())
  * )
+ * Schema.decodeSync(Uncapitalized)("Hello") // => "hello"
  * ```
  *
  * @see {@link capitalize}
  * @see {@link toLowerCase}
  *
- * @category String transformations
+ * @category transforming
  * @since 4.0.0
  */
 export function uncapitalize(): Transformation<string, string> {
@@ -636,7 +644,7 @@ export function uncapitalize(): Transformation<string, string> {
  *
  * **Example** (Parsing key-value pairs)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const Config = Schema.String.pipe(
@@ -645,13 +653,13 @@ export function uncapitalize(): Transformation<string, string> {
  *     SchemaTransformation.splitKeyValue({ separator: ";", keyValueSeparator: ":" })
  *   )
  * )
- * // "host:localhost;port:3000" → { host: "localhost", port: "3000" }
+ * Schema.decodeSync(Config)("host:localhost;port:3000") // => { host: "localhost", port: "3000" }
  * ```
  *
  * @see {@link trim}
  * @see {@link snakeToCamel}
  *
- * @category String transformations
+ * @category transforming
  * @since 4.0.0
  */
 export function splitKeyValue(options?: {
@@ -687,12 +695,13 @@ const passthrough_ = new Transformation(
  *
  * **Example** (Chaining schemas with no conversion)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.Trim.pipe(
  *   Schema.decodeTo(Schema.FiniteFromString, SchemaTransformation.passthrough())
  * )
+ * Schema.decodeSync(schema)("1") // => 1
  * ```
  *
  * @see {@link passthroughSupertype}
@@ -724,10 +733,11 @@ export function passthrough<T>(): Transformation<T, T> {
  *
  * **Example** (Passing through supertypes)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { SchemaTransformation } from "effect"
  *
- * const t = SchemaTransformation.passthroughSupertype<"a" | "b", string>()
+ * const t: SchemaTransformation.Transformation<"a" | "b", string> =
+ *   SchemaTransformation.passthroughSupertype<"a" | "b", string>()
  * ```
  *
  * @see {@link passthrough}
@@ -757,10 +767,11 @@ export function passthroughSupertype<T>(): Transformation<T, T> {
  *
  * **Example** (Passing through subtypes)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { SchemaTransformation } from "effect"
  *
- * const t = SchemaTransformation.passthroughSubtype<string, "a" | "b">()
+ * const t: SchemaTransformation.Transformation<string, "a" | "b"> =
+ *   SchemaTransformation.passthroughSubtype<string, "a" | "b">()
  * ```
  *
  * @see {@link passthrough}
@@ -792,18 +803,19 @@ export function passthroughSubtype<T>(): Transformation<T, T> {
  *
  * **Example** (Converting a string to a number)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.String.pipe(
  *   Schema.decodeTo(Schema.Number, SchemaTransformation.numberFromString)
  * )
+ * Schema.decodeSync(schema)("42") // => 42
  * ```
  *
  * @see {@link bigintFromString}
  * @see {@link transform}
  *
- * @category Coercions
+ * @category converting
  * @since 4.0.0
  */
 export const numberFromString = new Transformation(
@@ -828,18 +840,19 @@ export const numberFromString = new Transformation(
  *
  * **Example** (Converting a string to a BigInt)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.String.pipe(
  *   Schema.decodeTo(Schema.BigInt, SchemaTransformation.bigintFromString)
  * )
+ * Schema.decodeSync(schema)("42") // => 42n
  * ```
  *
  * @see {@link numberFromString}
  * @see {@link transform}
  *
- * @category Coercions
+ * @category converting
  * @since 4.0.0
  */
 export const bigintFromString = new Transformation(
@@ -852,8 +865,8 @@ export const bigintFromString = new Transformation(
  *
  * **When to use**
  *
- * Use when you need a schema transformation to parse ISO 8601 date strings from
- * APIs or user input.
+ * Use when you need a schema transformation to parse date strings from APIs or
+ * user input.
  *
  * **Details**
  *
@@ -863,18 +876,19 @@ export const bigintFromString = new Transformation(
  *
  * **Example** (Converting a string to a Date)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.String.pipe(
  *   Schema.decodeTo(Schema.Date, SchemaTransformation.dateFromString)
  * )
+ * Schema.decodeSync(schema)("2024-01-01").toISOString() // => "2024-01-01T00:00:00.000Z"
  * ```
  *
  * @see {@link dateFromMillis}
  * @see {@link dateTimeUtcFromString}
  *
- * @category Coercions
+ * @category converting
  * @since 4.0.0
  */
 export const dateFromString: Transformation<globalThis.Date, string> = new Transformation(
@@ -903,18 +917,19 @@ export const dateFromString: Transformation<globalThis.Date, string> = new Trans
  *
  * **Example** (Converting milliseconds to a Date)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.Number.pipe(
  *   Schema.decodeTo(Schema.Date, SchemaTransformation.dateFromMillis)
  * )
+ * Schema.decodeSync(schema)(0).toISOString() // => "1970-01-01T00:00:00.000Z"
  * ```
  *
  * @see {@link dateFromString}
  * @see {@link SchemaGetter.dateTimeUtcFromInput}
  *
- * @category Coercions
+ * @category converting
  * @since 4.0.0
  */
 export const dateFromMillis: Transformation<globalThis.Date, number> = new Transformation(
@@ -940,12 +955,13 @@ export const dateFromMillis: Transformation<globalThis.Date, number> = new Trans
  *
  * **Example** (Converting a string to a Duration)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.String.pipe(
  *   Schema.decodeTo(Schema.Duration, SchemaTransformation.durationFromString)
  * )
+ * String(Schema.decodeSync(schema)("5 seconds")) // => "5000 millis"
  * ```
  *
  * @see {@link durationFromNanos}
@@ -958,10 +974,16 @@ export const durationFromString: Transformation<Duration.Duration, string> = tra
   Duration.Duration,
   string
 >({
-  decode: (s) =>
+  decode: (s, options) =>
     Option.match(Duration.fromInput(s as Duration.Input), {
       onNone: () =>
-        Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), { message: `Invalid Duration string: ${s}` })),
+        Effect.fail(
+          new SchemaIssue.InvalidValue(
+            { expected: "a valid Duration string" },
+            s,
+            options
+          )
+        ),
       onSome: Effect.succeed
     }),
   encode: (duration) => Effect.succeed(globalThis.String(duration))
@@ -984,12 +1006,13 @@ export const durationFromString: Transformation<Duration.Duration, string> = tra
  *
  * **Example** (Converting nanoseconds to a Duration)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.BigInt.pipe(
  *   Schema.decodeTo(Schema.Duration, SchemaTransformation.durationFromNanos)
  * )
+ * String(Schema.decodeSync(schema)(5n)) // => "5 nanos"
  * ```
  *
  * @see {@link durationFromMillis}
@@ -999,11 +1022,15 @@ export const durationFromString: Transformation<Duration.Duration, string> = tra
  */
 export const durationFromNanos: Transformation<Duration.Duration, bigint> = transformOrFail({
   decode: (i) => Effect.succeed(Duration.nanos(i)),
-  encode: (a) =>
+  encode: (a, options) =>
     Option.match(Duration.toNanos(a), {
       onNone: () =>
         Effect.fail(
-          new SchemaIssue.InvalidValue(Option.some(a), { message: `Unable to encode ${a} into a bigint` })
+          new SchemaIssue.InvalidValue(
+            { expected: "a Duration representable as a bigint" },
+            a,
+            options
+          )
         ),
       onSome: (nanos) => Effect.succeed(nanos)
     })
@@ -1025,12 +1052,13 @@ export const durationFromNanos: Transformation<Duration.Duration, bigint> = tran
  *
  * **Example** (Converting milliseconds to a Duration)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.Number.pipe(
  *   Schema.decodeTo(Schema.Duration, SchemaTransformation.durationFromMillis)
  * )
+ * String(Schema.decodeSync(schema)(5000)) // => "5000 millis"
  * ```
  *
  * @see {@link durationFromNanos}
@@ -1140,8 +1168,8 @@ export const defectFromJson = (options?: ErrorOptions) =>
  *
  * **Example** (Converting nullable values to an Option)
  *
- * ```ts
- * import { Schema, SchemaTransformation } from "effect"
+ * ```ts import.meta.vitest
+ * import { Option, Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.NullOr(Schema.String).pipe(
  *   Schema.decodeTo(
@@ -1149,6 +1177,7 @@ export const defectFromJson = (options?: ErrorOptions) =>
  *     SchemaTransformation.optionFromNullOr()
  *   )
  * )
+ * Schema.decodeSync(schema)(null) // => Option.none()
  * ```
  *
  * @see {@link optionFromNullishOr}
@@ -1180,8 +1209,8 @@ export function optionFromNullOr<T>(): Transformation<Option.Option<T>, T | null
  *
  * **Example** (Converting undefined-or values to an Option)
  *
- * ```ts
- * import { Schema, SchemaTransformation } from "effect"
+ * ```ts import.meta.vitest
+ * import { Option, Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.UndefinedOr(Schema.String).pipe(
  *   Schema.decodeTo(
@@ -1189,6 +1218,7 @@ export function optionFromNullOr<T>(): Transformation<Option.Option<T>, T | null
  *     SchemaTransformation.optionFromUndefinedOr()
  *   )
  * )
+ * Schema.decodeSync(schema)(undefined) // => Option.none()
  * ```
  *
  * @see {@link optionFromOptionalKey}
@@ -1223,8 +1253,8 @@ export function optionFromUndefinedOr<T>(): Transformation<Option.Option<T>, T |
  *
  * **Example** (Converting nullish values to an Option and encoding None as null)
  *
- * ```ts
- * import { Schema, SchemaTransformation } from "effect"
+ * ```ts import.meta.vitest
+ * import { Option, Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.NullishOr(Schema.String).pipe(
  *   Schema.decodeTo(
@@ -1232,6 +1262,7 @@ export function optionFromUndefinedOr<T>(): Transformation<Option.Option<T>, T |
  *     SchemaTransformation.optionFromNullishOr({ onNoneEncoding: null })
  *   )
  * )
+ * Schema.encodeSync(schema)(Option.none()) // => null
  * ```
  *
  * @see {@link optionFromNullOr}
@@ -1269,8 +1300,8 @@ export function optionFromNullishOr<T>(
  *
  * **Example** (Converting an optional key to an Option)
  *
- * ```ts
- * import { Schema, SchemaTransformation } from "effect"
+ * ```ts import.meta.vitest
+ * import { Option, Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.Struct({
  *   name: Schema.optionalKey(Schema.String).pipe(
@@ -1280,6 +1311,7 @@ export function optionFromNullishOr<T>(
  *     )
  *   )
  * })
+ * Schema.decodeSync(schema)({}).name // => Option.none()
  * ```
  *
  * @see {@link optionFromOptional}
@@ -1314,8 +1346,8 @@ export function optionFromOptionalKey<T>(): Transformation<Option.Option<T>, T>
  *
  * **Example** (Converting an optional value to an Option)
  *
- * ```ts
- * import { Schema, SchemaTransformation } from "effect"
+ * ```ts import.meta.vitest
+ * import { Option, Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.Struct({
  *   age: Schema.optional(Schema.Number).pipe(
@@ -1325,6 +1357,7 @@ export function optionFromOptionalKey<T>(): Transformation<Option.Option<T>, T>
  *     )
  *   )
  * })
+ * Schema.decodeSync(schema)({ age: undefined }).age // => Option.none()
  * ```
  *
  * @see {@link optionFromOptionalKey}
@@ -1357,12 +1390,13 @@ export function optionFromOptional<T>(): Transformation<Option.Option<T>, T | un
  *
  * **Example** (Converting a string to a URL)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.String.pipe(
  *   Schema.decodeTo(Schema.URL, SchemaTransformation.urlFromString)
  * )
+ * Schema.decodeSync(schema)("https://example.com/path").href // => "https://example.com/path"
  * ```
  *
  * @see {@link numberFromString}
@@ -1372,10 +1406,16 @@ export function optionFromOptional<T>(): Transformation<Option.Option<T>, T | un
  * @since 4.0.0
  */
 export const urlFromString: Transformation<URL, string> = transformOrFail<URL, string>({
-  decode: (s) =>
+  decode: (s, options) =>
     URL.canParse(s)
       ? Effect.succeed(new URL(s))
-      : Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), { message: `Invalid URL string: ${s}` })),
+      : Effect.fail(
+        new SchemaIssue.InvalidValue(
+          { expected: "a valid URL string" },
+          s,
+          options
+        )
+      ),
   encode: (url) => Effect.succeed(url.href)
 })
 
@@ -1401,10 +1441,16 @@ export const bigDecimalFromString: Transformation<BigDecimal.BigDecimal, string>
   BigDecimal.BigDecimal,
   string
 >({
-  decode: (s) => {
+  decode: (s, options) => {
     const result = BigDecimal.fromString(s)
     return Option.isNone(result)
-      ? Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), { message: `Invalid BigDecimal string: ${s}` }))
+      ? Effect.fail(
+        new SchemaIssue.InvalidValue(
+          { expected: "a valid BigDecimal string" },
+          s,
+          options
+        )
+      )
       : Effect.succeed(result.value)
   },
   encode: (bd) => Effect.succeed(BigDecimal.format(bd))
@@ -1426,12 +1472,13 @@ export const bigDecimalFromString: Transformation<BigDecimal.BigDecimal, string>
  *
  * **Example** (Converting Base64 to a Uint8Array)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.String.pipe(
  *   Schema.decodeTo(Schema.Uint8Array, SchemaTransformation.uint8ArrayFromBase64String)
  * )
+ * Array.from(Schema.decodeSync(schema)("AQID")) // => [1, 2, 3]
  * ```
  *
  * @see {@link fromJsonString}
@@ -1461,12 +1508,13 @@ export const uint8ArrayFromBase64String: Transformation<Uint8Array<ArrayBufferLi
  *
  * **Example** (Converting Base64 to a string)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.String.pipe(
  *   Schema.decodeTo(Schema.String, SchemaTransformation.stringFromBase64String)
  * )
+ * Schema.decodeSync(schema)("aGVsbG8=") // => "hello"
  * ```
  *
  * @see {@link uint8ArrayFromBase64String}
@@ -1495,12 +1543,13 @@ export const stringFromBase64String: Transformation<string, string> = new Transf
  *
  * **Example** (Converting Base64Url to a string)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.String.pipe(
  *   Schema.decodeTo(Schema.String, SchemaTransformation.stringFromBase64UrlString)
  * )
+ * Schema.decodeSync(schema)("aGVsbG8") // => "hello"
  * ```
  *
  * @see {@link stringFromBase64String}
@@ -1529,12 +1578,13 @@ export const stringFromBase64UrlString: Transformation<string, string> = new Tra
  *
  * **Example** (Converting hex to a string)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.String.pipe(
  *   Schema.decodeTo(Schema.String, SchemaTransformation.stringFromHexString)
  * )
+ * Schema.decodeSync(schema)("68656c6c6f") // => "hello"
  * ```
  *
  * @see {@link stringFromBase64String}
@@ -1565,12 +1615,13 @@ export const stringFromHexString: Transformation<string, string> = new Transform
  *
  * **Example** (Defining a URI component schema)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.String.pipe(
  *   Schema.decodeTo(Schema.String, SchemaTransformation.stringFromUriComponent)
  * )
+ * Schema.decodeSync(schema)("hello%20world") // => "hello world"
  * ```
  *
  * @see {@link stringFromBase64String}
@@ -1596,17 +1647,20 @@ export const stringFromUriComponent: Transformation<string, string> = new Transf
  *
  * **Details**
  *
- * Decode fails with `InvalidValue` for invalid JSON, and encode can fail with
- * `InvalidValue` when `JSON.stringify` cannot serialize the value.
+ * The `reviver` option is passed to `JSON.parse` during decoding. The
+ * `replacer` and `space` options are passed to `JSON.stringify` during
+ * encoding. Decode fails with `InvalidValue` for invalid JSON, and encode can
+ * fail with `InvalidValue` when `JSON.stringify` cannot serialize the value.
  *
  * **Example** (Parsing JSON)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.String.pipe(
- *   Schema.decodeTo(Schema.Unknown, SchemaTransformation.fromJsonString)
+ *   Schema.decodeTo(Schema.Unknown, SchemaTransformation.fromJsonString())
  * )
+ * Schema.decodeSync(schema)("{\"ok\":true}") // => { ok: true }
  * ```
  *
  * @see {@link uint8ArrayFromBase64String}
@@ -1615,10 +1669,16 @@ export const stringFromUriComponent: Transformation<string, string> = new Transf
  * @category decoding
  * @since 4.0.0
  */
-export const fromJsonString = new Transformation<unknown, string>(
-  SchemaGetter.parseJson(),
-  SchemaGetter.stringifyJson()
-)
+export function fromJsonString(options?: {
+  readonly reviver?: Parameters<typeof JSON.parse>[1] | undefined
+  readonly replacer?: SchemaGetter.JsonReplacer | undefined
+  readonly space?: Parameters<typeof JSON.stringify>[2] | undefined
+}): Transformation<unknown, string> {
+  return new Transformation(
+    SchemaGetter.parseJson(options ?? {}),
+    SchemaGetter.stringifyJson(options)
+  )
+}
 
 /**
  * Decodes a `FormData` instance into a nested record using bracket-path keys and
@@ -1637,12 +1697,15 @@ export const fromJsonString = new Transformation<unknown, string>(
  *
  * **Example** (Decoding FormData)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.instanceOf(FormData).pipe(
  *   Schema.decodeTo(Schema.Unknown, SchemaTransformation.fromFormData)
  * )
+ * const formData = new FormData()
+ * formData.append("user[name]", "Alice")
+ * Schema.decodeSync(schema)(formData) // => { user: { name: "Alice" } }
  * ```
  *
  * @see {@link fromURLSearchParams}
@@ -1673,12 +1736,13 @@ export const fromFormData = new Transformation<unknown, FormData>(
  *
  * **Example** (Decoding URLSearchParams)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.instanceOf(URLSearchParams).pipe(
  *   Schema.decodeTo(Schema.Unknown, SchemaTransformation.fromURLSearchParams)
  * )
+ * Schema.decodeSync(schema)(new URLSearchParams("user[name]=Alice")) // => { user: { name: "Alice" } }
  * ```
  *
  * @see {@link fromFormData}
@@ -1743,10 +1807,16 @@ export const timeZoneNamedFromString: Transformation<DateTime.TimeZone.Named, st
   DateTime.TimeZone.Named,
   string
 >({
-  decode: (s) => {
+  decode: (s, options) => {
     return Option.match(DateTime.zoneMakeNamed(s), {
       onNone: () =>
-        Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), { message: `Invalid IANA time zone: ${s}` })),
+        Effect.fail(
+          new SchemaIssue.InvalidValue(
+            { expected: "a valid IANA time zone" },
+            s,
+            options
+          )
+        ),
       onSome: Effect.succeed
     })
   },
@@ -1778,9 +1848,16 @@ export const timeZoneFromString: Transformation<DateTime.TimeZone, string> = tra
   DateTime.TimeZone,
   string
 >({
-  decode: (s) => {
+  decode: (s, options) => {
     return Option.match(DateTime.zoneFromString(s), {
-      onNone: () => Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), { message: `Invalid time zone: ${s}` })),
+      onNone: () =>
+        Effect.fail(
+          new SchemaIssue.InvalidValue(
+            { expected: "a valid time zone" },
+            s,
+            options
+          )
+        ),
       onSome: Effect.succeed
     })
   },
@@ -1812,10 +1889,16 @@ export const dateTimeUtcFromString: Transformation<DateTime.Utc, string> = trans
   DateTime.Utc,
   string
 >({
-  decode: (s) => {
+  decode: (s, options) => {
     return Option.match(DateTime.make(s), {
       onNone: () =>
-        Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), { message: `Invalid UTC DateTime string: ${s}` })),
+        Effect.fail(
+          new SchemaIssue.InvalidValue(
+            { expected: "a valid UTC DateTime string" },
+            s,
+            options
+          )
+        ),
       onSome: (result) => Effect.succeed(DateTime.toUtc(result))
     })
   },
@@ -1846,10 +1929,16 @@ export const dateTimeZonedFromString: Transformation<DateTime.Zoned, string> = t
   DateTime.Zoned,
   string
 >({
-  decode: (s) => {
+  decode: (s, options) => {
     return Option.match(DateTime.makeZonedFromString(s), {
       onNone: () =>
-        Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), { message: `Invalid Zoned DateTime string: ${s}` })),
+        Effect.fail(
+          new SchemaIssue.InvalidValue(
+            { expected: "a valid Zoned DateTime string" },
+            s,
+            options
+          )
+        ),
       onSome: Effect.succeed
     })
   },