wickra-wasm 0.1.3 → 0.2.0

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.
Files changed (6) hide show
  1. package/README.md +74 -38
  2. package/package.json +3 -3
  3. package/wickra_wasm.d.ts +554 -0
  4. package/wickra_wasm.js +1 -1
  5. package/wickra_wasm_bg.js +4898 -530
  6. package/wickra_wasm_bg.wasm +0 -0
package/README.md CHANGED
@@ -1,6 +1,7 @@
1
1
  # Wickra
2
2
 
3
3
  [![CI](https://github.com/kingchenc/wickra/actions/workflows/ci.yml/badge.svg)](https://github.com/kingchenc/wickra/actions/workflows/ci.yml)
4
+ [![codecov](https://codecov.io/gh/kingchenc/wickra/branch/main/graph/badge.svg)](https://codecov.io/gh/kingchenc/wickra)
4
5
  [![crates.io](https://img.shields.io/crates/v/wickra.svg?logo=rust&color=orange)](https://crates.io/crates/wickra)
5
6
  [![PyPI](https://img.shields.io/pypi/v/wickra.svg?logo=pypi&color=blue)](https://pypi.org/project/wickra/)
6
7
  [![npm](https://img.shields.io/npm/v/wickra.svg?logo=npm&color=red)](https://www.npmjs.com/package/wickra)
@@ -51,33 +52,47 @@ multi-language reach, and active maintenance.
51
52
 
52
53
  ## Benchmark: how much faster is "streaming-first"?
53
54
 
54
- Reproduced on this machine with `python -m benchmarks.compare_libraries`.
55
+ The numbers below were measured on a single developer workstation and are not
56
+ guaranteed to reproduce identically on different hardware — absolute µs values
57
+ depend on CPU, memory clock and OS scheduler. Read them as **relative
58
+ speedups** between libraries on identical input, not as a universal
59
+ performance contract.
60
+
61
+ - **Reproduced on:** Windows 11 Pro 26200, AMD Ryzen 9 7950X3D, 64 GB DDR5,
62
+ Rust 1.92 (release profile, `lto = "fat"`, `codegen-units = 1`),
63
+ Python 3.12, Node 20.
64
+ - **Reproduce yourself:** `pip install -e bindings/python[bench]` then
65
+ `python -m benchmarks.compare_libraries`. The script auto-detects every
66
+ installed peer library and runs them on the same generated inputs as
67
+ Wickra. The CI job `cross-library-bench` runs the same script on every
68
+ push and uploads the raw report as a build artefact.
69
+
55
70
  Lower µs/op = faster. Wickra wins every batch category outright, and the
56
71
  streaming gap widens linearly with how much history a batch-only library has
57
72
  to recompute on every tick.
58
73
 
59
- ### Batch — single full pass over a 5 000-bar series
74
+ ### Batch — single full pass over a 20 000-bar series
60
75
 
61
76
  Reading the table: each cell shows that library's runtime, plus how many times
62
77
  slower it is than Wickra in parentheses. **★** marks the winner per row.
63
78
 
64
- | Indicator | Wickra | finta | talipp |
65
- |---------------------|---------------------|------------------------|------------------------------|
66
- | SMA(20) | **26.0 µs ★** | 295.3 µs (11.4× slower) | 1 812.8 µs (69.7× slower) |
67
- | EMA(20) | **16.8 µs ★** | 205.5 µs (12.2× slower) | 2 534.4 µs (150.9× slower) |
68
- | RSI(14) | **31.2 µs ★** | 714.1 µs (22.9× slower) | 3 751.7 µs (120.2× slower) |
69
- | MACD(12, 26, 9) | **30.8 µs ★** | 359.5 µs (11.7× slower) | 11 642.2 µs (378.0× slower) |
70
- | Bollinger(20, 2.0) | **26.7 µs ★** | 690.6 µs (25.9× slower) | 27 482.4 µs (1 030.1× slower) |
71
- | ATR(14) | **40.6 µs ★** | 1 120.3 µs (27.6× slower) | 3 760.2 µs (92.7× slower) |
79
+ | Indicator | Wickra | finta | talipp |
80
+ |---------------------|---------------------|-----------------------------|-------------------------------|
81
+ | SMA(20) | **95.6 µs ★** | 343.5 µs (3.6× slower) | 7 640.6 µs (79.9× slower) |
82
+ | EMA(20) | **64.6 µs ★** | 223.1 µs (3.5× slower) | 12 160.9 µs (188.2× slower) |
83
+ | RSI(14) | **126.2 µs ★** | 1 107.1 µs (8.8× slower) | 15 792.2 µs (125.1× slower) |
84
+ | MACD(12, 26, 9) | **119.0 µs ★** | 531.8 µs (4.5× slower) | 49 788.1 µs (418.2× slower) |
85
+ | Bollinger(20, 2.0) | **105.3 µs ★** | 812.0 µs (7.7× slower) | 130 938.3 µs (1 243.7× slower)|
86
+ | ATR(14) | **123.5 µs ★** | 5 144.8 µs (41.7× slower) | 28 816.0 µs (233.4× slower) |
72
87
 
73
- ### Streaming — per-tick latency after seeding with 2 000 historical bars
88
+ ### Streaming — per-tick latency after seeding with 5 000 historical bars
74
89
 
75
90
  A batch-only library has to re-run its full indicator over the entire history on
76
91
  every new tick; Wickra updates state in O(1).
77
92
 
78
93
  | Indicator | Wickra (per tick) | talipp (per tick) |
79
94
  |-----------|---------------------|---------------------------|
80
- | RSI(14) | **0.07 µs ★** | 1.16 µs (17.5× slower) |
95
+ | RSI(14) | **0.119 µs ★** | 1.644 µs (13.8× slower) |
81
96
 
82
97
  > TA-Lib and pandas-ta are not included here because both fail to install
83
98
  > cleanly on Windows without C build tooling — which is precisely the install
@@ -92,18 +107,22 @@ pip install -e bindings/python[bench]
92
107
  python -m benchmarks.compare_libraries
93
108
  ```
94
109
 
95
- ## Indicators in 0.1.0
110
+ ## Indicators
96
111
 
97
- 25 streaming-first indicators across four families. Every one passes the
112
+ 71 streaming-first indicators across eight families. Every one passes the
98
113
  `batch == streaming` equivalence test, reference-value tests, and reset
99
114
  semantics tests.
100
115
 
101
- | Family | Indicators |
102
- |-------------|-----------|
103
- | Trend | SMA, EMA, WMA, DEMA, TEMA, HMA, KAMA |
104
- | Momentum | RSI (Wilder), MACD, Stochastic, CCI, ROC, Williams %R, ADX (+DI/-DI), MFI, TRIX, Awesome Oscillator, Aroon |
105
- | Volatility | Bollinger Bands, ATR, Keltner Channels, Donchian Channels, Parabolic SAR |
106
- | Volume | OBV, VWAP (cumulative + rolling) |
116
+ | Family | Indicators |
117
+ |--------|-----------|
118
+ | Moving Averages | SMA, EMA, WMA, DEMA, TEMA, HMA, KAMA, SMMA, TRIMA, ZLEMA, T3, VWMA |
119
+ | Momentum Oscillators | RSI (Wilder), Stochastic, CCI, ROC, Williams %R, MFI, Awesome Oscillator, MOM, CMO, TSI, PMO, StochRSI, Ultimate Oscillator |
120
+ | Trend & Directional | MACD, ADX (+DI/-DI), Aroon, TRIX, Aroon Oscillator, Vortex, Mass Index, Choppiness Index, Vertical Horizontal Filter |
121
+ | Price Oscillators | PPO, DPO, Coppock, Accelerator Oscillator, Balance of Power |
122
+ | Volatility & Bands | ATR, Bollinger Bands, Keltner Channels, Donchian Channels, NATR, StdDev, Ulcer Index, Historical Volatility, Bollinger Bandwidth, %B, True Range, Chaikin Volatility |
123
+ | Trailing Stops | Parabolic SAR, SuperTrend, Chandelier Exit, Chande Kroll Stop, ATR Trailing Stop |
124
+ | Volume | OBV, VWAP (cumulative + rolling), ADL, Volume-Price Trend, Chaikin Money Flow, Chaikin Oscillator, Force Index, Ease of Movement |
125
+ | Price Statistics | Typical Price, Median Price, Weighted Close, Linear Regression, Linear Regression Slope, Z-Score, Linear Regression Angle |
107
126
 
108
127
  Adding a new indicator means implementing one trait in Rust; all four bindings
109
128
  inherit it automatically.
@@ -113,9 +132,12 @@ inherit it automatically.
113
132
  | Binding | Install | Example |
114
133
  |-------------------|-----------------------------------------------|---------|
115
134
  | Python (PyO3) | `pip install wickra` | `examples/python/backtest.py` |
116
- | Node.js (napi-rs) | `npm install wickra` | `bindings/node/__tests__/smoke.test.js` |
117
- | Browser / WASM | `npm install wickra-wasm` | `bindings/wasm/examples/index.html` |
118
- | Rust | `cargo add wickra` | `crates/wickra/examples/backtest.rs` |
135
+ | Node.js (napi-rs) | `npm install wickra` | `examples/node/backtest.js` |
136
+ | Browser / WASM | `npm install wickra-wasm` | `examples/wasm/index.html` |
137
+ | Rust | `cargo add wickra` | `examples/rust/src/bin/backtest.rs` |
138
+
139
+ Each binding ships several runnable examples (streaming, backtest, live feed);
140
+ [`examples/README.md`](examples/README.md) is the full cross-language index.
119
141
 
120
142
  The wickra-core crate is `unsafe`-forbidden, so every binding inherits a
121
143
  memory-safe implementation.
@@ -173,20 +195,26 @@ A Python live-trading example using the public `websockets` package lives at
173
195
  ```
174
196
  wickra/
175
197
  ├── crates/
176
- │ ├── wickra-core/ core engine + all 25 indicators
177
- │ ├── wickra/ top-level facade crate (publishes on crates.io)
198
+ │ ├── wickra-core/ core engine + all 71 indicators
199
+ │ ├── wickra/ top-level facade crate (publishes on crates.io) + benches/
178
200
  │ └── wickra-data/ CSV reader, tick aggregator, live exchange feeds
179
201
  ├── bindings/
180
202
  │ ├── python/ PyO3 + maturin (publishes on PyPI)
181
203
  │ ├── node/ napi-rs (publishes on npm)
182
204
  │ └── wasm/ wasm-bindgen (browsers, bundlers, Node)
183
- ├── examples/
184
- │ └── python/ backtest, live trading, parallel assets, multi-tf
185
- │ (Rust examples live inside their crate at crates/<name>/examples/)
186
- ├── benches/ cargo bench targets
205
+ ├── examples/ examples/README.md indexes every language
206
+ │ ├── data/ real BTCUSDT OHLCV datasets, one per timeframe
207
+ │ ├── rust/ Rust workspace member (`wickra-examples`)
208
+ │ ├── python/ backtest, live trading, parallel assets, multi-tf
209
+ │ ├── node/ streaming, backtest, live trading (load `wickra`)
210
+ │ └── wasm/ browser demo for `wickra-wasm`
187
211
  └── .github/workflows/ CI and release pipelines
188
212
  ```
189
213
 
214
+ Rust benchmarks live in `crates/wickra/benches/`; runnable Rust examples live
215
+ in the workspace member crate at `examples/rust/`. There is no top-level
216
+ `benches/` directory.
217
+
190
218
  ## Building everything from source
191
219
 
192
220
  ```bash
@@ -207,15 +235,23 @@ wasm-pack build bindings/wasm --target web --release --features panic-hook
207
235
  cd bindings/node && npm install && npm run build && npm test
208
236
  ```
209
237
 
210
- ## Test counts
211
-
212
- - `wickra-core`: 171 unit tests + 2 doctests, including textbook-value tests
213
- for Wilder RSI, Bollinger Bands, MACD, ATR, and Stochastic.
214
- - `wickra-data`: 11 unit tests + 1 doctest, covers CSV decoding, the tick
215
- aggregator, the resampler, and the Binance payload parser.
216
- - `bindings/python`: 56 pytest tests covering smoke checks, streaming==batch
217
- equivalence, reference values, lifecycle, and dict/tuple candle inputs.
218
- - `bindings/node`: 7 Node test-runner cases via `node --test`.
238
+ ## Testing
239
+
240
+ Every layer is covered; run the suites with the commands in
241
+ [Building everything from source](#building-everything-from-source).
242
+
243
+ - `wickra-core`: unit tests per indicator — textbook reference values
244
+ (Wilder RSI, Bollinger Bands, MACD, ATR, Stochastic), `batch == streaming`
245
+ equivalence, `reset` semantics, NaN/Inf handling, and property tests.
246
+ - `wickra-data`: unit tests for CSV decoding, the tick aggregator, the
247
+ resampler, and the Binance payload parser.
248
+ - `bindings/python`: pytest covering smoke checks, streaming/batch
249
+ equivalence, reference values, lifecycle, input validation, and
250
+ dict/tuple candle inputs.
251
+ - `bindings/node`: `node --test` cases for batch, streaming, and reference
252
+ values across all indicators.
253
+ - `bindings/wasm`: `wasm-bindgen-test` cases for constructors, equivalence,
254
+ and reference values.
219
255
 
220
256
  ## Contributing
221
257
 
package/package.json CHANGED
@@ -2,11 +2,11 @@
2
2
  "name": "wickra-wasm",
3
3
  "type": "module",
4
4
  "collaborators": [
5
- "Wickra Contributors"
5
+ "kingchenc <kingchencp@gmail.com>"
6
6
  ],
7
7
  "description": "WASM bindings for the Wickra streaming-first technical indicators library.",
8
- "version": "0.1.3",
9
- "license": "SEE LICENSE IN LICENSE",
8
+ "version": "0.2.0",
9
+ "license": "PolyForm-Noncommercial-1.0.0",
10
10
  "repository": {
11
11
  "type": "git",
12
12
  "url": "https://github.com/kingchenc/wickra"