Class NanoKV<E, Q>

A key-value database designed for efficient data storage and retrieval.

In this database, data is saved and accessed through key-value pairs. The key is a KvKey, and the value is any JavaScript object that can be structured and serialized. Keys are sorted lexicographically as per the KvKey documentation, and each key in the database is unique. When a key is read, the system returns the most recent value associated with it. Keys can be removed from the database, and upon deletion, they will no longer appear during read operations.

Values can be any JavaScript object that is structured-serializable, such as objects, arrays, strings, or numbers.

Each key is versioned upon writing by assigning it an ever-increasing "versionstamp". This versionstamp signifies the versionstamp of the key-value pair at a specific moment and facilitates transactional operations on the database without the need for locks. Atomic operations, which can include conditions to check against the expected versionstamp, ensure that the operation only completes if the versionstamp matches the anticipated value.

The NanoKV database also provides a lightweight message queue feature. Please note: Although the API names are similar to those of denokv, there are significant differences in their behaviors. For instance, denokv's message delivery is more inclined towards real-time processing, and thus denokv will attempt to redeliver to the consumer within a specific time frame (with settings for the number of retries and frequency). In contrast, NanoKV leans more towards the essence of a "queue", where consumers can retrieve outdated messages from the queue (if not manually dequeued), as well as receive new messages in real-time.

Additionally, NanoKV supports the existence of multiple queues simultaneously. Different parts of an application (such as various microservices) can listen only to the queues they are interested in, whereas denokv can only have a single global queue (for a denokv instance). This is also a significant difference.

Example

type EntryType =
  | KvEntry<["user", id: number, "name"], string>
  | KvEntry<["user", id: number, "age"], number>;
type QueueType =
  | KvQueueEntry<["user-joined"], number>
  | KvQueueEntry<["user-left"], number>;
const kv = new NanoKV<EntryType, QueueType>("http://127.0.0.1:2256");

Type Parameters

E extends KvEntry = KvEntry
KvEntry type
Q extends KvQueueEntry = KvQueueEntry
KvQueueEntry type

Implements

KvApi<E, Q>

Index

Constructors

constructor

new NanoKV<E extends KvEntry = KvEntry, Q extends KvQueueEntry = KvQueueEntry>(
endpoint: string,
options?: { encoding?: ProtocolEncoding },
): NanoKV<E, Q>
Create a new NanoKV connection.
Type Parameters
- E extends KvEntry = KvEntry
- Q extends KvQueueEntry = KvQueueEntry
Parameters
- endpoint: string
  Current NanoKV endpoint
- options: { encoding?: ProtocolEncoding } = {}
  Specify a custom encoding method for values, by default it will use JSON as serialization format
Returns NanoKV<E, Q>
- Defined in index.ts:279

Properties

`Readonly`endpoint

endpoint: string

Current NanoKV endpoint

Methods

atomic

atomic(): AtomicOperation<E, Q>
Create a new AtomicOperation object which can be used to perform an atomic transaction on the database. This does not perform any operations on the database - the atomic transaction must be committed explicitly using the AtomicOperation.commit method once all checks and mutations have been added to the operation.

Returns AtomicOperation<E, Q>
Implementation of KvApi.atomic
- Defined in index.ts:523

delete

delete(
key: E["key"],
signal?: AbortSignal,
): Promise<KvCommitResult | KvCommitError>
Delete the value for the given key from the database. If no value exists for the key, this operation is a no-op.
Parameters
- key: E["key"]
  The key to delete.
- Optionalsignal: AbortSignal
Returns Promise<KvCommitResult | KvCommitError>
A promise resolving to an object containing a boolean indicating whether the operation was successful, and the versionstamp of the deleted key-value entry.
Implementation of KvApi.delete
- Defined in index.ts:464

get

get<K extends KvKey>(
key: K,
signal?: AbortSignal,
): Promise<KvPairMaybe<SelectKvPair<E, K>>>
Retrieve the value and versionstamp for the given key from the database in the form of a KvEntryMaybe. If no value exists for the key, the returned entry will have a null value and versionstamp.
Type Parameters
- K extends KvKey
Parameters
- key: K
- Optionalsignal: AbortSignal
Returns Promise<KvPairMaybe<SelectKvPair<E, K>>>
Implementation of KvApi.get
- Defined in index.ts:398

getMany

getMany<Ks extends [] | E["key"][]>(
    keys: Ks,
    signal?: AbortSignal,
): Promise<
    {
        [N in string
        | number
        | symbol]: KvPairMaybe<SelectKvPair<E, Ks[N<N>]>>
    },
>
Retrieve multiple values and versionstamp from the database in the form of an array of KvEntryMaybe objects. The returned array will have the same length as the keys array, and the entries will be in the same order as the keys. If no value exists for a given key, the returned entry will have a null value and versionstamp.
Type Parameters
- Ks extends [] | E["key"][]
Parameters
- keys: Ks
- Optionalsignal: AbortSignal
Returns Promise<
    {
        [N in string
        | number
        | symbol]: KvPairMaybe<SelectKvPair<E, Ks[N<N>]>>
    },
>
Implementation of KvApi.getMany
- Defined in index.ts:419

list

list<K extends KvKey, P extends KvKey | []>(
selector: KvListSelector<K, P>,
options?: KvListOptions,
): NanoStream<SelectKvPairByPrefix<E, P>>
Retrieve a list of keys in the database. The returned list is a NanoStream which can be used to iterate over the entries in the database. Each list operation must specify a selector which is used to specify the range of keys to return. The selector can either be a prefix selector, or a range selector:
- A prefix selector selects all keys that start with the given prefix of key parts. For example, the selector ["users"] will select all keys that start with the prefix ["users"], such as ["users", "alice"] and ["users", "bob"]. Note that you can not partially match a key part, so the selector ["users", "a"] will not match the key ["users", "alice"]. A prefix selector may specify a start key that is used to skip over keys that are lexicographically less than the start key.
- A range selector selects all keys that are lexicographically between the given start and end keys (including the start, and excluding the end). For example, the selector ["users", "a"], ["users", "n"] will select all keys that start with the prefix ["users"] and have a second key part that is lexicographically between a and n, such as ["users", "alice"], ["users", "bob"], and ["users", "mike"], but not ["users", "noa"] or ["users", "zoe"].
Type Parameters
- K extends KvKey
- P extends KvKey | []
Parameters
- selector: KvListSelector<K, P>
- options: KvListOptions = {}
Returns NanoStream<SelectKvPairByPrefix<E, P>>
See
The options argument can be used to specify additional options for the list operation. See the documentation for KvListOptions for more information.
Implementation of KvApi.list
- Defined in index.ts:474

listenQueue

listenQueue<Ks extends [] | Q["key"][]>(
...keys: Ks,
): NanoStream<{ [N in number]: SelectKvPair<Q, Ks[N]> }[keyof Ks & number]>
Listen for queue values to be delivered from the database queue, which were enqueued with AtomicOperation.enqueue, you can spcify which keys to listen to.

You need to use AtomicOperation.dequeue to dequeue values from the queue after you have received and processed them, or you will get duplicates in next time you call this method.
Type Parameters
- Ks extends [] | Q["key"][]
Parameters
- ...keys: Ks
  The keys to listen to.
Returns NanoStream<{ [N in number]: SelectKvPair<Q, Ks[N]> }[keyof Ks & number]>
A readable stream of key-value pairs.
Implementation of KvApi.listenQueue
- Defined in index.ts:597

set

set<K extends KvKey>(
    key: K,
    value: ValueFotKvPair<E, K>,
    options?: { expireIn?: number; signal?: AbortSignal },
): Promise<KvCommitResult | KvCommitError>
Set the value for the given key in the database. If a value already exists for the key, it will be overwritten.

Optionally an expireIn option can be specified to set a time-to-live (TTL) for the key. The TTL is specified in milliseconds, and the key will be deleted from the database at earliest after the specified number of milliseconds have elapsed. Once the specified duration has passed, the key may still be visible for some additional time. If the expireIn option is not specified, the key will not expire.
Type Parameters
- K extends KvKey
Parameters
- key: K
  The key to set.
- value: ValueFotKvPair<E, K>
  The value to set.
- options: { expireIn?: number; signal?: AbortSignal } = {}
  Options for the set operation.
  - OptionalexpireIn?: number
    The number of milliseconds after which the key-value entry will expire.
  - Optionalsignal?: AbortSignal
Returns Promise<KvCommitResult | KvCommitError>
Implementation of KvApi.set
- Defined in index.ts:444

subspace

subspace<P extends KvKey | []>(
prefix: P,
): KvApi<RemoveKvPairPrefix<E, P>, RemoveKvPairPrefix<Q, P>>
Get a subspace of the database, operating on all key with the given prefix.
Type Parameters
- P extends KvKey | []
Parameters
- prefix: P
Returns KvApi<RemoveKvPairPrefix<E, P>, RemoveKvPairPrefix<Q, P>>
Implementation of KvApi.subspace
- Defined in index.ts:646

watch

watch<Ks extends [] | E["key"][]>(
    keys: Ks,
): NanoStream<
    {
        [N in string
        | number
        | symbol]: KvPairMaybe<SelectKvPair<E, Ks[N<N>]>>
    },
>
Watch for changes to the given keys in the database. The returned stream is a NanoStream that emits a new value whenever any of the watched keys change their versionstamp. The emitted value is an array of KvEntryMaybe objects, with the same length and order as the keys array. If no value exists for a given key, the returned entry will have a null value and versionstamp.

The returned stream does not return every single intermediate state of the watched keys, but rather only keeps you up to date with the latest state of the keys. This means that if a key is modified multiple times quickly, you may not receive a notification for every single change, but rather only the latest state of the key.
Type Parameters
- Ks extends [] | E["key"][]
Parameters
- keys: Ks
  An array of keys to watch for changes.
Returns NanoStream<
    {
        [N in string
        | number
        | symbol]: KvPairMaybe<SelectKvPair<E, Ks[N<N>]>>
    },
>
Implementation of KvApi.watch
- Defined in index.ts:534

Class NanoKV<E, Q>

Example

Type Parameters

Implements

Index

Constructors

Properties

Methods

Constructors

constructor

Type Parameters

Parameters

Returns NanoKV<E, Q>

Properties

Readonlyendpoint

Methods

atomic

Returns AtomicOperation<E, Q>

delete

Parameters

Returns Promise<KvCommitResult | KvCommitError>

get

Type Parameters

Parameters

Returns Promise<KvPairMaybe<SelectKvPair<E, K>>>

getMany

Type Parameters

Parameters

Returns Promise< { [N in string | number | symbol]: KvPairMaybe<SelectKvPair<E, Ks[N<N>]>> },>

list

Type Parameters

Parameters

Returns NanoStream<SelectKvPairByPrefix<E, P>>

See

listenQueue

Type Parameters

Parameters

Returns NanoStream<{ [N in number]: SelectKvPair<Q, Ks[N]> }[keyof Ks & number]>

set

Type Parameters

Parameters

OptionalexpireIn?: number

Optionalsignal?: AbortSignal

Returns Promise<KvCommitResult | KvCommitError>

subspace

Type Parameters

Parameters

Returns KvApi<RemoveKvPairPrefix<E, P>, RemoveKvPairPrefix<Q, P>>

watch

Type Parameters

Parameters

Returns NanoStream< { [N in string | number | symbol]: KvPairMaybe<SelectKvPair<E, Ks[N<N>]>> },>

Settings

On This Page

`Readonly`endpoint

Returns Promise<
{
[N in string
| number
| symbol]: KvPairMaybe<SelectKvPair<E, Ks[N<N>]>>
},
>

`Optional`expireIn?: number

`Optional`signal?: AbortSignal

Returns NanoStream<
{
[N in string
| number
| symbol]: KvPairMaybe<SelectKvPair<E, Ks[N<N>]>>
},
>