RcMap: support dynamic idleTimeToLive values per key (#5859)

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Tim Smart <hello@timsmart.co>

Author: 3 people

.changeset/dynamic-idle-ttl-rcmap.md

@@ -0,0 +1,17 @@
+---
+"effect": minor
+---
+
+RcMap: support dynamic `idleTimeToLive` values per key
+
+The `idleTimeToLive` option can now be a function that receives the key and returns a duration, allowing different TTL values for different resources.
+
+```ts
+const map = yield* RcMap.make({
+  lookup: (key: string) => acquireResource(key),
+  idleTimeToLive: (key: string) => {
+    if (key.startsWith("premium:")) return Duration.minutes(10)
+    return Duration.minutes(1)
+  }
+})
+```

packages/effect/src/RcMap.ts

@@ -56,6 +56,7 @@ export declare namespace RcMap {
  *
  * - `capacity`: The maximum number of resources that can be held in the map.
  * - `idleTimeToLive`: When the reference count reaches zero, the resource will be released after this duration.
+ *   Can be a static duration or a function that returns a duration based on the key.
  *
  * @since 3.5.0
  * @category models
@@ -85,14 +86,14 @@ export const make: {
   <K, A, E, R>(
     options: {
       readonly lookup: (key: K) => Effect.Effect<A, E, R>
-      readonly idleTimeToLive?: Duration.DurationInput | undefined
+      readonly idleTimeToLive?: Duration.DurationInput | ((key: K) => Duration.DurationInput) | undefined
       readonly capacity?: undefined
     }
   ): Effect.Effect<RcMap<K, A, E>, never, Scope.Scope | R>
   <K, A, E, R>(
     options: {
       readonly lookup: (key: K) => Effect.Effect<A, E, R>
-      readonly idleTimeToLive?: Duration.DurationInput | undefined
+      readonly idleTimeToLive?: Duration.DurationInput | ((key: K) => Duration.DurationInput) | undefined
       readonly capacity: number
     }
   ): Effect.Effect<RcMap<K, A, E | Cause.ExceededCapacityException>, never, Scope.Scope | R>

packages/effect/src/internal/rcMap.ts

@@ -4,7 +4,7 @@ import type * as Deferred from "../Deferred.js"
 import * as Duration from "../Duration.js"
 import type { Effect } from "../Effect.js"
 import type { RuntimeFiber } from "../Fiber.js"
-import { dual, identity } from "../Function.js"
+import { constant, dual, flow, identity } from "../Function.js"
 import * as MutableHashMap from "../MutableHashMap.js"
 import { pipeArguments } from "../Pipeable.js"
 import type * as RcMap from "../RcMap.js"
@@ -33,6 +33,7 @@ declare namespace State {
     readonly deferred: Deferred.Deferred<A, E>
     readonly scope: Scope.CloseableScope
     readonly finalizer: Effect<void>
+    readonly idleTimeToLive: Duration.Duration
     fiber: RuntimeFiber<void, never> | undefined
     expiresAt: number
     refCount: number
@@ -58,7 +59,7 @@ class RcMapImpl<K, A, E> implements RcMap.RcMap<K, A, E> {
     readonly lookup: (key: K) => Effect<A, E, Scope.Scope>,
     readonly context: Context.Context<never>,
     readonly scope: Scope.Scope,
-    readonly idleTimeToLive: Duration.Duration | undefined,
+    readonly idleTimeToLive: ((key: K) => Duration.Duration) | undefined,
     readonly capacity: number
   ) {
     this[TypeId] = variance
@@ -73,27 +74,32 @@ class RcMapImpl<K, A, E> implements RcMap.RcMap<K, A, E> {
 export const make: {
   <K, A, E, R>(options: {
     readonly lookup: (key: K) => Effect<A, E, R>
-    readonly idleTimeToLive?: Duration.DurationInput | undefined
+    readonly idleTimeToLive?: Duration.DurationInput | ((key: K) => Duration.DurationInput) | undefined
     readonly capacity?: undefined
   }): Effect<RcMap.RcMap<K, A, E>, never, Scope.Scope | R>
   <K, A, E, R>(options: {
     readonly lookup: (key: K) => Effect<A, E, R>
-    readonly idleTimeToLive?: Duration.DurationInput | undefined
+    readonly idleTimeToLive?: Duration.DurationInput | ((key: K) => Duration.DurationInput) | undefined
     readonly capacity: number
   }): Effect<RcMap.RcMap<K, A, E | Cause.ExceededCapacityException>, never, Scope.Scope | R>
 } = <K, A, E, R>(options: {
   readonly lookup: (key: K) => Effect<A, E, R>
-  readonly idleTimeToLive?: Duration.DurationInput | undefined
+  readonly idleTimeToLive?: Duration.DurationInput | ((key: K) => Duration.DurationInput) | undefined
   readonly capacity?: number | undefined
 }) =>
   core.withFiberRuntime<RcMap.RcMap<K, A, E>, never, R | Scope.Scope>((fiber) => {
     const context = fiber.getFiberRef(core.currentContext) as Context.Context<R | Scope.Scope>
     const scope = Context.get(context, fiberRuntime.scopeTag)
+    const idleTimeToLive = options.idleTimeToLive === undefined
+      ? undefined
+      : typeof options.idleTimeToLive === "function"
+      ? flow(options.idleTimeToLive, Duration.decode)
+      : constant(Duration.decode(options.idleTimeToLive))
     const self = new RcMapImpl<K, A, E>(
       options.lookup as any,
       context,
       scope,
-      options.idleTimeToLive ? Duration.decode(options.idleTimeToLive) : undefined,
+      idleTimeToLive,
       Math.max(options.capacity ?? Number.POSITIVE_INFINITY, 0)
     )
     return core.as(
@@ -169,10 +175,12 @@ const acquire = core.fnUntraced(function*<K, A, E>(self: RcMapImpl<K, A, E>, key
     core.flatMap((exit) => core.deferredDone(deferred, exit)),
     circular.forkIn(scope)
   )
+  const idleTimeToLive = self.idleTimeToLive ? self.idleTimeToLive(key) : Duration.zero
   const entry: State.Entry<A, E> = {
     deferred,
     scope,
     finalizer: undefined as any,
+    idleTimeToLive,
     fiber: undefined,
     expiresAt: 0,
     refCount: 1
@@ -192,19 +200,19 @@ const release = <K, A, E>(self: RcMapImpl<K, A, E>, key: K, entry: State.Entry<A
     } else if (
       self.state._tag === "Closed"
       || !MutableHashMap.has(self.state.map, key)
-      || self.idleTimeToLive === undefined
+      || Duration.isZero(entry.idleTimeToLive)
     ) {
       if (self.state._tag === "Open") {
         MutableHashMap.remove(self.state.map, key)
       }
       return core.scopeClose(entry.scope, core.exitVoid)
     }
 
-    if (!Duration.isFinite(self.idleTimeToLive)) {
+    if (!Duration.isFinite(entry.idleTimeToLive)) {
       return core.void
     }
 
-    entry.expiresAt = clock.unsafeCurrentTimeMillis() + Duration.toMillis(self.idleTimeToLive)
+    entry.expiresAt = clock.unsafeCurrentTimeMillis() + Duration.toMillis(entry.idleTimeToLive)
     if (entry.fiber) return core.void
 
     return core.interruptibleMask(function loop(restore): Effect<void> {
@@ -276,10 +284,12 @@ export const touch: {
   <K, A, E>(self_: RcMap.RcMap<K, A, E>, key: K) =>
     coreEffect.clockWith((clock) => {
       const self = self_ as RcMapImpl<K, A, E>
-      if (!self.idleTimeToLive || self.state._tag === "Closed") return core.void
+      if (self.state._tag === "Closed") return core.void
       const o = MutableHashMap.get(self.state.map, key)
       if (o._tag === "None") return core.void
-      o.value.expiresAt = clock.unsafeCurrentTimeMillis() + Duration.toMillis(self.idleTimeToLive)
+      const entry = o.value
+      if (Duration.isZero(entry.idleTimeToLive)) return core.void
+      entry.expiresAt = clock.unsafeCurrentTimeMillis() + Duration.toMillis(entry.idleTimeToLive)
       return core.void
     })
 )

packages/effect/test/RcMap.test.ts

@@ -175,4 +175,63 @@ describe("RcMap", () => {
 
       deepStrictEqual(yield* RcMap.keys(map), ["foo", "bar", "baz"])
     }))
+
+  it.scoped("dynamic idleTimeToLive", () =>
+    Effect.gen(function*() {
+      const acquired: Array<string> = []
+      const released: Array<string> = []
+      const map = yield* RcMap.make({
+        lookup: (key: string) =>
+          Effect.acquireRelease(
+            Effect.sync(() => {
+              acquired.push(key)
+              return key
+            }),
+            () => Effect.sync(() => released.push(key))
+          ),
+        idleTimeToLive: (key: string) => key.startsWith("short:") ? 500 : 2000
+      })
+
+      deepStrictEqual(acquired, [])
+
+      yield* Effect.scoped(RcMap.get(map, "short:a"))
+      yield* Effect.scoped(RcMap.get(map, "long:b"))
+      deepStrictEqual(acquired, ["short:a", "long:b"])
+      deepStrictEqual(released, [])
+
+      yield* TestClock.adjust(500)
+      deepStrictEqual(released, ["short:a"])
+
+      yield* TestClock.adjust(1500)
+      deepStrictEqual(released, ["short:a", "long:b"])
+    }))
+
+  it.scoped("dynamic idleTimeToLive with touch", () =>
+    Effect.gen(function*() {
+      const acquired: Array<string> = []
+      const released: Array<string> = []
+      const map = yield* RcMap.make({
+        lookup: (key: string) =>
+          Effect.acquireRelease(
+            Effect.sync(() => {
+              acquired.push(key)
+              return key
+            }),
+            () => Effect.sync(() => released.push(key))
+          ),
+        idleTimeToLive: (key: string) => key.startsWith("short:") ? 500 : 2000
+      })
+
+      yield* Effect.scoped(RcMap.get(map, "short:a"))
+      deepStrictEqual(acquired, ["short:a"])
+      deepStrictEqual(released, [])
+
+      yield* TestClock.adjust(250)
+      yield* RcMap.touch(map, "short:a")
+      yield* TestClock.adjust(250)
+      deepStrictEqual(released, [])
+
+      yield* TestClock.adjust(250)
+      deepStrictEqual(released, ["short:a"])
+    }))
 })