# y-leveldb

> LevelDb database adapter for Yjs

Latest version **0.2.0** (published 2025-04-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install y-leveldb
pnpm add y-leveldb
yarn add y-leveldb
bun add y-leveldb
```

## Health

**Score 50/100 (C)** — status: stable.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 0.2.0 |
| Published | 2025-04-23 |
| First published | 2016-08-04 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 2.5 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 115 |
| Author | Kevin Jahns |
| Maintainers | dmonad |
| Keywords | Yjs, CRDT, offline, shared editing, collaboration, concurrency |

## Links

- npm: https://www.npmjs.com/package/y-leveldb
- Repository: https://github.com/yjs/y-leveldb
- Homepage: https://yjs.dev
- Issues: https://github.com/yjs/y-leveldb/issues
- Funding: https://github.com/sponsors/dmonad
- npm.io page: https://npm.io/package/y-leveldb

## Dependencies (3)

- [lib0](https://npm.io/package/lib0.md) ^0.2.31
- [level](https://npm.io/package/level.md) ^8.0.1
- [level-read-stream](https://npm.io/package/level-read-stream.md) ^2.0.0

## Alternatives

- [localforage](https://npm.io/package/localforage.md) — 6.2M weekly downloads
- [localforage-observable](https://npm.io/package/localforage-observable.md) — 30.8K weekly downloads
- [@y/y](https://npm.io/package/@y/y.md) — 30.1K weekly downloads
- [@metaobjectsdev/render](https://npm.io/package/@metaobjectsdev/render.md) — 3.5K weekly downloads
- [@ledgerhq/coin-algorand](https://npm.io/package/@ledgerhq/coin-algorand.md) — 1.1K weekly downloads

## Recent versions

- 0.2.0 (latest) — 2025-04-23
- 0.1.2 — 2023-01-16
- 0.1.1 — 2021-11-30
- 0.1.0 — 2020-07-09
- 0.0.3 — 2017-10-30
- 0.0.2 — 2017-10-30
- 0.0.1 — 2016-09-20
- 0.0.0 — 2016-08-04

## README

# LevelDB database adapter for [Yjs](https://github.com/yjs/yjs)

LevelDB is a fast embedded database. It is the underlying technology of IndexedDB.

Internally, y-leveldb uses [`level`](https://github.com/Level/level) which
allows to exchange the storage medium for a different supported database.
Hence this adapter also supports rocksdb, lmdb, and many more..

* Persistent storage for the server
* Exchangeable storage medium
* Can be used in [y-websocket](https://github.com/yjs/y-websocket)
* A single y-leveldb instance can handle many documents.

## Use it

```sh
npm install y-leveldb --save
```

```js
import * as Y from 'yjs'
import { LeveldbPersistence } from 'y-leveldb'

const persistence = new LeveldbPersistence('./storage-location')

const ydoc = new Y.Doc()
ydoc.getArray('arr').insert(0, [1, 2, 3])
ydoc.getArray('arr').toArray() // => [1, 2, 3]

// store document updates retrieved from other clients
persistence.storeUpdate('my-doc', Y.encodeStateAsUpdate(ydoc))

// when you want to sync, or store data to a database,
// retrieve the temporary Y.Doc to consume data
const ydocPersisted = await persistence.getYDoc('my-doc')
ydocPersisted.getArray('arr') // [1, 2, 3]
```

## API

### `persistence = LeveldbPersistence(storageLocation, [{ [level] }])`

Create a y-leveldb persistence instance.

You can use any levelup-compatible adapter.

```js
import { LeveldbPersistence } from 'y-leveldb'
import level from 'level-mem'

const persistence = new LeveldbPersistence('./storage-location', { level })
```

#### `persistence.getYDoc(docName: string): Promise<Y.Doc>`

Create a Y.Doc instance with the data persisted in leveldb. Use this to
temporarily create a Yjs document to sync changes or extract data.

#### `persistence.storeUpdate(docName: string, update: Uint8Array): Promise`

Store a single document update to the database.

#### `persistence.getStateVector(docName: string): Promise<Uint8Array>`

The state vector (describing the state of the persisted document - see
[Yjs docs](https://github.com/yjs/yjs#Document-Updates)) is maintained in a separate
field and constantly updated.

This allows you to sync changes without actually creating a Yjs document.

#### `persistence.getDiff(docName: string, stateVector: Uint8Array): Promise<Uint8Array>`

Get the differences directly from the database. The same as
`Y.encodeStateAsUpdate(ydoc, stateVector)`.

#### `persistence.clearDocument(docName: string): Promise`

Delete a document, and all associated data from the database.

#### `persistence.setMeta(docName: string, metaKey: string, value: any): Promise`

Persist some meta information in the database and associate it with a document.
It is up to you what you store here. You could, for example, store credentials
here.

#### `persistence.getMeta(docName: string, metaKey: string): Promise<any|undefined>`

Retrieve a store meta value from the database. Returns undefined if the
`metaKey` doesn't exist.

#### `persistence.delMeta(docName: string, metaKey: string): Promise`

Delete a store meta value.

#### `persistence.getAllDocNames(docName: string): Promise<Array<string>>`

Retrieve the names of all stored documents.

#### `persistence.getAllDocStateVectors(docName: string): Promise<Array<{ name:string,clock:number,sv:Uint8Array}`

Retrieve the state vectors of all stored documents. You can use this to sync
two y-leveldb instances.

Note: The state vectors might be outdated if the associated document is not
yet flushed. So use with caution.

#### `persistence.flushDocument(docName: string): Promise` (dev only)

Internally y-leveldb stores incremental updates. You can merge all document
updates to a single entry. You probably never have to use this.

## License

y-leveldb is licensed under the [MIT License](./LICENSE).

<kevin.jahns@protonmail.com>

---
_Source: https://npm.io/package/y-leveldb · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._