effect 4.0.0-beta.102 → 4.0.0-beta.103

package/dist/SchemaTransformation.js

@@ -48,13 +48,15 @@ import * as SchemaIssue from "./SchemaIssue.js";
  *
  * **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
@@ -99,14 +101,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
@@ -148,14 +149,11 @@ export class Transformation {
  *
  * **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}
@@ -183,13 +181,14 @@ export function isTransformation(u) {
  *
  * **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
@@ -222,7 +221,7 @@ export const make = 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(
@@ -232,20 +231,21 @@ export const make = options => {
  *       decode: (s) => {
  *         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" }))
  *           : 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(options) {
@@ -268,7 +268,7 @@ export function transformOrFail(options) {
  *
  * **Example** (Converting between cents and dollars)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const CentsFromDollars = Schema.Number.pipe(
@@ -280,13 +280,14 @@ export function transformOrFail(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(options) {
@@ -311,7 +312,7 @@ export function transform(options) {
  *
  * **Example** (Converting an optional key to Option)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Option, Schema, SchemaTransformation } from "effect"
  *
  * const schema = Schema.Struct({
@@ -325,13 +326,14 @@ export function transform(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(options) {
@@ -354,19 +356,20 @@ export function transformOptional(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() {
@@ -389,18 +392,19 @@ export function trim() {
  *
  * **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() {
@@ -422,18 +426,19 @@ export function snakeToCamel() {
  *
  * **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() {
@@ -455,18 +460,19 @@ export function toLowerCase() {
  *
  * **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() {
@@ -488,18 +494,19 @@ export function toUpperCase() {
  *
  * **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() {
@@ -521,18 +528,19 @@ export function capitalize() {
  *
  * **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() {
@@ -556,7 +564,7 @@ export function uncapitalize() {
  *
  * **Example** (Parsing key-value pairs)
  *
- * ```ts
+ * ```ts import.meta.vitest
  * import { Schema, SchemaTransformation } from "effect"
  *
  * const Config = Schema.String.pipe(
@@ -565,13 +573,13 @@ export function uncapitalize() {
  *     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) {
@@ -605,18 +613,19 @@ export function passthroughSubtype() {
  *
  * **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 = /*#__PURE__*/new Transformation(/*#__PURE__*/SchemaGetter.Number(), /*#__PURE__*/SchemaGetter.String());
@@ -637,18 +646,19 @@ export const numberFromString = /*#__PURE__*/new Transformation(/*#__PURE__*/Sch
  *
  * **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 = /*#__PURE__*/new Transformation(/*#__PURE__*/SchemaGetter.BigInt(), /*#__PURE__*/SchemaGetter.String());
@@ -668,18 +678,19 @@ export const bigintFromString = /*#__PURE__*/new Transformation(/*#__PURE__*/Sch
  *
  * **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 = /*#__PURE__*/new Transformation(/*#__PURE__*/SchemaGetter.Date(), /*#__PURE__*/SchemaGetter.transform(formatDate));
@@ -704,18 +715,19 @@ export const dateFromString = /*#__PURE__*/new Transformation(/*#__PURE__*/Schem
  *
  * **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 = /*#__PURE__*/new Transformation(/*#__PURE__*/SchemaGetter.Date(), /*#__PURE__*/SchemaGetter.transform(date => date.getTime()));
@@ -737,12 +749,13 @@ export const dateFromMillis = /*#__PURE__*/new Transformation(/*#__PURE__*/Schem
  *
  * **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}
@@ -753,8 +766,8 @@ export const dateFromMillis = /*#__PURE__*/new Transformation(/*#__PURE__*/Schem
  */
 export const durationFromString = /*#__PURE__*/transformOrFail({
   decode: s => Option.match(Duration.fromInput(s), {
-    onNone: () => Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), {
-      message: `Invalid Duration string: ${s}`
+    onNone: () => Effect.fail(new SchemaIssue.InvalidValue({
+      message: "Expected a valid Duration string"
     })),
     onSome: Effect.succeed
   }),
@@ -777,12 +790,13 @@ export const durationFromString = /*#__PURE__*/transformOrFail({
  *
  * **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}
@@ -793,8 +807,8 @@ export const durationFromString = /*#__PURE__*/transformOrFail({
 export const durationFromNanos = /*#__PURE__*/transformOrFail({
   decode: i => Effect.succeed(Duration.nanos(i)),
   encode: a => Option.match(Duration.toNanos(a), {
-    onNone: () => Effect.fail(new SchemaIssue.InvalidValue(Option.some(a), {
-      message: `Unable to encode ${a} into a bigint`
+    onNone: () => Effect.fail(new SchemaIssue.InvalidValue({
+      message: "Expected a Duration representable as a bigint"
     })),
     onSome: nanos => Effect.succeed(nanos)
   })
@@ -815,12 +829,13 @@ export const durationFromNanos = /*#__PURE__*/transformOrFail({
  *
  * **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}
@@ -907,8 +922,8 @@ export const defectFromJson = options => transform({
  *
  * **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(
@@ -916,6 +931,7 @@ export const defectFromJson = options => transform({
  *     SchemaTransformation.optionFromNullOr()
  *   )
  * )
+ * Schema.decodeSync(schema)(null) // => Option.none()
  * ```
  *
  * @see {@link optionFromNullishOr}
@@ -946,8 +962,8 @@ export function optionFromNullOr() {
  *
  * **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(
@@ -955,6 +971,7 @@ export function optionFromNullOr() {
  *     SchemaTransformation.optionFromUndefinedOr()
  *   )
  * )
+ * Schema.decodeSync(schema)(undefined) // => Option.none()
  * ```
  *
  * @see {@link optionFromOptionalKey}
@@ -988,8 +1005,8 @@ export function optionFromUndefinedOr() {
  *
  * **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(
@@ -997,6 +1014,7 @@ export function optionFromUndefinedOr() {
  *     SchemaTransformation.optionFromNullishOr({ onNoneEncoding: null })
  *   )
  * )
+ * Schema.encodeSync(schema)(Option.none()) // => null
  * ```
  *
  * @see {@link optionFromNullOr}
@@ -1029,8 +1047,8 @@ export function optionFromNullishOr(options) {
  *
  * **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(
@@ -1040,6 +1058,7 @@ export function optionFromNullishOr(options) {
  *     )
  *   )
  * })
+ * Schema.decodeSync(schema)({}).name // => Option.none()
  * ```
  *
  * @see {@link optionFromOptional}
@@ -1073,8 +1092,8 @@ export function optionFromOptionalKey() {
  *
  * **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(
@@ -1084,6 +1103,7 @@ export function optionFromOptionalKey() {
  *     )
  *   )
  * })
+ * Schema.decodeSync(schema)({ age: undefined }).age // => Option.none()
  * ```
  *
  * @see {@link optionFromOptionalKey}
@@ -1115,12 +1135,13 @@ export function optionFromOptional() {
  *
  * **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}
@@ -1130,8 +1151,8 @@ export function optionFromOptional() {
  * @since 4.0.0
  */
 export const urlFromString = /*#__PURE__*/transformOrFail({
-  decode: s => URL.canParse(s) ? Effect.succeed(new URL(s)) : Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), {
-    message: `Invalid URL string: ${s}`
+  decode: s => URL.canParse(s) ? Effect.succeed(new URL(s)) : Effect.fail(new SchemaIssue.InvalidValue({
+    message: "Expected a valid URL string"
   })),
   encode: url => Effect.succeed(url.href)
 });
@@ -1156,8 +1177,8 @@ export const urlFromString = /*#__PURE__*/transformOrFail({
 export const bigDecimalFromString = /*#__PURE__*/transformOrFail({
   decode: s => {
     const result = BigDecimal.fromString(s);
-    return Option.isNone(result) ? Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), {
-      message: `Invalid BigDecimal string: ${s}`
+    return Option.isNone(result) ? Effect.fail(new SchemaIssue.InvalidValue({
+      message: "Expected a valid BigDecimal string"
     })) : Effect.succeed(result.value);
   },
   encode: bd => Effect.succeed(BigDecimal.format(bd))
@@ -1178,12 +1199,13 @@ export const bigDecimalFromString = /*#__PURE__*/transformOrFail({
  *
  * **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}
@@ -1209,12 +1231,13 @@ export const uint8ArrayFromBase64String = /*#__PURE__*/new Transformation(/*#__P
  *
  * **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}
@@ -1239,12 +1262,13 @@ export const stringFromBase64String = /*#__PURE__*/new Transformation(/*#__PURE_
  *
  * **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}
@@ -1269,12 +1293,13 @@ export const stringFromBase64UrlString = /*#__PURE__*/new Transformation(/*#__PU
  *
  * **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}
@@ -1301,12 +1326,13 @@ export const stringFromHexString = /*#__PURE__*/new Transformation(/*#__PURE__*/
  *
  * **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}
@@ -1328,17 +1354,20 @@ export const stringFromUriComponent = /*#__PURE__*/new Transformation(/*#__PURE_
  *
  * **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}
@@ -1347,7 +1376,9 @@ export const stringFromUriComponent = /*#__PURE__*/new Transformation(/*#__PURE_
  * @category decoding
  * @since 4.0.0
  */
-export const fromJsonString = /*#__PURE__*/new Transformation(/*#__PURE__*/SchemaGetter.parseJson(), /*#__PURE__*/SchemaGetter.stringifyJson());
+export function fromJsonString(options) {
+  return new Transformation(SchemaGetter.parseJson(options ?? {}), SchemaGetter.stringifyJson(options));
+}
 /**
  * Decodes a `FormData` instance into a nested record using bracket-path keys and
  * encodes object-like values back into `FormData`.
@@ -1365,12 +1396,15 @@ export const fromJsonString = /*#__PURE__*/new Transformation(/*#__PURE__*/Schem
  *
  * **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}
@@ -1397,12 +1431,13 @@ export const fromFormData = /*#__PURE__*/new Transformation(/*#__PURE__*/SchemaG
  *
  * **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}
@@ -1458,8 +1493,8 @@ export const timeZoneOffsetFromNumber = /*#__PURE__*/transform({
 export const timeZoneNamedFromString = /*#__PURE__*/transformOrFail({
   decode: s => {
     return Option.match(DateTime.zoneMakeNamed(s), {
-      onNone: () => Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), {
-        message: `Invalid IANA time zone: ${s}`
+      onNone: () => Effect.fail(new SchemaIssue.InvalidValue({
+        message: "Expected a valid IANA time zone"
       })),
       onSome: Effect.succeed
     });
@@ -1490,8 +1525,8 @@ export const timeZoneNamedFromString = /*#__PURE__*/transformOrFail({
 export const timeZoneFromString = /*#__PURE__*/transformOrFail({
   decode: s => {
     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({
+        message: "Expected a valid time zone"
       })),
       onSome: Effect.succeed
     });
@@ -1522,8 +1557,8 @@ export const timeZoneFromString = /*#__PURE__*/transformOrFail({
 export const dateTimeUtcFromString = /*#__PURE__*/transformOrFail({
   decode: s => {
     return Option.match(DateTime.make(s), {
-      onNone: () => Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), {
-        message: `Invalid UTC DateTime string: ${s}`
+      onNone: () => Effect.fail(new SchemaIssue.InvalidValue({
+        message: "Expected a valid UTC DateTime string"
       })),
       onSome: result => Effect.succeed(DateTime.toUtc(result))
     });
@@ -1553,8 +1588,8 @@ export const dateTimeUtcFromString = /*#__PURE__*/transformOrFail({
 export const dateTimeZonedFromString = /*#__PURE__*/transformOrFail({
   decode: s => {
     return Option.match(DateTime.makeZonedFromString(s), {
-      onNone: () => Effect.fail(new SchemaIssue.InvalidValue(Option.some(s), {
-        message: `Invalid Zoned DateTime string: ${s}`
+      onNone: () => Effect.fail(new SchemaIssue.InvalidValue({
+        message: "Expected a valid Zoned DateTime string"
       })),
       onSome: Effect.succeed
     });