[API reference](https://evolu.dev/docs/api-reference) › [@evolu/common](https://evolu.dev/docs/api-reference/common) › [Resource](https://evolu.dev/docs/api-reference/common/Resource) › SharedResourceByKey

Defined in: [packages/common/src/Resource.ts:598](https://github.com/evoluhq/evolu/blob/037c390af081e9944d616ff298a729515c5c5ab7/packages/common/src/Resource.ts#L598)

Shared [Resource](https://evolu.dev/docs/api-reference/common/Resource/type-aliases/Resource)s keyed by logical identity.

A map-like registry of [SharedResource](https://evolu.dev/docs/api-reference/common/Resource/interfaces/SharedResource)s. Each key owns at most one
current resource instance. The first
[acquire](https://evolu.dev/docs/api-reference/common/Resource/interfaces/SharedResourceByKey#acquire) for a key lazily creates that
key's resource; releasing the key's last [Lease](https://evolu.dev/docs/api-reference/common/Resource/interfaces/Lease) disposes it and removes
the key from the registry.

Different keys are independent and may progress concurrently. Operations for
the same key are serialized.

By default, keys use reference identity, matching native `Map`. Callers may
instead provide a [lookup](https://evolu.dev/docs/api-reference/common/Lookup/type-aliases/Lookup) so logical equality is based on a
derived stable key.

### Example

```ts
import {
  all,
  assertEqual,
  assertSame,
  createRun,
  createSharedResourceByKey,
  ok,
  type Task,
} from "@evolu/common";

interface Connection extends Disposable {
  readonly ownerId: string;
  readonly send: (message: string) => void;
  readonly flush: () => ReadonlyArray<string>;
}

const createConnection =
  (ownerId: string): Task<Connection> =>
  () => {
    const pendingMessages: Array<string> = [];
    return ok({
      ownerId,
      send: (message) => {
        pendingMessages.push(message);
      },
      flush: () => pendingMessages.splice(0),
      [Symbol.dispose]: () => {},
    });
  };

await using run = createRun();
await using connections = await run.ok(
  createSharedResourceByKey(createConnection, {
    idleDisposeAfter: "30s",
  }),
);
const send = (ownerId: string, message: string): Task<void> =>
  connections.use(ownerId, (connection) => () => {
    connection.send(message);
    return ok();
  });

// Same-key calls share one connection. Work for different keys remains
// independent, so all three operations can run concurrently.
await run.ok(
  all(
    [
      send("owner-1", "first"),
      send("owner-1", "second"),
      send("owner-2", "hello"),
    ],
    { concurrency: 3 },
  ),
);

// `acquireCurrent` does not create absent keys. The idle delay keeps the two
// existing connections available to enumerate and flush.
using missingLease = await run.ok(connections.acquireCurrent("owner-3"));
const messagesByOwnerId = new Map<string, ReadonlyArray<string>>();
await run.ok(
  connections.forEachCurrent((connection) => {
    messagesByOwnerId.set(connection.ownerId, connection.flush());
  }),
);

assertSame(missingLease, undefined);
assertEqual(
  messagesByOwnerId,
  new Map([
    ["owner-1", ["first", "second"]],
    ["owner-2", ["hello"]],
  ]),
);
```

## Extends

- [`AsyncDisposable`](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management)

## Methods

<a id="asyncdispose"></a>

### \[asyncDispose\]()

```ts
asyncDispose: PromiseLike<void>;
```

Defined in: node\_modules/@typescript/old/lib/lib.esnext.disposable.d.ts:38

#### Inherited from

```ts
AsyncDisposable.[asyncDispose]
```

## Properties

<a id="acquire"></a>

### acquire

```ts
readonly acquire: (key: K) => Task<Lease<T>>;
```

Defined in: [packages/common/src/Resource.ts:611](https://github.com/evoluhq/evolu/blob/037c390af081e9944d616ff298a729515c5c5ab7/packages/common/src/Resource.ts#L611)

Acquires a [Lease](https://evolu.dev/docs/api-reference/common/Resource/interfaces/Lease) on the shared resource for `key`, creating the
resource on first use.

The same contract as [SharedResource.acquire](https://evolu.dev/docs/api-reference/common/Resource/interfaces/SharedResource#acquire): once started, acquire
runs to completion even when the caller aborts its Fiber, and the returned
lease still counts as held. Registry disposal before lease transfer aborts
the acquisition. Always await the result and release the lease.

### acquireCurrent

```ts
readonly acquireCurrent: (key: K) => Task<
  | Lease<T>
| undefined>;
```

Defined in: [packages/common/src/Resource.ts:623](https://github.com/evoluhq/evolu/blob/037c390af081e9944d616ff298a729515c5c5ab7/packages/common/src/Resource.ts#L623)

Acquires a [Lease](https://evolu.dev/docs/api-reference/common/Resource/interfaces/Lease) on the current resource for `key` without creating
one.

Waits for preceding creation or disposal for the same key to finish.
Returns `undefined` if no current resource remains. Registry disposal while
waiting aborts the acquisition before a lease is transferred. Registry
disposal after transfer can drain the lease before the caller resumes,
matching [SharedResource.acquireCurrent](https://evolu.dev/docs/api-reference/common/Resource/interfaces/SharedResource#acquirecurrent).

### forEachCurrent

```ts
readonly forEachCurrent: (callback: (resource: DistributiveOmit<T>, key: K) => void) => Task<void>;
```

Defined in: [packages/common/src/Resource.ts:654](https://github.com/evoluhq/evolu/blob/037c390af081e9944d616ff298a729515c5c5ab7/packages/common/src/Resource.ts#L654)

Calls `callback` for each current resource it can lease from keys
registered when this Task starts.

Never creates resources. A resource whose creation is in progress may be
included after creation finishes; one disposed before its temporary lease
is acquired is skipped. Each acquired lease stays held while later keys are
awaited, and every callback runs while all acquired resources remain
leased. Caller abort is observed between keys; already-collected leases are
released and no callbacks run.

### snapshot

```ts
readonly snapshot: () => SharedResourceByKeySnapshot<K>;
```

Defined in: [packages/common/src/Resource.ts:659](https://github.com/evoluhq/evolu/blob/037c390af081e9944d616ff298a729515c5c5ab7/packages/common/src/Resource.ts#L659)

Returns current per-key shared-resource states for monitoring/debugging.

### use

```ts
readonly use: <R, E, D>(key: K, callback: (resource: DistributiveOmit<T>, created: boolean) => Task<R, E, D>) => Task<R, E, D>;
```

Defined in: [packages/common/src/Resource.ts:635](https://github.com/evoluhq/evolu/blob/037c390af081e9944d616ff298a729515c5c5ab7/packages/common/src/Resource.ts#L635)

Acquires a [Lease](https://evolu.dev/docs/api-reference/common/Resource/interfaces/Lease), runs a Task with the shared resource for `key`,
and releases the lease after the Task settles.

Creates the resource when absent. The callback receives whether this use
created the resource generation. While the registry remains running, the
lease prevents ordinary idle disposal. Disposing this registry is forceful:
it drains the lease and may dispose the resource before or while the
callback Task runs.