@deno/kv

!https://github.com/denoland/denokv/actions

A Deno KV client library optimized for Node.js.

- Access Deno Deploy remote databases (or any
endpoint implementing the open
KV Connect
protocol) on Node 18+.
- Create local KV databases backed by
SQLite, using optimized native
NAPI packages for
Node - compatible with databases created by Deno itself.
- Create ephemeral in-memory KV instances backed by SQLite memory files or by a
lightweight JS-only implementation for testing.
- Zero JS dependencies, architecture-specific native code for SQLite backend
(see below).
- Simply call the exported openKv function (equiv to
Deno.openKv) with a url or
local path to get started!

$3

_Install the npm package_ 👉
npm install @deno/kv

_Remote KV Database_

``js
import { openKv } from "@deno/kv";

// to open a database connection to an existing Deno Deploy KV database,
// first obtain the database ID from your project dashboard:
// https://dash.deno.com/projects/YOUR_PROJECT/kv

// connect to the remote database
const kv = await openKv(
"https://api.deno.com/databases/YOUR_DATABASE_ID/connect",
);
// access token for auth is the value of environment variable DENO_KV_ACCESS_TOKEN by default

// do anything using the KV api: https://deno.land/api?s=Deno.Kv&unstable
const result = await kv.set(["from-client"], "hello!");
console.log(result);

// close the database connection
kv.close();

// to provide an explicit access token, pass it as an additional option
const kv2 = await openKv(
"https://api.deno.com/databases/YOUR_DATABASE_ID/connect",
{ accessToken: mySecretAccessToken },
);
`

_Local KV Database_

`js
import { openKv } from "@deno/kv";

// create a local KV database instance backed by SQLite
const kv = await openKv("kv.db");

// do anything using the KV api: https://deno.land/api?s=Deno.Kv&unstable
const result = await kv.set(["from-client"], "hello!");
console.log(result);

// close the database connection
kv.close();
`

_In-Memory KV Database (no native code)_

`js
import { openKv } from "@deno/kv";

// create an ephemeral KV instance for testing
const kv = await openKv("");

// do anything using the KV api: https://deno.land/api?s=Deno.Kv&unstable
const result = await kv.set(["from-client"], "hello!");
console.log(result);

// close the database connection
kv.close();
`

> Examples use ESM syntax, but this package supports CJS require-based usage
> as well

$3

Local disk-based databases are backed by
SQLite, and are compatible with databases created
with Deno itself:

- leverages shared Rust code from
denoland/denokv with a small shim
compiled for Node's native interface via the NAPI-RS
framework
- an architecture-specific native package dependency is selected and installed
at npm install time via the standard npm
peer dependency mechanism

The following native architectures are supported:

| | node18 | node20 |
| ------------- | ------ | ------ |
| Windows x64 | ✓ | ✓ |
| macOS x64 | ✓ | ✓ |
| macOS arm64 | ✓ | ✓ |
| Linux x64 gnu | ✓ | ✓ |

$3

- Protobuf code generated with pb
- npm package generated with dnt
- Initial code contributed by
skymethod/kv-connect-kit

---

$3

This package exports a single convenience function openKv, taking an optional
string path, with optional opts. Depending on the path provided, one of
three different implementations are used:

- if path is omitted or blank, an ephemeral in-memory db implementation is
used, useful for testing
- if path is an http or https url, the remote client implementation is used
to connect to Deno Deploy or self-hosted
denokv instances
- otherwise the path is passed to the native sqlite implementation - can
specify local paths or :memory: for SQLite's
in-memory mode

You can override the implementation used via the implementation option:

`js
const kv = await openKv("https://example.com/not-really-remote", {
implementation: "in-memory",
});
`

Pass the debug option to console.log additional debugging info:

`js
const kv = await openKv("http://localhost:4512/", {
debug: true
});
`

$3

Each implementation supports different additional options,
via the second parameter to openKv:

Remote backend

`ts
export interface RemoteServiceOptions {
/* Access token used to authenticate to the remote service /
readonly accessToken: string;

/** Wrap unsupported V8 payloads to instances of UnknownV8 instead of failing.
*
Only applicable when using the default serializer. /
readonly wrapUnknownValues?: boolean;

/* Enable some console logging /
readonly debug?: boolean;

/** Custom serializer to use when serializing v8-encoded KV values.
*
When you are running on Node 18+, pass the 'serialize' function in Node's 'v8' module. /
readonly encodeV8?: EncodeV8;

/** Custom deserializer to use when deserializing v8-encoded KV values.
*
When you are running on Node 18+, pass the 'deserialize' function in Node's 'v8' module. /
readonly decodeV8?: DecodeV8;

/** Custom fetcher to use for the underlying http calls.
*
* Defaults to global 'fetch'
*/
readonly fetcher?: Fetcher;

/* Max number of times to attempt to retry certain fetch errors (like 5xx) /
readonly maxRetries?: number;

/* Limit to specific KV Connect protocol versions /
readonly supportedVersions?: KvConnectProtocolVersion[];
}
``

Native SQLite backend

`ts
export interface NapiBasedServiceOptions {
/* Enable some console logging /
readonly debug?: boolean;

/* Underlying native napi interface /
readonly napi?: NapiInterface;

/** Custom serializer to use when serializing v8-encoded KV values.
*
When you are running on Node 18+, pass the 'serialize' function in Node's 'v8' module. /
readonly encodeV8: EncodeV8;

/** Custom deserializer to use when deserializing v8-encoded KV values.
*
When you are running on Node 18+, pass the 'deserialize' function in Node's 'v8' module. /
readonly decodeV8: DecodeV8;

/* The database will be opened as an in-memory database. /
readonly inMemory?: boolean;
}
`

Lightweight In-Memory backend

`ts
export interface InMemoryServiceOptions {
/* Enable some console logging /
readonly debug?: boolean;

/* Maximum number of attempts to deliver a failing queue message before giving up. Defaults to 10. /
readonly maxQueueAttempts?: number;
}
`

$3

This package is targeted for Node.js, but may work on other runtimes with the following caveats:

V8 Serialization

Deno KV uses V8's serialization format to serialize values, provided natively by Deno and when using this
package on Node automatically via the built-in v8 module.

Bun also provides a v8 module, but uses a different serialization format under the hood (JavaScriptCore).

This can present data corruption problems if you want to use databases on Deno Deploy or other databases shared
with Node/Deno that use actual V8 serialization: you might create data you cannot read, or vice versa.

For this reason, openKV on Bun will throw by default to avoid unexpected data corruption.

If you are only going to read and write to your local databases in Bun, you can force the use of Bun's serializers by providing
a custom encodeV8, decodeV8 explicitly as the second parameter to openKv. Note any data will be unreadable by
Node (using @deno/kv), or Deno - since they use the actual V8 format.

`js
import { openKv } from "@deno/kv";
import { serialize as encodeV8, deserialize as decodeV8 } from "v8"; // actually JavaScriptCore format on Bun!

const kv = await openKv("kv.db", { encodeV8, decodeV8 });
`

If a native v8 module is not available on your runtime, you can use a limited JS-based V8 serializer provided by this package.
It only supports a limited number of value types (string, boolean, null, undefined), so consider using JSON.parse/JSON.stringify
to marshall values to and from strings for storage.

`js
import { openKv, makeLimitedV8Serializer } from "@deno/kv";

const { encodeV8, decodeV8 } = makeLimitedV8Serializer();

const kv = await openKv("kv.db", { encodeV8, decodeV8 });
`

V8 serialization is only necessary for SQLite and remote databases, the in-memory implementation
used when calling openKv() or openKv('')` uses in-process values and structuredClone
instead.