effect 4.0.0-beta.66 → 4.0.0-beta.67

package/src/TxReentrantLock.ts

@@ -20,8 +20,8 @@ import * as TxRef from "./TxRef.ts"
 const TypeId = "~effect/transactions/TxReentrantLock"
 
 /**
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 interface LockState {
   readonly readers: HashMap.HashMap<number, number>
@@ -38,7 +38,8 @@ const emptyState: LockState = {
  * Multiple readers can hold the lock concurrently, or a single writer can hold exclusive
  * access. A fiber holding the write lock may acquire additional read/write locks (reentrancy).
  *
- * @example
+ * **Example** (Using read and write locks)
+ *
  * ```ts
  * import { Effect, TxReentrantLock } from "effect"
  *
@@ -53,8 +54,8 @@ const emptyState: LockState = {
  * })
  * ```
  *
- * @since 4.0.0
  * @category models
+ * @since 4.0.0
  */
 export interface TxReentrantLock extends Inspectable, Pipeable {
   readonly [TypeId]: typeof TypeId
@@ -84,7 +85,8 @@ const TxReentrantLockProto: Omit<TxReentrantLock, typeof TypeId | "stateRef"> =
 /**
  * Creates a new TxReentrantLock.
  *
- * @example
+ * **Example** (Creating a reentrant lock)
+ *
  * ```ts
  * import { Effect, TxReentrantLock } from "effect"
  *
@@ -95,8 +97,8 @@ const TxReentrantLockProto: Omit<TxReentrantLock, typeof TypeId | "stateRef"> =
  * })
  * ```
  *
- * @since 4.0.0
  * @category constructors
+ * @since 4.0.0
  */
 export const make = (): Effect.Effect<TxReentrantLock> =>
   Effect.gen(function*() {
@@ -116,7 +118,8 @@ export const make = (): Effect.Effect<TxReentrantLock> =>
  * If the current fiber already holds the write lock, the read lock is granted (reentrancy).
  * Returns the current number of read locks held by this fiber.
  *
- * @example
+ * **Example** (Acquiring a read lock)
+ *
  * ```ts
  * import { Effect, TxReentrantLock } from "effect"
  *
@@ -128,8 +131,8 @@ export const make = (): Effect.Effect<TxReentrantLock> =>
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const acquireRead = (self: TxReentrantLock): Effect.Effect<number> =>
   Effect.withFiber((fiber) =>
@@ -159,7 +162,8 @@ export const acquireRead = (self: TxReentrantLock): Effect.Effect<number> =>
  * If the current fiber holds a read lock, the write lock is granted (upgrade).
  * Returns the current number of write locks held by this fiber.
  *
- * @example
+ * **Example** (Acquiring a write lock)
+ *
  * ```ts
  * import { Effect, TxReentrantLock } from "effect"
  *
@@ -171,8 +175,8 @@ export const acquireRead = (self: TxReentrantLock): Effect.Effect<number> =>
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const acquireWrite = (self: TxReentrantLock): Effect.Effect<number> =>
   Effect.withFiber((fiber) =>
@@ -216,7 +220,8 @@ export const acquireWrite = (self: TxReentrantLock): Effect.Effect<number> =>
  * Releases a read lock held by the current fiber.
  * Returns the remaining number of read locks held by this fiber.
  *
- * @example
+ * **Example** (Releasing a read lock)
+ *
  * ```ts
  * import { Effect, TxReentrantLock } from "effect"
  *
@@ -228,8 +233,8 @@ export const acquireWrite = (self: TxReentrantLock): Effect.Effect<number> =>
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const releaseRead = (self: TxReentrantLock): Effect.Effect<number> =>
   Effect.withFiber((fiber) =>
@@ -254,7 +259,8 @@ export const releaseRead = (self: TxReentrantLock): Effect.Effect<number> =>
  * Releases a write lock held by the current fiber.
  * Returns the remaining number of write locks held by this fiber.
  *
- * @example
+ * **Example** (Releasing a write lock)
+ *
  * ```ts
  * import { Effect, TxReentrantLock } from "effect"
  *
@@ -266,8 +272,8 @@ export const releaseRead = (self: TxReentrantLock): Effect.Effect<number> =>
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const releaseWrite = (self: TxReentrantLock): Effect.Effect<number> =>
   Effect.withFiber((fiber) =>
@@ -291,7 +297,8 @@ export const releaseWrite = (self: TxReentrantLock): Effect.Effect<number> =>
  * Acquires a read lock for the duration of the scope.
  * The lock is automatically released when the scope closes.
  *
- * @example
+ * **Example** (Holding a scoped read lock)
+ *
  * ```ts
  * import { Effect, TxReentrantLock } from "effect"
  *
@@ -308,8 +315,8 @@ export const releaseWrite = (self: TxReentrantLock): Effect.Effect<number> =>
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const readLock = (self: TxReentrantLock): Effect.Effect<number, never, Scope.Scope> =>
   Effect.acquireRelease(
@@ -321,7 +328,8 @@ export const readLock = (self: TxReentrantLock): Effect.Effect<number, never, Sc
  * Acquires a write lock for the duration of the scope.
  * The lock is automatically released when the scope closes.
  *
- * @example
+ * **Example** (Holding a scoped write lock)
+ *
  * ```ts
  * import { Effect, TxReentrantLock } from "effect"
  *
@@ -338,8 +346,8 @@ export const readLock = (self: TxReentrantLock): Effect.Effect<number, never, Sc
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const writeLock = (self: TxReentrantLock): Effect.Effect<number, never, Scope.Scope> =>
   Effect.acquireRelease(
@@ -351,7 +359,8 @@ export const writeLock = (self: TxReentrantLock): Effect.Effect<number, never, S
  * Runs the provided effect while holding a read lock. The lock is automatically
  * released after the effect completes, fails, or is interrupted.
  *
- * @example
+ * **Example** (Running an effect with a read lock)
+ *
  * ```ts
  * import { Effect, TxReentrantLock } from "effect"
  *
@@ -365,15 +374,16 @@ export const writeLock = (self: TxReentrantLock): Effect.Effect<number, never, S
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const withReadLock: {
   /**
    * Runs the provided effect while holding a read lock. The lock is automatically
    * released after the effect completes, fails, or is interrupted.
    *
-   * @example
+   * **Example** (Running an effect with a read lock)
+   *
    * ```ts
    * import { Effect, TxReentrantLock } from "effect"
    *
@@ -387,15 +397,16 @@ export const withReadLock: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category mutations
+   * @since 4.0.0
    */
   <A, E, R>(effect: Effect.Effect<A, E, R>): (self: TxReentrantLock) => Effect.Effect<A, E, R>
   /**
    * Runs the provided effect while holding a read lock. The lock is automatically
    * released after the effect completes, fails, or is interrupted.
    *
-   * @example
+   * **Example** (Running an effect with a read lock)
+   *
    * ```ts
    * import { Effect, TxReentrantLock } from "effect"
    *
@@ -409,8 +420,8 @@ export const withReadLock: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category mutations
+   * @since 4.0.0
    */
   <A, E, R>(self: TxReentrantLock, effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R>
 } = ((...args: Array<any>) => {
@@ -435,7 +446,8 @@ export const withReadLock: {
  * Runs the provided effect while holding a write lock. The lock is automatically
  * released after the effect completes, fails, or is interrupted.
  *
- * @example
+ * **Example** (Running an effect with a write lock)
+ *
  * ```ts
  * import { Effect, TxReentrantLock } from "effect"
  *
@@ -449,15 +461,16 @@ export const withReadLock: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const withWriteLock: {
   /**
    * Runs the provided effect while holding a write lock. The lock is automatically
    * released after the effect completes, fails, or is interrupted.
    *
-   * @example
+   * **Example** (Running an effect with a write lock)
+   *
    * ```ts
    * import { Effect, TxReentrantLock } from "effect"
    *
@@ -471,15 +484,16 @@ export const withWriteLock: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category mutations
+   * @since 4.0.0
    */
   <A, E, R>(effect: Effect.Effect<A, E, R>): (self: TxReentrantLock) => Effect.Effect<A, E, R>
   /**
    * Runs the provided effect while holding a write lock. The lock is automatically
    * released after the effect completes, fails, or is interrupted.
    *
-   * @example
+   * **Example** (Running an effect with a write lock)
+   *
    * ```ts
    * import { Effect, TxReentrantLock } from "effect"
    *
@@ -493,8 +507,8 @@ export const withWriteLock: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category mutations
+   * @since 4.0.0
    */
   <A, E, R>(self: TxReentrantLock, effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R>
 } = ((...args: Array<any>) => {
@@ -518,7 +532,8 @@ export const withWriteLock: {
 /**
  * Alias for `withWriteLock`. Runs the provided effect while holding a write lock.
  *
- * @example
+ * **Example** (Running an effect with exclusive access)
+ *
  * ```ts
  * import { Effect, TxReentrantLock } from "effect"
  *
@@ -532,14 +547,15 @@ export const withWriteLock: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category mutations
+ * @since 4.0.0
  */
 export const withLock: {
   /**
    * Alias for `withWriteLock`. Runs the provided effect while holding a write lock.
    *
-   * @example
+   * **Example** (Running an effect with exclusive access)
+   *
    * ```ts
    * import { Effect, TxReentrantLock } from "effect"
    *
@@ -553,14 +569,15 @@ export const withLock: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category mutations
+   * @since 4.0.0
    */
   <A, E, R>(effect: Effect.Effect<A, E, R>): (self: TxReentrantLock) => Effect.Effect<A, E, R>
   /**
    * Alias for `withWriteLock`. Runs the provided effect while holding a write lock.
    *
-   * @example
+   * **Example** (Running an effect with exclusive access)
+   *
    * ```ts
    * import { Effect, TxReentrantLock } from "effect"
    *
@@ -574,8 +591,8 @@ export const withLock: {
    * })
    * ```
    *
-   * @since 4.0.0
    * @category mutations
+   * @since 4.0.0
    */
   <A, E, R>(self: TxReentrantLock, effect: Effect.Effect<A, E, R>): Effect.Effect<A, E, R>
 } = withWriteLock
@@ -587,7 +604,8 @@ export const withLock: {
 /**
  * Returns the total number of read locks held across all fibers.
  *
- * @example
+ * **Example** (Counting read locks)
+ *
  * ```ts
  * import { Effect, TxReentrantLock } from "effect"
  *
@@ -600,8 +618,8 @@ export const withLock: {
  * })
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const readLocks = (self: TxReentrantLock): Effect.Effect<number> =>
   Effect.gen(function*() {
@@ -616,7 +634,8 @@ export const readLocks = (self: TxReentrantLock): Effect.Effect<number> =>
 /**
  * Returns the number of write locks held (0 or the reentrant count).
  *
- * @example
+ * **Example** (Counting write locks)
+ *
  * ```ts
  * import { Effect, TxReentrantLock } from "effect"
  *
@@ -627,8 +646,8 @@ export const readLocks = (self: TxReentrantLock): Effect.Effect<number> =>
  * })
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const writeLocks = (self: TxReentrantLock): Effect.Effect<number> =>
   Effect.gen(function*() {
@@ -639,7 +658,8 @@ export const writeLocks = (self: TxReentrantLock): Effect.Effect<number> =>
 /**
  * Checks if the lock is held by any fiber (read or write).
  *
- * @example
+ * **Example** (Checking whether a lock is held)
+ *
  * ```ts
  * import { Effect, TxReentrantLock } from "effect"
  *
@@ -650,8 +670,8 @@ export const writeLocks = (self: TxReentrantLock): Effect.Effect<number> =>
  * })
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const locked = (self: TxReentrantLock): Effect.Effect<boolean> =>
   Effect.gen(function*() {
@@ -662,7 +682,8 @@ export const locked = (self: TxReentrantLock): Effect.Effect<boolean> =>
 /**
  * Checks if any fiber holds a read lock.
  *
- * @example
+ * **Example** (Checking whether a read lock is held)
+ *
  * ```ts
  * import { Effect, TxReentrantLock } from "effect"
  *
@@ -673,8 +694,8 @@ export const locked = (self: TxReentrantLock): Effect.Effect<boolean> =>
  * })
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const readLocked = (self: TxReentrantLock): Effect.Effect<boolean> =>
   Effect.gen(function*() {
@@ -685,7 +706,8 @@ export const readLocked = (self: TxReentrantLock): Effect.Effect<boolean> =>
 /**
  * Checks if any fiber holds a write lock.
  *
- * @example
+ * **Example** (Checking whether a write lock is held)
+ *
  * ```ts
  * import { Effect, TxReentrantLock } from "effect"
  *
@@ -696,8 +718,8 @@ export const readLocked = (self: TxReentrantLock): Effect.Effect<boolean> =>
  * })
  * ```
  *
- * @since 4.0.0
  * @category getters
+ * @since 4.0.0
  */
 export const writeLocked = (self: TxReentrantLock): Effect.Effect<boolean> =>
   Effect.gen(function*() {
@@ -712,7 +734,8 @@ export const writeLocked = (self: TxReentrantLock): Effect.Effect<boolean> =>
 /**
  * Checks if the given value is a TxReentrantLock.
  *
- * @example
+ * **Example** (Checking for TxReentrantLock values)
+ *
  * ```ts
  * import { TxReentrantLock } from "effect"
  *
@@ -723,7 +746,7 @@ export const writeLocked = (self: TxReentrantLock): Effect.Effect<boolean> =>
  * }
  * ```
  *
- * @since 4.0.0
  * @category guards
+ * @since 4.0.0
  */
 export const isTxReentrantLock = (u: unknown): u is TxReentrantLock => hasProperty(u, TypeId)

package/src/TxRef.ts

@@ -24,9 +24,8 @@ const TypeId = "~effect/transactions/TxRef"
  * transaction explicitely calls to `Effect.txRetry` and any of the accessed TxRef values
  * change.
  *
- * @since 4.0.0
- * @category Models
- * @example
+ * **Example** (Using a transactional reference)
+ *
  * ```ts
  * import { Effect, TxRef } from "effect"
  *
@@ -44,6 +43,9 @@ const TypeId = "~effect/transactions/TxRef"
  *   console.log(final) // 1
  * })
  * ```
+ *
+ * @category Models
+ * @since 4.0.0
  */
 export interface TxRef<in out A> extends Pipeable {
   readonly [TypeId]: typeof TypeId
@@ -56,9 +58,8 @@ export interface TxRef<in out A> extends Pipeable {
 /**
  * Creates a new `TxRef` with the specified initial value.
  *
- * @since 4.0.0
- * @category Constructors
- * @example
+ * **Example** (Creating transactional references)
+ *
  * ```ts
  * import { Effect, TxRef } from "effect"
  *
@@ -77,15 +78,20 @@ export interface TxRef<in out A> extends Pipeable {
  *   console.log(yield* TxRef.get(name)) // "Bob"
  * })
  * ```
+ *
+ * @category Constructors
+ * @since 4.0.0
  */
 export const make = <A>(initial: A) => Effect.sync(() => makeUnsafe(initial))
 
 /**
- * Creates a new `TxRef` with the specified initial value.
+ * Synchronously creates a new `TxRef` with the specified initial value.
+ *
+ * Prefer `make` in Effect code so allocation stays inside the Effect workflow.
+ * Use `makeUnsafe` only when a `TxRef` must be constructed outside an effect.
+ *
+ * **Example** (Creating transactional references unsafely)
  *
- * @since 4.0.0
- * @category Constructors
- * @example
  * ```ts
  * import { TxRef } from "effect"
  *
@@ -97,6 +103,9 @@ export const make = <A>(initial: A) => Effect.sync(() => makeUnsafe(initial))
  * console.log(counter.value) // 0
  * console.log(config.value) // { timeout: 5000, retries: 3 }
  * ```
+ *
+ * @category Constructors
+ * @since 4.0.0
  */
 export const makeUnsafe = <A>(initial: A): TxRef<A> => ({
   [TypeId]: TypeId,
@@ -111,9 +120,8 @@ export const makeUnsafe = <A>(initial: A): TxRef<A> => ({
 /**
  * Modifies the value of the `TxRef` using the provided function.
  *
- * @since 4.0.0
- * @category Combinators
- * @example
+ * **Example** (Modifying transactional references)
+ *
  * ```ts
  * import { Effect, TxRef } from "effect"
  *
@@ -127,14 +135,16 @@ export const makeUnsafe = <A>(initial: A): TxRef<A> => ({
  *   console.log(yield* TxRef.get(counter)) // 1 (the new value: current + 1)
  * })
  * ```
+ *
+ * @category Combinators
+ * @since 4.0.0
  */
 export const modify: {
   /**
    * Modifies the value of the `TxRef` using the provided function.
    *
-   * @since 4.0.0
-   * @category Combinators
-   * @example
+   * **Example** (Modifying transactional references)
+   *
    * ```ts
    * import { Effect, TxRef } from "effect"
    *
@@ -148,14 +158,16 @@ export const modify: {
    *   console.log(yield* TxRef.get(counter)) // 1 (the new value: current + 1)
    * })
    * ```
+   *
+   * @category Combinators
+   * @since 4.0.0
    */
   <A, R>(f: (current: NoInfer<A>) => [returnValue: R, newValue: A]): (self: TxRef<A>) => Effect.Effect<R>
   /**
    * Modifies the value of the `TxRef` using the provided function.
    *
-   * @since 4.0.0
-   * @category Combinators
-   * @example
+   * **Example** (Modifying transactional references)
+   *
    * ```ts
    * import { Effect, TxRef } from "effect"
    *
@@ -169,6 +181,9 @@ export const modify: {
    *   console.log(yield* TxRef.get(counter)) // 1 (the new value: current + 1)
    * })
    * ```
+   *
+   * @category Combinators
+   * @since 4.0.0
    */
   <A, R>(self: TxRef<A>, f: (current: A) => [returnValue: R, newValue: A]): Effect.Effect<R>
 } = dual(2, <A, R>(
@@ -193,9 +208,8 @@ export const modify: {
 /**
  * Updates the value of the `TxRef` using the provided function.
  *
- * @since 4.0.0
- * @category Combinators
- * @example
+ * **Example** (Updating transactional references)
+ *
  * ```ts
  * import { Effect, TxRef } from "effect"
  *
@@ -210,14 +224,16 @@ export const modify: {
  *   console.log(yield* TxRef.get(counter)) // 20
  * })
  * ```
+ *
+ * @category Combinators
+ * @since 4.0.0
  */
 export const update: {
   /**
    * Updates the value of the `TxRef` using the provided function.
    *
-   * @since 4.0.0
-   * @category Combinators
-   * @example
+   * **Example** (Updating transactional references)
+   *
    * ```ts
    * import { Effect, TxRef } from "effect"
    *
@@ -232,14 +248,16 @@ export const update: {
    *   console.log(yield* TxRef.get(counter)) // 20
    * })
    * ```
+   *
+   * @category Combinators
+   * @since 4.0.0
    */
   <A>(f: (current: NoInfer<A>) => A): (self: TxRef<A>) => Effect.Effect<void>
   /**
    * Updates the value of the `TxRef` using the provided function.
    *
-   * @since 4.0.0
-   * @category Combinators
-   * @example
+   * **Example** (Updating transactional references)
+   *
    * ```ts
    * import { Effect, TxRef } from "effect"
    *
@@ -254,6 +272,9 @@ export const update: {
    *   console.log(yield* TxRef.get(counter)) // 20
    * })
    * ```
+   *
+   * @category Combinators
+   * @since 4.0.0
    */
   <A>(self: TxRef<A>, f: (current: A) => A): Effect.Effect<void>
 } = dual(2, <A>(
@@ -264,9 +285,8 @@ export const update: {
 /**
  * Reads the current value of the `TxRef`.
  *
- * @since 4.0.0
- * @category Combinators
- * @example
+ * **Example** (Reading transactional references)
+ *
  * ```ts
  * import { Effect, TxRef } from "effect"
  *
@@ -281,15 +301,17 @@ export const update: {
  *   console.log(value) // 42
  * })
  * ```
+ *
+ * @category Combinators
+ * @since 4.0.0
  */
 export const get = <A>(self: TxRef<A>): Effect.Effect<A> => modify(self, (current) => [current, current])
 
 /**
  * Sets the value of the `TxRef`.
  *
- * @since 4.0.0
- * @category Combinators
- * @example
+ * **Example** (Setting transactional references)
+ *
  * ```ts
  * import { Effect, TxRef } from "effect"
  *
@@ -304,14 +326,16 @@ export const get = <A>(self: TxRef<A>): Effect.Effect<A> => modify(self, (curren
  *   console.log(yield* TxRef.get(counter)) // 100
  * })
  * ```
+ *
+ * @category Combinators
+ * @since 4.0.0
  */
 export const set: {
   /**
    * Sets the value of the `TxRef`.
    *
-   * @since 4.0.0
-   * @category Combinators
-   * @example
+   * **Example** (Setting transactional references)
+   *
    * ```ts
    * import { Effect, TxRef } from "effect"
    *
@@ -326,14 +350,16 @@ export const set: {
    *   console.log(yield* TxRef.get(counter)) // 100
    * })
    * ```
+   *
+   * @category Combinators
+   * @since 4.0.0
    */
   <A>(value: A): (self: TxRef<A>) => Effect.Effect<void>
   /**
    * Sets the value of the `TxRef`.
    *
-   * @since 4.0.0
-   * @category Combinators
-   * @example
+   * **Example** (Setting transactional references)
+   *
    * ```ts
    * import { Effect, TxRef } from "effect"
    *
@@ -348,6 +374,9 @@ export const set: {
    *   console.log(yield* TxRef.get(counter)) // 100
    * })
    * ```
+   *
+   * @category Combinators
+   * @since 4.0.0
    */
   <A>(self: TxRef<A>, value: A): Effect.Effect<void>
 } = dual(2, <A>(