cacheable 2.1.0 → 2.2.0

package/README.md

@@ -32,6 +32,7 @@
 * [Storage Tiering and Caching](#storage-tiering-and-caching)
 * [TTL Propagation and Storage Tiering](#ttl-propagation-and-storage-tiering)
 * [Shorthand for Time to Live (ttl)](#shorthand-for-time-to-live-ttl)
+* [Iteration on Primary and Secondary Stores](#iteration-on-primary-and-secondary-stores)
 * [Non-Blocking Operations](#non-blocking-operations)
 * [Non-Blocking with @keyv/redis](#non-blocking-with-keyvredis)
 * [CacheableSync - Distributed Updates](#cacheablesync---distributed-updates)
@@ -279,6 +280,110 @@ raws.forEach((entry, idx) => {
 });
 ```
 
+## Checking multiple keys with hasMany
+
+The `hasMany` method allows you to efficiently check if multiple keys exist in the cache. It leverages Keyv's native `hasMany` support for optimal performance:
+
+```typescript
+import { Cacheable } from 'cacheable';
+
+const cache = new Cacheable();
+
+// set some values
+await cache.set('user:1', { name: 'Alice' });
+await cache.set('user:2', { name: 'Bob' });
+
+// check if multiple keys exist
+const exists = await cache.hasMany(['user:1', 'user:2', 'user:3']);
+console.log(exists); // [true, true, false]
+```
+
+The `hasMany` method returns an array of booleans in the same order as the input keys. This is particularly useful when you need to verify the existence of multiple cache entries before performing batch operations.
+
+# Iteration on Primary and Secondary Stores
+
+The `Cacheable` class exposes both `primary` and `secondary` Keyv instances, which support iteration over their stored entries using the `iterator()` method. This allows you to access and process all keys and values in either storage layer.
+
+**Important Notes:**
+- Not all storage adapters support iteration. Always check if `iterator` exists before using it.
+- The iterator automatically filters by namespace, skips expired entries (and deletes them), and deserializes values.
+- **Performance Warning:** Be careful when using `iterator()` as it can cause performance issues with large datasets.
+
+## Basic Iteration Example
+
+```typescript
+import { Cacheable } from 'cacheable';
+import KeyvRedis from '@keyv/redis';
+
+// Create cache with primary (in-memory) and secondary (Redis) stores
+const secondary = new KeyvRedis('redis://user:pass@localhost:6379');
+const cache = new Cacheable({ secondary });
+
+// Add some data
+await cache.set('user:1', { name: 'Alice', role: 'admin' });
+await cache.set('user:2', { name: 'Bob', role: 'user' });
+await cache.set('session:abc', { userId: '1', active: true });
+
+// Iterate over primary store (in-memory)
+console.log('Primary store contents:');
+if (cache.primary.iterator) {
+    for await (const [key, value] of cache.primary.iterator()) {
+        console.log(`  ${key}:`, JSON.stringify(value));
+    }
+}
+
+// Iterate over secondary store (Redis)
+console.log('\nSecondary store contents:');
+if (cache.secondary?.iterator) {
+    for await (const [key, value] of cache.secondary.iterator()) {
+        console.log(`  ${key}:`, JSON.stringify(value));
+    }
+}
+```
+
+## Safe Iteration Helper
+
+Here's a recommended helper function for safe iteration that checks for store availability and iterator support:
+
+```typescript
+import { Cacheable } from 'cacheable';
+import type { Keyv } from 'keyv';
+
+async function iterateStore(store: Keyv | undefined, storeName: string) {
+    if (!store) {
+        console.log(`${storeName} store not configured`);
+        return;
+    }
+
+    if (!store.iterator) {
+        console.log(`${storeName} store does not support iteration`);
+        return;
+    }
+
+    console.log(`${storeName} store entries:`);
+    for await (const [key, value] of store.iterator()) {
+        console.log(`  ${key}:`, value);
+    }
+}
+
+// Usage
+const cache = new Cacheable({ /* options */ });
+await iterateStore(cache.primary, 'Primary');
+await iterateStore(cache.secondary, 'Secondary');
+```
+
+## Storage Adapter Support
+
+The `iterator()` method is available when:
+- The store is a Map instance (has Symbol.iterator)
+- The store implements an `iterator()` method (e.g., Redis, Valkey, etc.)
+- The store is a supported iterable adapter
+
+Common stores that support iteration:
+- In-memory (Map-based stores)
+- @keyv/redis
+- @keyv/valkey
+- Other Keyv adapters that implement the iterator interface
 
 # Non-Blocking Operations
 
@@ -517,7 +622,8 @@ _This does not enable statistics for your layer 2 cache as that is a distributed
 * `removeHook(hook)`: Removes a hook.
 * `on(event, callback)`: Listens for an event.
 * `removeListener(event, callback)`: Removes a listener.
-* `hash(object: any, algorithm = 'sha256'): string`: Hashes an object with the algorithm. Default is `sha256`.
+* `hash(object: any, algorithm = 'SHA-256'): Promise<string>`: Asynchronously hashes an object with a cryptographic algorithm (SHA-256, SHA-384, SHA-512). Default is `SHA-256`.
+* `hashSync(object: any, algorithm = 'djb2'): string`: Synchronously hashes an object with a non-cryptographic algorithm (djb2, fnv1, murmer, crc32). Default is `djb2`.
 * `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.
 * `namespace`: The namespace for the cache. Default is `undefined`. This will set the namespace for the primary and secondary stores.
@@ -544,7 +650,7 @@ To learn more go to [@cacheable/memory](https://cacheable.org/docs/memory/)
 
 # Wrap / Memoization for Sync and Async Functions
 
-`Cacheable` and `CacheableMemory` has a feature called `wrap` that comes from [@cacheable/memoize](https://cacheable.org/docs/memoize/) and allows you to wrap a function in a cache. This is useful for memoization and caching the results of a function. You can wrap a `sync` or `async` function in a cache. Here is an example of how to use the `wrap` function:
+`Cacheable` and `CacheableMemory` has a feature called `wrap` that comes from [@cacheable/utils](https://cacheable.org/docs/utils/) and allows you to wrap a function in a cache. This is useful for memoization and caching the results of a function. You can wrap a `sync` or `async` function in a cache. Here is an example of how to use the `wrap` function:
 
 ```javascript
 import { Cacheable } from 'cacheable';
@@ -637,11 +743,11 @@ If you would like to generate your own key for the wrapped function you can set
 
 We will pass in the `function` that is being wrapped, the `arguments` passed to the function, and the `options` used to wrap the function. You can then use these to generate a custom key for the cache.
 
-To learn more visit [@cacheable/memoize](https://cacheable.org/docs/memoize/)
+To learn more visit [@cacheable/utils](https://cacheable.org/docs/utils/)
 
 # Get Or Set Memoization Function
 
-The `getOrSet`  method that comes from [@cacheable/memoize](https://cacheable.org/docs/memoize/) provides a convenient way to implement the cache-aside pattern. It attempts to retrieve a value from cache, and if not found, calls the provided function to compute the value and store it in cache before returning it. Here are the options:
+The `getOrSet`  method that comes from [@cacheable/utils](https://cacheable.org/docs/utils/) provides a convenient way to implement the cache-aside pattern. It attempts to retrieve a value from cache, and if not found, calls the provided function to compute the value and store it in cache before returning it. Here are the options:
 
 ```typescript
 export type GetOrSetFunctionOptions = {
@@ -677,17 +783,17 @@ const function_ = async () => Math.random() * 100;
 const value = await cache.getOrSet(generateKey(), function_, { ttl: '1h' });
 ```
 
-To learn more go to [@cacheable/memoize](https://cacheable.org/docs/memoize/)
+To learn more go to [@cacheable/utils](https://cacheable.org/docs/utils/)
 
 # v1 to v2 Changes
 
-`cacheable` is now using `@cacheable/utils`, `@cacheable/memoize`, and `@cacheable/memory` for its core functionality as we are moving to this modular architecture and plan to eventually have these modules across `cache-manager` and `flat-cache`. In addition there are some breaking changes:
+`cacheable` is now using `@cacheable/utils` and `@cacheable/memory` for its core functionality as we are moving to this modular architecture and plan to eventually have these modules across `cache-manager` and `flat-cache`. In addition there are some breaking changes:
 
 * `get()` and `getMany()` no longer have the `raw` option but instead we have built out `getRaw()` and `getManyRaw()` to use.
 * All `get` related functions now support `nonBlocking` which means if `nonBlocking: true` the primary store will return what it has and then in the background will work to sync from secondary storage for any misses. You can disable this by setting at the `get` function level the option `nonBlocking: false` which will look for any missing keys in the secondary.
-* `Keyv` v5.5+ is now the recommended supported version as we are using its native `getMany*` and `getRaw*`
+* `Keyv` v5.5+ is now the recommended supported version as we are using its native `getMany*`, `getRaw*`, and `hasMany` methods for improved performance
 * `Wrap` and `getOrSet` have been updated with more robust options including the ability to use your own `serialize` function for creating the key in `wrap`.
-* `hash` has now been updated with robust options and also an enum for setting the algorithm.
+* `hash` has been split into async (`hash()` and `hashToNumber()`) and sync (`hashSync()` and `hashToNumberSync()`) methods. MD5 support has been removed. Now uses Hashery library with support for additional algorithms (SHA-384, FNV1, MURMER, CRC32).
 
 # How to Contribute