@openclaw/whatsapp 2026.7.1-beta.2 → 2026.7.1-beta.4

package/node_modules/cacheable/README.md

@@ -29,9 +29,13 @@
 * [v1 to v2 Changes](#v1-to-v2-changes)
 * [Basic Usage](#basic-usage)
 * [Hooks and Events](#hooks-and-events)
+  * [Overriding the TTL in a BEFORE_SET Hook](#overriding-the-ttl-in-a-before_set-hook)
 * [Storage Tiering and Caching](#storage-tiering-and-caching)
 * [TTL Propagation and Storage Tiering](#ttl-propagation-and-storage-tiering)
+* [Per-Store TTL per Operation](#per-store-ttl-per-operation)
 * [Shorthand for Time to Live (ttl)](#shorthand-for-time-to-live-ttl)
+* [Maximum Time to Live (maxTtl)](#maximum-time-to-live-maxttl)
+* [Tag Based Invalidation](#tag-based-invalidation)
 * [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)
@@ -39,6 +43,7 @@
 * [Cacheable Options](#cacheable-options)
 * [Cacheable Statistics (Instance Only)](#cacheable-statistics-instance-only)
 * [Cacheable - API](#cacheable---api)
+* [Static Instance (Singleton)](#static-instance-singleton)
 * [CacheableMemory - In-Memory Cache](#cacheablememory---in-memory-cache)
 * [Keyv Storage Adapter - KeyvCacheableMemory](#keyv-storage-adapter---keyvcacheablememory)
 * [Wrap / Memoization for Sync and Async Functions](#wrap--memoization-for-sync-and-async-functions)
@@ -114,6 +119,61 @@ cacheable.onHook(CacheableHooks.BEFORE_SET, (data) => {
 });
 ```
 
+## Overriding the TTL in a BEFORE_SET Hook
+
+A `BEFORE_SET` hook can change an entry's time-to-live by reassigning `data.ttl`. This works for `set()`, `getOrSet()`, and `wrap()` because they all run through `BEFORE_SET`. You can assign a single value (applied to every store) or a per-store object so the primary and secondary stores expire at different rates:
+
+```javascript
+import { Cacheable, CacheableHooks } from 'cacheable';
+import KeyvRedis from '@keyv/redis';
+const secondary = new KeyvRedis('redis://user:pass@localhost:6379');
+const cache = new Cacheable({ secondary });
+
+cache.onHook(CacheableHooks.BEFORE_SET, (data) => {
+  // Keep this entry short-lived in memory (primary) but longer in Redis (secondary)
+  data.ttl = { primary: '10s', secondary: '5m' };
+});
+```
+
+Each store resolves its TTL independently, taking the first defined value down this list and then capping it with [`maxTtl`](#maximum-time-to-live-maxttl). This is the single source of truth for how *every* TTL (operation, hook, or default) is resolved:
+
+| Precedence (highest first) | Primary store | Secondary store |
+| --- | --- | --- |
+| 1. `BEFORE_SET` hook | `data.ttl` (scalar, or `.primary`) | `data.ttl` (scalar, or `.secondary`) |
+| 2. Operation `ttl` | `ttl` (scalar, or `.primary`) | `ttl` (scalar, or `.secondary`) |
+| 3. Store default | `new Keyv({ ttl })` on the primary | `new Keyv({ ttl })` on the secondary |
+| 4. Instance `ttl` | `new Cacheable({ ttl })` | `new Cacheable({ ttl })` |
+| Cap (applied last) | `maxTtl` | `maxTtl` |
+
+What happens when you override:
+
+* **Per-store object** (`{ primary, secondary }`): each field applies to that store independently. A field you leave out falls back to that store's normal resolution — including any per-store `ttl` you passed to the operation.
+* **Scalar** (a number or [shorthand string](#shorthand-for-time-to-live-ttl)): applied to **every** store, discarding any per-store `secondary` you passed to the operation. Use the object form if you want the stores to differ.
+* **Any assignment counts as an override**, even assigning the value `data.ttl` already holds. Leaving `data.ttl` untouched keeps each store on its normal resolution (the default behavior).
+* **`0`, `null`, or `undefined` clears the TTL** → the entry never expires, *ignoring* the cascade (store default and instance `ttl`). This matches the "disable the ttl" behavior in [Shorthand for Time to Live](#shorthand-for-time-to-live-ttl); take care when assigning a possibly-nullable value to `data.ttl`.
+* **An invalid shorthand string aborts the whole write.** Assigning an unparseable string (e.g. `'10 seconds'`) throws; `set` catches it, emits the [`error` event](#hooks-and-events), and returns `false` **without caching** — so a hook typo silently disables caching for that write. Listen on `error` to catch it.
+* **`maxTtl` is re-applied to each store after the hook**, so a hook can never push an entry past the cap.
+* **Tag snapshots** use the longer of the two store TTLs (and never expire while either copy is immortal, including `ttl: 0`) so [tag invalidation](#tag-based-invalidation) can always reach the longest-lived copy.
+* By the time **`AFTER_SET`** runs (and for [sync replication](#cacheablesync---distributed-updates)), `data.ttl` has been normalized to the effective **primary** TTL as a number; the secondary store's effective TTL is not exposed on the item. **`AFTER_SET_MANY` differs:** `setMany` does not mutate the items you passed, so a handler there still sees each `item.ttl` exactly as set (a per-store object stays an object).
+
+> **TypeScript:** `onHook(CacheableHooks.BEFORE_SET, (data) => …)` types `data` automatically — no annotation needed, and an invalid `data.ttl` shape is a compile error. Payload types are exported too (`CacheableHookItem`, `CacheableSetItem`).
+
+> **Note on backfills:** like a per-store `ttl` passed to an operation, a primary TTL set by a hook governs only that write — it is not persisted per key. Once the primary copy expires, the next read repopulates the primary from the secondary using the usual [TTL propagation](#ttl-propagation-and-storage-tiering) rules. Set a primary store default TTL (`new Keyv({ ttl })`) or an instance `maxTtl` if you need the primary to stay short across backfills.
+
+> **Note on sync:** a per-store TTL writes the secondary's TTL to the (typically shared) secondary store directly; [CacheableSync](#cacheablesync---distributed-updates) replicates only the **primary** TTL to other instances' in-memory primaries. For the usual shared-secondary topology this is correct — the secondary is written once and read by every instance.
+
+The same per-store object is accepted by `setMany` items and the `BEFORE_SET_MANY` hook:
+
+```javascript
+cache.onHook(CacheableHooks.BEFORE_SET_MANY, (items) => {
+  for (const item of items) {
+    item.ttl = { primary: '10s', secondary: '5m' };
+  }
+});
+
+await cache.setMany([{ key: 'a', value: 1, ttl: { primary: '10s', secondary: '5m' } }]);
+```
+
 Here is an example of how to use `BEFORE_SECONDARY_SETS_PRIMARY` hook:
 
 ```javascript
@@ -125,7 +185,7 @@ cache.onHook(CacheableHooks.BEFORE_SECONDARY_SETS_PRIMARY, (data) => {
   console.log(`before secondary sets primary: ${data.key} ${data.value} ${data.ttl}`);
 });
 ```
-This is called when the secondary store sets the value in the primary store. This is useful if you want to do something before the value is set in the primary store such as manipulating the ttl or the value.
+This is called when the secondary store sets the value in the primary store. This is useful if you want to do something before the value is set in the primary store such as manipulating the ttl or the value. Because this hook only writes the primary store, its `ttl` is a single value (a number or shorthand string), not a per-store object.
 
 The following events are provided:
 
@@ -210,6 +270,43 @@ ttl = set at the function ?? storage adapter ttl ?? cacheable ttl
 
 This means that if you set a TTL at the function level it will override the storage adapter TTL and the cacheable TTL. If you do not set a TTL at the function level it will use the storage adapter TTL and then the cacheable TTL. If you do not set a TTL at all it will use the default TTL of `undefined` which is disabled.
 
+# Per-Store TTL per Operation
+
+When you override the `ttl` on an operation it normally applies to both the primary and secondary stores. If you want each store to expire at a different rate for that specific key, pass a per-store object as the `ttl` with `primary` and/or `secondary` fields. Each field accepts a number in milliseconds or a [shorthand string](#shorthand-for-time-to-live-ttl).
+
+```javascript
+import { Cacheable } from 'cacheable';
+import { Keyv } from 'keyv';
+import KeyvRedis from '@keyv/redis';
+const secondary = new KeyvRedis('redis://user:pass@localhost:6379');
+const cache = new Cacheable({ secondary });
+
+// Keep this key 10 seconds in memory (primary) but 5 minutes in Redis (secondary)
+await cache.set('key', 'value', { ttl: { primary: '10s', secondary: '5m' } });
+```
+
+Any field you leave out falls back to that store's own default TTL resolution (storage adapter TTL, then the cacheable instance TTL). For example, only overriding the primary store leaves the secondary on its default:
+
+```javascript
+const secondary = new Keyv({ store: new KeyvRedis('redis://user:pass@localhost:6379'), ttl: '1h' });
+const cache = new Cacheable({ secondary });
+
+// Primary expires in 10s; secondary keeps its own 1 hour default
+await cache.set('key', 'value', { ttl: { primary: '10s' } });
+```
+
+The per-store object works anywhere a `ttl` is accepted, including [`getOrSet`](#get-or-set-memoization-function) and [`wrap`](#wrap--memoization-for-sync-and-async-functions):
+
+```javascript
+await cache.getOrSet('key', async () => 'value', { ttl: { primary: '10s', secondary: '5m' } });
+
+const getUser = cache.wrap(fetchUser, { ttl: { primary: '1m', secondary: '1d' } });
+```
+
+Passing a plain number or shorthand string (such as `'1h'`) still applies the same TTL to every store, and the [`maxTtl`](#maximum-time-to-live-maxttl) cap is applied to each store independently. The same per-store object is accepted by `setMany` items, and a [`BEFORE_SET` hook](#overriding-the-ttl-in-a-before_set-hook) can override these per-store TTLs and takes precedence over the value passed to the operation.
+
+> **Note on backfills:** A per-store TTL (whether passed to the operation or set by a `BEFORE_SET` hook) governs the *write* of that operation. The primary TTL is not persisted per key, so once a primary (layer 1) entry expires, the next read is served from the secondary and repopulates the primary using the secondary's remaining lifetime — following the usual [TTL propagation](#ttl-propagation-and-storage-tiering) rules — rather than re-applying the original primary TTL. If you need the primary to keep a consistently shorter lifetime across backfills, set a primary store default TTL (`new Keyv({ ttl })`) or an instance `maxTtl`, which both bound the repopulated TTL.
+
 # Shorthand for Time to Live (ttl)
 
 By default `Cacheable` and `CacheableMemory` the `ttl` is in milliseconds but you can use shorthand for the time to live. Here are the following shorthand values:
@@ -303,42 +400,88 @@ The `hasMany` method returns an array of booleans in the same order as the input
 
 # 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.
+The `Cacheable` class exposes both `primary` and `secondary` as [Keyv](https://keyv.org) instances. Keyv provides an `iterator()` async generator for walking every entry in a store, but **it is only available on stores that support iteration**. When a store does not support it, `keyv.iterator` is `undefined`, so you must feature-check it before calling.
+
+Keyv enables `iterator()` for:
+
+- A plain `new Keyv()` whose store is a `Map` (the Keyv default), and
+- The server-backed adapters Keyv recognizes as iterable: `@keyv/redis`, `@keyv/valkey`, `@keyv/mongo`, `@keyv/sqlite`, `@keyv/postgres`, `@keyv/mysql`, and `@keyv/etcd`.
+
+> **Heads up:** Cacheable's *default* primary store is the high-performance in-memory store from [`@cacheable/memory`](https://cacheable.org/docs/memory/) (created with `createKeyv()`). It is neither a raw `Map` nor one of the recognized adapters, so `cache.primary.iterator` is `undefined`. See [Iterating the default in-memory primary](#iterating-the-default-in-memory-primary) for how to walk it.
 
 **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
+- Always check that `iterator` exists before using it — it is `undefined` on stores that don't support iteration.
+- The iterator filters by namespace, skips expired entries (deleting them), and deserializes values for you.
+- **Performance Warning:** Iterating can be expensive on large datasets (for example, `@keyv/redis` uses `SCAN` under the hood). Avoid it on hot paths.
+
+## Iterating a Secondary Store
+
+A secondary store backed by a recognized adapter (Redis, Valkey, Mongo, SQLite, Postgres, MySQL, etcd) supports `iterator()` directly. Each iteration yields a `[key, value]` tuple:
 
 ```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.secondary?.iterator) {
+    for await (const [key, value] of cache.secondary.iterator()) {
+        console.log(`${key}:`, value);
+    }
+}
+```
+
+## Iterating the Primary Store
+
+If you need a primary store you can walk with `iterator()`, use a `Map`-backed `new Keyv()` (or any recognized adapter) as the primary. A plain `Keyv` is iterable because its default store is a `Map`:
+
+```typescript
+import { Cacheable } from 'cacheable';
+import { Keyv } from 'keyv';
+
+const cache = new Cacheable({ primary: new Keyv() });
+
+await cache.set('user:1', { name: 'Alice' });
+await cache.set('user:2', { name: 'Bob' });
+
 if (cache.primary.iterator) {
     for await (const [key, value] of cache.primary.iterator()) {
-        console.log(`  ${key}:`, JSON.stringify(value));
+        console.log(`${key}:`, 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));
-    }
+### Iterating the default in-memory primary
+
+The default primary from `@cacheable/memory` does not provide a Keyv `iterator()`. To walk it, reach the underlying `CacheableMemory` store through `cache.primary.store` and use its `items` iterator. Each item is a `{ key, value, expires }` record (expired entries are skipped automatically), where `value` holds Keyv's stored envelope — the decoded value is at `item.value.value`:
+
+```typescript
+import { Cacheable, KeyvCacheableMemory } from 'cacheable';
+
+const cache = new Cacheable();
+await cache.set('user:1', { name: 'Alice' });
+await cache.set('user:2', { name: 'Bob' });
+
+// cache.primary.store is the KeyvCacheableMemory adapter; its .store is the CacheableMemory
+const memory = (cache.primary.store as KeyvCacheableMemory).store;
+
+for (const item of memory.items) {
+    // item.value is Keyv's { value, expires } envelope
+    console.log(`${item.key}:`, item.value.value);
+}
+```
+
+If you'd rather not depend on the envelope shape, iterate the keys and read each entry back through the cache:
+
+```typescript
+const memory = (cache.primary.store as KeyvCacheableMemory).store;
+for (const { key } of memory.items) {
+    console.log(`${key}:`, await cache.get(key));
 }
 ```
 
@@ -373,18 +516,22 @@ await iterateStore(cache.primary, 'Primary');
 await iterateStore(cache.secondary, 'Secondary');
 ```
 
+Note that with the default configuration the `Primary` branch above will report that it "does not support iteration" — that is expected, because the default `@cacheable/memory` primary has no `iterator()`. Use the [`CacheableMemory.items`](#iterating-the-default-in-memory-primary) approach for it.
+
 ## 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
+Keyv assigns an `iterator()` method only when the store is a raw `Map` or one of the adapters it recognizes as iterable. For every other store, `keyv.iterator` is `undefined`.
+
+Stores that support `iterator()`:
+
+- A plain `new Keyv()` (its store is a `Map`)
+- `@keyv/redis` and `@keyv/valkey`
+- `@keyv/mongo`, `@keyv/sqlite`, `@keyv/postgres`, `@keyv/mysql`, and `@keyv/etcd`
 
-Common stores that support iteration:
-- In-memory (Map-based stores)
-- @keyv/redis
-- @keyv/valkey
-- Other Keyv adapters that implement the iterator interface
+Stores that do **not** support `iterator()`:
+
+- The default `@cacheable/memory` primary (`createKeyv()`) — walk it through its [`CacheableMemory.items`](#iterating-the-default-in-memory-primary) accessor instead
+- Any adapter that doesn't implement Keyv's iterable interface
 
 # Non-Blocking Operations
 
@@ -607,6 +754,94 @@ const value = await serviceB.get('config'); // undefined
 * The sync feature requires a message provider to be running and accessible by all cache instances.
 * Each cache instance has a unique `cacheId`. Events are only applied if they come from a different instance, preventing infinite loops.
 
+# Maximum Time to Live (maxTtl)
+
+You can set a `maxTtl` option to enforce an upper bound on any TTL in the cache. When `maxTtl` is set:
+- Any per-entry TTL that exceeds `maxTtl` will be capped to `maxTtl`.
+- Entries with no TTL (that would otherwise live indefinitely) will be capped to `maxTtl`.
+- The default TTL is still respected if it is within the `maxTtl` limit.
+- The `maxTtl` is enforced on both primary and secondary stores.
+- A TTL set by a [`BEFORE_SET` hook](#overriding-the-ttl-in-a-before_set-hook) is also capped, per store.
+
+This is useful when you want to guarantee that no cache entry lives longer than a certain duration, regardless of what TTL is passed to individual `set()` calls or set by a hook.
+
+```javascript
+import { Cacheable } from 'cacheable';
+
+// No entry can live longer than 1 hour
+const cache = new Cacheable({ maxTtl: '1h' });
+
+await cache.set('key1', 'value1', '2h'); // capped to 1 hour
+await cache.set('key2', 'value2');        // also capped to 1 hour (would otherwise be indefinite)
+await cache.set('key3', 'value3', '30m'); // 30 minutes is within maxTtl, so it stays as-is
+```
+
+You can also set `maxTtl` after construction:
+
+```javascript
+const cache = new Cacheable();
+cache.maxTtl = 5000; // 5 seconds max
+cache.maxTtl = '10m'; // 10 minutes max
+cache.maxTtl = undefined; // disable maxTtl (no upper bound)
+```
+
+# Tag Based Invalidation
+
+You can associate cache entries with tags and later invalidate every entry that shares a tag in a single call. This is useful for content caching where one upstream entity (a product, a user, a CMS document) is referenced by many cache entries:
+
+```javascript
+import { Cacheable } from 'cacheable';
+
+const cache = new Cacheable({ tags: true });
+
+await cache.set('page:/products', html, { ttl: '10m', tags: ['entity:42', 'collection:products'] });
+await cache.set('page:/products/42', detailHtml, { ttl: '10m', tags: ['entity:42'] });
+
+// entity 42 changed - purge everything that referenced it
+await cache.tags.invalidateTag('entity:42');
+
+await cache.get('page:/products'); // undefined
+await cache.get('page:/products/42'); // undefined
+```
+
+You can also pass tags per item with `setMany`, and invalidate several tags at once:
+
+```javascript
+await cache.setMany([
+  { key: 'user:1', value: userOne, tags: ['users'] },
+  { key: 'user:2', value: userTwo, tags: ['users', 'org:7'] },
+]);
+
+await cache.tags.invalidateTags(['users', 'org:7']);
+```
+
+Tag functionality lives on the `tags` service — an instance of the `CacheTags` class from [`@cacheable/utils`](https://npmjs.com/package/@cacheable/utils) that is created by default in the constructor. Invalidation uses a lazy, constant-time model: `invalidateTag` simply bumps a version counter for the tag, no matter how many entries reference it. Each tagged entry stores a snapshot of its tags' versions, and on the next `get` / `getMany` the snapshot is compared to the live versions. If any tag has been bumped since, the entry is treated as a miss and removed from both the primary and secondary stores (and a `delete` is published via [sync](#cacheablesync---distributed-updates) when enabled). The trade-off is one additional tag-store read per cache lookup while the tag service is enabled.
+
+Tag metadata is stored in the secondary store when one is configured, otherwise in the primary store. With a shared secondary store (such as Redis), an invalidation performed by one instance is seen by every instance:
+
+```javascript
+import { Cacheable } from 'cacheable';
+import KeyvRedis from '@keyv/redis';
+
+// enable tags on every instance that shares the store - writers and readers
+const writer = new Cacheable({ secondary: new KeyvRedis('redis://localhost:6379'), tags: true });
+const reader = new Cacheable({ secondary: new KeyvRedis('redis://localhost:6379'), tags: true });
+
+await writer.set('page:/products', html, { tags: ['entity:42'] });
+await writer.tags.invalidateTag('entity:42');
+await reader.get('page:/products'); // undefined - stale copy is also purged from reader's primary
+```
+
+The tag service is disabled by default so untagged workloads pay no extra cost, and you have to turn it on to use it — either with the `tags: true` option or by setting `cache.tags.enabled = true`. While disabled, all tag operations are no-ops: values set with `tags` are stored without tag tracking and invalidations have no effect. The service never enables itself, which keeps behavior predictable across distributed instances — enable it on every instance that shares the store (writers and readers) so invalidations are honored and tag snapshots are cleaned up consistently.
+
+The full `CacheTags` API is available on the service:
+
+```javascript
+await cache.tags.getTags('page:/products'); // ['entity:42', 'collection:products']
+await cache.tags.getKeysByTag('entity:42'); // keys referencing a tag (debugging / tests)
+cache.tags.enabled; // whether freshness checks run on get / getMany
+```
+
 # Cacheable Options
 
 The following options are available for you to configure `cacheable`:
@@ -616,8 +851,10 @@ The following options are available for you to configure `cacheable`:
 * `nonBlocking`: If the secondary store is non-blocking. Default is `false`.
 * `stats`: To enable statistics for this instance. Default is `false`.
 * `ttl`: The default time to live for the cache in milliseconds. Default is `undefined` which is disabled.
+* `maxTtl`: The maximum time to live for any cache entry. When set, TTLs exceeding this value are capped. Enforced on both primary and secondary stores. Default is `undefined` (no maximum).
 * `namespace`: The namespace for the cache. Default is `undefined`.
 * `cacheId`: A unique identifier for this cache instance. Used for sync filtering. Default is a random string.
+* `tags`: Enables the tag service so tag-based invalidation can be used and freshness checks run on `get` / `getMany`. Tags must be explicitly enabled — while disabled, all tag operations are no-ops. Default is `false`.
 * `sync`: Enable distributed cache synchronization. Can be:
   - `CacheableSync` instance
   - `CacheableSyncOptions` object with `{ qified: MessageProvider | MessageProvider[] | Qified }`
@@ -642,8 +879,8 @@ _This does not enable statistics for your layer 2 cache as that is a distributed
 
 # Cacheable - API
 
-* `set(key, value, ttl?)`: Sets a value in the cache.
-* `setMany([{key, value, ttl?}])`: Sets multiple values in the cache.
+* `set(key, value, ttlOrOptions?)`: Sets a value in the cache. The third argument can be a `ttl` or an options object such as `{ ttl: '1h', tags: ['entity:42'] }`.
+* `setMany([{key, value, ttl?, tags?}])`: Sets multiple values in the cache.
 * `get(key)`: Gets a value from the cache.
 * `get(key, { raw: true })`: Gets a raw value from the cache.
 * `getMany([keys])`: Gets multiple values from the cache.
@@ -655,6 +892,7 @@ _This does not enable statistics for your layer 2 cache as that is a distributed
 * `delete(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.
+* `tags`: The `CacheTags` service from `@cacheable/utils` used for tag-based invalidation, such as `tags.invalidateTag(tag)`, `tags.invalidateTags([tags])`, `tags.getTags(key)`, `tags.getKeysByTag(tag)`, and `tags.enabled`.
 * `wrap(function, WrapOptions)`: Wraps an `async` function in a cache.
 * `getOrSet(GetOrSetKey, valueFunction, GetOrSetFunctionOptions)`: Gets a value from cache or sets it if not found using the provided function.
 * `disconnect()`: Disconnects from the cache stores.
@@ -664,12 +902,51 @@ _This does not enable statistics for your layer 2 cache as that is a distributed
 * `removeListener(event, callback)`: Removes a listener.
 * `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`.
+* `getStaticInstance(options?)`: Static. Gets a shared singleton instance, creating it on the first call. Options apply only on first creation; passing options after init emits an `error` event and is otherwise ignored.
+* `setStaticInstance(instance?)`: Static. Sets or clears the shared singleton instance. Pass `undefined` to reset it.
 * `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.
+* `maxTtl`: The maximum time to live for any cache entry. When set, TTLs exceeding this value are capped. Default is `undefined` (no maximum).
 * `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`.
 
+# Static Instance (Singleton)
+
+If you want a single cache shared across your application without constructing a `Cacheable` instance and passing it around, use the static `getStaticInstance()` accessor. The first call creates the shared instance; every later call returns that same instance:
+
+```javascript
+import { Cacheable } from 'cacheable';
+
+const cache = Cacheable.getStaticInstance({ ttl: '1h' });
+await cache.set('key', 'value');
+
+// Anywhere else in your app, the same instance is returned:
+const same = Cacheable.getStaticInstance();
+```
+
+Options are only applied when the instance is first created. If you pass options again after the instance already exists, they are ignored and an `error` event is emitted on the instance to surface the conflict — listen with `cache.on('error', ...)`. To reconfigure, replace the instance with `setStaticInstance()` (shown below).
+
+You can replace or reset the shared instance with `setStaticInstance()`. Pass a `Cacheable` instance to swap it, or `undefined` to clear it so the next `getStaticInstance()` call creates a fresh one:
+
+```javascript
+import { Cacheable } from 'cacheable';
+import KeyvRedis from '@keyv/redis';
+
+// Provide a fully configured instance as the shared one
+Cacheable.setStaticInstance(new Cacheable({ secondary: new KeyvRedis('redis://localhost:6379') }));
+
+// Reset back to no shared instance
+Cacheable.setStaticInstance(undefined);
+```
+
+Things to know:
+
+* The shared instance is process-global and long-lived. Calling `clear()` or `disconnect()` on it affects every part of your app that uses it.
+* After `disconnect()`, `getStaticInstance()` keeps returning the same (now disconnected) instance — it is not recreated automatically. Call `setStaticInstance(undefined)` first, then `getStaticInstance()` to get a fresh one.
+* `setStaticInstance(undefined)` only drops the reference; it does not `disconnect()` or `clear()` the previous instance, so disconnect it first if it holds open connections.
+* This package ships separate CommonJS and ESM builds. An app (or dependency graph) that loads both formats gets one shared instance *per build*, not one process-wide. For a single shared cache, use one module format, or create the instance once and share it via `setStaticInstance()`.
+
 # CacheableMemory - In-Memory Cache
 
 `cacheable` comes with a built-in in-memory cache called `CacheableMemory` from `@cacheable/memory`. 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`:
@@ -791,13 +1068,15 @@ The `getOrSet`  method that comes from [@cacheable/utils](https://cacheable.org/
 
 ```typescript
 export type GetOrSetFunctionOptions = {
-	ttl?: number | string;
+	ttl?: number | string | { primary?: number | string; secondary?: number | string };
 	cacheErrors?: boolean;
 	throwErrors?: boolean;
 	nonBlocking?: boolean;
 };
 ```
 
+The `ttl` also accepts a [per-store object](#per-store-ttl-per-operation) such as `{ primary: '10s', secondary: '5m' }` to give the primary and secondary stores different expirations for this operation.
+
 The `nonBlocking` option allows you to override the instance-level `nonBlocking` setting for the `get` call within `getOrSet`. When set to `false`, the `get` will block and wait for a response from the secondary store before deciding whether to call the provided function. When set to `true`, the primary store returns immediately and syncs from secondary in the background.
 
 Here is an example of how to use the `getOrSet` method: