dexie-observable

library4.0.1-beta.13jsnpmunverified

Dexie.Observable is an addon for Dexie.js that significantly enhances IndexedDB functionality by enabling cross-window and cross-instance database change observation. It introduces an event mechanism, similar to `localStorage`'s `onstorage`, specifically for IndexedDB, allowing web applications to react in real-time to data modifications, irrespective of the originating tab or worker. This ensures views remain synchronized and up-to-date across all connected clients. The package is an integral part of the Dexie.js ecosystem, fully compatible with Dexie v4.x, and typically releases in alignment with Dexie.js's maintenance and feature updates. Although the package version provided is `4.0.1-beta.13`, it functions within the broader stable Dexie v4 environment. Furthermore, it forms the foundational layer for `Dexie.Syncable.js`, which provides robust two-way data replication capabilities with remote servers.

database

npm install dexie-observable

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · DEXIE-OBSERVABLE

dexie-observable

databasejavascriptv4.0.1-beta.13

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.

Dexie

✓ import Dexie from 'dexie'; import 'dexie-observable';

✗ import { Dexie } from 'dexie'; import { DexieObservable } from 'dexie-observable';

Dexie itself is typically a default import. `dexie-observable` is imported for its side-effects, extending the Dexie prototype, so there are no named exports to import directly from 'dexie-observable'.

db.on('changes')

✓ db.on('changes', (changes) => { /* handle changes */ });

✗ db.on('change', () => { /* ... */ });

The event name is 'changes' (plural), not 'change', and the callback receives an array of `DatabaseChange` objects.

$$uuid primary key

✓ db.version(1).stores({ friends: '$$uuid,name' });

✗ db.version(1).stores({ friends: 'uuid,name' });

Use the `$$` prefix for the primary key to automatically generate UUIDs when adding new objects. Without `$$`, 'uuid' would be a regular indexed property.

This example demonstrates how to initialize Dexie with the observable addon, define a store using UUID primary keys, and subscribe to the `db.on('changes')` event to react to database modifications, including those from other browser windows.

import Dexie from 'dexie'; import 'dexie-observable'; // Enables db.on('changes') const db = new Dexie('ObservableTestDB'); db.version(1).stores({ friends: '$$uuid,name,age' }); // Subscribe to database changes across all windows/instances db.on('changes', (changes) => { console.log('Database changes detected:'); changes.forEach((change) => { switch (change.type) { case 1: // CREATED console.log(`CREATED: ${JSON.stringify(change.obj)}`); break; case 2: // UPDATED console.log(`UPDATED: Old: ${JSON.stringify(change.oldObj)}, New: ${JSON.stringify(change.obj)}`); break; case 3: // DELETED console.log(`DELETED: ${JSON.stringify(change.oldObj)}`); break; } }); }); async function addFriend() { await db.friends.add({ name: 'Alice', age: 30 }); console.log('Added Alice. Check other browser tabs!'); await db.friends.add({ name: 'Bob', age: 25 }); console.log('Added Bob. Check other browser tabs!'); } addFriend();

Debug

Known issues

breakingWhen integrating `dexie-observable` with an existing Dexie database, a schema upgrade is mandatory to allow the addon to install its internal tables. Failing to do so will prevent `dexie-observable` from functioning correctly.

fix

Add a new version to your database schema, even if it's an empty `db.version(X).stores({});` entry, after your existing schema. This triggers the necessary upgrade logic.

affects: >=3.0.0

gotchaThe `dexie-observable` package is primarily imported for its side-effects, meaning it extends the Dexie prototype directly. There are no named exports from 'dexie-observable' itself that you would typically import and use directly.

fix

Use `import 'dexie-observable';` after `import Dexie from 'dexie';`. Any functionality, like `db.on('changes')`, will then be available on your Dexie database instance.

affects: >=3.0.0

gotchaThe package version `4.0.1-beta.13` indicates it is a beta release. While generally stable for use with Dexie v4, users should be aware that it's not a final major release and could potentially introduce minor changes before a stable 4.x version of the addon is officially released.

fix

Monitor the Dexie.js GitHub releases for a stable `dexie-observable` v4.x release, or use with caution in production environments, ensuring thorough testing.

affects: 4.0.1-beta.13

gotchaThe `$$` prefix for a primary key (e.g., `$$uuid`) is a special syntax introduced by `dexie-observable` to automatically generate UUID strings for that key. If you need a custom UUID generation logic, you can override `Dexie.createUUID`.

fix

To use a custom UUID generator, assign your function to `Dexie.createUUID = myCustomUUIDFunction;` before initializing your database. Ensure your custom function returns a unique string suitable for primary keys.

affects: >=3.0.0

Errors

Common errors & fixes

TypeError: db.on is not a function

`dexie-observable` has not been correctly imported and initialized, or the `db.on` method is being called before the addon has extended the Dexie prototype.

fix

Ensure `import Dexie from 'dexie';` is followed by `import 'dexie-observable';` in your module. Also, make sure you are calling `db.on()` on an instance of Dexie created *after* the import.

Changes not propagating across browser windows/tabs.

The required schema upgrade for `dexie-observable` to create its internal tables was not performed, or the browser's IndexedDB implementation is not firing the necessary events.

fix

If using an existing database, ensure you have added a new, empty version to your schema definition (`db.version(X).stores({});`) to trigger the addon's installation. Verify browser compatibility with cross-window IndexedDB events.

Upgrade

Version history

4.0.1-beta.13latest on npm

Audit

Dependencies

dexierequiredCore database library that dexie-observable extends.

Agent activity

15 hits · last 30 days

node

Resources

githubhttps://github.com/dexie/Dexie.js ↗

packagehttps://www.npmjs.com/package/dexie-observable ↗

homepagehttps://dexie.org ↗