Resource

Resource: object

Defined in: Core/Resource.ts:34

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, all already-acquired resources (K-1 … 0) are released in reverse order before Resource.use returns 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 Resource.use({
  run: ({ db, redis, s3 }: AppInfra) => runMigration(db, redis, s3),
})(appInfra);

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 returns an error, Resource.use releases the first resource before returning 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, the first is released before Resource.use returns 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 Resource.use({
  run: ([conn, cache]: readonly [DbClient, CacheClient]) => lookupWithFallback(conn, cache, userId),
})(combined);

make

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

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

Convert an infallible acquisition with Task.Result.from.Task before passing it here.

Type Parameters

E

E

A

A

Parameters

acquire

Result<E, A>

release

(value) => Task<unknown>

Returns

Resource<E, A>

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.

The transform must not throw.

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>(options) => <E1>(resource) => Deferred<Result<E2 | E1, B>>

Acquires the resource, runs the supplied work, then releases it.

Successfully acquired resources are released in reverse order when acquisition or work returns an error. If acquisition returns an error, work and its release are skipped. Release tasks and callbacks must not throw or reject.

The run callback parameter must be annotated: the resource arrives after the options, so TypeScript cannot infer its value type from the resource.

Type Parameters

A

A

E2

E2

B

B

Parameters

options

run

(value) => Result<E2, B>

signal?

AbortSignal

Returns

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

Example

const rows = await Resource.use({
  run: (conn: DbClient) => runQuery(conn, "SELECT * FROM users"),
})(dbResource);
// conn is closed whether the query succeeds or returns an error