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

package/dist/SchemaTransformation.d.ts

@@ -47,13 +47,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
@@ -93,14 +95,13 @@ declare 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
@@ -135,14 +136,11 @@ export declare 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}
@@ -168,13 +166,14 @@ export declare function isTransformation(u: unknown): u is Transformation<any, a
  *
  * **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
@@ -205,30 +204,31 @@ export declare 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 declare function transformOrFail<T, E, RD = never, RE = never>(options: {
@@ -252,7 +252,7 @@ export declare 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(
@@ -264,13 +264,14 @@ export declare 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 declare function transform<T, E>(options: {
@@ -296,7 +297,7 @@ export declare 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({
@@ -310,13 +311,14 @@ export declare 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 declare function transformOptional<T, E>(options: {
@@ -340,19 +342,20 @@ export declare 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 declare function trim(): Transformation<string, string>;
@@ -373,18 +376,19 @@ export declare 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 declare function snakeToCamel(): Transformation<string, string>;
@@ -404,18 +408,19 @@ export declare 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 declare function toLowerCase(): Transformation<string, string>;
@@ -435,18 +440,19 @@ export declare 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 declare function toUpperCase(): Transformation<string, string>;
@@ -466,18 +472,19 @@ export declare 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 declare function capitalize(): Transformation<string, string>;
@@ -497,18 +504,19 @@ export declare 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 declare function uncapitalize(): Transformation<string, string>;
@@ -530,7 +538,7 @@ export declare 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(
@@ -539,13 +547,13 @@ export declare 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 declare function splitKeyValue(options?: {
@@ -570,12 +578,13 @@ export declare function splitKeyValue(options?: {
  *
  * **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}
@@ -605,10 +614,11 @@ export declare 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}
@@ -634,10 +644,11 @@ export declare function passthroughSupertype<T extends E, E>(): Transformation<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}
@@ -665,18 +676,19 @@ export declare function passthroughSubtype<T, E extends T>(): Transformation<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 declare const numberFromString: Transformation<number, string, never, never>;
@@ -697,18 +709,19 @@ export declare const numberFromString: Transformation<number, string, never, nev
  *
  * **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 declare const bigintFromString: Transformation<bigint, string, never, never>;
@@ -717,8 +730,8 @@ export declare const bigintFromString: Transformation<bigint, string, never, nev
  *
  * **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**
  *
@@ -728,18 +741,19 @@ export declare const bigintFromString: Transformation<bigint, string, never, nev
  *
  * **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 declare const dateFromString: Transformation<globalThis.Date, string>;
@@ -764,18 +778,19 @@ export declare const dateFromString: Transformation<globalThis.Date, string>;
  *
  * **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 declare const dateFromMillis: Transformation<globalThis.Date, number>;
@@ -797,12 +812,13 @@ export declare const dateFromMillis: Transformation<globalThis.Date, number>;
  *
  * **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}
@@ -829,12 +845,13 @@ export declare const durationFromString: Transformation<Duration.Duration, strin
  *
  * **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}
@@ -859,12 +876,13 @@ export declare const durationFromNanos: Transformation<Duration.Duration, bigint
  *
  * **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}
@@ -890,8 +908,8 @@ export declare const durationFromMillis: Transformation<Duration.Duration, numbe
  *
  * **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(
@@ -899,6 +917,7 @@ export declare const durationFromMillis: Transformation<Duration.Duration, numbe
  *     SchemaTransformation.optionFromNullOr()
  *   )
  * )
+ * Schema.decodeSync(schema)(null) // => Option.none()
  * ```
  *
  * @see {@link optionFromNullishOr}
@@ -924,8 +943,8 @@ export declare function optionFromNullOr<T>(): Transformation<Option.Option<T>,
  *
  * **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(
@@ -933,6 +952,7 @@ export declare function optionFromNullOr<T>(): Transformation<Option.Option<T>,
  *     SchemaTransformation.optionFromUndefinedOr()
  *   )
  * )
+ * Schema.decodeSync(schema)(undefined) // => Option.none()
  * ```
  *
  * @see {@link optionFromOptionalKey}
@@ -961,8 +981,8 @@ export declare function optionFromUndefinedOr<T>(): Transformation<Option.Option
  *
  * **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(
@@ -970,6 +990,7 @@ export declare function optionFromUndefinedOr<T>(): Transformation<Option.Option
  *     SchemaTransformation.optionFromNullishOr({ onNoneEncoding: null })
  *   )
  * )
+ * Schema.encodeSync(schema)(Option.none()) // => null
  * ```
  *
  * @see {@link optionFromNullOr}
@@ -999,8 +1020,8 @@ export declare function optionFromNullishOr<T>(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(
@@ -1010,6 +1031,7 @@ export declare function optionFromNullishOr<T>(options?: {
  *     )
  *   )
  * })
+ * Schema.decodeSync(schema)({}).name // => Option.none()
  * ```
  *
  * @see {@link optionFromOptional}
@@ -1038,8 +1060,8 @@ export declare function optionFromOptionalKey<T>(): Transformation<Option.Option
  *
  * **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(
@@ -1049,6 +1071,7 @@ export declare function optionFromOptionalKey<T>(): Transformation<Option.Option
  *     )
  *   )
  * })
+ * Schema.decodeSync(schema)({ age: undefined }).age // => Option.none()
  * ```
  *
  * @see {@link optionFromOptionalKey}
@@ -1075,12 +1098,13 @@ export declare function optionFromOptional<T>(): Transformation<Option.Option<T>
  *
  * **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}
@@ -1125,12 +1149,13 @@ export declare const bigDecimalFromString: Transformation<BigDecimal.BigDecimal,
  *
  * **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}
@@ -1156,12 +1181,13 @@ export declare const uint8ArrayFromBase64String: Transformation<Uint8Array<Array
  *
  * **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}
@@ -1186,12 +1212,13 @@ export declare const stringFromBase64String: Transformation<string, string>;
  *
  * **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}
@@ -1216,12 +1243,13 @@ export declare const stringFromBase64UrlString: Transformation<string, string>;
  *
  * **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}
@@ -1248,12 +1276,13 @@ export declare const stringFromHexString: Transformation<string, string>;
  *
  * **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}
@@ -1275,17 +1304,20 @@ export declare const stringFromUriComponent: Transformation<string, string>;
  *
  * **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}
@@ -1294,7 +1326,11 @@ export declare const stringFromUriComponent: Transformation<string, string>;
  * @category decoding
  * @since 4.0.0
  */
-export declare const fromJsonString: Transformation<unknown, string, never, never>;
+export declare 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>;
 /**
  * Decodes a `FormData` instance into a nested record using bracket-path keys and
  * encodes object-like values back into `FormData`.
@@ -1312,12 +1348,15 @@ export declare const fromJsonString: Transformation<unknown, string, never, neve
  *
  * **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}
@@ -1344,12 +1383,13 @@ export declare const fromFormData: Transformation<unknown, FormData, never, neve
  *
  * **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}