effect 4.0.0-beta.77 → 4.0.0-beta.79

package/src/Pool.ts

@@ -1,47 +1,11 @@
 /**
- * Scoped resource pools for sharing expensive or limited resources across
- * fibers.
- *
- * The `Pool` module acquires values with a scoped effect, lets fibers borrow
- * them with {@link get}, and releases all acquired values when the pool scope
- * closes. Pools are useful for database connections, clients, buffers, or other
- * resources where acquisition is expensive and total concurrency must be
- * bounded.
- *
- * **Mental model**
- *
- * - A pool owns resources between its configured minimum and maximum size.
- * - Each item is acquired in the pool scope and finalized when removed or when
- *   the pool shuts down.
- * - {@link get} checks out an item in the caller's scope; leaving that scope
- *   returns the item to the pool.
- * - `concurrency` is per item, so a pool with size 4 and concurrency 2 can
- *   serve up to 8 simultaneous checkouts.
- * - `targetUtilization` controls when the resize strategy grows or shrinks the pool.
- *
- * **Common tasks**
- *
- * - Create a fixed-size pool with {@link make}.
- * - Create an elastic pool that expires idle items with {@link makeWithTTL}.
- * - Use {@link makeWithStrategy} for custom resize or reclamation behavior.
- * - Borrow items safely in scoped effects with {@link get}.
- * - Replace a broken item lazily with {@link invalidate}.
+ * Shares scoped resources across fibers.
  *
- * **Gotchas**
- *
- * - Pool construction requires `Scope`; closing that scope shuts down the pool.
- * - A checked-out item is returned only when the checkout scope closes, so do
- *   not leak scoped effects that hold pool items indefinitely.
- * - Acquisition failures fail the {@link get} effect for that checkout; later
- *   checkouts can try acquisition again.
- * - Invalidated items are finalized when they are no longer checked out, then
- *   replacement happens on demand.
- *
- * **See also**
- *
- * - {@link Pool} for the pool value.
- * - {@link get} for checked-out access.
- * - {@link invalidate} for removing a specific item.
+ * A `Pool<A, E>` acquires resource-backed values with a scoped effect, lets
+ * fibers borrow them with `get`, can invalidate broken values, and releases all
+ * acquired values when the pool scope closes. This module includes fixed-size
+ * pools, pools that resize with a time-to-live policy, custom strategy pools,
+ * per-item concurrency limits, and runtime state types used by pool strategies.
  *
  * @since 2.0.0
  */

package/src/Predicate.ts

@@ -1,66 +1,11 @@
 /**
- * Predicates are small boolean functions for checking values at runtime.
- * Refinements are predicates that also narrow TypeScript types after a
- * successful check. This module provides primitive guards for common JavaScript
- * values and combinators for building larger checks from smaller ones.
- *
- * **Mental model**
- *
- * - A `Predicate<A>` is `(a: A) => boolean`
- * - A `Refinement<A, B>` is `(a: A) => a is B`; when it returns `true`,
- *   TypeScript can treat the value as `B`
- * - Guards such as {@link isString}, {@link isNumber}, and {@link isObject}
- *   refine `unknown` values into useful runtime types
- * - Combinators such as {@link and}, {@link or}, {@link not}, and {@link xor}
- *   build new predicates while preserving refinement information where possible
- * - {@link Tuple} and {@link Struct} lift element and property predicates to
- *   tuple-like arrays and object shapes
- *
- * **Common tasks**
- *
- * - Check primitive runtime types: {@link isString}, {@link isNumber},
- *   {@link isBoolean}, {@link isBigInt}, {@link isSymbol}
- * - Check object-like values: {@link isObject}, {@link isObjectOrArray},
- *   {@link hasProperty}, {@link isTagged}
- * - Combine predicates: {@link and}, {@link or}, {@link not}, {@link xor}
- * - Reuse a predicate on derived input: {@link mapInput}
- * - Compose refinements that narrow in stages: {@link compose}
- * - Validate tuple or object shapes: {@link Tuple}, {@link Struct}
- *
- * **Gotchas**
- *
- * - Predicates only return `true` or `false`; they do not explain why a value
- *   failed a check
- * - {@link isTruthy} uses JavaScript truthiness, so `0`, `""`, and `false`
- *   are rejected
- * - {@link isObject} excludes arrays; use {@link isObjectOrArray} when arrays
- *   should also pass
- * - {@link isIterable} accepts strings because strings are iterable in
- *   JavaScript
- * - {@link isPromise} and {@link isPromiseLike} are structural checks, not
- *   `instanceof` checks
- * - {@link isTupleOf} and {@link isTupleOfAtLeast} check length only, not
- *   element types
- *
- * **Quickstart**
- *
- * **Example** (Filter by a predicate)
+ * Defines runtime checks for values.
  *
- * ```ts
- * import { Predicate } from "effect"
- *
- * const values: Array<unknown> = ["one", 2, "three", null]
- * const strings = values.filter(Predicate.isString)
- *
- * console.log(strings)
- * // Output: ["one", "three"]
- * ```
- *
- * **See also**
- *
- * - {@link Predicate} for plain boolean checks
- * - {@link Refinement} for checks that narrow types
- * - {@link Struct} and {@link Tuple} for checking compound values
+ * A `Predicate<A>` returns `true` or `false` for an `A`. A
+ * `Refinement<A, B>` is a predicate that also narrows the TypeScript type when
+ * it succeeds. This module includes guards for common JavaScript values,
+ * property and tag checks, tuple and struct checks, boolean combinators, and
+ * helpers for composing predicates and refinements.
  *
  * @since 2.0.0
  */

package/src/PrimaryKey.ts

@@ -4,46 +4,6 @@
  * method at {@link symbol}; consumers can check unknown values with
  * {@link isPrimaryKey} and read the key with {@link value}.
  *
- * **Mental model**
- *
- * - `PrimaryKey` is structural: no base class or registration step is required
- * - The key is produced by a symbol-named method, which avoids collisions with
- *   ordinary object fields
- * - The returned string is expected to be stable for the lifetime of the value
- *   when it is used for maps, caches, or persistence boundaries
- *
- * **Common tasks**
- *
- * - Implement the protocol on a class or object literal with
- *   `[PrimaryKey.symbol]`
- * - Accept unknown input safely by checking {@link isPrimaryKey}
- * - Convert a known `PrimaryKey` to its string identifier with {@link value}
- *
- * **Gotchas**
- *
- * - {@link isPrimaryKey} only checks that the symbol property exists; it does
- *   not call the method or verify the returned string
- * - The module does not enforce global uniqueness. Choose key formats that are
- *   unambiguous for the domain where they are compared
- *
- * **Example** (Implementing a stable key)
- *
- * ```ts
- * import { PrimaryKey } from "effect"
- *
- * class UserId implements PrimaryKey.PrimaryKey {
- *   constructor(readonly id: number) {}
- *
- *   [PrimaryKey.symbol](): string {
- *     return `user:${this.id}`
- *   }
- * }
- *
- * const id = new UserId(42)
- *
- * PrimaryKey.value(id) // "user:42"
- * ```
- *
  * @since 2.0.0
  */
 

package/src/PubSub.ts

@@ -1,60 +1,12 @@
 /**
- * The `PubSub` module provides asynchronous publish-subscribe hubs for
- * broadcasting values to many subscribers. Publishers add messages with
- * {@link publish} or {@link publishAll}; each active {@link Subscription}
- * receives its own copy of every accepted message.
- *
- * Unlike a queue, subscribers do not compete for messages. A published value is
- * retained until all subscribers that were active for that value have taken it
- * or unsubscribed.
- *
- * **Mental model**
- *
- * - A `PubSub<A>` is the shared publish side, and each `Subscription<A>` is an
- *   independent read side
- * - {@link subscribe} is scoped; leaving the scope automatically unsubscribes
- *   the subscription and releases any retained messages for it
- * - {@link bounded} applies back pressure when the buffer is full,
- *   {@link dropping} drops new messages, and {@link sliding} drops old messages
- * - {@link unbounded} removes the capacity limit but can retain an unbounded
- *   number of messages for slow subscribers
- * - The optional replay buffer lets late subscribers first consume recently
- *   published messages
- *
- * **Common tasks**
- *
- * - Create hubs: {@link bounded}, {@link dropping}, {@link sliding},
- *   {@link unbounded}
- * - Publish values: {@link publish}, {@link publishAll}
- * - Subscribe and consume: {@link subscribe}, {@link take}, {@link takeAll},
- *   {@link takeUpTo}, {@link takeBetween}
- * - Inspect lifecycle and capacity: {@link capacity}, {@link size},
- *   {@link isFull}, {@link isEmpty}, {@link isShutdown}
- * - Stop a hub: {@link shutdown}, {@link awaitShutdown}
- *
- * **Example** (Publishing to one scoped subscriber)
- *
- * ```ts
- * import { Effect, PubSub } from "effect"
- *
- * const program = Effect.scoped(
- *   Effect.gen(function*() {
- *     const pubsub = yield* PubSub.bounded<string>(16)
- *     const subscription = yield* PubSub.subscribe(pubsub)
- *
- *     yield* PubSub.publish(pubsub, "ready")
- *
- *     return yield* PubSub.take(subscription)
- *   })
- * )
- * ```
- *
- * **Gotchas**
- *
- * - `bounded` can suspend publishers when a subscriber is slow
- * - `dropping` and `sliding` can lose messages by design
- * - Replay buffers are for late subscribers; they do not make the hub a
- *   permanent event log
+ * Broadcasts values from publishers to many subscribers.
+ *
+ * Publishers add messages with `publish` or `publishAll`, and each active
+ * `Subscription` receives its own copy of every accepted message. Unlike a
+ * queue, subscribers do not compete for messages. This module includes bounded,
+ * dropping, sliding, and unbounded hubs, optional replay buffers for late
+ * subscribers, message-taking helpers, capacity and shutdown operations, and
+ * low-level types for custom hub strategies.
  *
  * @since 2.0.0
  */

package/src/Pull.ts

@@ -1,29 +1,12 @@
 /**
- * The `Pull` module provides the low-level pull-step abstraction used by
- * stream-like consumers. A `Pull<A, E, Done, R>` is an `Effect` that can
- * produce one value of type `A`, fail with an ordinary error `E`, or signal
- * end-of-input with a `Cause.Done<Done>` value.
- *
- * **Mental model**
- *
- * - `Pull` is an `Effect` with a distinguished completion signal in the error channel
- * - ordinary failures and completion are both represented by `Cause`, but can be separated with the helpers in this module
- * - the `Done` value can carry leftover state or a final value needed by a downstream consumer
- * - `Pull` is useful when repeatedly evaluating an effect until it either produces values, fails, or reports that no more input is available
- *
- * **Common tasks**
- *
- * - Extract type parameters from a pull: {@link Success}, {@link Error}, {@link Leftover}, {@link Services}
- * - Detect and filter completion: {@link isDoneCause}, {@link filterDone}, {@link filterNoDone}
- * - Recover from completion while preserving ordinary failures: {@link catchDone}
- * - Convert done causes to successful exits: {@link doneExitFromCause}
- * - Handle all outcomes explicitly: {@link matchEffect}
- *
- * **Gotchas**
- *
- * - `Cause.Done` is not an ordinary failure; use this module's helpers before treating a pull failure as an error
- * - `Done` lives in the error channel, so generic `Effect` error handling can catch it unless you filter it deliberately
- * - `Pull` is a low-level primitive; most user-facing stream workflows should prefer higher-level stream APIs when available
+ * Models one low-level pull step for stream-like consumers.
+ *
+ * A `Pull<A, E, Done, R>` is an `Effect` that can produce one `A`, fail with an
+ * ordinary error `E`, or signal end-of-input with `Cause.Done<Done>`. The
+ * separate done signal lets low-level consumers distinguish normal completion
+ * from failure. This module includes type extractors and helpers for detecting,
+ * filtering, catching, converting, and matching done signals separately from
+ * ordinary failures.
  *
  * @since 4.0.0
  */

package/src/Queue.ts

@@ -1,67 +1,10 @@
 /**
- * The `Queue` module provides asynchronous queues for communicating between
- * fibers. A `Queue<A, E>` accepts values of type `A`, hands each value to one
- * consumer in offer order, and can later complete, fail, interrupt, or shut
- * down through the queue lifecycle.
- *
- * **Mental model**
- *
- * - A queue is a fiber-aware channel with a write side ({@link Enqueue}) and a
- *   read side ({@link Dequeue}).
- * - Producers add values with {@link offer} or {@link offerAll}; consumers
- *   remove values with {@link take}, {@link takeN}, {@link takeBetween}, or
- *   {@link takeAll}.
- * - Unlike publish-subscribe hubs, consumers compete for values; a successful
- *   take removes the value from the queue.
- * - Bounded queues use an overflow strategy: {@link bounded} suspends
- *   producers, {@link dropping} rejects new values, and {@link sliding} drops
- *   old values.
- * - Operations are `Effect` values, so waiting producers and consumers compose
- *   with interruption, scheduling, and structured concurrency.
- *
- * **Common tasks**
- *
- * - Create queues: {@link make}, {@link bounded}, {@link dropping},
- *   {@link sliding}, {@link unbounded}.
- * - Restrict capabilities: {@link asEnqueue}, {@link asDequeue}.
- * - Produce values: {@link offer}, {@link offerAll}.
- * - Consume values: {@link take}, {@link takeN}, {@link takeBetween},
- *   {@link takeAll}, {@link poll}, {@link peek}.
- * - Drain or reset buffered values: {@link collect}, {@link clear}.
- * - Signal lifecycle: {@link end}, {@link fail}, {@link failCause},
- *   {@link interrupt}, {@link shutdown}.
- * - Inspect state: {@link size}, {@link isFull}.
- *
- * **Example** (One producer and one consumer)
+ * Passes values asynchronously between fibers.
  *
- * ```ts
- * import { Effect, Queue } from "effect"
- *
- * const program = Effect.gen(function*() {
- *   const queue = yield* Queue.bounded<string>(16)
- *
- *   yield* Queue.offer(queue, "work")
- *
- *   return yield* Queue.take(queue)
- * })
- * ```
- *
- * **Gotchas**
- *
- * - {@link take} waits when the queue is empty; use {@link poll} when absence
- *   should be represented as an empty `Option`.
- * - {@link dropping} and {@link sliding} queues can lose values by design; use
- *   {@link bounded} when every offered value must be preserved.
- * - Completion and failure are observed by consumers through the queue's error
- *   channel, so include `Cause.Done` in the error type when using {@link end}.
- * - The `Unsafe` variants are synchronous, low-level operations; prefer the
- *   effectful APIs in application code.
- *
- * **See also**
- *
- * - {@link Enqueue} for write-only queue handles.
- * - {@link Dequeue} for read-only queue handles.
- * - {@link Pull} for stream-style completion errors.
+ * A `Queue<A, E>` accepts values, hands each value to one consumer in offer
+ * order, and can complete, fail, interrupt, or shut down. Queues can be bounded
+ * or unbounded, and bounded queues can suspend, drop, or slide values when
+ * producers are faster than consumers.
  *
  * @since 3.8.0
  */

package/src/Random.ts

@@ -1,44 +1,10 @@
 /**
- * Pseudo-random generation through Effect's service context. The module exposes
- * effectful generators for booleans, doubles, safe integers, bounded numbers,
- * shuffling, and deterministic seeded runs.
+ * Provides pseudo-random generation through an Effect service.
  *
- * **Mental model**
- *
- * Randomness is read from the current {@link Random} service instead of a
- * global singleton. That makes random programs reproducible in tests and local
- * simulations with {@link withSeed}, while still allowing applications to
- * replace the service at the edge.
- *
- * **Common tasks**
- *
- * - Draw a floating-point value in `[0, 1)` with {@link next}
- * - Draw an integer with {@link nextInt} or {@link nextIntBetween}
- * - Draw a floating-point value in a custom range with {@link nextBetween}
- * - Randomize an iterable with {@link shuffle}
- * - Run the same random sequence repeatedly with {@link withSeed}
- *
- * **Gotchas**
- *
- * - The default service is not suitable for secrets, session identifiers,
- *   tokens, or other security-sensitive values.
- * - `withSeed` is deterministic by design. A predictable seed does not make
- *   generated values cryptographically secure.
- * - Bounded integer generation rounds bounds before drawing from the range.
- *
- * **Example** (Generating random values)
- *
- * ```ts
- * import { Effect, Random } from "effect"
- *
- * const program = Effect.gen(function*() {
- *   const randomFloat = yield* Random.next
- *   const randomInt = yield* Random.nextInt
- *   const diceRoll = yield* Random.nextIntBetween(1, 6)
- *
- *   return { randomFloat, randomInt, diceRoll }
- * })
- * ```
+ * This module exposes effectful generators for booleans, doubles, safe
+ * integers, bounded numbers, shuffling, and deterministic seeded runs. Because
+ * random generation is a service, tests and applications can replace the
+ * generator used by Effect programs.
  *
  * @since 4.0.0
  */
@@ -639,84 +605,22 @@ function add32(x: number, y: number): number {
   return (msb << 16) | (lsb & 0xffff)
 }
 
+const seedEncoder = new TextEncoder()
+
 /**
- * Convert a UTF-16 strings to UTF-8 encoded 32-bit integers (little-endian).
+ * Convert a string to UTF-8 encoded 32-bit integers (little-endian).
  */
 function toIntArray(seed: string): Array<number> {
-  let c1 = 0 // First UTF-16 code unit
-  let c2 = 0 // Second UTF-16 code unit (for surrogate pairs)
-  let unicode = 0 // Combined unicode code point from surrogate pair
-  const result: Array<number> = [] // Result array of 32-bit integers
-  const buffer: Array<number> = [] // Temporary buffer for the UTF-8 bytes (max 4 bytes)
-  const length = seed.length - 1
-
-  let index = 0
-  while (index < length) {
-    c1 = seed.charCodeAt(index++)
-    c2 = seed.charCodeAt(index + 1)
-
-    // 0x0000 - 0x007f: ASCII, single byte UTF-8: 0xxxxxxxx
-    // Example: 'A' (0x41) -> [0x41]
-    if (c1 < 0x0080) {
-      buffer.push(c1)
-    } //
-    // 0x0080 - 0x07ff: Two byte UTF-8: 110xxxxx 10xxxxxx
-    // Example: '¢' (0xA2) -> [0xC2, 0xA2]
-    else if (c1 < 0x0800) {
-      // First byte: upper 5 bits + 110xxxxx marker
-      // 0xA2 >>> 6 (0x02), & 0x1f = 0x02, | 0xc0 = 0xC2
-      buffer.push(((c1 >>> 6) & 0x1f) | 0xc0)
-      // Second byte: lower 6 bits + 10xxxxxxxx marker
-      // 0xA2 & 0x3f = 0x22, | 0x80 = 0xA2
-      buffer.push(((c1 >>> 0) & 0x3f) | 0x80)
-    } //
-    // 0x0800 - 0xffff (non-surrogate): Three byte UTF-8: 1110xxxx 10xxxxxx 10xxxxxx
-    // Example: '€' (0x20AC) -> [0xE2, 0x82, 0xAC]
-    else if ((c1 & 0xf800) != 0xd800) {
-      // First byte: top 4 bits + 1110xxxx marker
-      // 0x20AC >>> 12 = 0x02, & 0x0f = 0x02, | 0xe0 = 0xE2
-      buffer.push(((c1 >>> 12) & 0x0f) | 0xe0)
-      // Second byte: middle 6 bits + 10xxxxxx marker
-      // 0x20AC >>> 6 = 0x82, & 0x3f = 0x02, | 0x80 = 0x82
-      buffer.push(((c1 >>> 6) & 0x3f) | 0x80)
-      // Third byte: lower 6 bits + 10xxxxxx marker
-      // 0x20AC & 0x3f = 0x2C, | 0x80 = 0xAC
-      buffer.push(((c1 >>> 0) & 0x3f) | 0x80)
-    } //
-    // 0xd800 - 0xdfff: Surrogate pairs, four byte UTF-8: 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx
-    // Example: '𐍈' (U+10348, surrogates 0xD800 0xDF48) -> [0xF0, 0x90, 0x8D, 0x88]
-    else if (((c1 & 0xfc00) == 0xd800) && ((c2 & 0xfc00) == 0xdc00)) {
-      // Decode surrogate pair: combine 10 bits from each + 0x10000
-      // ((0xDF48 & 0x3f) | ((0xD800 & 0x3f) << 10)) + 0x10000 = 0x10348
-      unicode = ((c2 & 0x3f) | ((c1 & 0x3f) << 10)) + 0x10000
-      // First byte: top 3 bits + 11110xxx marker
-      // 0x10348 >>> 18 = 0x00, & 0x07 = 0x00, | 0xf0 = 0xF0
-      buffer.push(((unicode >>> 18) & 0x07) | 0xf0)
-      // Second byte: next 6 bits + 10xxxxxx marker
-      // 0x10348 >>> 12 = 0x10, & 0x3f = 0x10, | 0x80 = 0x90
-      buffer.push(((unicode >>> 12) & 0x3f) | 0x80)
-      // Third byte: next 6 bits + 10xxxxxx marker
-      // 0x10348 >>> 6 = 0x40D, & 0x3f = 0x0D, | 0x80 = 0x8D
-      buffer.push(((unicode >>> 6) & 0x3f) | 0x80)
-      // Fourth byte: lower 6 bits + 10xxxxxx marker
-      // 0x10348 & 0x3f = 0x08, | 0x80 = 0x88
-      buffer.push(((unicode >>> 0) & 0x3f) | 0x80)
-      index++ // Skip second surrogate
-    } else {
-      // invalid char
-    }
-
-    // Pack 4 UTF-8 bytes -> 32-bit int (little-endian)
-    // Example: [0xE2, 0x82, 0xAC, 0x00] -> 0x00ACE2E2
-    if (buffer.length > 3) {
-      result.push(
-        (buffer.shift()! << 0) | // Byte 0 at bits 0-7:   0xE2 << 0  = 0x000000E2
-          (buffer.shift()! << 8) | // Byte 1 at bits 8-15:  0x82 << 8  = 0x00008200
-          (buffer.shift()! << 16) | // Byte 2 at bits 16-23: 0xAC << 16 = 0x00AC0000
-          (buffer.shift()! << 24) // Byte 3 at bits 24-31: 0x00 << 24 = 0x00000000
-      )
-      // Result: 0x00AC82E2
-    }
+  const bytes = seedEncoder.encode(seed)
+  const result: Array<number> = []
+
+  for (let index = 0; index < bytes.length; index += 4) {
+    result.push(
+      ((bytes[index] ?? 0) << 0) |
+        ((bytes[index + 1] ?? 0) << 8) |
+        ((bytes[index + 2] ?? 0) << 16) |
+        ((bytes[index + 3] ?? 0) << 24)
+    )
   }
 
   return result

package/src/RcMap.ts

@@ -1,21 +1,13 @@
 /**
- * The `RcMap` module provides a scoped, reference-counted map for sharing
- * resources by key. It is useful when many fibers may request the same
- * resource, such as a connection, client, session, or cached handle, and the
- * resource should be acquired once, reused while it has active references, and
- * released automatically when it is no longer needed.
- *
- * Each key is resolved with a user-provided lookup effect on first access via
- * {@link get}. Further accesses to the same key share the in-flight or acquired
- * resource and increment its reference count for the caller's current
- * `Scope`. When those scopes close, references are released; resources can be
- * closed immediately, kept alive for an idle time-to-live, invalidated
- * explicitly, or bounded by a maximum capacity.
- *
- * `RcMap` is designed for Effect resource lifecycles rather than general
- * mutable caching. The map itself is scoped, lookups require a `Scope`, and
- * complex keys should provide `Equal` / `Hash` behavior when they need
- * value-based lookup semantics.
+ * Shares scoped resources by key and releases them when no one is using them.
+ *
+ * An `RcMap` runs a lookup effect the first time a key is requested, shares the
+ * in-progress or acquired resource with other callers for the same key, and
+ * tracks each caller through its current `Scope`. When the last scope for a key
+ * closes, the resource can be released, kept alive for an idle time, or removed
+ * by capacity limits or explicit invalidation. It is meant for resource
+ * lifecycles such as clients, sessions, and connections, not as a general
+ * mutable cache.
  *
  * @since 3.5.0
  */

package/src/RcRef.ts

@@ -1,40 +1,10 @@
 /**
- * The `RcRef` module provides a reference-counted handle for sharing one
- * scoped resource across many scoped users. An `RcRef<A, E>` is lazy: it
- * acquires the resource the first time {@link get} needs it, reuses that value
- * while it is borrowed or kept idle, and finalizes it when the final borrowing
- * scope closes unless an idle timeout keeps it available.
- *
- * **Mental model**
- *
- * - {@link make} stores the acquisition effect and captures the surrounding
- *   `Scope`
- * - {@link get} borrows the current resource for the caller's scope,
- *   acquiring it on demand
- * - Each borrowing scope increments the reference count and installs a release
- *   finalizer
- * - When the count reaches zero, the resource is finalized immediately or kept
- *   for `idleTimeToLive`
- * - {@link invalidate} stops reusing the current value; active borrowers keep
- *   it until their scopes close
- *
- * **Common tasks**
- *
- * - Lazily share a connection, client, cache, worker, or other scoped resource
- *   with {@link make}
- * - Borrow the shared resource inside a scoped operation with {@link get}
- * - Force the next borrow to reacquire after a stale or broken resource with
- *   {@link invalidate}
- *
- * **Gotchas**
- *
- * - {@link get} requires `Scope`; use `Effect.scoped` or run it inside an
- *   existing scoped workflow
- * - Invalidation does not revoke values already returned to active scopes
- * - With a finite `idleTimeToLive`, a zero-reference resource remains
- *   available until the timeout expires
- * - With an infinite `idleTimeToLive`, an idle resource remains until
- *   invalidated or the owning scope closes
+ * Reference-counted handles for sharing one scoped resource across many scoped
+ * users. An `RcRef<A, E>` acquires the resource lazily the first time `get`
+ * needs it, reuses that value while it is borrowed or kept idle, and finalizes
+ * it when the final borrowing scope closes unless an idle timeout keeps it
+ * available. The module also provides `invalidate` for forcing the next `get`
+ * to acquire a fresh resource.
  *
  * @since 3.5.0
  */