Yjs LevelDB Persistence Adapter

Common errors

• TypeError: LeveldbPersistence is not a constructor

  cause 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

  cause 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'

  cause 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'

  cause 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).

Warnings

• breaking Version `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.
• gotcha The `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).
• gotcha The `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.
• gotcha The 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.

Install

• npm install y-leveldb npm
• yarn add y-leveldb yarn
• pnpm add y-leveldb pnpm

Imports

• LeveldbPersistence
  wrong:

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

  correct:

  import { LeveldbPersistence } from '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.
• Y
  wrong:

  import Y from 'yjs'

  correct:

  import * as 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
  wrong:

  const level = require('level-mem')

  correct:

  import level from '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.

Quickstart

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)