Resource

Resource: object

Defined in: Core/Resource.ts:35

Type Declaration

all

all: <R>(resources) => Resource<InferError<R>, InferValue<R>>

Sequentially acquires an array/tuple or named record of resources.

All resources are released in strict reverse (LIFO) order upon completion. If the K-th resource fails to acquire or throws, all already-acquired resources (K-1 … 0) are immediately released in reverse order before propagating the error.

Type Parameters

R

R extends Readonly<Record<string, Resource<any, any>>> | readonly Resource<any, any>[]

Parameters

resources

R

Returns

Resource<InferError<R>, InferValue<R>>

See

Resource.combine for binary resource pairing.

Example

// Tuple acquisition:
const infraTuple = Resource.all([dbResource, redisResource, lockResource]);

// Named record acquisition:
const appInfra = Resource.all({
  db: connectDb(dbConfig),
  redis: connectRedis(redisConfig),
  s3: createTempBucket(s3Config),
});

const result = await pipe(
  appInfra,
  Resource.use(({ db, redis, s3 }) => runMigration(db, redis, s3)),
)();

chain

chain: <A, E2, B>(transform) => <E1>(resource) => Resource<E2 | E1, B>

Sequentially acquires a second resource that depends on the value of the first.

If acquiring the second resource fails or throws, the first resource is released immediately before propagating the error. When Resource.use completes, both resources are released in reverse (LIFO) order: the second is released before the first.

Type Parameters

A

A

E2

E2

B

B

Parameters

transform

(value) => Resource<E2, B>

Returns

<E1>(resource) => Resource<E2 | E1, B>

See

Resource.map for transforming acquired values without opening a new resource.

Example

const dbWithLock = pipe(
  connectPostgres(dbConfig),
  Resource.chain((db) =>
    pipe(
      acquireAdvisoryLock(db, "migrations"),
      Resource.map((lock) => ({ db, lock })),
    ),
  ),
);

combine

combine: <E1, A, E2, B>(resourceA, resourceB) => Resource<E1 | E2, readonly [A, B]>

Acquires two resources in sequence and presents them as a tuple.

Resources are released in reverse order: the second is released before the first. If the second resource fails to acquire or throws, the first is released immediately before propagating the error.

Type Parameters

E1

E1

A

A

E2

E2

B

B

Parameters

resourceA

Resource<E1, A>

resourceB

Resource<E2, B>

Returns

Resource<E1 | E2, readonly [A, B]>

See

Resource.all for acquiring arbitrary tuples or named records of resources.

Example

const combined = Resource.combine(dbResource, cacheResource);

const result = await pipe(
  combined,
  Resource.use(([conn, cache]) => lookupWithFallback(conn, cache, userId)),
)();

from

from: object

from.Task

Task: <A, E>(acquire, release) => Resource<E, A> = makeTask

Creates a Resource from an acquire operation that cannot fail. Use this when opening the resource is guaranteed to succeed, such as in-memory locks, counters, or timers.

Type Parameters

A

A

E

E = never

Parameters

acquire

Task<A>

release

(value) => Task<unknown>

Returns

Resource<E, A>

See

Resource.make for creating resources with fallible acquisition.

Example

const timerResource = Resource.from.Task(
  Task.tryCatch(() => Promise.resolve(startTimer()), { onError: () => defaultTimer }),
  (timer) => Task.tryCatch(() => Promise.resolve(timer.stop()), { onError: () => {} }),
);

make

make: <E, A>(acquire, release) => Resource<E, A> = makeResource

Creates a Resource from an acquire operation that may fail and a release finalizer.

Type Parameters

E

E

A

A

Parameters

acquire

Result<E, A>

release

(value) => Task<unknown>

Returns

Resource<E, A>

See

Resource.from.Task for creating resources with infallible acquisition.

Example

const fileResource = Resource.make(
  Task.Result.tryCatch(() => fs.promises.open("data.csv", "r"), { onError: toFileError }),
  (handle) => Task.tryCatch(() => handle.close(), { onError: () => {} }),
);

map

map: <A, B>(transform) => <E>(resource) => Resource<E, B>

Transforms the value of an acquired resource while retaining guaranteed cleanup of the original asset.

If transform throws an exception, the acquired resource is released immediately before propagating the error.

Type Parameters

A

A

B

B

Parameters

transform

(value) => B

Returns

<E>(resource) => Resource<E, B>

See

Resource.chain for sequencing dependent resource acquisitions.

Example

const clientResource = pipe(
  connectCluster(clusterConfig),
  Resource.map((cluster) => cluster.getClient("analytics")),
);

use

use: <A, E2, B>(consume) => <E1>(resource) => Result<E2 | E1, B>

Acquires the resource, runs consume with it, then releases it.

Release always runs, even when consume returns an error or throws. If acquire fails, consume and release are both skipped and the error is returned.

Type Parameters

A

A

E2

E2

B

B

Parameters

consume

(value) => Result<E2, B>

Returns

<E1>(resource) => Result<E2 | E1, B>

Example

const rows = await pipe(
  dbResource,
  Resource.use((conn) => runQuery(conn, "SELECT * FROM users")),
)();
// conn is closed whether the query succeeds, fails, or throws