isync

A straightforward and zero-dependency NodeJS module to automatically persist JavaScript objects to disk at intervals, in JSON.

Released under the terms of the Beerware license.

Contact me on Telegram at @kuvam.

Installation

npm install isync --save

Usage

1. Load isync.

const isync = require('isync')

2. Create an instance of isync. (If the file already exists, isync will attempt to synchronously parse it as JSON to the data property.)

const store = new isync('./store.json')

3. (a) Use the data property as a plain-jane JavaScript object.

store.data.x = "foo"
store.data.y = [3, "bar", false]
store.data.z = { baz: store.data.x + "d", _: [null] }

3. (b) Alternatively, set it to an existing object you want to persist.

const blob = { pi: 22 / 7, e: [2, 7, 1, 8] }
store.data = blob

4. The data object will be automatically synced at the specified interval (defaults to 10 minutes if unspecified) while your NodeJS program is running.

5. Before exiting, flush any last-minute changes manually using flushSync().

store.flushSync()

Details

1. An instance of isync is initialised with this constructor signature.

new isync(path: String, period?: Number)

The period is specified in minutes and optional (defaults to 10 minutes).

2. Instances expose the following properties.

path

File path which this isync instance saves the data object to. Change it by assigning a new file path to this property.

data

A regular JavaScript object, which is serialised as JSON and synced to the file path specified. Properties which aren't JSON-serialisable won't be saved to disk.

period

The interval in minutes at which to flush the data object to disk. Change this interval by setting this property; its value will be used from the next sync onwards.

3. Instances expose the following methods.

unlink()

Stops syncing the data object to disk at intervals. You can still use it as you would, but changes since the last sync won't be saved automatically.

link()

Restarts syncing the data object, after a call to unlink(). (You don't need to call this if you haven't unlinked the instance; by default, newly initialised instances of isync will be syncing automatically.)

flushSync()

Force a synchronous (thread blocking) flush of the data object to disk, even if the instance is unlinked. It is necessary to call this before your NodeJS application exits, unless you're absolutely sure there have been no changes to data since the last sync.

flush(link: Boolean)

An asynchronous (non-blocking) call to save the data object to disk, even if the instance is unlinked. If the link parameter is set, calls link() on this instance after completion.

Bear in mind that you can't await this call; however, you can listen on the next 'flush' event after making this call to proceed whenever the flush is completed.

4. You can listen on 'flush' events on an isync instance (store in this example) using idiomatic NodeJS events.

store.on('flush', callback)

This event is emitted on completion of both manual and automatic syncs. You can use it to confirm that data has been saved to disk successfully or to log disk syncs.

❤️   June, 2017  –  March, 2019.