Solidis

The fastest Redis client for Node.js.
Zero dependencies, 2x+ faster than ioredis, battle-tested in production.


npm coverage deps bundle RESP modules

빠른 시작  ·  기능  ·  설정  ·  아키텍처  ·  확장  ·  English


번들 크기 비교

Rocket
0 deps
제로 의존성		 Package
383
커맨드		 Test Tube
19K+
테스트 라인		 Feather
< 29KB
최소 번들

## 빠른 시작 ```bash npm install @vcms-io/solidis ``` ```typescript import { SolidisFeaturedClient } from '@vcms-io/solidis/featured'; const client = new SolidisFeaturedClient({ host: '127.0.0.1', port: 6379 }); await client.set('key', 'value'); const value = await client.get('key'); ``` > [!TIP] > **번들 크기가 중요하다면?** `SolidisClient` + `.extend()`로 쓰는 커맨드만 가져오세요. > 트리 쉐이킹 적용 시 **< 29KB**까지 줄일 수 있습니다.
  트리 쉐이킹 클라이언트
```typescript import { SolidisClient } from '@vcms-io/solidis'; import { get } from '@vcms-io/solidis/command/get'; import { set } from '@vcms-io/solidis/command/set'; import type { SolidisClientExtensions } from '@vcms-io/solidis'; const extensions = { get, set } satisfies SolidisClientExtensions; const client = new SolidisClient({ host: '127.0.0.1', port: 6379 }).extend(extensions); ```
  트랜잭션 & 파이프라인
```typescript // 트랜잭션 (MULTI/EXEC) const tx = client.multi(); tx.set('key', 'value'); tx.incr('counter'); const results = await tx.exec(); // 파이프라인 (raw) const results = await client.send([ ['set', 'a', '1'], ['incr', 'counter'], ['get', 'a'] ]); ```
  Pub/Sub
```typescript client.on('message', (channel, message) => { console.log(`${channel}: ${message}`); }); await client.subscribe('events'); ```

## Bar Chart 벤치마크
# High Voltage Solidis vs ioredis High Voltage 측정일 2026-06-20 11:21:19 · linux x64 · Node.js v22.22.3 ### ioredis 대비 최대 **2.1x 빠릅니다**! Rocket ---
**15**개 중 **15**개 벤치마크 우위 · 평균 **72%** 성능 향상 · 최대 **106%** 성능 향상 _100,000번 반복 × 10,000 동시 실행 · 1 KB 페이로드 · 10회 측정_ | | 벤치마크 | 명령어 | solidis | ioredis | 차이 | 성능 | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :------------------ | :-----------------------------------------------------------------------------------------------------: | :--------: | :-----: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------- | | 1st Place Medal | **Set 변경** | SADD SISMEMBER SREM | **1651ms** | 3396ms | **2.1x** FireFire | `██████████` | | 2nd Place Medal | **List 범위** | LPUSH RPUSH LRANGE | **1860ms** | 3623ms | **1.9x** FireFire | `█████████░` | | 3rd Place Medal | **Multi-Key** | MSET MGET | **1623ms** | 3045ms | **1.9x** FireFire | `████████░░` | | 4. | **List 변경** | LPUSH RPUSH LPOP RPOP LLEN | **2615ms** | 4844ms | **1.9x** FireFire | `████████░░` | | 5. | **Set** | SET | **754ms** | 1352ms | **1.8x** FireFire | `████████░░` | | 6. | **Set 조회** | SADD SISMEMBER SMEMBERS | **1842ms** | 3267ms | **1.8x** FireFire | `███████░░░` | | 7. | **Hash 변경** | HMSET HMGET HDEL | **1933ms** | 3414ms | **1.8x** FireFire | `███████░░░` | | 8. | **Sorted Set** | ZADD ZRANGE ZREM | **1559ms** | 2673ms | **1.7x** FireFire | `███████░░░` | | 9. | **Expire** | SET EXPIRE TTL | **1478ms** | 2530ms | **1.7x** FireFire | `███████░░░` | | 10. | **비트랜잭션** | SETPX GET | **1227ms** | 2051ms | **1.7x** FireFire | `██████░░░░` | | 11. | **Stream** | XADD XRANGE XLEN | **1986ms** | 3216ms | **1.6x** FireFire | `██████░░░░` | | 12. | **Hash 왕복** | HSET HGET HGETALL | **1829ms** | 2749ms | **1.5x** Fire | `█████░░░░░` | | 13. | **Counter** | INCR DECR | **988ms** | 1481ms | **1.5x** Fire | `█████░░░░░` | | 14. | **파이프라인 혼합** | SET INCR GET | **1710ms** | 2562ms | **1.5x** Fire | `█████░░░░░` | | 15. | **Get Buffer** | GETBUFFER | **649ms** | 960ms | **1.5x** Fire | `█████░░░░░` | ### 엄격 비교가 불가능한 벤치마크 라이브러리별 고유 동작으로 인해 엄밀한 비교가 어려운 벤치마크입니다. | | 벤치마크 | 명령어 | solidis | ioredis | 차이 | 성능 | | --: | :---------------- | :-------------------------------------------------------------------: | :-----: | :-----: | :-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | :----------- | | 16. | **Pub/Sub** | PUBLISH MESSAGE | 717ms | 2679ms | **3.7x** FireFire | `██████████` | | 17. | **트랜잭션** | SET EXPIRE GET | 1285ms | 4760ms | **3.7x** FireFire | `██████████` | | 18. | **트랜잭션 혼합** | SET GET | 1708ms | 6079ms | **3.6x** FireFire | `██████████` | | 19. | **Info / Config** | INFO CONFIGGET | 1073ms | 1993ms | **1.9x** FireFire | `████████░░` | `solidis`의 `ioredis` (기준) 대비 성능 향상률 순으로 정렬. 소요 시간 = 반복 측정의 중앙값.

## Bar Chart 상세 지표 라이브러리별 전체 지표: 초당 작업 수, 초당 명령 수, 소요 시간 중앙값, 분산 (변동 계수).
상세 지표 테이블 펼치기 | 벤치마크 | 라이브러리 | ops/s | cmds/s | 소요 시간 | 분산 | | :----------------------------------------------------------------------------------------------------------------------------------------- | :---------- | -----: | -----: | --------: | ----: | | **Set 변경: SADD SISMEMBER SREM**
1 KB | **solidis** | 60.6K | 181.7K | 1651ms | ±2.8% | | | ioredis | 29.4K | 88.3K | 3396ms | ±3.0% | | **List 범위: LPUSH RPUSH LRANGE**
1 KB | **solidis** | 53.8K | 161.3K | 1860ms | ±3.7% | | | ioredis | 27.6K | 82.8K | 3623ms | ±0.8% | | **Multi-Key: MSET MGET**
1 KB | **solidis** | 61.6K | 123.2K | 1623ms | ±2.8% | | | ioredis | 32.8K | 65.7K | 3045ms | ±2.6% | | **List 변경: LPUSH RPUSH LPOP RPOP LLEN**
1 KB | **solidis** | 38.2K | 191.2K | 2615ms | ±2.6% | | | ioredis | 20.6K | 103.2K | 4844ms | ±2.4% | | **Set: SET**
1 KB | **solidis** | 132.7K | 132.7K | 754ms | ±9.2% | | | ioredis | 74.0K | 74.0K | 1352ms | ±1.9% | | **Set 조회: SADD SISMEMBER SMEMBERS**
1 KB | **solidis** | 54.3K | 162.9K | 1842ms | ±3.6% | | | ioredis | 30.6K | 91.8K | 3267ms | ±2.1% | | **Hash 변경: HMSET HMGET HDEL**
1 KB | **solidis** | 51.7K | 155.2K | 1933ms | ±3.3% | | | ioredis | 29.3K | 87.9K | 3414ms | ±1.6% | | **Sorted Set: ZADD ZRANGE ZREM**
1 KB | **solidis** | 64.2K | 192.5K | 1559ms | ±4.0% | | | ioredis | 37.4K | 112.2K | 2673ms | ±0.8% | | **Expire: SET EXPIRE TTL**
1 KB | **solidis** | 67.7K | 203.0K | 1478ms | ±5.9% | | | ioredis | 39.5K | 118.6K | 2530ms | ±1.4% | | **비트랜잭션: SETPX GET**
1 KB | **solidis** | 81.5K | 163.0K | 1227ms | ±2.7% | | | ioredis | 48.7K | 97.5K | 2051ms | ±1.3% | | **Stream: XADD XRANGE XLEN**
1 KB | **solidis** | 50.4K | 151.1K | 1986ms | ±3.5% | | | ioredis | 31.1K | 93.3K | 3216ms | ±3.2% | | **Hash 왕복: HSET HGET HGETALL**
1 KB | **solidis** | 54.7K | 164.0K | 1829ms | ±8.1% | | | ioredis | 36.4K | 109.1K | 2749ms | ±1.4% | | **Counter: INCR DECR**
1 KB | **solidis** | 101.2K | 202.4K | 988ms | ±2.1% | | | ioredis | 67.5K | 135.0K | 1481ms | ±1.2% | | **파이프라인 혼합: SET INCR GET**
1 KB | **solidis** | 58.5K | 175.4K | 1710ms | ±1.1% | | | ioredis | 39.0K | 117.1K | 2562ms | ±1.4% | | **Get Buffer: GETBUFFER**
1 KB | **solidis** | 154.2K | 154.2K | 649ms | ±4.1% | | | ioredis | 104.2K | 104.2K | 960ms | ±1.8% |
--- ## Gear 설정
벤치마크 설정 펼치기 | 항목 | 값 | | :--------------------- | :------------------ | | 모드 | `autopipeline` | | 페이로드 크기 | 1 KB | | 반복 횟수 | 100,000 | | 워밍업 | 1,000 | | 클라이언트 수 | 1 | | 클라이언트당 동시 실행 | 10000 | | 총 동시 실행 | 10000 | | 측정 횟수 | 10 | | 쿨다운 | 2500ms | | 플랫폼 | linux x64 | | Node.js | v22.22.3 | | 날짜 | 2026-06-20 11:21:19 |
--- ## Open Book 측정 방법론 - 각 벤치마크는 GC 및 JIT 간섭을 방지하기 위해 **격리된 워커 스레드**에서 실행됩니다 - 순서 편향을 줄이기 위해 반복 측정 시 라이브러리를 **번갈아 실행**합니다 - Redis 서버는 각 벤치마크 케이스 사이에 **초기화 및 안정화**됩니다 - 페이로드는 두 라이브러리가 공유하는 **결정론적 의사 난수 풀**을 사용합니다 - 소요 시간은 전체 반복 샘플의 **중앙값**입니다 - 분산은 **변동 계수** (σ / 중앙값 × 100%)입니다
## 기능
### High Voltage 성능 - `setImmediate` 기반 파이프라인 자동 병합 - 바이너리 세이프 RESP 파서와 독립 버퍼 반환 - 백프레셔 대응 청크 단위 소켓 쓰기 - 이벤트 루프 양보 포인트 설정 가능 ### Electric Plug 프로토콜 - RESP2 + RESP3 와이어 레벨 풀 구현 - 17가지 RESP3 데이터 타입 전부 지원 (Map, Set, Push, BigNumber, ...) - unsafe integer 자동 BigInt 변환 - 바이너리 세이프, 멀티바이트 문자 정상 처리
### Shield 안정성 - 자동 재연결 (configurable backoff) - 재연결 시 SELECT, Pub/Sub 구독 자동 복구 - 파이프라인 단위 커맨드 타임아웃 - Ready check로 서버 로딩 완료까지 대기 - 장애 발생 시 in-flight 요청 즉시 reject ### Locked 보안 - TLS/SSL 지원 (`rediss://` 또는 `tls` 옵션) - ACL 인증 (username/password) - 디버그 로그에서 자격 증명 자동 마스킹 - `maxBulkStringLength`로 비정상 응답 차단
### Bullseye 타입 안전성 - TypeScript `strict` 모드, 커맨드별 I/O 타입 정의 - 런타임 응답 가드 (`tryReplyToString`, ...) - 구조화된 에러 계층 + cause chain ### Puzzle Piece 확장성 - `.extend()`로 커맨드 조합 (트리 쉐이킹 가능) - 커스텀 커맨드에서 클라이언트 `this` 접근 - MULTI/EXEC 프록시에서 금지 메서드 자동 차단
## 설정
전체 옵션 레퍼런스 ```typescript const client = new SolidisClient({ // 연결 uri: 'redis://localhost:6379', host: '127.0.0.1', port: 6379, tls: { /* tls.ConnectionOptions */ }, lazyConnect: false, // 인증 authentication: { username: 'user', password: 'pass' }, database: 0, // 프로토콜 / 복구 clientName: 'solidis', protocol: 'RESP2', // 'RESP2' | 'RESP3' autoReconnect: true, enableReadyCheck: true, maxReadyCheckRetries: 100, readyCheckInterval: 100, maxConnectionRetries: 20, connectionRetryDelay: 100, autoRecovery: { database: true, subscribe: true, ssubscribe: true, psubscribe: true, }, // 타임아웃 (ms) commandTimeout: 5000, connectionTimeout: 2000, socketWriteTimeout: 1000, // 성능 튜닝 maxCommandsPerPipeline: 300, maxProcessRepliesPerChunk: 4096, maxProcessReplyBytesPerChunk: 8_388_608, // 8MB maxSocketWriteSizePerOnce: 65_536, // 64KB rejectOnPartialPipelineError: false, // 파서 parser: { buffer: { initial: 4_194_304, shiftThreshold: 2_097_152 }, maxBulkStringLength: 536_870_912, // 512MB }, // 기타 maxEventListenersForClient: 10_240, maxEventListenersForSocket: 10_240, debug: false, debugMaxEntries: 10_240, }); ```
## 아키텍처 ```mermaid graph TD subgraph SolidisClient direction LR Conn[Connection
TCP · TLS · Reconnect] Req[Requester
Queue · Pipeline · Timeout] Parse[Parser
RESP2 · RESP3 · Binary-safe] PS[PubSub
Channel · Pattern · Shard] DM[Debug Memory
Ring buffer · Sanitized] end Conn -->|socket data| Req Req -->|raw bytes| Parse Req -->|push messages| PS DM -.->|injected| Conn DM -.->|injected| Req style Conn fill:#1a1a2e,stroke:#f5a623,color:#fff style Req fill:#1a1a2e,stroke:#f5a623,color:#fff style Parse fill:#1a1a2e,stroke:#f5a623,color:#fff style PS fill:#1a1a2e,stroke:#f5a623,color:#fff style DM fill:#16213e,stroke:#555,color:#aaa ``` ```mermaid sequenceDiagram participant App participant Client as SolidisClient participant Req as Requester participant Socket as TCP Socket App->>Client: await client.set('key', 'value') Client->>Req: enqueue command Note over Req: setImmediate batching Req->>Socket: write pipeline chunk Socket-->>Req: RESP reply bytes Req-->>Client: parsed reply Client-->>App: 'OK' ``` | 모듈 | 역할 | | :--------------- | :------------------------------------------------ | | **Connection** | TCP/TLS 소켓 관리, 재연결 백오프 | | **Requester** | 커맨드 큐, 파이프라인 청킹, 응답 매칭, 타임아웃 | | **Parser** | RESP 디코딩, 버퍼 관리, 바이너리 세이프 응답 처리 | | **PubSub** | 채널/패턴/샤드 상태 추적, 메시지 디스패치 | | **Debug Memory** | 링 버퍼 기반 디버그 로그, credential 마스킹 | ## 이벤트 ```typescript client.on('connect', () => {}); // TCP 연결 수립 client.on('ready', () => {}); // 인증 완료, 커맨드 전송 가능 client.on('reconnected', () => {}); // 재연결 성공 client.on('end', () => {}); // 연결 종료 client.on('error', (err) => {}); // 소켓/프로토콜 에러 client.on('message', (ch, msg) => {}); // Pub/Sub 메시지 수신 client.on('pmessage', (pat, ch, msg) => {}); client.on('smessage', (ch, msg) => {}); // Shard 채널 메시지 client.on('debug', (entry) => {}); // 디버그 로그 엔트리 ``` ## 에러 처리 ```typescript import { unwrapSolidisError, SolidisConnectionError, SolidisRequesterError } from '@vcms-io/solidis'; try { await client.set('key', 'value'); } catch (error) { const root = unwrapSolidisError(error); // cause chain 전체 추적 } ``` > [!NOTE] > Solidis가 throw하는 모든 에러는 `SolidisError`를 상속합니다. > `unwrapSolidisError()`로 root cause까지 cause chain을 추적할 수 있습니다. | 에러 클래스 | 발생 조건 | | :----------------------- | :-------------------------------------------- | | `SolidisConnectionError` | TCP/TLS 연결 실패, 타임아웃, 소켓 리셋 | | `SolidisRequesterError` | 커맨드 타임아웃, 파이프라인 reject, 쓰기 실패 | | `SolidisParserError` | 잘못된 RESP 포맷, bulk string 크기 초과 | | `SolidisPubSubError` | 구독 상태 관련 에러 | ## 확장 ```bash npm install @vcms-io/solidis-extensions ``` | 확장 | 설명 | | :--------------------------------------------------------------------------------------------------------- | :--------------------------------------- | | [**SpinLock**](https://github.com/vcms-io/solidis-extensions/blob/main/sources/domains/spinlock/README.md) | 가벼운 Redis 기반 뮤텍스 (단일 인스턴스) | | [**RedLock**](https://github.com/vcms-io/solidis-extensions/blob/main/sources/domains/redlock/README.md) | 분산 잠금 (Redlock 알고리즘, 내결함성) | ## 기여하기 ```bash git clone https://github.com/vcms-io/solidis.git && cd solidis npm install && npm run build && npm test ``` TypeScript strict · 외부 의존성 추가 금지 · 번들 사이즈 최소화 · SemVer ## 라이선스 MIT · [LICENSE](/LICENSE) 참조