Class OxiaClient

Asynchronous client for the Oxia service.

Build one with OxiaClient.connect. Call OxiaClient.close when done to release the gRPC channels, stop the background shard-assignment watcher, and cleanly tear down any open sessions.

The client is safe to use from multiple async contexts — every method is non-blocking and internally dispatches to the appropriate shard leader.

Example

const client = await OxiaClient.connect('localhost:6648');
try {
  await client.put('/users/alice', 'hello');
  const r = await client.get('/users/alice');
  console.log(new TextDecoder().decode(r.value));
} finally {
  await client.close();
}

Index

Methods

connect put delete deleteRange get list rangeScan getNotifications getSequenceUpdates close

Methods

`Static`connect

connect(
serviceAddress: string,
options?: OxiaClientOptions,
): Promise<OxiaClient>
Connect to an Oxia service and wait for the initial shard assignments to arrive before returning.
Parameters
- serviceAddress: string
  host:port of any Oxia server. The client uses this address only to discover shard assignments; subsequent requests go directly to each shard's leader.
- options: OxiaClientOptions = {}
  See OxiaClientOptions.
Returns Promise<OxiaClient>
Throws
If the initial shard-assignment fetch does not complete within initTimeoutMs.
- Defined in client.ts:247

put

put(
    key: string,
    value: string | Uint8Array<ArrayBufferLike>,
    opts?: PutOptions,
): Promise<PutResult>
Associate a value with a key.
Parameters
- key: string
  The key to write. When PutOptions.sequenceKeysDeltas is used this is the prefix; the returned PutResult.key is the full server-assigned key.
- value: string | Uint8Array<ArrayBufferLike>
  Bytes to store. Strings are encoded as UTF-8.
- opts: PutOptions = {}
  See PutOptions.
Returns Promise<PutResult>
The final key and version metadata for the written record.

Throws
UnexpectedVersionIdError if expectedVersionId mismatches the server's current version.

Throws
SessionNotFoundError for an ephemeral put when the client's session on the target shard no longer exists server-side.

Throws
InvalidOptionsError for incompatible option combinations (e.g. sequenceKeysDeltas without partitionKey).
- Defined in client.ts:289

delete

delete(key: string, opts?: DeleteOptions): Promise<boolean>
Delete the record stored at key.
Parameters
- key: string
  The key to delete.
- opts: DeleteOptions = {}
  See DeleteOptions.
Returns Promise<boolean>
true if a record existed and was removed, false if no record was found at that key (or at that key within the target partition).

Throws
UnexpectedVersionIdError if expectedVersionId mismatches the server's current version.
- Defined in client.ts:355

deleteRange

deleteRange(
    minKeyInclusive: string,
    maxKeyExclusive: string,
    opts?: DeleteRangeOptions,
): Promise<void>
Delete every record whose key falls in [minKeyInclusive, maxKeyExclusive).

Without a partitionKey the operation is fanned out to every shard; with one it targets a single shard.

Bounds are interpreted in Oxia's hierarchical key order — see https://oxia-db.github.io/docs/features/oxia-key-sorting
Parameters
- minKeyInclusive: string
  Start of the range (inclusive).
- maxKeyExclusive: string
  End of the range (exclusive).
- opts: DeleteRangeOptions = {}
  See DeleteRangeOptions.
Returns Promise<void>
- Defined in client.ts:396

get

get(key: string, opts?: GetOptions): Promise<GetResult>
Retrieve the record for a key.

With the default EQUAL comparison this is an exact-match lookup on a single shard. With any other ComparisonType — or with useIndex — the client fans out to every shard and picks the best match in hierarchical key order.
Parameters
- key: string
  The key to look up. When useIndex is set, this is treated as a secondary key for that index.
- opts: GetOptions = {}
  See GetOptions.
Returns Promise<GetResult>
The matched record (primary key, value, and version).

Throws
KeyNotFoundError if no record matches.
- Defined in client.ts:444

list

list(
    minKeyInclusive: string,
    maxKeyExclusive: string,
    opts?: ListOptions,
): Promise<string[]>
List every key in [minKeyInclusive, maxKeyExclusive).

Without a partitionKey, each shard is queried in parallel and the results are merged. Keys are returned in Oxia's hierarchical sort order — see https://oxia-db.github.io/docs/features/oxia-key-sorting

Use OxiaClient.rangeScan if you also need the values.
Parameters
- minKeyInclusive: string
  Start of the range (inclusive).
- maxKeyExclusive: string
  End of the range (exclusive).
- opts: ListOptions = {}
  See ListOptions.
Returns Promise<string[]>
Sorted keys in the range, or [] if none match.
- Defined in client.ts:509

rangeScan

rangeScan(
    minKeyInclusive: string,
    maxKeyExclusive: string,
    opts?: RangeScanOptions,
): AsyncIterable<GetResult>
Stream records in [minKeyInclusive, maxKeyExclusive) as an AsyncIterable<GetResult>.

Without a partitionKey, one streaming RPC is opened per shard and the results are merged in hierarchical key order. Break out of the for await (...) loop to cancel the remaining server streams.

Use OxiaClient.list if you only need the keys (cheaper).
Parameters
- minKeyInclusive: string
  Start of the range (inclusive).
- maxKeyExclusive: string
  End of the range (exclusive).
- opts: RangeScanOptions = {}
  See RangeScanOptions.
Returns AsyncIterable<GetResult>
- Defined in client.ts:545

getNotifications

getNotifications(): CloseableAsyncIterable<Notification>
Subscribe to change notifications across every shard. Returns an AsyncIterable that yields one Notification per change; the returned object's close() method stops the subscription and ends the iterator. Multiple subscriptions can run concurrently.

Returns CloseableAsyncIterable<Notification>
- Defined in client.ts:569

getSequenceUpdates

getSequenceUpdates(
prefixKey: string,
options: SequenceUpdatesOptions,
): CloseableAsyncIterable<string>
Subscribe to updates on a sequential key. Yields the latest assigned key each time the sequence advances; the returned object's close() method ends the subscription.
Parameters
- prefixKey: string
  The key prefix used with sequence-key puts.
- options: SequenceUpdatesOptions
  Requires partitionKey to route to the owning shard.
Returns CloseableAsyncIterable<string>
- Defined in client.ts:582

close

close(): Promise<void>
Release all resources held by the client: close any open sessions (triggering server-side removal of this client's ephemerals), stop the shard-assignment watcher, and close every gRPC channel.

Idempotent. Any subsequent client call throws OxiaError.

Returns Promise<void>
- Defined in client.ts:601

Class OxiaClient

Example

Index

Methods

Methods

Staticconnect

Parameters

Returns Promise<OxiaClient>

Throws

put

Parameters

Returns Promise<PutResult>

Throws

Throws

Throws

delete

Parameters

Returns Promise<boolean>

Throws

deleteRange

Parameters

Returns Promise<void>

get

Parameters

Returns Promise<GetResult>

Throws

list

Parameters

Returns Promise<string[]>

rangeScan

Parameters

Returns AsyncIterable<GetResult>

getNotifications

Returns CloseableAsyncIterable<Notification>

getSequenceUpdates

Parameters

Returns CloseableAsyncIterable<string>

close

Returns Promise<void>

Settings

On This Page

`Static`connect