effect 4.0.7 → 4.1.1

package/src/Pool.ts

@@ -10,7 +10,6 @@
  * @stability stable
  * @since 2.0.0
  */
-import type * as Cause from "./Cause.ts"
 import { Clock } from "./Clock.ts"
 import * as Context from "./Context.ts"
 import * as Duration from "./Duration.ts"
@@ -23,7 +22,6 @@ import * as internal from "./internal/effect.ts"
 import { type Pipeable, pipeArguments } from "./Pipeable.ts"
 import { hasProperty } from "./Predicate.ts"
 import * as Queue from "./Queue.ts"
-import { UnhandledLogLevel } from "./References.ts"
 import * as Scope from "./Scope.ts"
 import * as Semaphore from "./Semaphore.ts"
 
@@ -96,6 +94,29 @@ export interface Config<A, E> {
   readonly targetUtilization: number
 }
 
+/**
+ * A point-in-time count of a pool's items and waiting borrowers.
+ *
+ * **Details**
+ *
+ * `idle` and `used` count acquired items, not borrowers, so an item shared by
+ * several borrowers counts once. `pending` counts borrowers waiting for an
+ * item. `min` and `max` are the configured size bounds.
+ *
+ * @see {@link stats} for reading a snapshot
+ *
+ * @stability unstable
+ * @category models
+ * @since 4.0.0
+ */
+export interface Stats {
+  readonly idle: number
+  readonly used: number
+  readonly pending: number
+  readonly min: number
+  readonly max: number
+}
+
 /**
  * Mutable runtime state maintained by a `Pool`.
  *
@@ -357,7 +378,8 @@ export const makeWithStrategy = <A, E, R>(options: {
 }): Effect.Effect<Pool<A, E>, never, Scope.Scope | R> =>
   Effect.uninterruptibleMask(Effect.fnUntraced(function*(restore) {
     const services = yield* Effect.context<R | Scope.Scope>()
-    const scope = Context.get(services, Scope.Scope)
+    // A child scope keeps the pool usable in later finalizers of the outer scope
+    const scope = Scope.forkUnsafe(Context.get(services, Scope.Scope))
     const acquire = Effect.updateContext(
       options.acquire,
       (input) => Context.merge(services, input)
@@ -1026,6 +1048,52 @@ export const reserve: {
     ))
 )
 
+/**
+ * Returns a snapshot of how many items are idle or in use and how many
+ * borrowers are waiting.
+ *
+ * **When to use**
+ *
+ * Use to sample pool occupancy for metrics, such as connection counts for a
+ * database driver.
+ *
+ * **Details**
+ *
+ * - Only successfully acquired items are counted. Items still being acquired
+ *   and failed acquisitions are not.
+ * - An item is used while it has a borrower or a reservation, otherwise idle.
+ * - An invalidated item counts as used until its last borrower returns it.
+ *
+ * **Gotchas**
+ *
+ * The replacement for an invalidated item is acquired while the old one is
+ * still borrowed, so `idle + used` can briefly exceed `max`. A borrower that
+ * has been woken but has not yet taken its item is not counted as pending.
+ *
+ * @see {@link Stats} for the snapshot fields
+ *
+ * @stability unstable
+ * @category getters
+ * @since 4.0.0
+ */
+export const stats = <A, E>(self: Pool<A, E>): Effect.Effect<Stats> =>
+  Effect.sync(() => {
+    let idle = 0
+    let used = 0
+    for (const item of self.state.items) {
+      if (item.exit._tag !== "Success") continue
+      if (item.refCount > 0 || reservations.has(item)) used++
+      else idle++
+    }
+    return {
+      idle,
+      used,
+      pending: self.state.waiters.size,
+      min: self.config.minSize,
+      max: self.config.maxSize
+    }
+  })
+
 const invalidatePoolItem = <A, E>(self: Pool<A, E>, poolItem: PoolItem<A, E>): Effect.Effect<void> =>
   Effect.suspend(() => {
     if (!self.state.items.has(poolItem)) {
@@ -1111,7 +1179,10 @@ const allocate = <A, E>(self: Pool<A, E>): Effect.Effect<PoolItem<A, E>> =>
       const use = Effect.flatMap(Effect.exit(impl[Acquire]), (exit) => {
         const item: PoolItem<A, E> = {
           exit,
-          finalizer: Effect.catchCause(Scope.close(scope, exit), reportUnhandledError),
+          finalizer: Effect.ignoreCause(Scope.close(scope, exit), {
+            log: "Unhandled",
+            message: "Unhandled error in pool finalizer"
+          }),
           refCount: 0,
           idleSince: impl[PoolClock].currentTimeMillisUnsafe(),
           disableReclaim: false,
@@ -1235,15 +1306,3 @@ const strategyUsageTTL = Effect.fnUntraced(function*<A, E>(ttl: Duration.Input)
     reclaim: (_) => Effect.undefined
   })
 })
-
-const reportUnhandledError = <E>(cause: Cause.Cause<E>) =>
-  Effect.withFiber<void>((fiber) => {
-    const unhandledLogLevel = fiber.getRef(UnhandledLogLevel)
-    if (unhandledLogLevel) {
-      return Effect.logWithLevel(unhandledLogLevel)(
-        "Unhandled error in pool finalizer",
-        cause
-      )
-    }
-    return Effect.void
-  })

package/src/Random.ts

@@ -12,6 +12,7 @@
 import type * as Arr from "./Array.ts"
 import * as Cause from "./Cause.ts"
 import type * as Context from "./Context.ts"
+import * as SecureRandom from "./crypto/SecureRandom.ts"
 import * as Effect from "./Effect.ts"
 import { dual } from "./Function.ts"
 import * as random from "./internal/random.ts"
@@ -419,9 +420,8 @@ function ISAAC_CSPRNG(userSeed?: string | number) {
   seed(internalSeed)
 
   function getInitialSeed() {
-    const uint32a = new Uint32Array(2)
-    crypto.getRandomValues(uint32a)
-    return uint32a[0] + uint32a[1]
+    const view = new DataView(SecureRandom.randomBytesUnsafe(8).buffer)
+    return view.getUint32(0) + view.getUint32(4)
   }
 
   function reset() {

package/src/RcMap.ts

@@ -771,6 +771,7 @@ const removeInterrupted = <K, A, E>(
   // Borrowers close the entry on release; an idle entry has none left.
   if (entry.refCount > 0) return
   closeEntry(entry).pipe(
+    Effect.ignoreCause({ log: "Unhandled", message: "Unhandled error in RcMap finalizer" }),
     Effect.runForkWith(context),
     Fiber.runIn(self.scope)
   )
@@ -812,7 +813,10 @@ const release = <K, A, E>(self: RcMap<K, A, E>, key: K, entry: State.Entry<A, E>
         const o = MutableHashMap.get(self.state.map, key)
         if (o._tag === "None" || o.value !== entry) return Effect.void
         MutableHashMap.remove(self.state.map, key)
-        return Scope.close(entry.scope, Exit.void)
+        return Effect.ignoreCause(Scope.close(entry.scope, Exit.void), {
+          log: "Unhandled",
+          message: "Unhandled error in RcMap finalizer"
+        })
       }
       return Effect.flatMap(restore(clock.sleep(Duration.millis(remaining))), () => loop(restore))
     }).pipe(

package/src/Schedule.ts

@@ -809,6 +809,11 @@ const maxDuration = (results: ReadonlyArray<Duration.Duration | undefined>): Dur
  * Returns a new `Schedule` that recurs on the specified `Cron` schedule and
  * outputs the duration between recurrences.
  *
+ * **Details**
+ *
+ * A string expression is parsed with `Cron.parse`, using the optional time zone
+ * and `onDstOverlap` policy. A pre-parsed `Cron` value keeps its own policy.
+ *
  * **Example** (Scheduling work with cron expressions)
  *
  * ```ts import.meta.vitest
@@ -827,6 +832,11 @@ export const cron: {
    * Returns a new `Schedule` that recurs on the specified `Cron` schedule and
    * outputs the duration between recurrences.
    *
+   * **Details**
+   *
+   * A string expression is parsed with `Cron.parse`, using the optional time zone
+   * and `onDstOverlap` policy. A pre-parsed `Cron` value keeps its own policy.
+   *
    * **Example** (Scheduling work with cron expressions)
    *
    * ```ts import.meta.vitest
@@ -845,6 +855,11 @@ export const cron: {
    * Returns a new `Schedule` that recurs on the specified `Cron` schedule and
    * outputs the duration between recurrences.
    *
+   * **Details**
+   *
+   * A string expression is parsed with `Cron.parse`, using the optional time zone
+   * and `onDstOverlap` policy. A pre-parsed `Cron` value keeps its own policy.
+   *
    * **Example** (Scheduling work with cron expressions)
    *
    * ```ts import.meta.vitest
@@ -858,9 +873,17 @@ export const cron: {
    * @category constructors
    * @since 2.0.0
    */
-  (expression: string, tz?: string | DateTime.TimeZone): Schedule<Duration.Duration, unknown, Cron.CronParseError>
-} = (expression: string | Cron.Cron, tz?: string | DateTime.TimeZone) => {
-  const parsed = Cron.isCron(expression) ? Result.succeed(expression) : Cron.parse(expression, tz)
+  (
+    expression: string,
+    tz?: string | DateTime.TimeZone,
+    options?: {
+      readonly onDstOverlap?: Cron.DstOverlapPolicy | undefined
+    }
+  ): Schedule<Duration.Duration, unknown, Cron.CronParseError>
+} = (expression: string | Cron.Cron, tz?: string | DateTime.TimeZone, options?: {
+  readonly onDstOverlap?: Cron.DstOverlapPolicy | undefined
+}) => {
+  const parsed = Cron.isCron(expression) ? Result.succeed(expression) : Cron.parse(expression, tz, options)
   return fromStep(effect.map(effect.fromResult(parsed), (cron) => (now, _) => {
     if (now === Number.POSITIVE_INFINITY) {
       return Cause.done(Duration.zero)