A local JSON database with overlays
Local JSON DB is exclusively designed for local environments and testing purpose. Globally, it's a memory database using overlays and that can persist to JSON files.
Let's say you want a local environment for your HTML5 application (could be any other type of
application), but without the pain and overload of a VM or any other heavy install for a local API.
You could have for example an extremely simple
expresjs app delivering content hard-coded in that
fake API, or source from some JSON.
But then you need your developers to be able to save locally some different records than the ones shared by the fake API, while still using the constantly updated core records pushed to the VCS. You also want to be able to have some other specific data to run unit tests of your client for example.
local-json-db is here for that!
First of all, install it as a dependency of your project. In the root path of your project, run this:
npm install --save-dev local-json-db
Then, in your CoffeeScript file:
ljdb = require 'local-json-db'db = './data'dbaddOverlay 'local'dbcreateRecord 'user'name: 'Huafu'dbsave
var ljdb = ;var db = './data';db;db;db;
Full API documentation of
Database is here.
Here is the directory structure of your app:
app/ # all the client files, in our case HTML5 application for example mock-api/ lib/ # the simple API using `local-json-db` to provide read-only but also rw mocks data/ # the core json files containing the records shared in all overlays users.json posts.json local/ # ignored by the VCS, containing the overlays for local use only, # as for each developer for example
PROJECT_ROOT is a reference to the root directory of our project, when running the micro
fake API delivering mocks:
var db = PROJECT_ROOT + 'mock-api/data';db; // relative to the path given in new Database()
You'll then have a database reading records from
mock-api/data JSON files and merging them with
the ones in
mock-api/data/local. When saving the DB (with
db.save()), only the difference
will be saved in
mock-api/data/local JSON files. Nothing will be changed in the JSON files
mock-api/data, not even the deleted records.
Now you want to update the core files to share with others the addition of records or such. It's
as easy as commenting the second line in the script above. Without overlay, the changes will be
saved directly in the root directory given as parameter of
Also you might want to keep the records volatile and not saving the database after a run. Well,
again as simple as commenting out the
db.save() you'd usually place in the shutdown of your app.
You might use this for unit testing as well, having multiple set of data but with a core data being constant, without duplicating it over and over in all unit tests.
You can add as many overlay as you want, just keep in mind tha
db.save() will save the diff (ie the
created, changed or deleted) records in the last overlay you added before using the database object.
modelName will be dasherized and pluralized to get the file name used as a record store for
that model. Also whatever you are going to use in the following methods as model name will always
meet the same base model name (for example
user_post, ... will all point
to the same model, and so the same store in each overlay)
An important thing to note is that updating a record MUST be done with
faster processing and to avoid unwanted changes, the returned record by any method of the API is a
copy of the original one, with
id property being read-only.
The API documentation can be found here.
More examples and features on their way ;-)