Simple key-value storage (a persistent data structure) directly on file system, maps each key to a separate file.
A very nice replacement for any of these node modules: node-persist, configstore, flat-cache, conf, simple-store and more...
- Simple key-value storage model
- Very easy to learn and use
- Both Synchronous and Asynchronous APIs
- One JSON containing file per each key
- Built-in configurable cache
- Both Promise and Callback support
var kfs = require("key-file-storage")('my/storage/path');
// Write something to file 'my/storage/path/myfile'
kfs.myfile = { mydata: 123 };
// Read contents of file 'my/storage/path/myfile'
var mydata = kfs.myfile.mydata;
// Delete file 'my/storage/path/myfile'
delete kfs.myfile;
Just give it a try, you'll like it!
Installing package on Node.js (Node.js 6.0.0 or higher is required) :
$ npm install key-file-storage
Initializing a key-file storage :
var keyFileStorage = require("key-file-storage");
var kfs = keyFileStorage('/storage/directory/path', caching);
The value of caching
can be
-
true
(By default, if not specified) : Unlimited cache, anything will be cached on memory, good for small data volumes. -
false
: No cache, read the files from disk every time, good when other applications can modify the files' contents arbitrarily. -
n
(An integer number) : Limited cache, only then
latest referred key-values will be cached, good for large data volumes where only a fraction of data is being used frequently .
As simple as native javascript objects :
kfs['key'] = value // Write file
kfs['key'] // Read file
delete kfs['key'] // Delete file
delete kfs['*'] // Delete all storage files
'key' in kfs // Check for file existence
//=> true or false
-
You can use
kfs.keyName
instead ofkfs['keyName']
anywhere if the key name allows. -
undefined
is not supported as a savable value, butnull
is. Saving a key with valueundefined
is equivalent to remove it. So, you can usekfs['key'] = undefined
or evenkfs['*'] = undefined
to delete files. -
Synchronous API will throw an exception if any errors happens, so you shall handle it your way.
Every one of the following calls returns a promise :
kfs('key', value) // Write file
kfs('key') // Read file
new kfs('key') // Delete file
new kfs('*') /* or */
new kfs() /* or */
new kfs // Delete all storage files
('key' in kfs(), kfs()) // Check for file existence
// Resolves to true or false
- Once again,
undefined
is not supported as a savable value, butnull
is. Saving a key with valueundefined
is equivalent to remove it. So, you can usekfs('key', undefined)
or evenkfs('*', undefined)
to delete files.
The same as asynchronous with promises, but with callback function as the last input parameter of kfs()
:
kfs('key', value, cb) // Write file
kfs('key', cb) // Read file
new kfs('key', cb) // Delete file
new kfs('*', cb) /* or */
new kfs(cb) // Delete all storage files
'key' in kfs(cb) // Check for file existence
// without promise output
/* or */
('key' in kfs(), kfs(cb))
// Check for file existence
// with promise output
-
These calls still return a promise on their output (except for
'key' in kfs(callback)
form of existence check). -
The first input parameter of all callback functions is
err
, so you shall handle it within the callback. Reading and Existence checking callbacks provide the return values as their second input parameter.
Every folder in the storage can be treated as a collection of key-values.
You can query the list of all containing keys (filenames) within a collection (folder) like this (Note that a collection path must end with a forward slash '/'
) :
var keys = kfs['col/path/']
// keys = ['col/path/key1', 'col/path/sub/key2', ... ]
kfs('col/path/').then(function(keys) {
// keys = ['col/path/key1', 'col/path/sub/key2', ... ]
});
kfs('col/path/', function(error, keys) {
// keys = ['col/path/key1', 'col/path/sub/key2', ... ]
});
-
NOTE 1 : Each key will map to a separate file (using the key itself as its relative path). Therefore, keys may be relative paths, e.g:
'data.json'
,'/my/key/01'
or'any/other/relative/path/to/a/file'
. The only exception is strings including'..'
(double dot) which will not be accepted for security reasons. -
NOTE 2 : If a key's relative path ends with a forward slash
'/'
, it will be considered to be a collection (folder) name. So,'data/set/'
is a collection and'data/set/key'
is a key in that collection. -
NOTE 3 : This module has a built-in implemented cache, so, when activated, accessing a certain key more than once won't require file-system level operations again for that file.
var keyFileStorage = require("key-file-storage");
// Locate 'db' folder in the current directory as the storage path,
// Require 100 latest accessed key-values to be cached:
var kfs = keyFileStorage('./db', 100);
// Create file './db/users/hessam' containing this user data, synchronously:
kfs['users/hessam'] = {
name: "Hessam",
skills: { java: 10, csharp: 15 }
};
// Read file './db/users/hessam' as a JSON object, asynchronously:
kfs('users/hessam').then(function(hessamData) {
console.log("Hessam's java skill is ",
hessamData.skills.java);
});
// Check whether file './db/users/mahdiar' exists or not, asynchronously:
'users/mahdiar' in kfs(function(error, exists) {
if(exists) {
console.log("We have Mahdiar's data!");
}
});
// List all the keys in './db/users/', synchronously:
var allUsers = kfs['users/'];
//=> ['users/hessam', 'users/mahdiar', ... ]
The code is simple! It would be appreciated if you had any suggestions or contribution on it or detected any bug or issue.
- See the code on GitHub.com (key-file-storage)
- Contact me by my gmail address (Hessam A Shokravi)