Transactional key-value store on top of any database.
I needed a key-value store supporting ACID transactions. Since currently there are not many solutions out there, I created a layer above SQL databases like MySQL. My hope is that in the near future I will be able to replace the SQL database with something doing just what I want.
- Simple API.
- If a key is an array it is serialized in a way that sort element-wise.
- Easy transactions with automatic begin/commit/rollback.
- Asynchronous functions return promises, feel free to handle them with ES7 async/await feature.
- Every databases supported by AnySQL.
- More to come...
npm install --save key-value-store
importKeyValueStorefrom'key-value-store';letstore=newKeyValueStore('mysql://test@localhost/test');asyncfunctionsimple(){letkey=['users','abcde12345'];// Createawaitstore.put(key,{firstName: 'Manu',age: 42});// Readletuser=awaitstore.get(key);// Updateawaitstore.put(key,{firstName: 'Manu',age: 43});// Deleteawaitstore.delete(key);}importKeyValueStorefrom'key-value-store';letstore=newKeyValueStore('mysql://test@localhost/test');asyncfunctionquery(){returnawaitstore.find({prefix: 'users',startAfter: 'abcde12345',limit: 30});}importKeyValueStorefrom'key-value-store';letstore=newKeyValueStore('mysql://test@localhost/test');asyncfunctioncriticalOperation(){awaitstore.transaction(asyncfunction(transaction){letkey=['users','abcde12345'];letuser=awaittransaction.get(key);user.age++;awaittransaction.put(key,user);// ...// if no error has been thrown, the transaction is automatically committed});}Keys and values can be any kind of data.
If a key is an array it is automatically serialized in a way that sort element-wise. Thanks to that, keys can easily represent "path" (e.g.: ['users', 'abcde12345']).
Values are serialized with JSON.stringify. If you need to customize the serialization of your objects, you can implement a toJSON() method on them.
Every asynchronous operation returns a promise. It is a good idea to handle them with the great ES7 async/await feature. Since ES7 is not really there yet, you should compile your code with something like Babel.
Create a store for the specified URL.
importKeyValueStorefrom'key-value-store';letstore=newKeyValueStore('mysql://test@localhost/test');Get an item from the store.
letuser=awaitstore.get(['users','abcde12345']);errorIfMissing(default:true): iftrue, an error is thrown if the specifiedkeyis missing from the store. Iffalse, the method returnsundefinedwhen thekeyis missing.
Put an item in the store.
awaitstore.put(['users','abcde12345'],{firstName: 'Manu',age: 42});createIfMissing(default:true): iffalse, an error is thrown if the specifiedkeyis missing from the store. This way you can ensure an "update" semantic.errorIfExists(default:false): iftrue, an error is thrown if the specifiedkeyis already present in the store. This way you can ensure a "create" semantic.
Delete an item from the store.
awaitstore.delete(['users','abcde12345']);errorIfMissing(default:true): iftrue, an error is thrown if the specifiedkeyis missing from the store. Iffalse, the method returnsfalsewhen thekeyis missing.
Get several items from the store. Return an array of objects composed of two properties: key and value. The order of the specified keys is preserved in the result.
letusers=awaitstore.getMany([['users','abcde12345'],['users','abcde67890'],// ...]);errorIfMissing(default:true): iftrue, an error is thrown if one of the specifiedkeysis missing from the store.returnValues(default:true): iffalse, only keys found in the store are returned (novalueproperty).
Not implemented yet.
Not implemented yet.
Fetch items matching the specified criteria. Return an array of objects composed of two properties: key and value. The returned items are ordered by key.
// Fetch all usersletusers=awaitstore.find({prefix: 'users'});// Fetch 30 users after the 'abcde12345' keyletusers=awaitstore.find({prefix: 'users',startAfter: 'abcde12345',limit: 30});prefix: fetch items with keys starting with the specified value.start,startAfter: fetch items with keys greater than (or equal to if you use thestartoption) the specified value.end,endBefore: fetch items with keys less than (or equal to if you use theendoption) the specified value.reverse(default:false): iftrue, reverse the order of returned items.limit(default:50000): limit the number of fetched items to the specified value.returnValues(default:true): iffalse, only keys found in the store are returned (novalueproperty).
Count items matching the specified criteria.
letusers=awaitstore.count({prefix: 'users',startAfter: 'abcde12345'});prefix: count items with keys starting with the specified value.start,startAfter: count items with keys greater than (or equal to if you use thestartoption) the specified value.end,endBefore: count items with keys less than (or equal to if you use theendoption) the specified value.
Delete items matching the specified criteria. Return the number of deleted items.
letdeletedItemsCount=awaitstore.findAndDelete({prefix: 'users',startAfter: 'abcde12345'});prefix: delete items with keys starting with the specified value.start,startAfter: delete items with keys greater than (or equal to if you use thestartoption) the specified value.end,endBefore: delete items with keys less than (or equal to if you use theendoption) the specified value.
Run the specified function inside a transaction. The function receives a transaction handler as first argument. This handler should be used as a replacement of the store for every operation made during the execution of the transaction. If any error occurs, the transaction is aborted and the store is automatically rolled back.
// Increment a counterawaitstore.transaction(asyncfunction(transaction){letvalue=awaittransaction.get('counter');value++;awaittransaction.put('counter',value);});Close all connections to the store.
MIT