cacheable 0.2.9 → 0.8.0

package/LICENSE

@@ -0,0 +1,19 @@
+MIT License & © Jared Wray 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to
+deal in the Software without restriction, including without limitation the
+rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+sell copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,189 +1,184 @@
+[<img align="center" src="https://cacheable.org/logo.svg" alt="Cacheable" />](https://github.com/jaredwray/cacheable)
+
 # Cacheable
 
-Cache manager that doesn't suck.
+> Simple Caching Engine using Keyv
 
-Make the result of you async functions cacheable, automatically pickle and unpickle the data.
-Manage all cache keys in one place, use a simple `._clearCache()` to purge cache.
+[![codecov](https://codecov.io/gh/jaredwray/cacheable/graph/badge.svg?token=lWZ9OBQ7GM)](https://codecov.io/gh/jaredwray/cacheable)
+[![tests](https://github.com/jaredwray/cacheable/actions/workflows/tests.yml/badge.svg)](https://github.com/jaredwray/cacheable/actions/workflows/tests.yml)
+[![npm](https://img.shields.io/npm/dm/cacheable.svg)](https://www.npmjs.com/package/cacheable)
+[![npm](https://img.shields.io/npm/v/cacheable)](https://www.npmjs.com/package/cacheable)
 
+`cacheable` is a high performance layer 1 / layer 2 caching engine that is focused on distributed caching with enterprise features such as `CacheSync`. It is built on top of the robust storage engine [Keyv](https://keyv.org) and provides a simple API to cache and retrieve data.
 
-## Usage
+* Simple to use with robust API
+* Not bloated with additional modules
+* Extendable to your own caching engine
+* Scalable and trusted storage engine by Keyv
+* Resilient to failures with try/catch and offline
+* Hooks and Events to extend functionality
+* Comprehensive testing and code coverage
+* Distributed Caching Sync via Pub/Sub (coming soon)
+* Maintained and supported regularly
 
-```javascript
-var Redis = require('redis');
-var Cacheable = require('cacheable');
-
-var client = Redis.createClient();
-var cached = Cacheable({
-  client: client,
-  ttl: 60, // set a default max age of one minute for `cached.set`
-  prefix: 'myapp:' // the prefix for every cache key
-});
+## Getting Started
 
-cached.set(key, value, callback)
-cached.set(key, value, 300, callback)
-cached.get(key, callback)
-cached.del(['abc', 'aba'], callback)
-```
+`cacheable` is primarily used as an extension to you caching engine with a robust storage backend [Keyv](https://keyv.org), Memonization, Hooks, Events, and Statistics.
 
-Wraping an async function:
-
-```javascript
-// Get remote content that expires in 3600 seconds
-var getUrlContent = cached.wrap(function(url, callback) {
-    request(url, function() {
-      // ...
-    })
-}, 'url-{0}', 3600)
+```bash
+npm install cacheable
 ```
 
-Manage cache for your models:
+## Basic Usage
 
 ```javascript
-function User(data) {
-  this.attributes = data
-}
-
-User.prototype.toJSON = function() {
-  return this.attributes
-}
+import { Cacheable } from 'cacheable';
 
-// get user by id
-User.get = function(user_id, callback) {
-  // get the user from data base
-  // ...
-  var user = new User(data)
-
-  callback(err, user);
-}
-
-User.prototype.getPostIds = function(start, limit, callback) {
-  callback(null, [1,2,3...])
-}
-
-// register the constructor first
-cached.register(User)
-
-// enable cache for `User.get` method
-// So when you call `User.get(some_id)`, it will fetch data
-// from cache first, when cache not found, then the original function will be called.
-User.enableCache('get', '{_model_}:{0}') // '{0}' means the `arguments[0]`
-
-// You can also enable cache for an instance method
-User.enableCache('.getPostIds', '{_model_}:posts-{0}-{1}')
+const cacheable = new Cacheable();
+await cacheable.set('key', 'value', 1000);
+const value = await cacheable.get('key');
 ```
 
-## API
+This is a basic example where you are only using the in-memory storage engine. To enable layer 1 and layer 2 caching you can use the `secondary` property in the options:
 
-### cached.register(cls, name)
+```javascript
+import { Cacheable } from 'cacheable';
+import KeyvRedis from '@keyv/redis';
 
-You have to `register` all model constructors, so when cache is hit, the cached manager would know
-how to restore the data as a proper JavaScript Object.
+const secondary = new KeyvRedis('redis://user:pass@localhost:6379');
+const cache = new Cacheable({secondary});
+``` 
 
-If your model constructor doesn't have a name, you can give a name as the second parameter,
-then cached will use this name.
+In this example, the primary store we will use `lru-cache` and the secondary store is Redis. You can also set multiple stores in the options:
 
 ```javascript
-var Book = function() {
-}
-cached.register(Book, 'Book')
+import { Cacheable } from 'cacheable';
+import { Keyv } from 'keyv';
+import KeyvRedis from '@keyv/redis';
+import { LRUCache } from 'lru-cache'
+
+const primary = new Keyv({store: new LRUCache()});
+const secondary = new KeyvRedis('redis://user:pass@localhost:6379');
+const cache = new Cacheable({primary, secondary});
 ```
 
-Your class.prototype must have a `.toJSON` method, so the cache wrapper could know how to save it to cache.
-The `.toJSON` will be extended by `cache.register`, the output object will always have a property `__cachedname`,
-as is the constructor's modelName. You can add a `.toObject = .toJSON`, and use `.toObject` whenever you need a clean object.
+This is a more advanced example and not needed for most use cases.
 
+## Hooks and Events
 
-If an `._unpickle` method is also defined, it will be called each time the object is restored from cache.
+The following hooks are available for you to extend the functionality of `cacheable` via `CacheableHooks` enum:
 
-That is:
+* `BEFORE_SET`: This is called before the `set()` method is called.
+* `AFTER_SET`: This is called after the `set()` method is called.
+* `BEFORE_SET_MANY`: This is called before the `setMany()` method is called.
+* `AFTER_SET_MANY`: This is called after the `setMany()` method is called.
+* `BEFORE_GET`: This is called before the `get()` method is called.
+* `AFTER_GET`: This is called after the `get()` method is called.
+* `BEFORE_GET_MANY`: This is called before the `getMany()` method is called.
+* `AFTER_GET_MANY`: This is called after the `getMany()` method is called.
 
-```javascript
-var item = new User(json)
-item._unpickle()
-return item
-```
-Note that it would be impossible to unpickle a cache if the constructor's name was changed.
-
-When registered, the class will have a property `._cacheKeys` and an instance would have
-a method `._clearCache()`.
+An example of how to use these hooks:
 
 ```javascript
-User.prototype.destroy = function(callback) {
-  var self = this
-  // destroy the item from database
-  db.destroy(..., function() {
-    // then clear the cache
-    self._clearCache(callback)
-  })
-}
-```
+import { Cacheable, CacheableHooks } from 'cacheable';
 
-### cached.wrap(fn, [key], [ttl])
+const cacheable = new Cacheable();
+cacheable.onHook(CacheableHooks.BEFORE_SET, (data) => {
+  console.log(`before set: ${data.key} ${data.value}`);
+});
+```
 
-Wrap an standard nodejs async function(which should have a `callback(err, result)` as the last parameter).
-The `ttl` is in seconds. If no `ttl` set, the cache will never automatically expire, even it an `options.ttl`
-is passed when you do `new Cached()`.
+## Storage Tiering and Caching
 
-The parameter `key` is a pattern for formatting real cache keys.
+`cacheable` is built as a layer 1 and layer 2 caching engine by default. The purpose is to have your layer 1 be fast and your layer 2 be more persistent. The primary store is the layer 1 cache and the secondary store is the layer 2 cache. By adding the secondary store you are enabling layer 2 caching. By default the operations are blocking but fault tolerant:
 
-The default `key` is:
+* `Setting Data`: Sets the value in the primary store and then the secondary store.
+* `Getting Data`: Gets the value from the primary if the value does not exist it will get it from the secondary store and set it in the primary store.
+* `Deleting Data`: Deletes the value from the primary store and secondary store at the same time waiting for both to respond.
+* `Clearing Data`: Clears the primary store and secondary store at the same time waiting for both to respond.
 
-    {_model_}:{_fn_}
+## Non-Blocking Operations
 
-`{_fn_}` is the name of the function `fn`. If not found, an error will throw.
-So you'd better alway name your functions, like this:
+If you want your layer 2 (secondary) store to be non-blocking you can set the `nonBlocking` property to `true` in the options. This will make the secondary store non-blocking and will not wait for the secondary store to respond on `setting data`, `deleting data`, or `clearing data`. This is useful if you want to have a faster response time and not wait for the secondary store to respond.
 
 ```javascript
-User.get = function get(id) {
-  // ...
-}
+import { Cacheable } from 'cacheable';
+import {KeyvRedis} from '@keyv/redis';
+
+const secondary = new KeyvRedis('redis://user:pass@localhost:6379');
+const cache = new Cacheable({secondary, nonBlocking: true});
 ```
 
-`{_model_}` equals to `{this.name}`, which is `this.modelName || this.name` in the scope when the function is called.
-For a class method, this usually means the name of a constructor.
+## CacheSync - Distributed Updates
 
-Numbers like `{0}` is indexes of arguments when the function is called.
-`%j{0}` mean the first argument value will be converted to json.
+`cacheable` has a feature called `CacheSync` that is coming soon. This feature will allow you to have distributed caching with Pub/Sub. This will allow you to have multiple instances of `cacheable` running and when a value is set, deleted, or cleared it will update all instances of `cacheable` with the same value. Current plan is to support the following:
 
+* [Google Pub/Sub](https://cloud.google.com/pubsub)
+* [AWS SQS](https://aws.amazon.com/sqs)
+* [RabbitMQ](https://www.rabbitmq.com)
+* [Nats](https://nats.io)
+* [Azure Service Bus](https://azure.microsoft.com/en-us/services/service-bus)
+* [Redis Pub/Sub](https://redis.io/topics/pubsub)
 
-### cls.enableCache(methodName, [key], [ttl])
+This feature should be live by end of year. 
 
-When a `cls` is registered, you can use `cls.enableCache` to enable cache for class/instance methods.
+## Cacheable Options
 
-If `methodName` starts with a dot `(.)`, it will be considered as an instance method, otherwise,
-it's a class method.
+The following options are available for you to configure `cacheable`:
 
-```javascript
-/**
- *
- * List all ids
- *
- * Options:
- *
- *    `limit`: limit per page
- *    `offset`: offset 
- * 
- */
-User.getAllIds = function(options, callback) {
-}
-
-User.prototype.getPostIds = function(start, limit, callback) {
-  // get user's posts
-  callback(null, [1,2,3...])
-}
-
-User.enableCache('getAllIds', 'ids-{0.limit}-{0.offset}')
-
-User.enableCache('.getPostIds', 'posts-{0}-{1}')
-
-// You can omit the key, cacheable will automatically use the method name
-User.enableCache('.getPostIds', 3600)
-// KEY: '{_model_}:{id}:getTagsIds', expires in: 3600 seconds
-```
+* `primary`: The primary store for the cache (layer 1) defaults to in-memory by Keyv.
+* `secondary`: The secondary store for the cache (layer 2) usually a persistent cache by Keyv.
+* `nonBlocking`: If the secondary store is non-blocking. Default is `false`.
+* `enableStats`: If you want to enable statistics for this instance. Default is `false`.
+
+## Cacheable Statistics (Instance Only)
 
-It is strongly recommended to use this approach to add cache, instead of directly call `cached.wrap`.
+If you want to enable statistics for your instance you can set the `enableStats` property to `true` in the options. This will enable statistics for your instance and you can get the statistics by calling the `stats` property. Here are the following property statistics:
 
+* `hits`: The number of hits in the cache.
+* `misses`: The number of misses in the cache.
+* `sets`: The number of sets in the cache.
+* `deletes`: The number of deletes in the cache.
+* `clears`: The number of clears in the cache.
+* `errors`: The number of errors in the cache.
+* `count`: The number of keys in the cache.
+* `vsize`: The estimated byte size of the values in the cache.
+* `ksize`: The estimated byte size of the keys in the cache.
 
-## License
+You can clear the stats by calling the `clearStats()` method.
+
+_This does not enable statistics for your layer 2 cache as that is a distributed cache_.
+
+## API
 
-the MIT licence.
+* `set(key, value, ttl? | [{string, string, ttl?}])`: Sets a value in the cache.
+* `setMany([{key, value, ttl?}])`: Sets multiple values in the cache.
+* `get(key | [keys])`: Gets a value from the cache.
+* `getMany([keys])`: Gets multiple values from the cache.
+* `has(key | [key])`: Checks if a value exists in the cache.
+* `hasMany([keys])`: Checks if multiple values exist in the cache.
+* `take(key)`: Takes a value from the cache and deletes it. (coming soon)
+* `takeMany([keys])`: Takes multiple values from the cache and deletes them. (coming soon)
+* `delete(key | [key])`: Deletes a value from the cache.
+* `deleteMany([keys])`: Deletes multiple values from the cache.
+* `clear()`: Clears the cache stores. Be careful with this as it will clear both layer 1 and layer 2.
+* `clearPrimary()`: Clears the primary store. (coming soon)
+* `clearSecondary()`: Clears the secondary store. (coming soon)
+* `wrap(function, options)`: Wraps a function in a cache. (coming soon)
+* `disconnect()`: Disconnects from the cache stores.
+* `onHook(hook, callback)`: Sets a hook.
+* `removeHook(hook)`: Removes a hook.
+* `on(event, callback)`: Listens for an event.
+* `removeListener(event, callback)`: Removes a listener.
+* `primary`: The primary store for the cache (layer 1) defaults to in-memory by Keyv.
+* `secondary`: The secondary store for the cache (layer 2) usually a persistent cache by Keyv.
+* `nonBlocking`: If the secondary store is non-blocking. Default is `false`.
+* `stats`: The statistics for this instance which includes `hits`, `misses`, `sets`, `deletes`, `clears`, `errors`, `count`, `vsize`, `ksize`.
+* `clearStats()`: Clears the statistics for this instance.
+
+## How to Contribute
+
+You can contribute by forking the repo and submitting a pull request. Please make sure to add tests and update the documentation. To learn more about how to contribute go to our main README [https://github.com/jaredwray/cacheable](https://github.com/jaredwray/cacheable). This will talk about how to `Open a Pull Request`, `Ask a Question`, or `Post an Issue`.
+
+## License and Copyright
+[MIT © Jared Wray](./LICENSE)