tradelab 0.1.2 → 0.2.0

package/README.md

@@ -2,21 +2,25 @@
 
 # tradelab
 
-`tradelab` is a candle-based backtesting toolkit for Node.js. It is built for two use cases:
-- you already have candles and want a solid execution/backtest engine
-- you want to fetch Yahoo Finance data or import CSVs and backtest with minimal setup
+`tradelab` is a Node.js backtesting toolkit for trading strategy research. It lets you:
+- load candles from Yahoo Finance or CSV
+- run candle-based backtests with sizing, exits, and risk controls
+- export trades, metrics, and HTML reports
 
-The package stays focused on historical research and testing, and is not trying to be a broker adapter or a live trading framework. 
+The package is modular by design, so you can use just the parts you need: data loading, backtesting, reporting, or the utility layer on its own.
+
+It is built for historical research and testing, not broker connectivity or live trading.
 
 ## Features
 
-- Backtest engine with pending entries, OCO exits, scale-outs, pyramiding, cooldowns, daily risk limits, and optional replay data
-- Yahoo Finance historical downloader with local caching
-- Flexible CSV import for common OHLCV layouts
-- Metrics for positions and realized legs
-- CSV trade export
-- Self-contained HTML report export
-- Utility indicators and session helpers for strategy code
+- Modular structure: use the full workflow or just the engine, data layer, reporting, or helpers
+- Backtest engine with pending entries, OCO exits, scale-outs, pyramiding, cooldowns, daily loss limits, and optional replay/equity capture
+- Historical data loading from Yahoo Finance, with local caching to avoid repeated downloads
+- CSV import for common OHLCV formats and custom column mappings
+- Position-level and leg-level metrics, including drawdown, expectancy, hold-time stats, and side breakdowns
+- HTML report export, metrics JSON export, and trade CSV export
+- Utility indicators and session helpers for strategy development
+- TypeScript definitions for the public API
 
 ## Installation
 
@@ -26,6 +30,22 @@ npm install tradelab
 
 Node `18+` is required.
 
+## Importing
+
+### CommonJS
+
+```js
+const { backtest, getHistoricalCandles, ema } = require("tradelab");
+const { fetchHistorical } = require("tradelab/data");
+```
+
+### ESM
+
+```js
+import { backtest, getHistoricalCandles, ema } from "tradelab";
+import { fetchHistorical } from "tradelab/data";
+```
+
 ## Quick Start
 
 ```js
@@ -72,7 +92,7 @@ exportBacktestArtifacts({
 
 ## Getting Historical Data
 
-The simplest entry point is `getHistoricalCandles()`.
+The simplest entry point is `getHistoricalCandles()`. For most users, it is the only data-loading function you need.
 
 ### Yahoo Finance
 
@@ -154,6 +174,7 @@ Quality-of-life behavior:
 - `takeProfit` can be omitted if `rr` or `_rr` is provided
 - `qty` or `size` can override risk-based sizing
 - `riskPct` or `riskFraction` can override the global risk setting per signal
+- `strict: true` throws if the strategy directly accesses candles beyond the current index
 
 Optional engine hints:
 
@@ -173,8 +194,8 @@ Optional engine hints:
 
 - `trades`: every realized leg, including scale-outs
 - `positions`: completed positions only
-- `metrics`: aggregate performance stats
-- `eqSeries`: realized equity history
+- `metrics`: aggregate stats including `winRate`, `expectancy`, `profitFactor`, `maxDrawdown`, `sharpe`, `avgHold`, and `sideBreakdown`
+- `eqSeries`: realized equity history as `{ time, timestamp, equity }`
 - `replay`: chart-friendly frame and event data
 
 ## Main Exports
@@ -186,11 +207,12 @@ Optional engine hints:
 - `loadCandlesFromCSV(filePath, options)`
 - `saveCandlesToCache(candles, meta)`
 - `loadCandlesFromCache(symbol, interval, period, outDir)`
+- `exportMetricsJSON({ result, outDir })`
 - `exportBacktestArtifacts({ result, outDir })`
 
 ## Reports
 
-The HTML report is self-contained apart from the Plotly CDN script. Report markup, CSS, and client-side chart code live under `templates/`, not inline in the report renderer.
+The HTML report is self-contained apart from the Plotly CDN script. Report markup, CSS, and client-side chart code live under `templates/`.
 
 Export helpers default CSV output to completed positions. Use `csvSource: "trades"` if you want every realized leg in the CSV.
 
@@ -206,3 +228,4 @@ node examples/yahooEmaCross.js SPY 1d 1y
 - Yahoo downloads can be cached under `output/data` by default.
 - The engine is intended for historical research, not brokerage execution.
 - File output only happens through the reporting and cache helpers.
+- CommonJS and ESM are both supported.