npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@prezentor/dexie-syncable

v1.0.0-beta.7

Published

Addon to Dexie that makes it possible to sync indexeDB with remote databases.

Downloads

2

Readme

Dexie.Syncable.js

Enables two-way synchronization with remote database.

Install

npm install dexie --save
npm install '@prezentor/dexie-observable' --save
npm install '@prezentor/dexie-syncable' --save

Use

import Dexie from 'dexie';
import 'dexie-syncable'; // will import dexie-observable as well.

// Use Dexie as normally - but you can also register your sync protocols though
// Dexie.Syncable.registerSyncProtocol() api as well as using the db.syncable api
// as documented here.

Dependency Tree

Tutorial

1. Include Required Sources

In your HTML, make sure to include Dexie.js, Dexie.Observable.js, Dexie.Syncable.js and an implementation of ISyncProtocol.

<html><head>
    <script src="dexie.min.js"></script>
    <script src="dexie-observable.min.js"></script>
    <script src="dexie-syncable.min.js"></script>
    <script src="WebSocketSyncProtocol.js"></script> <!-- Example implementation of ISyncProtocol -->
    ...
</head><body>
</body></html>
Usage with existing DB

In case you want to use Dexie.Syncable with your existing database, but do not want to use UUID based Primary Keys as described below, you will have to do a schema upgrade. Without it Dexie.Syncable will not be able to properly work.

import Dexie from 'dexie';
import 'dexie-observable';
import 'dexie-syncable';
import 'your-sync-protocol-implementation';

var db = new Dexie('myExistingDb');
db.version(1).stores(... existing schema ...);

// Now, add another version, just to trigger an upgrade for Dexie.Syncable
db.version(2).stores({}); // No need to add / remove tables. This is just to allow the addon to install its tables.

2. Use UUID based Primary Keys ($$)

Two way replication cannot use auto-incremented keys if any sync node should be able to create objects no matter if it is offline or online. Dexie.Syncable comes with a new syntax when defining your store schemas: the double-dollar prefix ($$). Similarly to the ++ prefix in Dexie (meaning auto-incremented primary key), the double-dollar prefix means that the key will be given a universally unique identifier (UUID), in string format (For example "9cc6768c-358b-4d21-ac4d-58cc0fddd2d6").

var db = new Dexie("MySyncedDB");
db.version(1).stores({
    friends: "$$oid,name,shoeSize",
    pets: "$$oid,name,kind"
});

3. Connect to Server

You must specify the URL of the server you want to keep in-sync with. This has to be done once in the entire database life-time, but doing it on every startup is ok as well, since it won't affect already connected URLs.

// This example uses the WebSocketSyncProtocol included in earlier steps.
db.syncable.connect ("websocket", "https://syncserver.com/sync");
db.syncable.on('statusChanged', function (newStatus, url) {
    console.log ("Sync Status changed: " + Dexie.Syncable.StatusTexts[newStatus]);
});

4. Use Your Database

Query and modify your database as if it was a simple Dexie instance. Any changes will be replicated to the server and changes on the server or an other window will replicate back to you.

db.transaction('rw', db.friends, function (friends) {
    friends.add({name: "Arne", shoeSize: 47});
    friends.where('shoeSize').above(40).each(function (friend) {
        console.log("Friend with shoeSize over 40: " + friend.name);
    });
});

NOTE: Transactions only provide the Atomicity part of the ACID properties when using 2-way synchronization. This is due to the fact that the syncronization phase may result in another change overwriting the changes. However, it's still meaningful to use the transaction() method for atomicity. Atomicity is guaranteed not only locally but also when synced to the server, meaning that a part of the changes will never commit on the server until all changes from the transaction have been synced. In practice, you cannot increment a counter in the database (for example) and expect it to be consistent, but you can have a guaranteed that if you add a sequence of objects, all or none of them will replicate.

API Reference

Static Members

Dexie.Syncable.registerSyncProtocol (name, protocolInstance) Define how to replicate changes with your type of server.

Dexie.Syncable.Statuses Enum of possible sync statuses, such as OFFLINE, CONNECTING, ONLINE and ERROR.

Dexie.Syncable.StatusTexts Text lookup for status numbers

Non-Static Methods and Events

db.syncable.connect (protocol, url, options) Create a persistend two-way sync connection with the given URL.

db.syncable.disconnect (url) Stop syncing with the given URL but keep revision states until next connect.

db.syncable.delete(url) Delete all states and change queue for given URL.

db.syncable.list() List the URLs of each remote node we have a state saved for.

db.syncable.on('statusChanged') Event triggered when sync status changes.

db.syncable.setFilter ([criteria], filter) Ignore certain objects from being synced defined by the given filter.

db.syncable.getStatus (url) Get sync status for the given URL.

db.syncable.getOptions (url) Get the options object for the given URL.

Source

Dexie.Syncable.js

Description

Dexie.Syncable enables synchronization with a remote database (of almost any kind). It has its own API ISyncProtocol. The ISyncProtocol is pretty straight-forward to implement. The implementation of that API defines how client- and server- changes are transported between local and remote nodes. The API support both poll-patterns (such as ajax calls) and direct reaction pattern (such as WebSocket or long-polling methods). See samples below for each pattern.

Sample ISyncProtocol Implementations

Sample Sync Servers