A tiny (~1kb minified & gzip'd) extension of the ES6 Map object that lets you set an expiration time for key/value pairs. Expired data is automatically pruned to avoid wasting memory.
const SnapMap = ;const myMap = ;const uniqueObj = uniqueData: 1 2 3 ;myMap// time (in ms) until data is deleted);console // `🦄`// More than 10 seconds later...console // undefined
npm install --save snapmap
The Snapmap API is exactly the same as the ES6 Map API with one exception: the
set() method accepts one extra, optional parameter.
ttl argument, when defined, specifies the number of milliseconds that will pass before the key/value pair is automatically deleted.
Browser & Node.js Support
- All modern browsers supported
- Node 8+ supported
If you update a key with a new ttl, the key/value pair won't be deleted until the new ttl elapses:
const SnapMap = ;const dynamicMap = ;// Let's say it's 01:00:00 PM heredynamicMap;// 30 seconds later... (01:00:30 PM)dynamicMap;// 30 more seconds go by... (01:01:00 PM)dynamicMap; // 'newVal' - still exists 60s after original set// And 30 more seconds... (01:01:30 PM)dynamicMap; // undefined - data deleted after second ttl
This means that you can effectively abort scheduled deletes by updating a key and passing no ttl value:
dynamicMap;// Less than 10s laterdynamicMap;// Some time in the distant future...dynamicMap; // 'newVal' - data is never deleted
Monitoring Delete Events
You can easily subscribe to the
onDelete event to be notified when a scheduled delete occurs. The
onDelete function is passed a single parameter, the deleted key:
const SnapMap = ;const monitorMap = ;monitorMap;monitorMap console;// 60 seconds later:// "monitoredKey"
1.2.0 Update: Version 1.2.0 adds ttl "clamping" behavior which mitigates
setTimeout delays. Now, Snapmap will always correctly report that expired keys do not exist, and
get operations will return
undefined. See the change commit for more information.
This package uses the
setTimeout() function to schedule deletions by 'sleeping' execution of an async function. (Take a look at the source to see exactly how this is done.) If you're familiar with the typical JS engine event loop, that probably scares you quite a bit. And rightfully so! Because of the reliance on
setTimeout, scheduled deletion times are not exact. They will never occur earlier than requested, but they may be delayed.
For more information on what causes
setTimeout delays and browser throttling of
setTimeout, check out MDN's explanation.
- Allow key updates that preserve original ttl
- Update tests to use higher resolution test methods (false negatives from inaccurate
Investigate alternate scheduling methods (higher resolution than
All are welcomed and encouraged to contribute to this project!
git clone https://github.com/cgatno/snapmap.git cd snapmap npm install
Even though this isn't exactly a "mission critical" or groundbreaking Node module, I think it's a great little project to hack on if you're just getting started with Node or looking for something fun to work on.
If you're feeling up to the challenge, please read on before jumping in! It's really not that bad, and I promise you'll have lots of fun along the way.
I've implemented a basic Jest setup for quick and easy unit testing.
If you're not familiar with Jest, take a look at the docs or some of the existing tests to get started. The syntax is extremely semantic and easy-to-read, so you'll be able to figure it out in no time.
You can run all unit tests at once using
npm run test. Don't forget to rebuild
your code before testing!
Even if you don't want to work on the project yourself, you can help out a lot just by reporting any bugs you find or enhancements you want to see added!
Head over to GitHub's issue tracker to submit a bug report or feature request!
Don't Be Afraid To Ask for Help!
Last but certainly not least, don't be afraid to reach out for help! If you have any questions, don't hesitate to shoot me an email! 📫🙌
See also the list of contributors who participated in this project.
This project is licensed under the MIT License. See the LICENSE file for details.