API reference › @evolu/common › Resource › SharedResourceByKey

Defined in: packages/common/src/Resource.ts:354

Shared Resources keyed by logical identity.

A map-like registry of SharedResources. Each key owns at most one current resource instance.

The first acquire for a key lazily creates that key's resource. Later acquires for the same key reuse the same resource until the final release starts the final disposal path for that key. Disposal and registry removal happen immediately by default, or after idleDisposeAfter elapses when configured.

Different keys are independent and may progress concurrently. Operations for the same key are serialized. Calls to release must be balanced with successful calls to acquire. Acquire and release may still be aborted before they start on an already-stopped Run, but once started they run to completion. Releasing more times than acquired is a programmer error checked with assert.

By default, createSharedResourceByKey uses reference identity for keys, matching native Map. Callers may instead provide a * lookup so logical equality is based on a derived stable key.

Extends

Methods

[asyncDispose]()

asyncDispose: PromiseLike<void>;

Defined in: node_modules/.bun/typescript@5.9.3/node_modules/typescript/lib/lib.esnext.disposable.d.ts:40

Inherited from

AsyncDisposable.[asyncDispose]

Properties

acquire

readonly acquire: (key: K) => Task<BorrowedResource<T>, never, D>;

Defined in: packages/common/src/Resource.ts:370

Acquires the shared resource for key, creating it on first use.

Once started, acquire runs to completion even if the caller aborts its Fiber. Always await the result. A successful result still counts as an acquired lease for key and must later be balanced with release.

get

readonly get: (key: K) =>
  | BorrowedResource<T>
  | undefined;

Defined in: packages/common/src/Resource.ts:360

Returns the current resource for key, or undefined if absent.

getCount

readonly getCount: (key: K) => Task<number & Brand<"Int"> & Brand<"NonNegative">, never, D>;

Defined in: packages/common/src/Resource.ts:387

Returns the current acquire count for key. Missing keys return 0.

release

readonly release: (key: K) => Task<void, never, D>;

Defined in: packages/common/src/Resource.ts:384

Releases one previously acquired shared reference for key.

When the last acquired reference for key is released, that key's current resource is disposed and removed from the registry immediately by default. If idleDisposeAfter is set, disposal and registry removal are scheduled instead and a new acquire for the same key during that delay reuses the current resource.

Once started, release runs to completion even if the caller aborts its Fiber. Always await the result instead of assuming no cleanup happened.

snapshot

readonly snapshot: () => SharedResourceByKeySnapshot<K, T>;

Defined in: packages/common/src/Resource.ts:390

Returns current keyed resources and their per-key mutex state.

Markdown for LLMs