Skip to content

Commit da586fe

Browse files
claudeclaude
committed
feat: add Memcached storage adapter and update documentation
Add a new @node-ts-cache/memcached-storage package that provides a Memcached-based storage backend for high-performance distributed caching. The implementation uses the memcached package and supports: - Basic get/set/clear operations via IAsynchronousCacheType interface - Single server or multi-server distributed configuration - Configurable connection options (retries, timeout, poolSize) Also updates all documentation to include both Elasticsearch and Memcached storage adapters in: - Main README.md (packages table, architecture diagram, choosing guide) - ts-cache/README.md (storage engines table) - ts-cache/ADVANCED.md (detailed configuration examples)
1 parent 003c994 commit da586fe

10 files changed

Lines changed: 462 additions & 30 deletions

File tree

‎README.md‎

Lines changed: 25 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -48,13 +48,15 @@ This is a monorepo containing the following packages:
4848

4949
### Storage Adapters
5050

51-
| Package | Version | Description |
52-
| ---------------------------------------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------ |
53-
| [@node-ts-cache/redis-storage](./storages/redis) | ![npm](https://img.shields.io/npm/v/@node-ts-cache/redis-storage.svg) | Redis storage using `redis` package (v4.x) |
54-
| [@node-ts-cache/ioredis-storage](./storages/redisio) | ![npm](https://img.shields.io/npm/v/@node-ts-cache/ioredis-storage.svg) | Redis storage using `ioredis` with compression support |
55-
| [@node-ts-cache/node-cache-storage](./storages/node-cache) | ![npm](https://img.shields.io/npm/v/@node-ts-cache/node-cache-storage.svg) | In-memory cache using `node-cache` |
56-
| [@node-ts-cache/lru-storage](./storages/lru) | ![npm](https://img.shields.io/npm/v/@node-ts-cache/lru-storage.svg) | LRU cache with automatic eviction |
57-
| [@node-ts-cache/lru-redis-storage](./storages/lru-redis) | ![npm](https://img.shields.io/npm/v/@node-ts-cache/lru-redis-storage.svg) | Two-tier caching (local LRU + remote Redis) |
51+
| Package | Version | Description |
52+
| ---------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------ |
53+
| [@node-ts-cache/redis-storage](./storages/redis) | ![npm](https://img.shields.io/npm/v/@node-ts-cache/redis-storage.svg) | Redis storage using `redis` package (v4.x) |
54+
| [@node-ts-cache/ioredis-storage](./storages/redisio) | ![npm](https://img.shields.io/npm/v/@node-ts-cache/ioredis-storage.svg) | Redis storage using `ioredis` with compression support |
55+
| [@node-ts-cache/node-cache-storage](./storages/node-cache) | ![npm](https://img.shields.io/npm/v/@node-ts-cache/node-cache-storage.svg) | In-memory cache using `node-cache` |
56+
| [@node-ts-cache/lru-storage](./storages/lru) | ![npm](https://img.shields.io/npm/v/@node-ts-cache/lru-storage.svg) | LRU cache with automatic eviction |
57+
| [@node-ts-cache/lru-redis-storage](./storages/lru-redis) | ![npm](https://img.shields.io/npm/v/@node-ts-cache/lru-redis-storage.svg) | Two-tier caching (local LRU + remote Redis) |
58+
| [@node-ts-cache/elasticsearch-storage](./storages/elasticsearch) | ![npm](https://img.shields.io/npm/v/@node-ts-cache/elasticsearch-storage.svg) | Elasticsearch storage for search-optimized caching |
59+
| [@node-ts-cache/memcached-storage](./storages/memcached) | ![npm](https://img.shields.io/npm/v/@node-ts-cache/memcached-storage.svg) | Memcached storage for distributed caching |
5860

5961
## Documentation
6062

@@ -80,25 +82,27 @@ For detailed documentation, see the [main package README](./ts-cache/README.md).
8082
│ └───────┬────────┘ │
8183
├──────────────────────────┼──────────────────────────────────────┤
8284
│ ▼ │
83-
│ ┌──────────────────────────────────────────────────────────┐ │
84-
│ │ Storage Layer │ │
85-
│ ├──────────┬──────────┬──────────┬──────────┬─────────────┤ │
86-
│ │ Memory │ FS │ Redis │ LRU │ LRU+Redis │ │
87-
│ └──────────┴──────────┴──────────┴──────────┴─────────────┘ │
85+
│ ┌────────────────────────────────────────────────────────────────────────┐ │
86+
│ │ Storage Layer │ │
87+
│ ├────────┬──────┬───────┬─────┬───────────┬───────────────┬────────────┤ │
88+
│ │ Memory │ FS │ Redis │ LRU │ LRU+Redis │ Elasticsearch │ Memcached │ │
89+
│ └────────┴──────┴───────┴─────┴───────────┴───────────────┴────────────┘ │
8890
└─────────────────────────────────────────────────────────────────┘
8991
```
9092

9193
## Choosing a Storage
9294

93-
| Storage | Type | Use Case | Features |
94-
| ----------------------- | ----- | ---------------------------- | ----------------------------- |
95-
| **MemoryStorage** | Sync | Development, small datasets | Zero config, bundled |
96-
| **FsJsonStorage** | Async | Persistent local cache | File-based, survives restarts |
97-
| **NodeCacheStorage** | Sync | Production single-instance | TTL support, multi-ops |
98-
| **LRUStorage** | Sync | Memory-constrained apps | Auto-eviction, size limits |
99-
| **RedisStorage** | Async | Distributed systems | Shared cache, redis v4 |
100-
| **RedisIOStorage** | Async | Distributed systems | Compression, modern ioredis |
101-
| **LRUWithRedisStorage** | Async | High-performance distributed | Local + remote tiers |
95+
| Storage | Type | Use Case | Features |
96+
| ------------------------ | ----- | ---------------------------- | ------------------------------ |
97+
| **MemoryStorage** | Sync | Development, small datasets | Zero config, bundled |
98+
| **FsJsonStorage** | Async | Persistent local cache | File-based, survives restarts |
99+
| **NodeCacheStorage** | Sync | Production single-instance | TTL support, multi-ops |
100+
| **LRUStorage** | Sync | Memory-constrained apps | Auto-eviction, size limits |
101+
| **RedisStorage** | Async | Distributed systems | Shared cache, redis v4 |
102+
| **RedisIOStorage** | Async | Distributed systems | Compression, modern ioredis |
103+
| **LRUWithRedisStorage** | Async | High-performance distributed | Local + remote tiers |
104+
| **ElasticsearchStorage** | Async | Search-integrated caching | Full-text search, scalable |
105+
| **MemcachedStorage** | Async | High-performance distributed | Simple, fast, widely supported |
102106

103107
## Requirements
104108

‎pnpm-lock.yaml‎

Lines changed: 58 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎storages/memcached/README.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# @node-ts-cache/memcached-storage
2+
3+
Memcached storage adapter for [node-ts-cache](https://github.com/simllll/node-ts-cache).
4+
5+
## Installation
6+
7+
```bash
8+
npm install @node-ts-cache/core @node-ts-cache/memcached-storage
9+
```
10+
11+
## Usage
12+
13+
```typescript
14+
import { Cache, ExpirationStrategy } from '@node-ts-cache/core';
15+
import { MemcachedStorage } from '@node-ts-cache/memcached-storage';
16+
17+
const memcachedCache = new ExpirationStrategy(
18+
new MemcachedStorage({
19+
location: 'localhost:11211'
20+
})
21+
);
22+
23+
class MyService {
24+
@Cache(memcachedCache, { ttl: 60 })
25+
async getUsers(): Promise<User[]> {
26+
// expensive operation
27+
}
28+
}
29+
```
30+
31+
## Configuration Options
32+
33+
```typescript
34+
interface MemcachedStorageOptions {
35+
/** Memcached server location(s) - e.g., 'localhost:11211' or ['server1:11211', 'server2:11211'] */
36+
location: Memcached.Location;
37+
/** Memcached client options */
38+
options?: Memcached.options;
39+
}
40+
```
41+
42+
### Multiple Servers (Distributed)
43+
44+
Memcached supports distributed caching across multiple servers:
45+
46+
```typescript
47+
import { MemcachedStorage } from '@node-ts-cache/memcached-storage';
48+
49+
const storage = new MemcachedStorage({
50+
location: ['server1:11211', 'server2:11211', 'server3:11211'],
51+
options: {
52+
retries: 3,
53+
timeout: 5000,
54+
poolSize: 10
55+
}
56+
});
57+
```
58+
59+
### Available Options
60+
61+
The `options` parameter accepts all standard [memcached](https://www.npmjs.com/package/memcached) options:
62+
63+
- `maxKeySize` - Maximum key size (default: 250)
64+
- `maxValue` - Maximum value size (default: 1048576)
65+
- `poolSize` - Connection pool size (default: 10)
66+
- `retries` - Number of retries for failed operations (default: 5)
67+
- `timeout` - Operation timeout in milliseconds (default: 5000)
68+
- `idle` - Idle timeout for connections (default: 5000)
69+
70+
## Running Tests Locally
71+
72+
Start Memcached using Docker:
73+
74+
```bash
75+
docker run -p 11211:11211 memcached:latest
76+
```
77+
78+
Then run the tests:
79+
80+
```bash
81+
npm test
82+
```
83+
84+
## License
85+
86+
MIT

‎storages/memcached/package.json‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
{
2+
"name": "@node-ts-cache/memcached-storage",
3+
"version": "1.0.0",
4+
"description": "Memcached storage adapter for node-ts-cache",
5+
"type": "module",
6+
"exports": {
7+
".": {
8+
"types": "./dist/index.d.ts",
9+
"import": "./dist/index.js"
10+
}
11+
},
12+
"files": [
13+
"dist"
14+
],
15+
"scripts": {
16+
"build": "tsc -p .",
17+
"clean": "git clean -fdx src",
18+
"dev": "tsc -p . -w",
19+
"prepublishOnly": "tsc -p .",
20+
"test": "vitest run"
21+
},
22+
"repository": {
23+
"type": "git",
24+
"url": "git+https://github.com/simllll/node-ts-cache.git"
25+
},
26+
"keywords": [
27+
"typescript",
28+
"cache",
29+
"memcached",
30+
"storage"
31+
],
32+
"author": "simllll",
33+
"license": "MIT",
34+
"bugs": {
35+
"url": "https://github.com/simllll/node-ts-cache/issues"
36+
},
37+
"homepage": "https://github.com/simllll/node-ts-cache#readme",
38+
"dependencies": {
39+
"@node-ts-cache/core": "workspace:*",
40+
"memcached": "^2.2.2"
41+
},
42+
"devDependencies": {
43+
"@types/memcached": "^2.2.10"
44+
},
45+
"engines": {
46+
"node": ">=18.0.0"
47+
},
48+
"publishConfig": {
49+
"access": "public"
50+
}
51+
}

‎storages/memcached/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
export { MemcachedStorage, MemcachedStorageOptions } from './memcached.storage.js';

0 commit comments

Comments
 (0)