effect 4.0.0-beta.31 → 4.0.0-beta.32

package/src/TxHashMap.ts

@@ -42,7 +42,7 @@ const TxHashMapProto = {
  *
  * @example
  * ```ts
- * import { Effect, Option, TxHashMap } from "effect"
+ * import { Effect, TxHashMap } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   // Create a transactional hash map
@@ -57,7 +57,7 @@ const TxHashMapProto = {
  *   yield* Effect.transaction(
  *     Effect.gen(function*() {
  *       const currentUser = yield* TxHashMap.get(txMap, "user1")
- *       if (Option.isSome(currentUser)) {
+ *       if (currentUser._tag === "Some") {
  *         yield* TxHashMap.set(txMap, "user1", currentUser.value + "_updated")
  *         yield* TxHashMap.remove(txMap, "user2")
  *       }
@@ -348,7 +348,7 @@ export const fromIterable = <K, V>(
  *
  *   // Use with pipe syntax for type-safe access
  *   const bobRole = yield* TxHashMap.get(userMap, "bob")
- *   if (Option.isSome(bobRole)) {
+ *   if (bobRole._tag === "Some") {
  *     console.log(bobRole.value.role) // "user"
  *   }
  * })
@@ -380,7 +380,7 @@ export const get: {
    *
    *   // Use with pipe syntax for type-safe access
    *   const bobRole = yield* TxHashMap.get(userMap, "bob")
-   *   if (Option.isSome(bobRole)) {
+   *   if (bobRole._tag === "Some") {
    *     console.log(bobRole.value.role) // "user"
    *   }
    * })
@@ -412,7 +412,7 @@ export const get: {
    *
    *   // Use with pipe syntax for type-safe access
    *   const bobRole = yield* TxHashMap.get(userMap, "bob")
-   *   if (Option.isSome(bobRole)) {
+   *   if (bobRole._tag === "Some") {
    *     console.log(bobRole.value.role) // "user"
    *   }
    * })
@@ -1068,7 +1068,7 @@ export const modify: {
  *
  * @example
  * ```ts
- * import { Effect, Option, TxHashMap } from "effect"
+ * import { Effect, TxHashMap } from "effect"
  *
  * const program = Effect.gen(function*() {
  *   const storage = yield* TxHashMap.make<string, string | number>([
@@ -1076,26 +1076,32 @@ export const modify: {
  *     "content1"
  *   ], ["access_count", 0])
  *
- *   // Increment counter or initialize to 1
- *   const updateFn = (opt: Option.Option<string | number>) =>
- *     Option.isSome(opt) && typeof opt.value === "number"
- *       ? Option.some(opt.value + 1)
- *       : Option.some(1)
- *
  *   // Increment existing counter
- *   yield* TxHashMap.modifyAt(storage, "access_count", updateFn)
+ *   yield* TxHashMap.modifyAt(storage, "access_count", (current) =>
+ *     current._tag === "Some" && typeof current.value === "number"
+ *       ? { ...current, value: current.value + 1 }
+ *       : current
+ *   )
  *   const count1 = yield* TxHashMap.get(storage, "access_count")
  *   console.log(count1) // Option.some(1)
  *
  *   // Increment existing counter again
- *   yield* TxHashMap.modifyAt(storage, "access_count", updateFn)
+ *   yield* TxHashMap.modifyAt(storage, "access_count", (current) =>
+ *     current._tag === "Some" && typeof current.value === "number"
+ *       ? { ...current, value: current.value + 1 }
+ *       : current
+ *   )
  *   const count2 = yield* TxHashMap.get(storage, "access_count")
  *   console.log(count2) // Option.some(2)
  *
- *   // Remove by returning None
- *   yield* TxHashMap.modifyAt(storage, "file1.txt", () => Option.none())
- *   const hasFile = yield* TxHashMap.has(storage, "file1.txt")
- *   console.log(hasFile) // false
+ *   // Update an existing string entry
+ *   yield* TxHashMap.modifyAt(storage, "file1.txt", (current) =>
+ *     current._tag === "Some" && typeof current.value === "string"
+ *       ? { ...current, value: `${current.value}.bak` }
+ *       : current
+ *   )
+ *   const backup = yield* TxHashMap.get(storage, "file1.txt")
+ *   console.log(backup) // Option.some("content1.bak")
  * })
  * ```
  *
@@ -1112,7 +1118,7 @@ export const modifyAt: {
    *
    * @example
    * ```ts
-   * import { Effect, Option, TxHashMap } from "effect"
+   * import { Effect, TxHashMap } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const storage = yield* TxHashMap.make<string, string | number>([
@@ -1120,26 +1126,32 @@ export const modifyAt: {
    *     "content1"
    *   ], ["access_count", 0])
    *
-   *   // Increment counter or initialize to 1
-   *   const updateFn = (opt: Option.Option<string | number>) =>
-   *     Option.isSome(opt) && typeof opt.value === "number"
-   *       ? Option.some(opt.value + 1)
-   *       : Option.some(1)
-   *
    *   // Increment existing counter
-   *   yield* TxHashMap.modifyAt(storage, "access_count", updateFn)
+   *   yield* TxHashMap.modifyAt(storage, "access_count", (current) =>
+   *     current._tag === "Some" && typeof current.value === "number"
+   *       ? { ...current, value: current.value + 1 }
+   *       : current
+   *   )
    *   const count1 = yield* TxHashMap.get(storage, "access_count")
    *   console.log(count1) // Option.some(1)
    *
    *   // Increment existing counter again
-   *   yield* TxHashMap.modifyAt(storage, "access_count", updateFn)
+   *   yield* TxHashMap.modifyAt(storage, "access_count", (current) =>
+   *     current._tag === "Some" && typeof current.value === "number"
+   *       ? { ...current, value: current.value + 1 }
+   *       : current
+   *   )
    *   const count2 = yield* TxHashMap.get(storage, "access_count")
    *   console.log(count2) // Option.some(2)
    *
-   *   // Remove by returning None
-   *   yield* TxHashMap.modifyAt(storage, "file1.txt", () => Option.none())
-   *   const hasFile = yield* TxHashMap.has(storage, "file1.txt")
-   *   console.log(hasFile) // false
+   *   // Update an existing string entry
+   *   yield* TxHashMap.modifyAt(storage, "file1.txt", (current) =>
+   *     current._tag === "Some" && typeof current.value === "string"
+   *       ? { ...current, value: `${current.value}.bak` }
+   *       : current
+   *   )
+   *   const backup = yield* TxHashMap.get(storage, "file1.txt")
+   *   console.log(backup) // Option.some("content1.bak")
    * })
    * ```
    *
@@ -1156,7 +1168,7 @@ export const modifyAt: {
    *
    * @example
    * ```ts
-   * import { Effect, Option, TxHashMap } from "effect"
+   * import { Effect, TxHashMap } from "effect"
    *
    * const program = Effect.gen(function*() {
    *   const storage = yield* TxHashMap.make<string, string | number>([
@@ -1164,26 +1176,32 @@ export const modifyAt: {
    *     "content1"
    *   ], ["access_count", 0])
    *
-   *   // Increment counter or initialize to 1
-   *   const updateFn = (opt: Option.Option<string | number>) =>
-   *     Option.isSome(opt) && typeof opt.value === "number"
-   *       ? Option.some(opt.value + 1)
-   *       : Option.some(1)
-   *
    *   // Increment existing counter
-   *   yield* TxHashMap.modifyAt(storage, "access_count", updateFn)
+   *   yield* TxHashMap.modifyAt(storage, "access_count", (current) =>
+   *     current._tag === "Some" && typeof current.value === "number"
+   *       ? { ...current, value: current.value + 1 }
+   *       : current
+   *   )
    *   const count1 = yield* TxHashMap.get(storage, "access_count")
    *   console.log(count1) // Option.some(1)
    *
    *   // Increment existing counter again
-   *   yield* TxHashMap.modifyAt(storage, "access_count", updateFn)
+   *   yield* TxHashMap.modifyAt(storage, "access_count", (current) =>
+   *     current._tag === "Some" && typeof current.value === "number"
+   *       ? { ...current, value: current.value + 1 }
+   *       : current
+   *   )
    *   const count2 = yield* TxHashMap.get(storage, "access_count")
    *   console.log(count2) // Option.some(2)
    *
-   *   // Remove by returning None
-   *   yield* TxHashMap.modifyAt(storage, "file1.txt", () => Option.none())
-   *   const hasFile = yield* TxHashMap.has(storage, "file1.txt")
-   *   console.log(hasFile) // false
+   *   // Update an existing string entry
+   *   yield* TxHashMap.modifyAt(storage, "file1.txt", (current) =>
+   *     current._tag === "Some" && typeof current.value === "string"
+   *       ? { ...current, value: `${current.value}.bak` }
+   *       : current
+   *   )
+   *   const backup = yield* TxHashMap.get(storage, "file1.txt")
+   *   console.log(backup) // Option.some("content1.bak")
    * })
    * ```
    *
@@ -1235,7 +1253,7 @@ export const modifyAt: {
  *   // Useful for iteration
  *   for (const username of usernames) {
  *     const role = yield* TxHashMap.get(userRoles, username)
- *     if (Option.isSome(role)) {
+ *     if (role._tag === "Some") {
  *       console.log(`${username}: ${role.value}`)
  *     }
  *   }
@@ -3061,8 +3079,8 @@ export const hasBy: {
  *     (task) => task.priority >= 2 && !task.completed
  *   )
  *
- *   if (highPriorityTask) {
- *     const [taskId, task] = highPriorityTask
+ *   if (highPriorityTask._tag === "Some") {
+ *     const [taskId, task] = highPriorityTask.value
  *     console.log(`Found task: ${taskId}, priority: ${task.priority}`)
  *     // "Found task: task3, priority: 2"
  *   }
@@ -3072,8 +3090,8 @@ export const hasBy: {
  *     TxHashMap.findFirst((task) => task.assignee === "alice")
  *   )
  *
- *   if (aliceTask) {
- *     console.log(`Alice's task: ${aliceTask[0]}`)
+ *   if (aliceTask._tag === "Some") {
+ *     console.log(`Alice's task: ${aliceTask.value[0]}`)
  *   }
  * })
  * ```
@@ -3104,8 +3122,8 @@ export const findFirst: {
    *     (task) => task.priority >= 2 && !task.completed
    *   )
    *
-   *   if (highPriorityTask) {
-   *     const [taskId, task] = highPriorityTask
+   *   if (highPriorityTask._tag === "Some") {
+   *     const [taskId, task] = highPriorityTask.value
    *     console.log(`Found task: ${taskId}, priority: ${task.priority}`)
    *     // "Found task: task3, priority: 2"
    *   }
@@ -3115,8 +3133,8 @@ export const findFirst: {
    *     TxHashMap.findFirst((task) => task.assignee === "alice")
    *   )
    *
-   *   if (aliceTask) {
-   *     console.log(`Alice's task: ${aliceTask[0]}`)
+   *   if (aliceTask._tag === "Some") {
+   *     console.log(`Alice's task: ${aliceTask.value[0]}`)
    *   }
    * })
    * ```
@@ -3124,7 +3142,7 @@ export const findFirst: {
    * @since 2.0.0
    * @category combinators
    */
-  <K, V>(predicate: (value: V, key: K) => boolean): (self: TxHashMap<K, V>) => Effect.Effect<[K, V] | undefined, never, Effect.Transaction>
+  <K, V>(predicate: (value: V, key: K) => boolean): (self: TxHashMap<K, V>) => Effect.Effect<Option.Option<[K, V]>, never, Effect.Transaction>
   /**
    * Finds the first entry in the TxHashMap that matches the given predicate.
    * Returns the key-value pair as a tuple wrapped in an Option.
@@ -3147,8 +3165,8 @@ export const findFirst: {
    *     (task) => task.priority >= 2 && !task.completed
    *   )
    *
-   *   if (highPriorityTask) {
-   *     const [taskId, task] = highPriorityTask
+   *   if (highPriorityTask._tag === "Some") {
+   *     const [taskId, task] = highPriorityTask.value
    *     console.log(`Found task: ${taskId}, priority: ${task.priority}`)
    *     // "Found task: task3, priority: 2"
    *   }
@@ -3158,8 +3176,8 @@ export const findFirst: {
    *     TxHashMap.findFirst((task) => task.assignee === "alice")
    *   )
    *
-   *   if (aliceTask) {
-   *     console.log(`Alice's task: ${aliceTask[0]}`)
+   *   if (aliceTask._tag === "Some") {
+   *     console.log(`Alice's task: ${aliceTask.value[0]}`)
    *   }
    * })
    * ```
@@ -3167,13 +3185,13 @@ export const findFirst: {
    * @since 2.0.0
    * @category combinators
    */
-  <K, V>(self: TxHashMap<K, V>, predicate: (value: V, key: K) => boolean): Effect.Effect<[K, V] | undefined, never, Effect.Transaction>
+  <K, V>(self: TxHashMap<K, V>, predicate: (value: V, key: K) => boolean): Effect.Effect<Option.Option<[K, V]>, never, Effect.Transaction>
 } = dual(
   2,
   <K, V>(
     self: TxHashMap<K, V>,
     predicate: (value: V, key: K) => boolean
-  ): Effect.Effect<[K, V] | undefined, never, Effect.Transaction> =>
+  ): Effect.Effect<Option.Option<[K, V]>, never, Effect.Transaction> =>
     TxRef.get(self.ref).pipe(Effect.map((map) => HashMap.findFirst(map, predicate)))
 )
 

package/src/TxSemaphore.ts

@@ -433,15 +433,102 @@ export const releaseN = (self: TxSemaphore, n: number): Effect.Effect<void, neve
  * @since 4.0.0
  * @category combinators
  */
-export const withPermit = <A, E, R>(
-  self: TxSemaphore,
-  effect: Effect.Effect<A, E, R>
-): Effect.Effect<A, E, R> =>
-  Effect.acquireUseRelease(
+export const withPermit: {
+  /**
+   * Executes an effect with a single permit from the semaphore. The permit is
+   * automatically acquired before execution and released afterwards, even if the
+   * effect fails or is interrupted.
+   *
+   * **Note**: The permit acquisition and release operations use atomic semantics
+   * to ensure proper resource management with Effect's scoped operations.
+   *
+   * @example
+   * ```ts
+   * import { Console, Effect, TxSemaphore } from "effect"
+   *
+   * const program = Effect.gen(function*() {
+   *   const semaphore = yield* TxSemaphore.make(2)
+   *
+   *   // Execute database operation with automatic permit management
+   *   const result = yield* TxSemaphore.withPermit(
+   *     semaphore,
+   *     Effect.gen(function*() {
+   *       yield* Console.log("Permit acquired, accessing database...")
+   *       yield* Effect.sleep("100 millis") // Simulate database work
+   *       yield* Console.log("Database operation complete")
+   *       return "query result"
+   *     })
+   *   )
+   *
+   *   yield* Console.log(`Result: ${result}`)
+   *   // Permit is automatically released here
+   * })
+   * ```
+   *
+   * @param self - The TxSemaphore to acquire a permit from
+   * @param effect - The effect to execute with the permit
+   * @returns Effect that succeeds with the result of the provided effect
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  (self: TxSemaphore): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  /**
+   * Executes an effect with a single permit from the semaphore. The permit is
+   * automatically acquired before execution and released afterwards, even if the
+   * effect fails or is interrupted.
+   *
+   * **Note**: The permit acquisition and release operations use atomic semantics
+   * to ensure proper resource management with Effect's scoped operations.
+   *
+   * @example
+   * ```ts
+   * import { Console, Effect, TxSemaphore } from "effect"
+   *
+   * const program = Effect.gen(function*() {
+   *   const semaphore = yield* TxSemaphore.make(2)
+   *
+   *   // Execute database operation with automatic permit management
+   *   const result = yield* TxSemaphore.withPermit(
+   *     semaphore,
+   *     Effect.gen(function*() {
+   *       yield* Console.log("Permit acquired, accessing database...")
+   *       yield* Effect.sleep("100 millis") // Simulate database work
+   *       yield* Console.log("Database operation complete")
+   *       return "query result"
+   *     })
+   *   )
+   *
+   *   yield* Console.log(`Result: ${result}`)
+   *   // Permit is automatically released here
+   * })
+   * ```
+   *
+   * @param self - The TxSemaphore to acquire a permit from
+   * @param effect - The effect to execute with the permit
+   * @returns Effect that succeeds with the result of the provided effect
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <A, E, R>(self: TxSemaphore, effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R>
+} = ((...args: Array<any>) => {
+  if (args.length === 1) {
+    const [self] = args
+    return (effect: Effect.Effect<any, any, any>) =>
+      Effect.acquireUseRelease(
+        Effect.transaction(acquire(self)),
+        () => effect,
+        () => Effect.transaction(release(self))
+      )
+  }
+  const [self, effect] = args
+  return Effect.acquireUseRelease(
     Effect.transaction(acquire(self)),
     () => effect,
     () => Effect.transaction(release(self))
   )
+}) as any
 
 /**
  * Executes an effect with the specified number of permits from the semaphore.
@@ -482,16 +569,104 @@ export const withPermit = <A, E, R>(
  * @since 4.0.0
  * @category combinators
  */
-export const withPermits = <A, E, R>(
-  self: TxSemaphore,
-  n: number,
-  effect: Effect.Effect<A, E, R>
-): Effect.Effect<A, E, R> =>
-  Effect.acquireUseRelease(
+export const withPermits: {
+  /**
+   * Executes an effect with the specified number of permits from the semaphore.
+   * The permits are automatically acquired before execution and released afterwards,
+   * even if the effect fails or is interrupted.
+   *
+   * **Note**: The permit acquisition and release operations use atomic semantics
+   * to ensure proper resource management with Effect's scoped operations.
+   *
+   * @example
+   * ```ts
+   * import { Console, Effect, TxSemaphore } from "effect"
+   *
+   * const program = Effect.gen(function*() {
+   *   const semaphore = yield* TxSemaphore.make(5)
+   *
+   *   // Execute batch operation with 3 permits
+   *   const results = yield* TxSemaphore.withPermits(
+   *     semaphore,
+   *     3,
+   *     Effect.gen(function*() {
+   *       yield* Console.log("3 permits acquired, processing batch...")
+   *       yield* Effect.sleep("200 millis") // Simulate batch processing
+   *       return ["result1", "result2", "result3"]
+   *     })
+   *   )
+   *
+   *   yield* Console.log(`Batch results: ${results.join(", ")}`)
+   *   // All 3 permits are automatically released here
+   * })
+   * ```
+   *
+   * @param self - The TxSemaphore to acquire permits from
+   * @param n - The number of permits to acquire (must be positive)
+   * @param effect - The effect to execute with the permits
+   * @returns Effect that succeeds with the result of the provided effect
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  (self: TxSemaphore, n: number): <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>
+  /**
+   * Executes an effect with the specified number of permits from the semaphore.
+   * The permits are automatically acquired before execution and released afterwards,
+   * even if the effect fails or is interrupted.
+   *
+   * **Note**: The permit acquisition and release operations use atomic semantics
+   * to ensure proper resource management with Effect's scoped operations.
+   *
+   * @example
+   * ```ts
+   * import { Console, Effect, TxSemaphore } from "effect"
+   *
+   * const program = Effect.gen(function*() {
+   *   const semaphore = yield* TxSemaphore.make(5)
+   *
+   *   // Execute batch operation with 3 permits
+   *   const results = yield* TxSemaphore.withPermits(
+   *     semaphore,
+   *     3,
+   *     Effect.gen(function*() {
+   *       yield* Console.log("3 permits acquired, processing batch...")
+   *       yield* Effect.sleep("200 millis") // Simulate batch processing
+   *       return ["result1", "result2", "result3"]
+   *     })
+   *   )
+   *
+   *   yield* Console.log(`Batch results: ${results.join(", ")}`)
+   *   // All 3 permits are automatically released here
+   * })
+   * ```
+   *
+   * @param self - The TxSemaphore to acquire permits from
+   * @param n - The number of permits to acquire (must be positive)
+   * @param effect - The effect to execute with the permits
+   * @returns Effect that succeeds with the result of the provided effect
+   *
+   * @since 4.0.0
+   * @category combinators
+   */
+  <A, E, R>(self: TxSemaphore, n: number, effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R>
+} = ((...args: Array<any>) => {
+  if (args.length === 2) {
+    const [self, n] = args
+    return (effect: Effect.Effect<any, any, any>) =>
+      Effect.acquireUseRelease(
+        Effect.transaction(acquireN(self, n)),
+        () => effect,
+        () => Effect.transaction(releaseN(self, n))
+      )
+  }
+  const [self, n, effect] = args
+  return Effect.acquireUseRelease(
     Effect.transaction(acquireN(self, n)),
     () => effect,
     () => Effect.transaction(releaseN(self, n))
   )
+}) as any
 
 /**
  * Acquires a single permit from the semaphore in a scoped manner. The permit

package/src/index.ts

@@ -1558,7 +1558,7 @@ export * as Inspectable from "./Inspectable.ts"
  *
  * @example
  * ```ts
- * import { Iterable } from "effect"
+ * import { Iterable, Option } from "effect"
  *
  * // Create iterables
  * const numbers = Iterable.range(1, 5)
@@ -1568,7 +1568,7 @@ export * as Inspectable from "./Inspectable.ts"
  * console.log(Array.from(filtered)) // [6, 8, 10]
  *
  * // Infinite iterables
- * const fibonacci = Iterable.unfold([0, 1], ([a, b]) => [a, [b, a + b]])
+ * const fibonacci = Iterable.unfold([0, 1], ([a, b]) => Option.some([a, [b, a + b]]))
  * const first10 = Iterable.take(fibonacci, 10)
  * console.log(Array.from(first10)) // [0, 1, 1, 2, 3, 5, 8, 13, 21, 34]
  * ```
@@ -2513,37 +2513,6 @@ export * as Newtype from "./Newtype.ts"
  */
 export * as NonEmptyIterable from "./NonEmptyIterable.ts"
 
-/**
- * This module provides small, allocation-free utilities for working with values of type
- * `A | null`, where `null` means "no value".
- *
- * Why not `Option<A>`?
- * In TypeScript, `Option<A>` is often unnecessary. If `null` already models absence
- * in your domain, using `A | null` keeps types simple, avoids extra wrappers, and
- * reduces overhead. The key is that `A` itself must not include `null`; in this
- * module `null` is reserved to mean "no value".
- *
- * When to use `A | null`:
- * - Absence can be represented by `null` in your domain model.
- * - You do not need to distinguish between "no value" and "value is null".
- * - You want straightforward ergonomics and zero extra allocations.
- *
- * When to prefer `Option<A>`:
- * - You must distinguish `None` from `Some(null)` (that is, `null` is a valid
- *   payload and carries meaning on its own).
- * - You need a tagged representation for serialization or pattern matching across
- *   boundaries where `null` would be ambiguous.
- * - You want the richer `Option` API and are comfortable with the extra wrapper.
- *
- * Lawfulness note:
- * All helpers treat `null` as absence. Do not use these utilities with payloads
- * where `A` can itself be `null`, or you will lose information. If you need to
- * carry `null` as a valid payload, use `Option<A>` instead.
- *
- * @since 4.0.0
- */
-export * as NullOr from "./NullOr.ts"
-
 /**
  * This module provides utility functions and type class instances for working with the `number` type in TypeScript.
  * It includes functions for basic arithmetic operations.
@@ -2808,6 +2777,11 @@ export * as Order from "./Order.ts"
  */
 export * as Ordering from "./Ordering.ts"
 
+/**
+ * @since 4.0.0
+ */
+export * as PartitionedSemaphore from "./PartitionedSemaphore.ts"
+
 /**
  * @since 4.0.0
  */
@@ -3273,6 +3247,88 @@ export * as Schedule from "./Schedule.ts"
 export * as Scheduler from "./Scheduler.ts"
 
 /**
+ * Define data shapes, validate unknown input, and transform values between formats.
+ *
+ * ## Mental model
+ *
+ * - **Schema** — a description of a data shape. Every schema carries a decoded
+ *   *Type* (the value you work with) and an *Encoded* representation (the
+ *   serialized form, e.g. JSON).
+ * - **Decoding** — turning unknown external data (API responses, form
+ *   submissions, config files) into typed, validated values.
+ * - **Encoding** — turning typed values back into a serializable format.
+ * - **Codec** — a schema that tracks both Type and Encoded, so it can decode
+ *   *and* encode. Most concrete schemas are Codecs.
+ * - **Check / Filter** — a constraint attached to a schema (e.g. `isMinLength`,
+ *   `isGreaterThan`). Attach them with `.check(...)`.
+ * - **Transformation** — a pair of functions (decode + encode) that convert
+ *   values between two schemas. Created with {@link decodeTo} / {@link encodeTo}.
+ * - **Annotation** — metadata attached to a schema (title, description, custom
+ *   keys). Attach with `.annotate(...)`.
+ *
+ * ## Common tasks
+ *
+ * - Define a struct: {@link Struct}
+ * - Define a union: {@link Union}, {@link TaggedUnion}, {@link Literals}
+ * - Define an array: {@link Array}, {@link NonEmptyArray}
+ * - Define a record: {@link Record}
+ * - Define a tuple: {@link Tuple}, {@link TupleWithRest}
+ * - Validate unknown data synchronously: {@link decodeUnknownSync}
+ * - Validate unknown data (Effect): {@link decodeUnknownEffect}
+ * - Encode a value: {@link encodeUnknownSync}, {@link encodeUnknownEffect}
+ * - Type guard: {@link is}
+ * - Assertion: {@link asserts}
+ * - Add constraints: `.check(...)` with filters like {@link isMinLength},
+ *   {@link isGreaterThan}, {@link isPattern}, {@link isUUID}
+ * - Transform between schemas: {@link decodeTo}, {@link encodeTo}
+ * - Add a default for missing keys: {@link withDecodingDefault}, {@link withDecodingDefaultKey}
+ * - Create branded types: {@link brand}
+ * - Define classes with validation: {@link Class}, {@link TaggedClass}
+ * - Define error classes: {@link ErrorClass}, {@link TaggedErrorClass}
+ * - Generate JSON Schema: {@link toJsonSchemaDocument}
+ * - Generate test data: {@link toArbitrary}
+ * - Derive equivalence: {@link toEquivalence}
+ *
+ * ## Gotchas
+ *
+ * - `Schema.optional` creates `T | undefined` (key can be missing *or*
+ *   `undefined`). Use `Schema.optionalKey` for exact optional properties.
+ * - `decodeTo` is curried: use `from.pipe(Schema.decodeTo(to, ...))`.
+ * - `decodeUnknownSync` throws on failure. Use `decodeUnknownExit` or
+ *   `decodeUnknownOption` for non-throwing alternatives.
+ * - Filters do not change the TypeScript type. Use {@link refine} or
+ *   {@link brand} to narrow the type.
+ * - Recursive schemas require {@link suspend} to avoid infinite loops.
+ *
+ * ## Quickstart
+ *
+ * **Example** (Validate a user object)
+ *
+ * ```ts
+ * import { Schema } from "effect"
+ *
+ * const User = Schema.Struct({
+ *   name: Schema.String.check(Schema.isMinLength(1)),
+ *   age: Schema.Number.check(Schema.isGreaterThanOrEqualTo(0)),
+ *   email: Schema.optionalKey(Schema.String)
+ * })
+ *
+ * // Decode unknown input — throws on failure
+ * const user = Schema.decodeUnknownSync(User)({
+ *   name: "Alice",
+ *   age: 30
+ * })
+ *
+ * console.log(user)
+ * // { name: "Alice", age: 30 }
+ * ```
+ *
+ * @see {@link Schema} — type-level view tracking only the decoded Type
+ * @see {@link Codec} — type-level view tracking both Type and Encoded
+ * @see {@link Struct} — define object shapes
+ * @see {@link decodeUnknownSync} — synchronous validation
+ * @see {@link decodeTo} — schema transformations
+ *
  * @since 4.0.0
  */
 export * as Schema from "./Schema.ts"