Caching Effects

This section covers several functions from the library that help manage caching and memoization in your application.

Memoizing a Function

To memoize an effectful function, create a Cache whose lookup is the function to memoize, then call Cache.get for each input. The cache stores one result per input, so calling the function again with the same input reuses the cached result instead of recomputing it.

Example (Memoizing a Function with Cache)

1
import { Cache, Effect } from "effect"
2

3
let i = 1
4

5
// Simulating a task whose result changes on each call
6
const randomNumber = (n: number) => Effect.sync(() => n + i++)
7

8
const program = Effect.gen(function* () {
9
  console.log("non-memoized version:")
10
  const a = yield* randomNumber(10) // Computes a new result
11
  console.log(a)
12
  const b = yield* randomNumber(10) // Computes a different result
13
  console.log(b)
14

15
  console.log("memoized version:")
16
  const cache = yield* Cache.make({
17
    capacity: Number.MAX_SAFE_INTEGER,
18
    lookup: randomNumber,
19
  })
20
  const memoized = (n: number) => Cache.get(cache, n)
21
  const c = yield* memoized(10) // Computes and caches the result
22
  console.log(c)
23
  const d = yield* memoized(10) // Reuses the cached result
24
  console.log(d)
25

26
  return { a, b, c, d }
27
})
28

29
const result = await Effect.runPromise(program)
30
result // => { a: 11, b: 12, c: 13, d: 13 }

cached

Effect.cached creates a reusable effect that executes the original effect at most once and caches its outcome.

First, obtain the cached effect with const cached = yield* Effect.cached(task). This step does not execute task. The first execution of cached runs task. Further executions behave as follows:

State of the first execution	Behavior of further executions of `cached`
Succeeded with `42`	Return the cached value `42` without running `task` again.
Failed	Fail with the cached failure without retrying `task`.
Interrupted	Propagate the cached interruption without running `task` again.
Still running	Wait for it to complete and share the same outcome.

Each execution of Effect.cached(task) creates an independent cache, so create the cached effect once and reuse it.

Example (Lazy Caching of an Expensive Task)

1
import { Effect, Console } from "effect"
2

3
let i = 1
4

5
// Simulating an expensive task with a delay
6
const expensiveTask = Effect.promise<string>(() => {
7
  console.log("expensive task...")
8
  return new Promise((resolve) => {
9
    setTimeout(() => {
10
      resolve(`result ${i++}`)
11
    }, 100)
12
  })
13
})
14

15
const program = Effect.gen(function* () {
16
  // Without caching, the task is executed each time
17
  console.log("-- non-cached version:")
18
  yield* expensiveTask.pipe(Effect.andThen(Console.log))
19
  yield* expensiveTask.pipe(Effect.andThen(Console.log))
20

21
  // With caching, the result is reused after the first run
22
  console.log("-- cached version:")
23
  const cached = yield* Effect.cached(expensiveTask)
24
  yield* cached.pipe(Effect.andThen(Console.log))
25
  yield* cached.pipe(Effect.andThen(Console.log))
26
})
27

28
const result = await Effect.runPromise(program)
29
/*
30
Output:
31
-- non-cached version:
32
expensive task...
33
result 1
34
expensive task...
35
result 2
36
-- cached version:
37
expensive task...
38
result 3
39
result 3
40
*/
41
result // => undefined

cachedWithTTL

Returns an effect that caches its result for a specified duration, known as the timeToLive. When the cache expires after the duration, the effect will be recomputed upon next evaluation.

Example (Caching with Time-to-Live)

1
import { Effect, Console } from "effect"
2

3
let i = 1
4

5
// Simulating an expensive task with a delay
6
const expensiveTask = Effect.promise<string>(() => {
7
  console.log("expensive task...")
8
  return new Promise((resolve) => {
9
    setTimeout(() => {
10
      resolve(`result ${i++}`)
11
    }, 100)
12
  })
13
})
14

15
const program = Effect.gen(function* () {
16
  // Caches the result for 150 milliseconds
17
  const cached = yield* Effect.cachedWithTTL(expensiveTask, "150 millis")
18

19
  // First evaluation triggers the task
20
  yield* cached.pipe(Effect.andThen(Console.log))
21

22
  // Second evaluation returns the cached result
23
  yield* cached.pipe(Effect.andThen(Console.log))
24

25
  // Wait for 200 milliseconds, ensuring the cache expires
26
  yield* Effect.sleep("200 millis")
27

28
  // Recomputes the task after cache expiration
29
  yield* cached.pipe(Effect.andThen(Console.log))
30
})
31

32
const result = await Effect.runPromise(program)
33
/*
34
Output:
35
expensive task...
36
result 1
37
result 1
38
expensive task...
39
result 2
40
*/
41
result // => undefined

cachedInvalidateWithTTL

Similar to Effect.cachedWithTTL, this function caches an effect’s result for a specified duration. It also includes an additional effect for manually invalidating the cached value before it naturally expires.

Example (Invalidating Cache Manually)

1
import { Effect, Console } from "effect"
2

3
let i = 1
4

5
// Simulating an expensive task with a delay
6
const expensiveTask = Effect.promise<string>(() => {
7
  console.log("expensive task...")
8
  return new Promise((resolve) => {
9
    setTimeout(() => {
10
      resolve(`result ${i++}`)
11
    }, 100)
12
  })
13
})
14

15
const program = Effect.gen(function* () {
16
  // Caches the result for 150 milliseconds
17
  const [cached, invalidate] = yield* Effect.cachedInvalidateWithTTL(
18
    expensiveTask,
19
    "150 millis",
20
  )
21

22
  // First evaluation triggers the task
23
  yield* cached.pipe(Effect.andThen(Console.log))
24

25
  // Second evaluation returns the cached result
26
  yield* cached.pipe(Effect.andThen(Console.log))
27

28
  // Invalidate the cache before it naturally expires
29
  yield* invalidate
30

31
  // Third evaluation triggers the task again
32
  // since the cache was invalidated
33
  yield* cached.pipe(Effect.andThen(Console.log))
34
})
35

36
const result = await Effect.runPromise(program)
37
/*
38
Output:
39
expensive task...
40
result 1
41
result 1
42
expensive task...
43
result 2
44
*/
45
result // => undefined