npm
npm
NPM
스트리밍 기술 지표 (Streaming Technical Indicators)
JavaScript/TypeScript용 스트리밍 방식의 할당(allocation)-경량 기술 분석 툴킷입니다. 모든 지표는 nextValue(...) 메서드를 가진 클래스로 구성되어 있으며, 이 메서드는 한 번에 하나의 봉(bar)을 소비합니다. 따라서 동일한 코드 경로가 상태를 재구축할 필요 없이 백테스트와 라이브 트레이딩 모두를 구동할 수 있습니다. 두 번째 메서드인 momentValue(...)는 어떠한 상태도 커밋하지 않고 가상의 봉에 대한 지표 값을 계산하며, 이는 미완성 캔들 내부에서 틱별(tick-by-tick) 재계산에 유용합니다.
주요 기능 (Features)
- 스트리밍 우선 설계. 봉당 O(period) 복잡도; 전체 배열을 다시 계산할 필요가 없습니다.
momentValue 전방위 사용 가능. 상태를 변경하지 않고 "만약 이 봉이 지금 마감된다면 값은 무엇일까?"를 물어볼 수 있습니다.- TypeScript 지원. 공개 인터페이스 전체에 걸쳐 강력한 타입(Strongly-typed)을 제공합니다.
- 크로스 SDK 검증 완료. 130개 이상의 jest 테스트가 외부 참조 라이브러리(
lwc 및 ti)와 비교하여 출력을 교차 확인하며, 오차 범위는 $\epsilon \le 1e-9$입니다. 각 지표 테이블의 Test 열에서 어떤 오라클(oracle)을 기준으로 검증되었는지 확인할 수 있습니다.
- 작은 패키지 크기. 사전 빌드된
lib/ 번들만 전송하며, 약 85 kB의 tarball 크기입니다.
설치 (Install)
npm install @debut/indicators
빠른 시작 (Quick start)
import { SMA, RSI, MACD, BollingerBands } from '@debut/indicators';
const sma = new SMA(20);
nextValue는 지표가 결과를 산출할 만큼 충분한 봉을 볼 때까지 undefined를 반환합니다 (이를 "웜업" 기간이라고 하며, 일반적으로 period 봉이 필요합니다). 그 이후부터는 호출될 때마다 현재 값을 반환합니다.
스트리밍 모델 (Streaming model)
nextValue(...) — 봉 마감 시점 (close-of-bar)
닫힌 봉(closed bar)마다 이 메서드를 한 번씩 호출하십시오. 이 메서드는 내부 상태를 전진시키고 새로운 지표 값을 반환합니다. 이후의 호출들은 커밋된 상태를 반영합니다.
momentValue(...) — 봉 내부 (intra-bar)
실시간으로 형성 중인 캔들의 가격/거래량을 사용하여, 어떠한 상태도 커밋하지 않고 해당 봉이 지금 마감된다면 지표가 보고할 값(what the indicator would report)을 읽어냅니다. 이 기능은 캔들 내부에서 반응하고 싶지만 다음 실제 nextValue가 도착했을 때 깨끗하게 재계산하기를 원할 때 유용합니다.
const sma = new SMA(4);
[1, 2, 3].forEach((v) => sma.nextValue(v)); // warmup
sma.momentValue(8); // 3.5 ← preview if close=8
...
사용 가능한 지표들 (Available indicators)
아래는 카테고리별로 분류된 전체 지표 목록입니다. code style의 이름은 @debut/indicators에서 가져온 정확한 네임드 export입니다. 링크가 걸린 지표 이름은 docs/에 있는 개별 지표 문서 페이지로 연결됩니다. Test 열은 크로스-SDK 검증이 어떤 외부 라이브러리를 대상으로 하는지 표시합니다. `lwc`는 lightweight-charts-indicators를, `ti`는 technicalindicators를 의미합니다 (자세한 내용은 Cross-SDK validation을 참조하세요).
이동 평균 (Moving Averages)
오실레이터 (Oscillators)
| 지표 | Export | Test | 설명 |
| :--- | :--- | :--- |
| Relative Strength Index | RSI | ti | 고전적인 14기간 모멘텀 오실레이터(Classic 14-period momentum oscillator). |
| ... |
모멘텀 (Momentum)
| 지표 | Export | Test | 설명 |
| :--- | :--- | :--- |
| MACD | MACD | ti | 시그널/히스토그램을 포함한 두 EMA(지수 이동 평균)의 차이(Difference of two EMAs with signal/histogram). |
| ... |
추세 (Trend)
| 지표 | Export | Test | 설명 |
| :--- | :--- | :--- |
| Average Directional Index | ADX | ti | 방향에 관계없이 추세 강도를 측정(Trend strength irrespective of direction). |
| ... |
변동성 (Volatility)
| 지표 | Export | Test | 설명 |
| :--- | :--- | :--- |
| Average True Range | ATR | ti | 선택 가능한 스무딩을 가진 Wilder ATR(Wilder ATR with selectable smoothing). |
| ... |
채널 및 밴드 (Channels & Bands)
| 지표 | Export | Test | 설명 |
| :--- | :--- | :--- |
| Bollinger Bands | BollingerBands | ti | SMA ± k × 표준 편차(stdev). |
| ... |
거래량 (Volume)
| Indicator | Export | Test | Description |
|---|
| On Balance Volume | OBV | lwc | 누적 부호화된 거래량 (Cumulative signed volume). |
| ... | | | |
캔들 및 피봇 (Candles & Pivots)
| Indicator | Export | Test | Description |
|---|
| Heiken Ashi | HeikenAshi | | 평활화된 캔들 스트림 (Smoothed candle stream). |
| ... | | | |
무브 / 웨이브 (Move / Wave) (사용자 정의)
| Indicator | Export | Description |
|---|
| Move | Move | 최소 전력 p를 가진 방향 이동. |
| Wave | Wave | 전력 p를 가진 강세/약세 캔들 시리즈 (Bullish/bearish candle series). |
런타임 상태 저장 및 복원 (Runtime state save & restore)
상태를 가지는(stateful) 모든 지표는 두 개의 메서드를 노출합니다:
dumpState(): 모든 내부 런타임 상태의 JSON 안전 스냅샷을 반환합니다.restoreState(state): 해당 스냅샷을 새로운 지표 인스턴스로 복원하고 인스턴스를 반환합니다.
이 스냅샷에는 CircularBuffer와 같은 중첩된 프로바이더 및 롤링 버퍼가 포함되므로, 지표는 전체 이력을 다시 재생할 필요 없이 프로세스가 재시작된 후에도 계속 작동할 수 있습니다. 생성자 매개변수(Constructor parameters) 또한 지표 구성의 일부이므로, 스냅샷을 생성한 것과 동일한 기간/옵션으로 생성된 인스턴스에 상태를 복원해야 합니다.
import { EMA } from '@debut/indicators';
const ema = new EMA(20);
...
실시간 시스템의 경우, 각 종가 봉을 확정할 때마다 지표 구성 및 스트림 식별자와 함께 상태를 저장해야 합니다. 시작 시에는 동일한 생성자 인수로 각 지표를 다시 생성하고, restoreState(...)를 호출한 다음, nextValue(...)를 통해 새로운 봉 데이터를 계속 공급합니다.
캔들스틱 패턴 (Candlestick Patterns)
각 패턴은 스트리밍 클래스입니다:
import { Doji, BullishEngulfingPattern, HammerPattern } from '@debut/indicators';
const doji = new Doji();
...
nextValue는 패턴이 발생하면 true를 반환하고, 그렇지 않으면 false를 반환하며, 아직 준비 중일 때는(undefined)을 반환합니다 (다중 봉 패턴은 전체 룩백(lookback) 기간이 필요합니다).
설정 가능한 임계값 (Configurable thresholds)
각 패턴은 생성자에서 옵션 묶음(options bag)을 받습니다. 기본값은 ti 참조와 정확히 일치하므로, 필요에 따라 이를 조정하거나 완화할 수 있습니다.
| Option | Used by | Default | Description |
|---|
precision | Doji-family, Marubozu, hammer-stick, HaramiCross, HammerPattern, HangingMan, ShootingStar, Abandoned/Doji-Star variants | 0.001 | 퍼지 매치 허용 오차(Fuzzy-match tolerance): '같다'고 판정하려면 open≈close (또는 body-touches-high/low)가 얼마나 가까워야 하는지를 나타냅니다. 0.001 ≈ 0.1% 상대적 허용 오차. |
| ... | | | |
const wideDoji = new Doji({ precision: 0.005 });
const fastHammer = new HammerPattern({ confirm: false });
const looseTweezer = new TweezerBottom({ equalityTolerance: 0.0001 });
결합 스캐너(Combined scanners)
한 개의 봉(bar)을 여러 패턴에 대해 동시에 스캔하려면 세 가지 결합 스캐너 중 하나를 사용하십시오. 이들은 패턴 모듈 내부에 선언된 싱글톤 OhlcBuffer를 공유하므로, 패턴별 버퍼 비용이 발생하지 않습니다.
import { AllCandlestickPatterns, BullishPatterns, BearishPatterns } from '@debut/indicators';
const all = new AllCandlestickPatterns();
...
AllCandlestickPatterns.nextValue는 해당 봉에서 발생한 패턴 이름 배열을 반환하며, BullishPatterns / BearishPatterns는 단일 부울 값("어떤 패턴이라도 발생했는지 여부")을 반환합니다.
싱글톤 버퍼 및 스트림 간 리셋(Singleton buffer & resetting between streams)
모든 다중 봉 패턴은 src/candlestick/patterns.ts에서 모듈 범위에 선언된 하나의 OhlcBuffer(5)를 공유합니다. 새 봉을 처음 감지하는 첫 번째 패턴이 버퍼를 전진시키며, 동일한 틱 내의 후속 호출들은 OHLC 동등성으로 중복 제거됩니다(dedup'd). 이는 새로운 패턴 인스턴스를 추가하는 것이 본질적으로 무료라는 것을 의미하며, 패턴별 링 할당(per-pattern ring allocation)이 없습니다.
독립적인 봉 스트림 간에 전환하거나(또는 테스트 케이스 사이에 깨끗한 상태를 원할 경우), BasePattern.reset()을 호출하십시오:
import { BasePattern } from '@debut/indicators/lib/src/candlestick/patterns';
BasePattern.reset();
네임스페이스 임포트(Namespaced import)
만약 스코프에 35개의 심볼을 가져오고 싶지 않다면:
import { Candlestick } from '@debut/indicators';
const doji = new Candlestick.Doji();
...
패턴 카탈로그(Pattern catalog)
| Lookback | Patterns |
|---|
| 1 bar | Doji, DragonFlyDoji, GraveStoneDoji, BearishHammerStick, BullishHammerStick, BearishInvertedHammerStick, BullishInvertedHammerStick, BearishMarubozu, BullishMarubozu, BearishSpinningTop, BullishSpinningTop |
| ... | |
세션 볼륨 프로파일(Session Volume Profile)
VolumeProfile은 가격 행(price rows) 전반에 걸쳐 거래된 볼륨을 집계하며, 설정 가능한 tickSize, 분포, 그리고 세션 앵커링('daily'가 기본값 — 무한 스트림은 row map을 영원히 성장시킬 수 없음)과 함께 POC, VAH / VAL을 노출합니다.
import { VolumeProfile } from '@debut/indicators';
const vp = new VolumeProfile({ tickSize: 0.5 });
for (const bar of bars) {
...
전체 옵션, 공식, 성능 참고 사항 및 사용자 지정 세션 레시피는 **docs/VolumeProfile.md**를 참조하세요.
유틸리티(Utilities)
| Export | Description |
|---|
CircularBuffer | at() / peek() / forEach()를 갖는 고정 크기 링 버퍼입니다. 대부분의 롤링-윈도우 지표에 사용됩니다. |
| ... | |
크로스-SDK 검증(Cross-SDK validation)
포팅된 모든 지표와 캔들스틱 패턴은 tests/<name>/<name>.spec.ts에 vitest 스타일의 스펙을 가지고 있으며, 이 스펙은 다음 작업을 수행합니다:
- 시드된 LCG(see
tests/lwc-fixtures.ts)를 사용하여 결정론적 합성 OHLCV 바를 생성합니다.
- 이를 스트리밍
@debut/indicators 클래스를 통해 실행합니다.
- 동일한 바를 해당
lwc의 calculate() (또는 구형 스펙을 위한 ti)를 통해 실행합니다 — 각 지표 테이블의 Test 열에서 어떤 오라클에 대해 패턴이 일치하는지 확인할 수 있습니다.
- 엡실론(epsilon) ≤ 1e-9인 숫자적 동등성을 검증하거나, 불리언 패턴 발동 시 멤버십을 확인합니다.
전체 스위트를 실행하려면 npm test를 실행하세요.
벤치마크(Benchmarks)
Apple M1 Pro, Node v16.14.0. 100k 요소 데이터셋에서 테스트되었습니다.
라이선스
GPL-3.0
