node-persist
(localStorage on the server)
Super-easy asynchronous persistent data structures in Node.js, modeled after HTML5 localStorage
Node-persist doesn't use a database. Instead, JSON documents are stored in the file system for persistence. Because there is no network overhead, node-persist is just about as fast as a database can get. Node-persist uses the HTML5 localStorage API, so it's easy to learn.
This is still a work in progress. Send pull requests please.
Note
If you're looking for the version that supports both synchronous
and asynchronous
use node-persist@2.1.0
Install
$ npm install node-persist
Basic Example
const storage = require('node-persist');
//you must first call storage.init
await storage.init( /* options ... */ );
await storage.setItem('name','yourname')
console.log(await storage.getItem('name')); // yourname
Run the counter example:
$ cd examples/counter
$ node counter.js
$ open up localhost:8080
3.0.0 change logs
Non-backward changes
- All the
*Sync
functions were removed, every operation is now asynchronous - All the
persist*
functions were removed - Nothing is held up in RAM use your own memory caching module, i.e. nano-cache
- Node 7.6+ is required now, we're using
async/await
continuous
andinterval
options were removed, since we immediately persist to disk now, asynchronouslyforEach
callback now accepts an objectcallback({key, value})
instead of 2 argumentscallback(key, value)
2.0.0 change logs
Non-backward changes
- filenames on the file system are now md5 hashed now and the structure of the saved data has changed to include the ttl in them.
- no longer need/support a
options.ttlDir
, since thettls
are now stored in the same file as each value - added
expiredInterval
option - added
forgiveParseErrors
option
1.0.0 change logs
Mostly non-backward changes
storage.getItem()
now returns a promisestorage.valuesWithKeyMatch()
no longer accepts a callbackstorage.values()
no longer accepts a callbackstorage.key()
is gone- The default
dir
is nowprocess.cwd() + (dir || '.node-persist/storage')
, unless you use an absolute path - added
storage.get()
, alias togetItem()
- added
storage.set()
, alias tosetItem()
- added
storage.del()
,storage.rm()
, as aliases toremoveItem()
- Keys, on the file system are base64 encoded with the replacement of the
/
API Documentation
async init(options, [callback])
if the storage dir is new, it will create it
Options
You can pass init()
an options object to customize the behavior of node-persist
These are the defaults
await storage.init({
dir: 'relative/path/to/persist',
stringify: JSON.stringify,
parse: JSON.parse,
encoding: 'utf8',
logging: false, // can also be custom logging function
ttl: false, // ttl* [NEW], can be true for 24h default or a number in MILLISECONDS or a valid Javascript Date object
expiredInterval: 2 * 60 * 1000, // every 2 minutes the process will clean-up the expired cache
// in some cases, you (or some other service) might add non-valid storage files to your
// storage dir, i.e. Google Drive, make this true if you'd like to ignore these files and not throw an error
forgiveParseErrors: false
});
async getItem(key)
This function will get the value for that key stored on disk
let value = await storage.getItem('obj');
async setItem(key, value, [options])
This function sets 'key' in your database to 'value'
await storage.setItem('fibonacci',[0,1,1,2,3,5,8]);
await storage.setItem(42,'the answer to life, the universe, and everything.');
await storage.setItem(42,'the answer to life, the universe, and everything.', {ttl: 1000*60 /* 1 min */ });
* The only option available when calling setItem(key, value, option)
is {ttl: Number|Date}
async updateItem(key, value, [options])
This function updates a 'key' in your database with a new 'value' without touching the ttl
, however, if the key
was not found of it was expired
a new item will get set
await storage.setItem(42,'the answer to life, the universe, and everything.', {ttl: 1000*60*10 /* 10 minutes */ });
await storage.setItem(42,'means nothing, do not trust wikipedia'); // ttl is still the same, will expired in 10 minutes since it was first set
* The only option available when calling setItem(key, value, option)
is {ttl: Number|Date}
async removeItem(key)
This function immediately deletes it from the file system asynchronously
await storage.removeItem('me');
async clear()
This function immediately deletes all files from the file system asynchronously.
await storage.clear();
async values()
This function returns all of the values
await storage.setItem("batman", {name: "Bruce Wayne"});
await storage.setItem("superman", {name: "Clark Kent"});
console.log(await storage.values()); //output: [{name: "Bruce Wayne"},{name: "Clark Kent"}]
async valuesWithKeyMatch(match)
This function returns all of the values matching a string or RegExp
await storage.setItem("batman", {name: "Bruce Wayne"});
await storage.setItem("superman", {name: "Clark Kent"});
await storage.setItem("hulk", {name: "Bruce Banner"});
console.log(await storage.valuesWithKeyMatch('man')); //output: [{name: "Bruce Wayne"},{name: "Clark Kent"}]
// also accepts a Regular Expression
console.log(await storage.valuesWithKeyMatch(/man/)); //output: [{name: "Bruce Wayne"},{name: "Clark Kent"}]
async keys()
this function returns an array of all the keys in the database.
console.log(await storage.keys()); // ['batman', 'superman']
async length()
This function returns the number of keys stored in the database.
console.log(await storage.length()); // 2
async forEach(callback)
This function iterates over each key/value pair and executes an asynchronous callback as well
storage.forEach(async function(datum) {
// use datum.key and datum.value
});
Factory method
create(options)
- synchronous, static method
If you choose to create multiple instances of storage, you can. Just avoid using the same dir
for the storage location.
You still have to call init
after create
- you can pass your configs to either create
or init
const storage = require('node-persist');
const myStorage = storage.create({dir: 'myDir', ttl: 3000});
await myStorage.init();
Tests
npm install
npm test