JavaScript In-Memory CAching REsource Singleton
Jimcares is a singleton for JavaScript in-memory caching. It is used to store complex data in memory, or large api responses which only need fetching once. It allows for querying the properties within large data structures, as well as more simple read/write functionality.
Note: Currently, the only driver shipped with Jimcares uses the window object. It is therefore at this stage a browser plugin only, and will not currently work with Node.
<script src="https://unpkg.com/jimcares/dist/jimcares.min.js"></script>
npm install jimcares
yarn add jimcares
You can require the Jim singleton like so:
const Jim = require('jimcares');
Alternatively, you can import the module directly if you are using an ES6-aware build tool like Webpack or Rollup, which makes use of the 'module' field in package.json.
import Jim from 'jimcares';
Initialise Jim. The default expiration will be 24 hours if this property is not specified. Setting a custom queryNotation will allow you to query nested objects. The default is a slash. See Querying Objects for more information.
Parameter {object} options
Returns void
Throws TypeError
let options = {
defaultExpiration: "4 hours",
queryNotation: "."
}
Jim.init(options);
Tell Jim to remember a value. You can override the default expiration for a given root.
Parameter {string} path
Parameter {mixed} value
Parameter {string} expiration
Returns boolean
Throws TypeError
Jim.remember('example', {example: true}, '10 minutes');
Check if Jim has a value at the given path.
Parameter {string} path
Returns boolean
Throws TypeError
Jim.has('example') === true;
Get the value at the given path.
Parameter {string} path
Returns mixed
Throws TypeError
Jim.get('example');
Get the root at the given path, including: value, created_at, updated_at, deleted_at, expires_at.
Parameter {string} path
Returns object
Throws TypeError
Jim.root('example');
Soft-delete the root at the given path. This sets the deleted_at property to the value of a current timestamp.
Parameter {string} path
Returns void
Throws TypeError
Jim.trash('example');
Check if the root at the given path has been soft-deleted. Note: this method will return false if the path is undefined.
Parameter {string} path
Returns boolean
Throws TypeError
Jim.isTrashed('example') === true;
Forget the root at the given path permanently.
Parameter {string} path
Returns void
Throws TypeError
Jim.forget('example');
Flush the cache of all its roots.
Returns void
Jim.flush();
Check if a given value of a path matches the given comparison.
Parameter {string} path
Parameter {mixed} comparison
Returns boolean
Throws TypeError
Jim.equals('example', 'Does not match') === false;
Writes the entire cache to local storage. This can be used for later retrieval.
Returns void
Throws Error if the client does not support local storage
Jim.writeToLS();
Get the entire cache as a JSON string.
Returns string
Jim.toJson();
Removes __jimcares from the window entirely. Note: The Jim singleton will still be present, so you can run the init() method again at any time.
Returns void
Jim.destroy();
Note: the below methods are currently available but are being refactored into a stats method, and will soon be deprecated.
Get an approximate size of the entire cache in bytes.
Jim.size()
Count the number of roots in the cache.
Jim.count()
Jim.get() and Jim.has() both support the querying of objects. You can use certain notations to get nested properties or check they exist. For example:
let data = {
"foo": {
"bar": "val"
}
};
Jim.remember('example', data);
Jim.get('example/foo/bar') === "val"
Jim.has('example/foo/bar') === true
Note: slash notation is the default. You can specify an alternative via the init method.