Node.js / WebAssembly API 参考

TechKit Node.js 绑定的完整 API 参考。TechKit 提供两个 npm 包：techkit（核心版）和 techkit-full（完整版）。

包选择指南

techkit（核心版）- 推荐大多数用户使用

特性：

• ✅ 158+ 核心指标（兼容 TA-Lib）

• ✅ 体积小（WASM ~200KB）

• ✅ 支持 Node.js 和浏览器

• ✅ 自动选择最优后端（原生模块或 WASM）

使用场景：

• 大多数应用

• 常用技术指标（SMA、RSI、MACD、BBANDS 等）

• 有体积限制

• 不需要高级分析功能

安装：

npm install techkit

techkit-full（完整版）- 完整功能

特性：

• ✅ 全部 189 个指标

• ✅ 高级分析（风险指标、波动率模型、形态识别）

• ✅ 体积较大（WASM ~800KB）

• ✅ 支持 Node.js 和浏览器

使用场景：

• 需要完整功能集

• 风险指标（夏普比率、索提诺比率、VaR 等）

• 波动率模型（GARCH、EWMA 等）

• 形态识别（谐波形态、图表形态等）

安装：

npm install techkit-full

功能对比

功能	techkit	techkit-full
核心指标（TA-Lib）	✅ 158	✅ 158
高级分析	❌	✅ 31
风险指标	❌	✅ Sharpe、Sortino、VaR、CVaR
波动率模型	❌	✅ GARCH、EWMA、Parkinson
形态识别	❌	✅ 谐波、图表形态
K 线形态	✅ 19 核心	✅ 61 完整
WASM 体积	~200KB	~800KB
Node.js 原生模块	✅	✅
浏览器支持	✅	✅

如何选择：

• 如果不确定，选择 techkit（核心版）

• 如果需要风险分析、形态识别等功能，选择 techkit-full

• 两个包的 API 完全相同，可无缝切换

快速开始

techkit（核心版）示例

import { init, SMA, RSI, MACD, getBackend } from 'techkit';

// 步骤 1：初始化（使用前必需）
await init();
console.log(`Backend: ${getBackend()}`); // 输出：'native' 或 'wasm'

// 步骤 2：创建指标实例
const sma = new SMA(20);  // 20 周期简单移动平均线
const rsi = new RSI(14);  // 14 周期相对强弱指数
const macd = new MACD({ 
    fastPeriod: 12,      // 快线 EMA 周期
    slowPeriod: 26,      // 慢线 EMA 周期
    signalPeriod: 9      // 信号线 EMA 周期
});

// 步骤 3：增量更新（用于实时流）
const result = sma.update(100.5);
if (result.valid) {
    console.log('SMA:', result.value);
}

// 步骤 4：批量计算（用于历史数据）
const prices = new Float64Array([100, 101, 102, 103, 104, 105]);
const smaValues = sma.calculate(prices);
console.log('SMA values:', smaValues);

// 步骤 5：清理（重要！）
sma.dispose();
rsi.dispose();
macd.dispose();

techkit-full 示例

// 相同的导入模式，只是包名不同
import { init, SMA, RSI, SharpeRatio, GARCHVolatility } from 'techkit-full';

await init();

// 核心指标（与 techkit 相同）
const sma = new SMA(20);
const rsi = new RSI(14);

// 高级功能（仅 techkit-full）
const sharpe = new SharpeRatio({ period: 252, riskFreeRate: 0.02 });
const garch = new GARCHVolatility({ alpha: 0.1, beta: 0.85, omega: 0.0001 });

// 相同的使用模式
const returns = new Float64Array([0.01, 0.02, -0.01, 0.03, -0.02]);
const sharpeValue = sharpe.calculate(returns);
console.log('Sharpe Ratio:', sharpeValue);

// 清理
sma.dispose();
rsi.dispose();
sharpe.dispose();
garch.dispose();

浏览器用法（CDN）

<script type="module">
    import { init, SMA, RSI, MACD } from 'https://unpkg.com/techkit@1.2.5/dist/browser.mjs';
    
    await init();
    
    const sma = new SMA(20);
    const result = sma.update(100.5);
    
    if (result.valid) {
        console.log(`SMA: ${result.value}`);
    }
</script>

后端选择

TechKit 支持两种后端：**原生模块（N-API）**和 WebAssembly（WASM）。系统会自动选择最优后端，也可以手动指定。

后端对比

特性	原生模块（N-API）	WASM
性能	⚡ 最快（原生 C++）	🚀 非常快（接近原生）
平台支持	Linux、macOS、Windows	所有平台
包体积	较大（平台特定）	较小（通用）
加载速度	快	稍慢（需要编译）
浏览器支持	❌	✅
推荐	Node.js 服务端	浏览器、跨平台

自动选择（推荐）

TechKit 会自动选择最优后端：

1. Node.js 环境：优先尝试原生模块，失败则回退到 WASM

2. 浏览器环境：自动使用 WASM

import { init, getBackend, isInitialized } from 'techkit';

// 自动选择最优后端
await init();

// 检查当前使用的后端
console.log(`Current backend: ${getBackend()}`);  // 输出：'native' 或 'wasm'
console.log(`Initialized: ${isInitialized()}`); // 输出：true

手动后端选择

强制使用特定后端：

import { initWithBackend, getBackend } from 'techkit';

// 强制使用原生模块后端（仅 Node.js）
try {
    await initWithBackend('native');
    console.log('Native backend loaded');
} catch (error) {
    console.error('Native unavailable, falling back to WASM');
    await initWithBackend('wasm');
}

// 强制使用 WASM 后端（所有环境）
await initWithBackend('wasm');
console.log(`Current backend: ${getBackend()}`); // 输出：'wasm'

API 参考

初始化

// 自动选择最佳后端
function init(): Promise<void>;

// 强制使用特定后端
function initWithBackend(backend: 'native' | 'wasm'): Promise<void>;

// 检查状态
function isInitialized(): boolean;
function getBackend(): 'native' | 'wasm' | null;

// 版本信息
function version(): string;          // "1.2.5"
function versionTuple(): [number, number, number]; // [1, 2, 5]

结果类型

interface IndicatorResult {
    value: number;   // 计算值
    valid: boolean;  // 如果预热完成则为 true
}

interface MACDResult {
    macd: number;
    signal: number;
    histogram: number;
    valid: boolean;
}

interface BBandsResult {
    upper: number;
    middle: number;
    lower: number;
    valid: boolean;
}

interface StochResult {
    k: number;
    d: number;
    valid: boolean;
}

interface OHLCV {
    open: number;
    high: number;
    low: number;
    close: number;
    volume: number;
}

指标基类

所有指标都继承自 Indicator：

abstract class Indicator {
    // 使用单个值更新
    update(value: number): IndicatorResult;
    
    // 使用 OHLCV K 线更新
    updateOHLCV(bar: OHLCV): IndicatorResult;
    
    // 批量计算
    calculate(data: Float64Array | number[]): Float64Array;
    
    // 使用 OHLCV 数据计算
    calculateOHLCV(
        open: Float64Array | number[],
        high: Float64Array | number[],
        low: Float64Array | number[],
        close: Float64Array | number[],
        volume: Float64Array | number[]
    ): Float64Array;
    
    // 重置到初始状态
    reset(): void;
    
    // 检查预热是否完成
    isReady(): boolean;
    
    // 属性
    readonly lookback: number;  // 预热周期
    readonly name: string;      // 指标名称
    
    // 清理（对 WASM 很重要！）
    dispose(): void;
    destroy(): void;  // dispose() 的别名
}

移动平均线

类	构造函数	描述
SMA	new SMA(period)	简单移动平均线
EMA	new EMA(period)	指数移动平均线
WMA	new WMA(period)	加权移动平均线
DEMA	new DEMA(period)	双指数移动平均线
TEMA	new TEMA(period)	三指数移动平均线
KAMA	new KAMA(period?)	考夫曼自适应移动平均线
TRIMA	new TRIMA(period)	三角移动平均线
T3	new T3(period?, vfactor?)	T3 移动平均线

动量指标

类	构造函数	描述
RSI	new RSI(period?)	相对强弱指数
MACD	new MACD(config?)	MACD
STOCH	new STOCH(config?)	随机振荡器
STOCHF	new STOCHF(k?, d?)	快速随机指标
CCI	new CCI(period?)	商品通道指数
ADX	new ADX(period?)	平均趋向指数
MOM	new MOM(period?)	动量指标
ROC	new ROC(period?)	变动率
WILLR	new WILLR(period?)	威廉指标 %R
MFI	new MFI(period?)	资金流量指标
APO	new APO(fast?, slow?)	绝对价格振荡器
PPO	new PPO(fast?, slow?)	百分比价格振荡器
CMO	new CMO(period?)	钱德动量振荡器
AROON	new AROON(period?)	Aroon 指标
ULTOSC	new ULTOSC(p1?, p2?, p3?)	终极振荡器
TRIX	new TRIX(period?)	三重指数平均

波动率指标

类	构造函数	说明
ATR	new ATR(period?)	需要 OHLCV
NATR	new NATR(period?)	需要 OHLCV
TRANGE	new TRANGE()	需要 OHLCV
BBANDS	new BBANDS(config?)	多输出

成交量指标

类	构造函数
OBV	new OBV()
AD	new AD()
ADOSC	new ADOSC(fast?, slow?)

统计函数

类	构造函数
STDDEV	new STDDEV(period?, nbdev?)
VAR	new VAR(period?)
LINEARREG	new LINEARREG(period?)
LINEARREG_SLOPE	new LINEARREG_SLOPE(period?)
LINEARREG_INTERCEPT	new LINEARREG_INTERCEPT(period?)
LINEARREG_ANGLE	new LINEARREG_ANGLE(period?)

K 线形态

核心版提供 19 种基本形态：

import { CDL_DOJI, CDL_HAMMER, CDL_ENGULFING } from 'techkit';

const doji = new CDL_DOJI();
const result = doji.updateOHLCV({ open, high, low, close, volume });
// result.value: +100（看涨）、-100（看跌）、0（无）

doji.dispose();

可用的 CDL 形态：CDL_DOJI、CDL_HAMMER、CDL_HANGINGMAN、 CDL_ENGULFING、CDL_MORNINGSTAR、CDL_EVENINGSTAR、CDL_SHOOTINGSTAR、 CDL_INVERTEDHAMMER、CDL_PIERCING、CDL_DARKCLOUDCOVER、CDL_HARAMI、 CDL_3WHITESOLDIERS、CDL_3BLACKCROWS、CDL_MARUBOZU、CDL_SPINNINGTOP、 CDL_DRAGONFLYDOJI、CDL_GRAVESTONEDOJI、CDL_ABANDONEDBABY、CDL_BELTHOLD

指标链

import { Chain, RSI, EMA } from 'techkit';

// RSI 经过 EMA 平滑
const chain = new Chain([new RSI(14), new EMA(9)]);
const smoothedRSI = chain.calculate(prices);

chain.dispose();

TypeScript 支持

包含完整的 TypeScript 类型定义：

import { 
    SMA, RSI, MACD, BBANDS,
    IndicatorResult, MACDResult, BBandsResult,
    SMAConfig, MACDConfig, BBandsConfig,
    OHLCV, MAType
} from 'techkit';

const sma = new SMA(20);
const result: IndicatorResult = sma.update(100.5);

const macd = new MACD({ fastPeriod: 12, slowPeriod: 26, signalPeriod: 9 });
const macdResult: MACDResult = macd.update(100.5);

实时图表集成示例

import { init, SMA, RSI, MACD, BBANDS } from 'techkit';

class ChartIndicators {
    constructor() {
        this.sma20 = null;
        this.sma50 = null;
        this.rsi = null;
        this.macd = null;
        this.bbands = null;
    }
    
    async initialize() {
        await init();
        
        this.sma20 = new SMA(20);
        this.sma50 = new SMA(50);
        this.rsi = new RSI(14);
        this.macd = new MACD();
        this.bbands = new BBANDS({ period: 20 });
    }
    
    onNewBar(bar) {
        const price = bar.close;
        
        const sma20Result = this.sma20.update(price);
        const sma50Result = this.sma50.update(price);
        const rsiResult = this.rsi.update(price);
        const macdResult = this.macd.update(price);
        const bbandsResult = this.bbands.update(price);
        
        return {
            sma20: sma20Result.valid ? sma20Result.value : null,
            sma50: sma50Result.valid ? sma50Result.value : null,
            rsi: rsiResult.valid ? rsiResult.value : null,
            macd: macdResult.valid ? {
                macd: macdResult.macd,
                signal: macdResult.signal,
                histogram: macdResult.histogram
            } : null,
            bbands: bbandsResult.valid ? {
                upper: bbandsResult.upper,
                middle: bbandsResult.middle,
                lower: bbandsResult.lower
            } : null
        };
    }
    
    dispose() {
        this.sma20?.dispose();
        this.sma50?.dispose();
        this.rsi?.dispose();
        this.macd?.dispose();
        this.bbands?.dispose();
    }
}

// 用法
const indicators = new ChartIndicators();
await indicators.initialize();

for (const bar of priceData) {
    const values = indicators.onNewBar(bar);
    renderChart(values);
}

indicators.dispose();

内存管理

⚠️ 重要：使用完指标后务必调用 dispose()！

// 正确：适当的清理
const sma = new SMA(20);
try {
    const result = sma.calculate(prices);
    // 使用结果
} finally {
    sma.dispose();
}

// 错误：内存泄漏（特别是在 WASM 模式下）
function calculate() {
    const sma = new SMA(20);
    return sma.calculate(prices);
    // sma 从未被清理！
}

性能提示

1. 复用指标实例：

   // 正确
   const sma = new SMA(20);
   for (const dataset of datasets) {
       sma.reset();
       const result = sma.calculate(dataset);
   }
   sma.dispose();
   
   // 错误：每次都创建新实例
   for (const dataset of datasets) {
       const sma = new SMA(20);
       const result = sma.calculate(dataset);
       sma.dispose();
   }
   

2. 对大型数据集使用 Float64Array：

   // 更快
   const prices = new Float64Array([100, 101, 102, ...]);
   const result = sma.calculate(prices);
   
   // 较慢（转换开销）
   const prices = [100, 101, 102, ...];
   const result = sma.calculate(prices);
   

3. 优先使用原生模块后端（如果可用）：

   try {
       await initWithBackend('native');
   } catch {
       await initWithBackend('wasm');
   }