painless-storage-adapter v2.0.2
╔═╗┌─┐┬┌┐┌┬ ┌─┐┌─┐┌─┐ ╔═╗┌┬┐┌─┐┬─┐┌─┐┌─┐┌─┐ ╔═╗┌┬┐┌─┐┌─┐┌┬┐┌─┐┬─┐
╠═╝├─┤│││││ ├┤ └─┐└─┐ ╚═╗ │ │ │├┬┘├─┤│ ┬├┤ ╠═╣ ││├─┤├─┘ │ ├┤ ├┬┘
╩ ┴ ┴┴┘└┘┴─┘└─┘└─┘└─┘ ╚═╝ ┴ └─┘┴└─┴ ┴└─┘└─┘ ╩ ╩─┴┘┴ ┴┴ ┴ └─┘┴└─
(Ascii-art generated by patorjk.com)
Upgrading to 2.0
The upgrade to 2.0 is fairly smooth, reference UPGRADE-2.0.md for details on upgrading from 1.0 to 2.0.
What is PainlessStorageAdapter?
It's a very simple storage adapter
and not meant for large data or
complicated tasks
. It's just meant for when you want to:
Load a whole piece of data
(such as a file but this is storage agnostic)Read and/or Write to parts of that data
directly using mainly getters and settersOptionally save
the data back to its source
In essence CRUD type operations
.
It's also important to note that this entire module is built to be
asynchronous for any operation except read
operations since read uses
the in-memory cache where the whole data is stored.
Even the emitted events are asynchronous
using my PainlessEventEmitter
package over the native and dreadfully synchronous EventEmitter.
Why is it called PainlessStorageAdapter?
Because I'm starting a simple-
series but most of them are already taken
so I'm being safe and using painless instead lol.
OK so how do I begin?
Well i encourage you to look through the API docs online here.
A lot of hard work went into making sure the api docs are full and complete. For a bit of speed there's a quick api overview located in the docs for this module here.
This adapter, although can be used directly, is meant to be derived from. In other words this is the base adapter, the one that's storage agnostic. It's intended to be extended with your own storage adapter for a specific type of storage.
You can use it directly without doing all this but you'll have to provide the data into load and save will just return the same data.
Here's a quick run through on making your own adapter in the same docs here.
A quick note about the event system
The Event System is based on my own emitter inspired from the native NodeJS EventEmitter. I call it PainlessEventEmitter.
It allows listeners or subscribers to be either asynchronous or synchronous and their treated the same (asynchronously synchronous) or waiting til one listener gets done before the other one is fired even if the listener is asynchronous, it'll still get waited on in a non-blocking manner.
If a listener needs to be asynchronous, return a promise or just prefix with the es6 async keyword.
Full details on PainlessEventEmitter can be found here.
And a quick overview for this module can be found in this modules docs here.
This package is solid
This package is actively tested with Jasmine and thoroughly documented throughout. It also contains complete JSDoc comments and full online JSDoc generated documentation.
Do you like this package or have an issue?
If this package has helped you I encourage you to follow it, give it a star, or fork it on github. If you have any ideas, suggestions, issues, or ways to improve upon it then let us know over at github by filing an issue.
Contributions are also encouraged and the CONTRIBUTING.md file shows all the details on development and how to contribute back but its mostly just commit changes and send a pull request.
This project is licensed Apache 2.0
http://www.apache.org/licenses/LICENSE-2.0.txt
Run it in your browser
Thanks to TonicDev, you now have a way to run this package right in your browser to test it out. If your on the NPM site you can see the TonicDev link on the right-hand side, otherwise you can always go to the link below.
TonicDev will load up a preset example we provide that you can play around with to get a feel for this package.
https://tonicdev.com/npm/painless-storage-adapter
How to develop
To develop, git clone
this repository and npm install
to install the
development dependencies. Make sure to run npm run build
when
needed which will test & compile ES6/7 to ES5 and re-generate the docs.
You can run those individually if you want with npm run docs
and
npm run compile
. To auto-copy over docs from master to gh-pages run
npm run pages
before committing and pushing.
For testing, just run npm run test
If you want to contribute back read the CONTRIBUTING.md
file.
Documentation
Detailed documentation exists for this package, it should already by viewable on clone. Feel free to look through it for any questions you may have. The source code is also heavily documented if you want to look through it as well for answers.
Online docs exist here http://junestoolbox.github.io/painless-storage-adapter/docs
Whats New
Check out the CHANGELOG.md file for latest changes and updates