Skip to content

Commit d192906

Browse files
committed
docs: bump README examples to v0.2.0, document Strategy/Backtest
The dependency snippets still pointed at v0.1.0 even though main is on v0.2.0; bring them in sync. Same for the Maven Central preview line. Also expand Quick start with a "decomposed" example that uses the v0.2 domain handles directly (compile -> Strategy -> Backtest), update the Cancellation section with the two cancel paths (future#cancel(true) and Backtest#cancel()), and refresh the roadmap so v0.2 reflects what shipped: domain objects + Flow.Publisher progress + hourly Lastra/ Parquet downloads.
1 parent aeda94d commit d192906

1 file changed

Lines changed: 37 additions & 11 deletions

File tree

README.md

Lines changed: 37 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -39,15 +39,15 @@ Where `net.qtsurfer:api-client` gives you one method per endpoint, this package
3939
<dependency>
4040
<groupId>com.github.QTSurfer</groupId>
4141
<artifactId>sdk-java</artifactId>
42-
<version>v0.1.0</version>
42+
<version>v0.2.0</version>
4343
</dependency>
4444
```
4545

4646
The transitive `com.github.QTSurfer:api-client-java` and `dev.failsafe:failsafe` come along automatically.
4747

4848
### Maven Central (future)
4949

50-
Once published to Central, the coordinate will be `net.qtsurfer:sdk:0.1.0`.
50+
Once published to Central, the coordinate will be `net.qtsurfer:sdk:0.2.0`.
5151

5252
## Quick start
5353

@@ -90,6 +90,27 @@ System.out.println("PnL: " + result.getPnlTotal());
9090
System.out.println("Trades: " + result.getTotalTrades());
9191
```
9292

93+
### Decomposed: reuse a compiled `Strategy` across runs
94+
95+
`qts.backtest(req)` is a shortcut for `compile → backtest → await`. When you want
96+
the intermediate handles — to reuse a compiled strategy, subscribe to progress as
97+
a reactive stream, or cancel mid-run — use them directly:
98+
99+
```java
100+
import net.qtsurfer.api.sdk.Backtest;
101+
import net.qtsurfer.api.sdk.Strategy;
102+
103+
Strategy strategy = qts.compile(request).join();
104+
Backtest job = strategy.backtest(request, options).join();
105+
106+
job.progress().subscribe(/* a Flow.Subscriber<BacktestProgress> */);
107+
108+
ResultMap result = job.await().join();
109+
```
110+
111+
`Backtest` exposes `id()`, `state()`, `progress()` (a `Flow.Publisher<BacktestProgress>`),
112+
`await()`, and `cancel()` (best-effort server-side `cancelExecution`).
113+
93114
## What `backtest()` does
94115

95116
Orchestrates the four-step workflow exposed by the raw API:
@@ -151,14 +172,21 @@ try {
151172

152173
## Cancellation
153174

154-
Cancel the returned `CompletableFuture` to stop polling. If the execute stage has already started server-side, the SDK best-effort calls `cancelExecution` on the backend.
175+
Two ways to cancel an in-flight backtest:
155176

156177
```java
178+
// 1. Cancel the future returned by the backtest() shortcut.
157179
CompletableFuture<ResultMap> future = qts.backtest(req, opts);
158-
// elsewhere:
159180
future.cancel(true);
181+
182+
// 2. Cancel through the Backtest handle (decomposed API).
183+
Backtest job = strategy.backtest(req, opts).join();
184+
job.cancel();
160185
```
161186

187+
Both stop polling immediately and, if the execute stage has already started
188+
server-side, best-effort call `cancelExecution` on the backend.
189+
162190
## Under the hood
163191

164192
- [`dev.failsafe:failsafe`](https://failsafe.dev) — retry policies with exponential backoff, optional per-stage `Timeout`, `withInterrupt()` so thread interruption from `CompletableFuture#cancel(true)` propagates cleanly.
@@ -194,16 +222,14 @@ JWT_API_TOKEN=... QTSURFER_API_URL=... QTSURFER_TEST_VERBOSE=1 mvn -B -Dtest='*I
194222
- [x] Backoff, timeout, and cancellation via Failsafe policies
195223
- [x] `QTSError` hierarchy
196224

197-
### v0.2 — Domain objects
225+
### v0.2 — Domain objects + binary downloads ✅
198226

199-
- [ ] `Strategy` + `BacktestJob` classes with methods like `wait()`, `cancel()`, `stream()`
227+
- [x] `Strategy` + `Backtest` handles with `id()`, `state()`, `progress()`, `await()`, `cancel()`
228+
- [x] Progress exposed as `Flow.Publisher<BacktestProgress>` (JDK reactive-streams)
229+
- [x] Hourly tickers/klines downloads (`qts.tickers(...)` / `qts.klines(...)`) with `DownloadFormat` (Lastra/Parquet)
200230
- [ ] TTL cache for `exchanges` / `instruments`
201231

202-
### v0.3 — Streaming progress
203-
204-
- [ ] Progress exposed as `Flow.Publisher<BacktestProgress>` (JDK reactive-streams)
205-
206-
### v0.4 — Ecosystem
232+
### v0.3 — Ecosystem
207233

208234
- [ ] Loaders for `signalsUrl` Parquet into `duckdb-java` / `lastra-java`
209235
- [ ] Optional reactive adapters (Reactor / RxJava)

0 commit comments

Comments
 (0)