y-leveldb

library0.2.0jsnpmunverified

y-leveldb is a persistence adapter for Yjs, the CRDT framework for real-time collaboration. It enables storing Yjs document updates persistently using LevelDB and its compatible implementations (like RocksDB, LMDB, or `level-mem`). The current stable version is `0.2.0`. Releases are infrequent but address compatibility, dependency updates, and bug fixes. Key differentiators include its flexibility to use various LevelUP-compatible storage backends, its direct integration into Yjs ecosystems (e.g., `y-websocket`), and its ability to manage multiple Yjs documents within a single database instance. The library provides a granular API for storing and retrieving document updates, state vectors, and custom metadata without necessarily hydrating a full Y.Doc object, which is crucial for efficient server-side synchronization and data management.

database communication

npm install y-leveldb

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · Y-LEVELDB

y-leveldb

databasejavascriptv0.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

LeveldbPersistence

✓ import { LeveldbPersistence } from 'y-leveldb'

✗ const { LeveldbPersistence } = require('y-leveldb')

Primarily designed for ESM. While CommonJS might work with transpilation or specific Node.js loader setups, native ESM import is the idiomatic approach.

✓ import * as Y from 'yjs'

✗ import Y from 'yjs'

Yjs exports its API as a namespace object; destructuring or a default import is generally incorrect for the core Y object.

level

✓ import level from 'level-mem'

✗ const level = require('level-mem')

When providing a custom LevelUP-compatible adapter, import it directly. This example uses `level-mem` for in-memory persistence, which is a named export from the module.

This quickstart demonstrates how to initialize `y-leveldb`, store a Yjs document's state, and then retrieve it from the persistent storage, including setting and getting metadata. It shows basic CRUD operations for Yjs documents.

import * as Y from 'yjs' import { LeveldbPersistence } from 'y-leveldb' // Create a persistence instance pointing to a storage location. // For in-memory, you could pass { level: require('level-mem') } as the second argument. const persistence = new LeveldbPersistence('./yjs-storage') async function runExample() { // Create a new Yjs document and make some changes. const ydoc = new Y.Doc() const yarray = ydoc.getArray('my-array') yarray.insert(0, ['item 1', 'item 2']) yarray.push(['item 3']) console.log('Initial Y.Doc content:', yarray.toArray()) // Store the current state of 'my-doc' to LevelDB. await persistence.storeUpdate('my-doc', Y.encodeStateAsUpdate(ydoc)) console.log('Document state stored.') // To retrieve data or sync, create a temporary Y.Doc from persistence. const persistedYDoc = await persistence.getYDoc('my-doc') const persistedYarray = persistedYDoc.getArray('my-array') console.log('Retrieved Y.Doc content:', persistedYarray.toArray()) // Example of retrieving metadata await persistence.setMeta('my-doc', 'owner', 'Alice') const owner = await persistence.getMeta('my-doc', 'owner') console.log('Document owner:', owner) // Clean up example data (optional) // await persistence.clearDocument('my-doc') // console.log('Document cleared.') } runExample().catch(console.error)

Debug

Known issues

breakingVersion `0.2.0` upgraded the underlying `level` dependency from version 6.x to 8.x. Users who directly interact with or pass custom `level` instances might encounter breaking changes due to API differences in `level` itself. Ensure compatibility if you rely on specific `level` versions or APIs.

fix

Review the changelog for the `level` package between v6 and v8 and update your custom `level` client code or configurations accordingly. Ensure your direct `level` dependencies are compatible with the version `y-leveldb` now expects.

affects: >=0.2.0

gotchaThe `getAllDocStateVectors` method returns state vectors that "might be outdated if the associated document is not yet flushed." Relying on these state vectors for critical synchronization without understanding the internal flushing mechanism can lead to inconsistent states. Use with caution for real-time synchronization.

fix

For highly critical synchronization or to ensure the most up-to-date state, retrieve the full `Y.Doc` using `getYDoc` and then encode its state, or ensure `flushDocument` has been called if you manually manage flushes (though `flushDocument` is generally not needed in production).

affects: >=0.1.0

gotchaThe `flushDocument` method is explicitly marked as 'dev only' and generally not recommended for regular use. Calling it unnecessarily could impact performance or lead to unexpected behavior if not fully understood.

fix

Avoid using `flushDocument` in production code unless you have a specific, well-understood need for it and have thoroughly tested its implications on your application's data integrity and performance.

affects: >=0.1.0

gotchaThe package has a peer dependency on `yjs` version `^13.0.0`. Incompatible versions of `yjs` can lead to runtime errors, unexpected behavior, or subtle data corruption due to mismatches in update formats or CRDT logic.

fix

Always ensure that `yjs` is installed in your project and matches the peer dependency version range specified (e.g., `npm install yjs@^13.0.0`). Check `npm ls yjs` to verify your installed version.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: LeveldbPersistence is not a constructor

Attempting to import `LeveldbPersistence` using CommonJS `require()` syntax in an environment expecting ESM, or using incorrect destructuring.

fix

Ensure you are using the correct ESM import: `import { LeveldbPersistence } from 'y-leveldb'`. If running in a pure CommonJS environment, ensure Node.js can resolve ESM modules or consider transpilation.

Error: Peer dependency yjs@^13.0.0 not met

The `yjs` package is either not installed or an incompatible version is installed in the project.

fix

Install the correct version of `yjs`: `npm install yjs@^13.0.0`. Verify with `npm ls yjs`.

Error: EACCES: permission denied, open './storage-location/manifest'

The Node.js process does not have sufficient read/write permissions for the specified `storageLocation` directory or its parent. This is common on servers when trying to write to `/` or system-protected directories.

fix

Change the `storageLocation` to a path where the Node.js process has full read/write permissions (e.g., a subdirectory within your application's data folder) or adjust the file system permissions for the target directory.

Error: Could not find module 'level-mem'

When providing a custom `level` adapter (e.g., `level-mem`), the adapter package itself must be installed as a dependency.

fix

Install the missing `level` adapter package: `npm install level-mem` (or the specific adapter you intend to use).

Upgrade

Version history

0.2.0latest on npm

Audit

Dependencies

yjsrequiredCore Yjs library for CRDT functionality and document updates.

Agent activity

40 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/yjs/y-leveldb ↗

packagehttps://www.npmjs.com/package/y-leveldb ↗

homepagehttps://yjs.dev ↗