From 2bc6cc550553b140b0f8fd2cef06c88e07a25083 Mon Sep 17 00:00:00 2001 From: kingchenc Date: Sat, 23 May 2026 00:45:51 +0200 Subject: [PATCH] docs: round out the docs for Z7's example additions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * examples/README.md — replace the single-row WASM section with a build block (one-time `wasm-pack` build), a serve note, and the full five-row table (`index`, `backtest`, `live_trading`, `multi_timeframe`, `parallel_assets`). * examples/wasm/README.md — new dedicated index for the WASM demos with the build and serve commands and a description of every file including the module worker companion. * CHANGELOG.md `[Unreleased]` gains three bullets: the Python and Node `fetch_btcusdt` siblings; the four new WASM browser demos; and the three new wiki pages from Z6 (TA-Lib-Migration, Cookbook, FAQ). --- CHANGELOG.md | 18 ++++++++++++++- examples/README.md | 19 ++++++++++++--- examples/wasm/README.md | 51 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 84 insertions(+), 4 deletions(-) create mode 100644 examples/wasm/README.md diff --git a/CHANGELOG.md b/CHANGELOG.md index e7fffab3..4c81de25 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -70,11 +70,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 tree: Rust moved into a new `examples/rust/` workspace member crate (`wickra-examples`, run via `cargo run -p wickra-examples --bin `), Node into `examples/node/` with its own `package.json` linking `wickra` via - `file:../../bindings/node`, and the WASM browser demo into + `file:../../bindings/node`, and the WASM browser demos into `examples/wasm/`. The bundled BTCUSDT datasets move alongside them at `examples/data/`. Six new examples close the cross-language parity matrix: streaming demos for Python and Rust; multi-timeframe and parallel-assets demos for both Rust and Node. +- Cross-language data-generator parity: `examples/python/fetch_btcusdt.py` + (stdlib only: `urllib` + `json` + `csv`) and `examples/node/fetch_btcusdt.js` + (Node 18+ built-in `fetch`) mirror the Rust `fetch_btcusdt` binary — + byte-for-byte identical CSV output on the same Binance snapshot. +- Four additional WebAssembly browser demos under `examples/wasm/` + alongside the original `index.html`: `backtest.html` (fetch + basket of + indicators), `live_trading.html` (browser-native `WebSocket` to + Binance), `multi_timeframe.html` (in-page resample) and + `parallel_assets.html` + `parallel_worker.js` (module-Worker pool with + serial-vs-parallel speedup). The cross-language matrix is now closed + for every cell where the pattern makes sense. +- Three new wiki pages: `TA-Lib-Migration.md` (full mapping table from + `talib.X(...)` calls to Wickra), `Cookbook.md` (seven concrete + strategy recipes — RSI mean reversion, MACD crossover, Bollinger + breakout, ADX-gated trend, multi-timeframe confirmation, SuperTrend, + chained indicators) and `FAQ.md`. All three linked from `Home.md`. ### Fixed - `Timeframe::floor` no longer overflows for timestamps near `i64::MIN`. diff --git a/examples/README.md b/examples/README.md index 48c868ac..2818e229 100644 --- a/examples/README.md +++ b/examples/README.md @@ -51,9 +51,22 @@ cd ../../examples/node && npm install # links wickra + installs `ws` ## WebAssembly — `examples/wasm/` -| Example | What it does | Run | -| --- | --- | --- | -| `index.html` | Browser demo: streams a price series through six indicators and draws a live `` chart. | `wasm-pack build bindings/wasm --target web --release --features panic-hook`, then serve the repository root and open `examples/wasm/index.html` | +Build the WASM module first (one-time): + +```bash +wasm-pack build bindings/wasm --target web --release --features panic-hook +``` + +Then serve the repository root (`python -m http.server`, `npx http-server`, +…) and open the demo you want in a browser. + +| Example | What it does | +| --- | --- | +| `index.html` | Streams a synthetic price series through six indicators and draws a live `` chart. | +| `backtest.html` | Streams a fetched OHLCV CSV through a basket of indicators (SMA, EMA, RSI, MACD, Bollinger, ATR, ADX, OBV) and prints a per-series summary table. | +| `live_trading.html` | Opens a browser-native `WebSocket` to Binance, runs RSI / MACD / Bollinger and flags BUY/SELL candidates. | +| `multi_timeframe.html` | Fetches a 1-minute CSV, rolls it up to 5m / 15m / 1h / 4h / 1d in-page, prints RSI / MACD hist / ADX per timeframe. | +| `parallel_assets.html` | Spawns a pool of module Workers (each loading its own copy of the WASM module) and reports the speedup over a serial baseline. | ## Example datasets diff --git a/examples/wasm/README.md b/examples/wasm/README.md new file mode 100644 index 00000000..8c0b5906 --- /dev/null +++ b/examples/wasm/README.md @@ -0,0 +1,51 @@ +# Wickra WASM examples + +Browser demos for the `wickra-wasm` WebAssembly binding. Every demo loads +the module the same way (`init()` then construct indicators) so the +patterns transfer one-to-one to your own page. + +## Build + +The WASM module ships as a `wasm-pack` `--target web` bundle. Build it +once from the repository root: + +```bash +wasm-pack build bindings/wasm --target web --release --features panic-hook +``` + +This drops `bindings/wasm/pkg/` with the `.wasm` binary, the JS loader +and TypeScript types. Every demo here imports the loader via +`../../bindings/wasm/pkg/wickra_wasm.js`. + +## Serve + +ES-module workers and `fetch()` over CSV both need a real HTTP origin, +not `file://`. Any static server from the repository root works: + +```bash +# Python: +python -m http.server 8000 + +# Or Node: +npx http-server -p 8000 +``` + +Then open the demo you want at `http://localhost:8000/examples/wasm/`. + +## Demos + +| File | What it does | +| --- | --- | +| `index.html` | The original showcase: streams a synthetic price series through six indicators and draws a live `` chart with `SMA`, `EMA`, `RSI`, `MACD`, `BollingerBands` and `ATR` cards. | +| `backtest.html` | Backtest: fetches an OHLCV CSV (default the bundled BTCUSDT daily dataset), streams every candle through a basket of eight indicators, prints a summary table. Mirrors `examples/python/backtest.py`. | +| `live_trading.html` | Browser-native `WebSocket` to Binance kline streams; runs RSI / MACD / Bollinger on the incoming closes and flags BUY/SELL candidates when the three agree. Mirrors `examples/python/live_trading.py`. | +| `multi_timeframe.html` | Fetches a 1-minute CSV, rolls it up in-page to 5m / 15m / 1h / 4h / 1d buckets and prints RSI / MACD-histogram / ADX per timeframe. Mirrors `examples/python/multi_timeframe.py`. | +| `parallel_assets.html` | Synthetic `(assets, bars)` panel, serial baseline on the main thread vs. a pool of module Workers each loading its own copy of the WASM module. Mirrors `examples/python/parallel_assets.py`. | +| `parallel_worker.js` | Module worker used by `parallel_assets.html` (not loaded directly). | + +## See also + +- [Quickstart: WASM](../../docs/wiki/Quickstart-WASM.md) — module-load + flow, `wasm-pack` targets, and the streaming API. +- [examples/README.md](../README.md) — cross-language index, including + the Rust, Python and Node siblings of every demo above.