DOCSEARCHbyAlgolia
Submit Docs

y-indexeddb

repository·master·Indexed 42 days ago

https://github.com/yjs/y-indexeddb

An IndexedDB database adapter for Yjs version 9.0.12 that enables persistent browser-based storage. It allows for offline editing and reduces network traffic by caching document state locally using the IndexeddbPersistence class.

Tokens
1.7K
Snippets
10
Records
10
Agent score
5%

What's inside y-indexeddb

  2. Get Started with IndexeddbPersistence

    master

    Use IndexeddbPersistence to store your shared Yjs data persistently in the browser. This enables offline editing and minimizes data exchange by loading existing content from IndexedDB when a session starts.

    To know when the local database has finished loading the document content, listen for the synced event.

    const provider = new IndexeddbPersistence(docName, ydoc)

provider.on('synced', () => {
  console.log('content from the database is loaded')
})

  3. Manage custom metadata with set(), get(), and del()

    master

    You can store custom meta-information for a persisted document directly on the provider instance.

    Warning: Data stored via these methods is local to the provider instance and will not be synced with other peers in the Yjs network.

    // Set a custom property
await provider.set(key: any, value: any);

// Retrieve a stored value
const value = await provider.get(key: any);

// Delete a stored value
await provider.del(key: any);

  4. Destroy the provider or clear database data

    master

    Use destroy() to stop syncing and close the database connection. This is automatically called when the associated Y.Doc is destroyed. Use clearData() to perform a complete wipe of the database, including the document and all associated metadata.

    // Close connection and stop syncing
await provider.destroy();

// Wipe the entire database for this provider
await provider.clearData();

  5. Initialize IndexeddbPersistence

    master

    Create a new persistence provider instance.

    docName should be a unique string identifying the document. It is recommended to use the same identifier used as the room-name in your connection provider to ensure consistency.

    provider = new IndexeddbPersistence(docName: string, ydoc: Y.Doc)

  6. Manage custom data in IndexeddbPersistence

    master

    In addition to persisting Yjs updates, IndexeddbPersistence exposes a custom object store. This allows you to store arbitrary key-value pairs alongside your Yjs document data within the same IndexedDB database.

    Available methods:

    • get(key): Retrieves a value associated with the key. Returns a Promise.
    • set(key, value): Sets a value for the given key. Returns a Promise.
    • del(key): Deletes the value associated with the key. Returns a Promise.
    // Assuming persistence is an instance of IndexeddbPersistence
await persistence.set('user-settings', { theme: 'dark' })
const settings = await persistence.get('user-settings')
await persistence.del('user-settings')

  7. Destroy IndexeddbPersistence and clear data

    master

    To prevent memory leaks and ensure database connections are closed, you should call destroy() when the persistence instance is no longer needed. If you want to completely wipe the IndexedDB database associated with a specific document name, use clearData().

    // Stop listening to updates and close the DB connection
await persistence.destroy()

// Destroy the instance AND delete the entire IndexedDB database for this name
await persistence.clearData()

  8. Use IndexeddbPersistence to persist Yjs documents

    master

    The IndexeddbPersistence class provides a way to automatically persist a Yjs Doc to IndexedDB. It listens for updates on the document and saves them to an updates store. When initialized, it fetches existing updates from IndexedDB and applies them to the document to ensure the local state is synchronized with the persisted state.

    Key features:

    • Automatic Sync: Automatically applies stored updates to the Doc on startup.
    • Sync Status: Emits a synced event when the document has been fully loaded from IndexedDB.
    • Custom Storage: Provides get, set, and del methods to interact with a custom store within the same IndexedDB database.
    • Lifecycle Management: Use destroy() to stop listening to updates and close the database connection, or clearData() to destroy the instance and wipe all data for that document name.
    import * as Y from 'yjs'
import { IndexeddbPersistence } from 'y-indexeddb'

const doc = new Y.Doc()
const persistence = new IndexeddbPersistence('my-document-name', doc)

// Wait for the document to be synced with IndexedDB
await persistence.whenSynced
console.log('Document is synced with IndexedDB')

// You can also listen to the 'synced' event
persistence.on('synced', () => {
  console.log('Synced!')
})

  9. Clear a document's IndexedDB database via clearDocument()

    master

    The clearDocument function allows you to delete an entire IndexedDB database by its name without needing an active IndexeddbPersistence instance.

    import { clearDocument } from 'y-indexeddb'

// Deletes the database named 'my-document-name'
await clearDocument('my-document-name')

  10. Listen for the 'synced' event

    master

    The synced event is fired when the connection to the IndexedDB database is established and all available content for the specified docName has been loaded into the Y.Doc. Note that this event also fires if no content is found for the given name.

    provider.on('synced', function(idbPersistence: IndexeddbPersistence))