@hyperttp/cache 1.1.0 → 1.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +64 -55
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
|
+
```markdown
|
|
1
2
|
# hyperttp-cache
|
|
2
3
|
|
|
3
|
-
>
|
|
4
|
+
> [Русский](https://github.com/IT-IF-OR/hyperttp-cache/tree/main/lang/ru) | English
|
|
4
5
|
|
|
5
6
|
---
|
|
6
7
|
|
|
@@ -11,45 +12,45 @@
|
|
|
11
12
|
|
|
12
13
|
---
|
|
13
14
|
|
|
14
|
-
|
|
15
|
-
|
|
15
|
+
Blazing fast, isomorphic cache management and concurrent request deduplication plugin for the high-performance
|
|
16
|
+
`Hyperttp` HTTP client. Optimized for **Bun** and **Node.js** runtimes.
|
|
16
17
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
18
|
+
The plugin seamlessly integrates into the flat `HyperCore` lifecycle pipeline, protecting your backend from server
|
|
19
|
+
breakdown (**Cache Stampede Protection**) and providing smart in-memory storage based on the **LRU (Least Recently Used)**
|
|
20
|
+
strategy.
|
|
20
21
|
|
|
21
22
|
---
|
|
22
23
|
|
|
23
|
-
## 🔥
|
|
24
|
+
## 🔥 Key Features
|
|
24
25
|
|
|
25
|
-
- 🧠 **LRU
|
|
26
|
-
|
|
27
|
-
- 🚀 **In-Flight Deduplication:**
|
|
28
|
-
hot path.
|
|
29
|
-
- 🔄 **HTTP Revalidation:**
|
|
30
|
-
(`If-Modified-Since`).
|
|
31
|
-
- 🛡️
|
|
32
|
-
|
|
33
|
-
- 📊
|
|
34
|
-
|
|
26
|
+
- 🧠 **LRU Strategy with TTL Support:** Automatically evicts old entries when reaching limits. With every `GET`
|
|
27
|
+
request, the entry age resets (`updateAgeOnGet: true`), keeping hot data cached in memory.
|
|
28
|
+
- 🚀 **In-Flight Deduplication:** Concurrent fan-out requests targeting the same URL are grouped into a single network
|
|
29
|
+
hot path. The response is cloned and distributed to all waiting subscribers simultaneously.
|
|
30
|
+
- 🔄 **HTTP Revalidation:** Full freshness verification support via `ETag` (`If-None-Match`) and `Last-Modified`
|
|
31
|
+
(`If-Modified-Since`). Automatically re-hydrates empty `304` responses with cached data bodies.
|
|
32
|
+
- 🛡️ **Fail-Safe Processing:** When network processing exceptions occur, the in-flight waiting pool is instantly
|
|
33
|
+
purged (`onError`), unblocking immediate subsequent retry attempts.
|
|
34
|
+
- 📊 **Core Extension:** Automatically injects cache management methods (`clearCache`) and appends a `cacheSize`
|
|
35
|
+
telemetry metric into the core `getStats()` architecture.
|
|
35
36
|
|
|
36
37
|
---
|
|
37
38
|
|
|
38
|
-
## 📦
|
|
39
|
+
## 📦 Installation
|
|
39
40
|
|
|
40
41
|
```bash
|
|
41
42
|
bun add hyperttp-cache
|
|
42
|
-
#
|
|
43
|
+
# or
|
|
43
44
|
npm install hyperttp-cache
|
|
44
45
|
|
|
45
46
|
```
|
|
46
47
|
|
|
47
48
|
---
|
|
48
49
|
|
|
49
|
-
## 🚀
|
|
50
|
+
## 🚀 Quick Start
|
|
50
51
|
|
|
51
|
-
|
|
52
|
-
|
|
52
|
+
Simply import the `withCache` factory and append it to your client's plugin array. Cache configurations are
|
|
53
|
+
passed directly within the global options block.
|
|
53
54
|
|
|
54
55
|
```typescript
|
|
55
56
|
import { createClient } from "@hyperttp/core";
|
|
@@ -59,75 +60,83 @@ const client = createClient({
|
|
|
59
60
|
plugins: [withCache()],
|
|
60
61
|
cache: {
|
|
61
62
|
enabled: true,
|
|
62
|
-
ttl: 60_000,
|
|
63
|
-
maxSize: 1000,
|
|
64
|
-
methods: ["GET"], // HTTP
|
|
63
|
+
ttl: 60_000, // 1 minute (defaults to 300_000 ms)
|
|
64
|
+
maxSize: 1000, // Limit to 1000 items (defaults to 500)
|
|
65
|
+
methods: ["GET"], // HTTP methods authorized for downstream caching
|
|
65
66
|
},
|
|
66
67
|
});
|
|
67
68
|
|
|
68
|
-
// 1.
|
|
69
|
+
// 1. The first request goes out to the network and populates the cache
|
|
69
70
|
const res1 = await client.get("/api/data");
|
|
70
71
|
|
|
71
|
-
// 2.
|
|
72
|
+
// 2. Subsequent requests instantly return an isolated clone from the cache
|
|
72
73
|
const res2 = await client.get("/api/data");
|
|
74
|
+
|
|
73
75
|
```
|
|
74
76
|
|
|
75
77
|
---
|
|
76
78
|
|
|
77
|
-
## ⚙️
|
|
79
|
+
## ⚙️ Configuration Options (`CacheManagerOptions`)
|
|
78
80
|
|
|
79
|
-
|
|
81
|
+
The plugin configuration layer is fully typed and extends the default client option interfaces:
|
|
80
82
|
|
|
81
|
-
|
|
|
82
|
-
|
|
|
83
|
-
| `cache.enabled` | `boolean`
|
|
84
|
-
| `cache.ttl`
|
|
85
|
-
| `cache.maxSize` | `number`
|
|
86
|
-
| `cache.methods` | `Method[]` | `["GET"]`
|
|
83
|
+
| Parameter | Type | Default | Description |
|
|
84
|
+
| --- | --- | --- | --- |
|
|
85
|
+
| `cache.enabled` | `boolean` | `false` | Activation status flag for the caching layer. |
|
|
86
|
+
| `cache.ttl` | `number` | `300_000` (5 min) | Cache entry time-to-live threshold (in milliseconds). |
|
|
87
|
+
| `cache.maxSize` | `number` | `500` | Maximum entries allowed inside the LRU pool before eviction begins. |
|
|
88
|
+
| `cache.methods` | `Method[]` | `["GET"]` | Array of HTTP methods authorized for response interception. |
|
|
87
89
|
|
|
88
90
|
---
|
|
89
91
|
|
|
90
|
-
## 🛠️ API
|
|
92
|
+
## 🛠️ Core API Extensions
|
|
91
93
|
|
|
92
|
-
|
|
93
|
-
|
|
94
|
+
The plugin extends the global `@hyperttp/types` interface declarations. The following lifecycle methods become
|
|
95
|
+
directly accessible via the client core instance:
|
|
94
96
|
|
|
95
|
-
###
|
|
97
|
+
### Purging Cache
|
|
96
98
|
|
|
97
99
|
```typescript
|
|
98
|
-
//
|
|
100
|
+
// Purge the entire cache system
|
|
99
101
|
client.clearCache();
|
|
100
102
|
|
|
101
|
-
//
|
|
103
|
+
// Evict a specific URL key from the storage
|
|
102
104
|
client.clearCache("/api/data");
|
|
105
|
+
|
|
103
106
|
```
|
|
104
107
|
|
|
105
|
-
###
|
|
108
|
+
### Telemetry
|
|
106
109
|
|
|
107
|
-
|
|
110
|
+
If your core implementation supports the `getStats()` routine, the plugin automatically appends the current cache size:
|
|
108
111
|
|
|
109
112
|
```typescript
|
|
110
113
|
const stats = client.getStats();
|
|
111
|
-
console.log(stats.cacheSize); //
|
|
114
|
+
console.log(stats.cacheSize); // Outputs the current number of active entries inside the LRU storage
|
|
115
|
+
|
|
112
116
|
```
|
|
113
117
|
|
|
114
118
|
---
|
|
115
119
|
|
|
116
|
-
## 📐
|
|
120
|
+
## 📐 Lifecycle Architecture
|
|
117
121
|
|
|
118
|
-
|
|
122
|
+
The plugin utilizes atomic, decoupled lifecycle hooks instead of overhead-heavy middleware wrappers:
|
|
119
123
|
|
|
120
|
-
1. **`onRequest`**:
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
124
|
+
1. **`onRequest`**: Evaluates local key hits inside the `CacheManager`. If the matching record is fresh and doesn't
|
|
125
|
+
require validation, it returns a clone, short-circuiting the chain. If a concurrent request to the same URL is active,
|
|
126
|
+
it hooks into its matching follower `Promise`. If a partial hit requires validation, it appends conditional headers
|
|
127
|
+
(`If-None-Match` / `If-Modified-Since`).
|
|
128
|
+
2. **`onResponse`**: Intercepts successful downstream outputs. Re-hydrates an empty `304 Not Modified` status code
|
|
129
|
+
back into a full `200 OK` response by recovering body content from memory. Saves valid `200` ranges containing validation
|
|
130
|
+
metadata and resolves execution triggers for all waiting `In-Flight` threads.
|
|
131
|
+
3. **`onError`**: In the event of a critical network failure, it instantly flushes matching active tracking task entries
|
|
132
|
+
from the map to ensure subsequent retries targeting the failed endpoint are never deadlocked.
|
|
128
133
|
|
|
129
134
|
---
|
|
130
135
|
|
|
131
|
-
## 📄
|
|
136
|
+
## 📄 License
|
|
132
137
|
|
|
133
138
|
MIT
|
|
139
|
+
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
```
|