cacheable 0.3.0 → 1.1.0

package/LICENSE

@@ -1,4 +1,4 @@
-MIT License
+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

package/README.md

@@ -1,23 +1,27 @@
-[<img align="center" src="https://jaredwray.com/images/cacheable_white.svg" alt="keyv">](https://github.com/jaredwray/cacheable)
+[<img align="center" src="https://cacheable.org/logo.svg" alt="Cacheable" />](https://github.com/jaredwray/cacheable)
 
-# cacheable
+# Cacheable
 
 > Simple Caching Engine using Keyv
 
-[![codecov](https://codecov.io/gh/jaredwray/cacheable/branch/master/graph/badge.svg?token=LDLaqe4PsI)](https://codecov.io/gh/jaredwray/cacheable)
+[![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 simple caching engine that uses [Keyv](https://keyv.org) as the storage engine. It is designed to be simple to use and extend. Here are some of the features:
+`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.
+
 * Simple to use with robust API
 * Not bloated with additional modules
 * Extendable to your own caching engine
 * Scalable and trusted storage engine by Keyv
-* Statistics built in by default
+* Memory Caching with LRU and Expiration `CacheableMemory`
+* Resilient to failures with try/catch and offline
 * Hooks and Events to extend functionality
 * Comprehensive testing and code coverage
-* Maintained and supported
+* Distributed Caching Sync via Pub/Sub (coming soon)
+* ESM and CommonJS support with TypeScript
+* Maintained and supported regularly
 
 ## Getting Started
 
@@ -33,186 +37,178 @@ npm install cacheable
 import { Cacheable } from 'cacheable';
 
 const cacheable = new Cacheable();
-cacheable.set('key', 'value', 1000);
-const value = cacheable.get('key');
+await cacheable.set('key', 'value', 1000);
+const value = await cacheable.get('key');
 ```
 
-## Extending Your own Caching Engine
+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:
 
 ```javascript
 import { Cacheable } from 'cacheable';
+import KeyvRedis from '@keyv/redis';
 
-export class MyCache extends Cacheable {
-  constructor() {
-	super();
-  }
-}
+const secondary = new KeyvRedis('redis://user:pass@localhost:6379');
+const cache = new Cacheable({secondary});
+``` 
+
+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
+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});
 ```
 
-From here you now how the ability to use the `cacheable` API. You can also extend the API to add your own functionality.
+This is a more advanced example and not needed for most use cases.
 
-## Storage Adapters and Keyv
+## Hooks and Events
+
+The following hooks are available for you to extend the functionality of `cacheable` via `CacheableHooks` enum:
+
+* `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.
 
-To set Keyv as the storage engine, you can do the following:
+An example of how to use these hooks:
 
 ```javascript
-import { Cacheable } from 'cacheable';
-import Keyv from 'keyv';
+import { Cacheable, CacheableHooks } from 'cacheable';
 
-export class MyCache extends Cacheable {
-  constructor() {
-	super(new Keyv('redis://user:pass@localhost:6379'));
-  }
-}
+const cacheable = new Cacheable();
+cacheable.onHook(CacheableHooks.BEFORE_SET, (data) => {
+  console.log(`before set: ${data.key} ${data.value}`);
+});
 ```
 
-or you can do it at the property level:
+## Storage Tiering and Caching
+
+`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:
+
+* `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.
+
+## Non-Blocking Operations
+
+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
 import { Cacheable } from 'cacheable';
-import Keyv from 'keyv';
+import {KeyvRedis} from '@keyv/redis';
 
-export class MyCache extends Cacheable {
-  constructor() {
-	super();
-
-	this.store = new Keyv('redis://user:pass@localhost:6379');
-  }
-}
+const secondary = new KeyvRedis('redis://user:pass@localhost:6379');
+const cache = new Cacheable({secondary, nonBlocking: true});
 ```
 
-## Statistics
+## CacheSync - Distributed Updates
 
-To get statistics on your cache, you can do the following:
+`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:
 
-```javascript
-import { Cacheable } from 'cacheable';
+* [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)
 
-export class MyCache extends Cacheable {
-  constructor() {
-	super();
-  }
+This feature should be live by end of year. 
 
-  async getStats() {
-	return this.stats.getReport();
-  }
-}
-```
+## Cacheable Options
 
-This will generate the following json object:
-
-```json
-{
-  "cacheSize": 100,
-  "currentSize": 80,
-  "hits": 500,
-  "misses": 200,
-  "hitRate": 0.71,
-  "evictions": 50,
-  "averageLoadPenalty": 0.05,
-  "loadSuccessCount": 700,
-  "loadExceptionCount": 10,
-  "totalLoadTime": 3500,
-  "topHits": [
-    {
-      "key": "key1",
-      "value": "value1",
-      "lastAccessed": 1627593600000,
-      "accessCount": 50
-    },
-    {
-      "key": "key2",
-      "value": "value2",
-      "lastAccessed": 1627593600000,
-      "accessCount": 45
-    }
-    // More items...
-  ],
-  "leastUsed": [
-    {
-      "key": "key3",
-      "value": "value3",
-      "lastAccessed": 1627593600000,
-      "accessCount": 5
-    },
-    {
-      "key": "key4",
-      "value": "value4",
-      "lastAccessed": 1627593600000,
-      "accessCount": 4
-    }
-    // More items...
-  ]
-}
-```
+The following options are available for you to configure `cacheable`:
 
-* `cacheSize`: The maximum number of items that can be stored in the cache.
-* `currentSize`: The current number of items in the cache.
-hits: The number of cache hits. A cache hit occurs when the requested data is found in the cache.
-* `misses`: The number of cache misses. A cache miss occurs when the requested data is not found in the cache and needs to be loaded.
-* `hitRate`: The ratio of cache hits to the total number of cache lookups. This is a measure of the cache's effectiveness.
-* `evictions`: The number of items that have been evicted from the cache, typically because the cache is full.
-* `averageLoadPenalty`: The average time spent loading new values into the cache, typically measured in milliseconds. This could be calculated as totalLoadTime / (hits + misses).
-* `loadSuccessCount`: The number of times cache loading has succeeded.
-* `loadExceptionCount`: The number of times cache loading has failed due to exceptions.
-* `totalLoadTime`: The total time spent loading new values into the cache, typically measured in milliseconds.
+* `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`: To enable statistics for this instance. Default is `false`.
 
-## Hooks and Events
+## Cacheable Statistics (Instance Only)
 
-The following hooks are available for you to extend the functionality of `cacheable`:
+If you want to enable statistics for your instance you can set the `.stats.enabled` 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:
 
-* `preSet`: This is called before the `set` method is called.
-* `postSet`: This is called after the `set` method is called.
-* `preSetMany`: This is called before the `setMany` method is called.
-* `postSetMany`: This is called after the `setMany` method is called.
-* `preGet`: This is called before the `get` method is called.
-* `postGet`: This is called after the `get` method is called.
-* `preGetMany`: This is called before the `getMany` method is called.
-* `postGetMany`: This is called after the `getMany` method is called.
+* `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.
 
-An example of how to use these hooks:
+You can clear / reset the stats by calling the `.stats.reset()` method.
 
-```javascript
-import { Cacheable } from 'cacheable';
+_This does not enable statistics for your layer 2 cache as that is a distributed cache_.
 
-const cacheable = new Cacheable();
-cacheable.hooks.setHook('preSet', (key, value) => {
-  console.log(`preSet: ${key} ${value}`);
-});
+## API
+
+* `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.
+* `takeMany([keys])`: Takes multiple values from the cache and deletes them.
+* `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.
+* `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`.
+
+## CacheableMemory - In-Memory Cache
+
+`cacheable` comes with a built-in in-memory cache called `CacheableMemory`. This is a simple in-memory cache that is used as the primary store for `cacheable`. You can use this as a standalone cache or as a primary store for `cacheable`. Here is an example of how to use `CacheableMemory`:
+
+```javascript
+import { CacheableMemory } from 'cacheable';
+const options = {
+  ttl: 60 * 60 * 1000, // 1 hour
+  useClones: true, // use clones for the values (default is true)
+  lruSize: 1000, // the size of the LRU cache (default is 0 which is unlimited)
+}
+const cache = new CacheableMemory(options);
+await cache.set('key', 'value');
+const value = await cache.get('key'); // value
 ```
 
-The following events are available for you to extend the functionality of `cacheable`:
+You can use `CacheableMemory` as a standalone cache or as a primary store for `cacheable`. You can also set the `useClones` property to `false` if you want to use the same reference for the values. This is useful if you are using large objects and want to save memory. The `lruSize` property is the size of the LRU cache and is set to `0` by default which is unlimited. When setting the `lruSize` property it will limit the number of keys in the cache.
 
-* `set`: This is called when the `set` method is called.
-* `setMany`: This is called when the `setMany` method is called.
-* `get`: This is called when the `get` method is called.
-* `getMany`: This is called when the `getMany` method is called.
-* `clear`: This is called when the `clear` method is called.
-* `has`: This is called when the `has` method is called.
-* `disconnect`: This is called when the `disconnect` method is called.
-* `error`: This is called when an error occurs.
+This simple in-memory cache uses multiple Map objects and a with `expiration` and `lru` policies if set to manage the in memory cache at scale.
 
-## API
+### CacheableMemory API
 
 * `set(key, value, ttl?)`: Sets a value in the cache.
-* `setMany([{key, value, ttl?}])`: Sets multiple values in the cache.
 * `get(key)`: Gets a value from the cache.
 * `has(key)`: Checks if a value exists in the cache.
-* `getMany([keys])`: Gets multiple values from the cache.
 * `delete(key)`: Deletes a value from the cache.
 * `clear()`: Clears the cache.
-* `disconnect()`: Disconnects from the cache.
-* `getStats()`: Gets statistics from the cache.
-* `setHook(hook, callback)`: Sets a hook.
-* `deleteHook(hook)`: Removes a hook.
-* `emitEvent(event, data)`: Emits an event.
-* `on(event, callback)`: Listens for an event.
-* `removeListener(event, callback)`: Removes a listener.
-* `store`: The [Keyv](https://keyv.org) storage engine.
+* `size()`: The number of keys in the cache.
+* `keys()`: The keys in the cache.
+
 
 ## 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 - [https://github.com/jaredwray/cacheable/blob/main/LICENSE](https://github.com/jaredwray/cacheable/blob/main/LICENSE)
+[MIT © Jared Wray](./LICENSE)