@devanshhq/indica 0.1.0

package/PLAN.md

@@ -0,0 +1,355 @@
+# indica — Implementation Plan
+
+> Fast technical analysis indicators for stock markets. Built in Rust.
+> Learning Rust by building something real.
+
+## What This Is
+
+A Rust library that computes stock market technical indicators (SMA, RSI, MACD, Bollinger Bands, etc.) — the same math currently done in JavaScript in the Metis codebase (`lib/stock/indicators.ts`). The goal is to eventually use this from Node.js via NAPI-RS for 10-50x faster batch screening.
+
+## Why Rust
+
+- Learn Rust by building, not reading books
+- Real performance gains for batch stock screening (2,000+ stocks)
+- Publishable to crates.io (Rust) and npm (Node.js via NAPI)
+- Portfolio project — first Rust TA library for Indian markets
+
+## Current JS Reference
+
+The TypeScript file we're reimplementing (`metis-2/lib/stock/indicators.ts`) has these functions:
+
+```
+sma(values, period)           → number        Simple Moving Average
+ema(values, period)           → number        Exponential Moving Average
+rsi(closes, period)           → number        RSI (Wilder's smoothing)
+macd(closes, fast, slow, sig) → MACDResult    MACD with crossover detection
+bollingerBands(closes, p, m)  → BBResult      Bollinger Bands
+atr(highs, lows, closes, p)  → number        Average True Range
+pivotPoints(high, low, close) → PivotResult   Classic Pivot Points
+volumeTrend(volumes)          → string        Volume trend classification
+relativeStrength(stock, bench, period) → number  RS vs benchmark
+```
+
+---
+
+## Phase 0: Rust Fundamentals (You Are Here)
+
+**Goal:** Get comfortable with Rust basics before writing indicators.
+
+### Concepts to learn:
+- [x] `fn`, return types, `pub`
+- [x] `let` (immutable) vs `let mut`
+- [x] `println!` macro
+- [x] `#[test]` and `assert_eq!`
+- [ ] **Ownership & borrowing** — Rust's core concept (`&`, `&mut`)
+- [ ] **Slices** (`&[f64]`) — how Rust handles arrays without copying
+- [ ] **Option** (`Some(value)` / `None`) — Rust's null replacement
+- [ ] **Vec<f64>** — growable arrays (like JS arrays)
+- [ ] **Iterators** (`.iter()`, `.map()`, `.sum()`, `.fold()`)
+- [ ] **Structs** — like TypeScript interfaces but with data
+- [ ] **Enums** — like TypeScript union types but more powerful
+- [ ] **Error handling** (`Result<T, E>`) — no try/catch in Rust
+
+### Mini exercises (do these in src/lib.rs):
+1. Write a function that takes `&[f64]` and returns the sum
+2. Write a function that returns `Option<f64>` (None if empty slice)
+3. Write a function that returns a `Vec<f64>` (new computed array)
+4. Create a struct with named fields and a method on it
+5. Create an enum with variants and match on it
+
+**When you're done:** You'll understand enough Rust to start Phase 1.
+
+---
+
+## Phase 1: Moving Averages — SMA & EMA
+
+**Goal:** First real indicator. Teaches slices, iterators, Option.
+
+### What to build:
+```rust
+/// Simple Moving Average of the last `period` values
+pub fn sma(values: &[f64], period: usize) -> Option<f64>
+
+/// Exponential Moving Average
+pub fn ema(values: &[f64], period: usize) -> Option<f64>
+```
+
+### Rust concepts you'll use:
+- `&[f64]` — borrowing a slice (read-only view of an array)
+- `Option<f64>` — returns `None` instead of `NaN` when data is insufficient
+- `.len()`, `.iter()`, `.sum::<f64>()` — iterator methods
+- `.last()` — safely get last element
+
+### Tests to write:
+- SMA of `[1, 2, 3, 4, 5]` with period 3 → 4.0
+- SMA with insufficient data → None
+- EMA matches known values
+- Edge cases: empty slice, period=1, period=len
+
+### File structure:
+```
+src/
+  lib.rs          ← re-exports everything
+  moving_avg.rs   ← sma() and ema()
+```
+
+---
+
+## Phase 2: RSI — Wilder's Smoothing
+
+**Goal:** More complex math. Teaches mutable state + loops.
+
+### What to build:
+```rust
+/// Relative Strength Index (Wilder's smoothing)
+pub fn rsi(closes: &[f64], period: usize) -> Option<f64>
+```
+
+### Rust concepts you'll use:
+- `let mut` — mutable variables (for running averages)
+- `for i in 1..closes.len()` — range-based loops
+- `.abs()` — method on f64
+- Pattern: seed with initial average, then smooth iteratively
+
+### Tests:
+- RSI of known data matches expected output
+- Oversold (RSI < 30) and overbought (RSI > 70) cases
+- All gains → RSI = 100, all losses → RSI = 0
+- Edge: insufficient data → None
+
+### File:
+```
+src/
+  rsi.rs
+```
+
+---
+
+## Phase 3: MACD — Structs & Enums
+
+**Goal:** Return complex data. Teaches structs, enums, derive macros.
+
+### What to build:
+```rust
+#[derive(Debug, Clone)]
+pub enum Crossover {
+    Bullish,
+    Bearish,
+    None,
+}
+
+#[derive(Debug, Clone)]
+pub struct MacdResult {
+    pub value: f64,
+    pub signal: f64,
+    pub histogram: f64,
+    pub crossover: Crossover,
+}
+
+pub fn macd(
+    closes: &[f64],
+    fast: usize,    // default 12
+    slow: usize,    // default 26
+    signal: usize,  // default 9
+) -> Option<MacdResult>
+```
+
+### Rust concepts:
+- `struct` with `pub` fields
+- `enum` with variants (no values)
+- `#[derive(Debug, Clone)]` — auto-generate formatting and copying
+- `Vec<f64>` — building the MACD line series
+- Internal helper: reuse `ema()` from Phase 1 or compute inline
+
+### File:
+```
+src/
+  macd.rs
+```
+
+---
+
+## Phase 4: Bollinger Bands & ATR
+
+**Goal:** Statistics (std dev) and multi-input functions.
+
+### What to build:
+```rust
+#[derive(Debug, Clone)]
+pub struct BollingerBands {
+    pub upper: f64,
+    pub middle: f64,
+    pub lower: f64,
+    pub percent_b: f64,
+}
+
+pub fn bollinger_bands(closes: &[f64], period: usize, std_dev_mult: f64) -> Option<BollingerBands>
+
+/// Average True Range (Wilder's smoothing)
+pub fn atr(highs: &[f64], lows: &[f64], closes: &[f64], period: usize) -> Option<f64>
+```
+
+### Rust concepts:
+- `.sqrt()`, `.powi(2)` — math on f64
+- Multiple slice parameters (`highs`, `lows`, `closes`)
+- `.zip()` — iterating multiple slices together
+- `f64::max()` / `.max()` — finding maximum of values
+
+### Files:
+```
+src/
+  bollinger.rs
+  atr.rs
+```
+
+---
+
+## Phase 5: Pivot Points, Volume Trend, Relative Strength
+
+**Goal:** Complete the indicator set. Teaches &str returns and simple logic.
+
+### What to build:
+```rust
+#[derive(Debug, Clone)]
+pub struct PivotPoints {
+    pub r3: f64, pub r2: f64, pub r1: f64,
+    pub pivot: f64,
+    pub s1: f64, pub s2: f64, pub s3: f64,
+}
+
+pub fn pivot_points(high: f64, low: f64, close: f64) -> PivotPoints
+
+pub fn volume_trend(volumes: &[f64]) -> &'static str
+
+pub fn relative_strength(stock: &[f64], benchmark: &[f64], period: usize) -> Option<f64>
+```
+
+### Rust concepts:
+- `&'static str` — string literals that live forever (like "surging", "declining")
+- Simple arithmetic (no new concepts, just practice)
+- Lifetime annotation basics (the `'static` part)
+
+### Files:
+```
+src/
+  pivot.rs
+  volume.rs
+  relative_strength.rs
+```
+
+---
+
+## Phase 6: Batch Processing
+
+**Goal:** Compute indicators for 2,000+ stocks at once. Where Rust shines.
+
+### What to build:
+```rust
+#[derive(Debug, Clone)]
+pub struct StockData {
+    pub symbol: String,
+    pub closes: Vec<f64>,
+    pub highs: Vec<f64>,
+    pub lows: Vec<f64>,
+    pub volumes: Vec<f64>,
+}
+
+#[derive(Debug, Clone)]
+pub struct IndicatorSnapshot {
+    pub symbol: String,
+    pub sma_20: Option<f64>,
+    pub sma_50: Option<f64>,
+    pub rsi_14: Option<f64>,
+    pub macd: Option<MacdResult>,
+    pub bb: Option<BollingerBands>,
+    pub atr_14: Option<f64>,
+}
+
+/// Compute all indicators for multiple stocks
+pub fn batch_compute(stocks: &[StockData]) -> Vec<IndicatorSnapshot>
+```
+
+### Rust concepts:
+- `String` vs `&str` — owned vs borrowed strings
+- `Vec<T>` — vectors of structs
+- **Rayon** (parallel iterator crate) — `stocks.par_iter().map(...)` for multi-core
+- `cargo add rayon` — adding dependencies
+
+### Why this matters:
+This is the function that Metis would call from Node.js. Screening 2,000 stocks through all indicators in parallel — Rust + Rayon can do this in milliseconds vs seconds in JS.
+
+---
+
+## Phase 7: NAPI-RS Bindings (Connect to Node.js)
+
+**Goal:** Make the library callable from Metis's TypeScript code.
+
+### What to do:
+1. Add napi-rs dependencies to Cargo.toml
+2. Create `src/napi.rs` with `#[napi]` annotated wrapper functions
+3. Build with `cargo build --release`
+4. Import in Metis: `import { sma, rsi, macd } from 'indica'`
+
+### Rust concepts:
+- `#[napi]` macro — generates JS bindings
+- Type conversion: JS number[] ↔ Rust Vec<f64>
+- Publishing to npm via napi-rs CLI
+
+### This is the payoff:
+```typescript
+// In Metis — same API, 50x faster
+import { batchCompute } from 'indica';
+
+const results = batchCompute(allStocks); // milliseconds, not seconds
+```
+
+---
+
+## File Structure (final)
+
+```
+indica/
+├── Cargo.toml
+├── src/
+│   ├── lib.rs              ← re-exports all modules
+│   ├── moving_avg.rs       ← Phase 1: SMA, EMA
+│   ├── rsi.rs              ← Phase 2: RSI
+│   ├── macd.rs             ← Phase 3: MACD
+│   ├── bollinger.rs        ← Phase 4: Bollinger Bands
+│   ├── atr.rs              ← Phase 4: ATR
+│   ├── pivot.rs            ← Phase 5: Pivot Points
+│   ├── volume.rs           ← Phase 5: Volume Trend
+│   ├── relative_strength.rs← Phase 5: RS vs Benchmark
+│   ├── batch.rs            ← Phase 6: Batch processing
+│   └── napi.rs             ← Phase 7: Node.js bindings
+├── tests/
+│   └── integration.rs      ← Cross-module integration tests
+├── benches/
+│   └── indicators.rs       ← Performance benchmarks
+├── PLAN.md                 ← This file
+└── README.md
+```
+
+---
+
+## Learning Resources
+
+- **The Rust Book** (free): https://doc.rust-lang.org/book/
+  - Ch 4: Ownership (READ THIS FIRST)
+  - Ch 5: Structs
+  - Ch 6: Enums and Pattern Matching
+  - Ch 8: Vectors
+  - Ch 13: Iterators
+- **Rust by Example** (free): https://doc.rust-lang.org/rust-by-example/
+- **Exercism Rust Track** (free): https://exercism.org/tracks/rust
+- **ta crate** (study code): https://github.com/greyblake/ta-rs
+
+---
+
+## How We'll Work
+
+1. Start each phase by reading the relevant Rust Book chapter
+2. Write the functions with tests
+3. `cargo test -- --nocapture` to verify
+4. Commit after each phase
+5. Ask questions when stuck — that's the whole point

package/README.md

@@ -0,0 +1,160 @@
+# indica
+
+Fast technical analysis indicators for stock markets. Built in Rust.
+
+[![Crates.io](https://img.shields.io/crates/v/indica)](https://crates.io/crates/indica)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+## Why
+
+JavaScript/Python TA libraries are slow when screening thousands of stocks. indica computes all indicators for **2,000 stocks in 6ms** using Rust + Rayon parallelism.
+
+| Stocks | Sequential | Parallel (Rayon) |
+|--------|-----------|-----------------|
+| 100 | 0.5ms | 0.3ms |
+| 2,000 | 11ms | 6ms |
+
+## Indicators
+
+- **SMA** — Simple Moving Average
+- **EMA** — Exponential Moving Average
+- **RSI** — Relative Strength Index (Wilder's smoothing)
+- **MACD** — Moving Average Convergence Divergence with crossover detection
+- **Bollinger Bands** — Upper, middle, lower bands + %B
+- **ATR** — Average True Range (Wilder's smoothing)
+- **Pivot Points** — Classic (R3/R2/R1/Pivot/S1/S2/S3)
+- **Volume Trend** — Surging / increasing / stable / declining / drying up
+- **Relative Strength** — Stock vs benchmark comparison
+
+## Installation
+
+### Rust
+
+```toml
+[dependencies]
+indica = "0.1"
+```
+
+### Node.js (via NAPI-RS)
+
+```bash
+npm install indica
+```
+
+## Usage (Rust)
+
+```rust
+use indica::{sma, rsi, macd, bollinger_bands, atr, pivot_points};
+
+fn main() {
+    let closes = vec![44.34, 44.09, 44.15, 43.61, 44.33, 44.83, 45.10,
+                      45.42, 45.84, 46.08, 45.89, 46.03, 45.61, 46.28,
+                      46.28, 46.00, 46.03, 46.41, 46.22, 46.21];
+
+    // Simple Moving Average
+    let sma_20 = sma(&closes, 20);
+    println!("SMA(20): {:?}", sma_20); // Some(45.52)
+
+    // RSI
+    let rsi_14 = rsi(&closes, 14);
+    println!("RSI(14): {:?}", rsi_14); // Some(55.37)
+
+    // MACD
+    if let Some(result) = macd(&closes, 12, 26, 9) {
+        println!("MACD: {}, Signal: {}, Crossover: {:?}",
+            result.value, result.signal, result.crossover);
+    }
+
+    // Bollinger Bands
+    if let Some(bb) = bollinger_bands(&closes, 20, 2.0) {
+        println!("BB Upper: {}, Lower: {}, %B: {}", bb.upper, bb.lower, bb.percent_b);
+    }
+}
+```
+
+## Batch Processing (screen thousands of stocks)
+
+```rust
+use indica::batch::{StockData, batch_compute_parallel};
+
+let stocks = vec![
+    StockData {
+        symbol: "RELIANCE".to_string(),
+        closes: vec![/* 250 daily closes */],
+        highs: vec![/* ... */],
+        lows: vec![/* ... */],
+        volumes: vec![/* ... */],
+    },
+    // ... 2000 more stocks
+];
+
+// Computes ALL indicators for ALL stocks using all CPU cores
+let results = batch_compute_parallel(&stocks);
+
+for snap in &results {
+    println!("{}: RSI={:?}, SMA20={:?}", snap.symbol, snap.rsi_14, snap.sma_20);
+}
+```
+
+## Usage (Node.js)
+
+```javascript
+const { calcRsi, calcMacd, batchComputeIndicators } = require('indica');
+
+// Single indicator
+const rsi = calcRsi([44.34, 44.09, /* ... */], 14);
+console.log('RSI:', rsi); // 55.37
+
+// MACD with crossover detection
+const macd = calcMacd(closes, 12, 26, 9);
+console.log(macd); // { value: 0.34, signal: 0.28, histogram: 0.06, crossover: 'bullish' }
+
+// Batch: screen 2000 stocks at once
+const results = batchComputeIndicators([
+  { symbol: 'RELIANCE', closes: [...], highs: [...], lows: [...], volumes: [...] },
+  { symbol: 'TCS', closes: [...], highs: [...], lows: [...], volumes: [...] },
+  // ... thousands more
+]);
+// Returns in ~6ms using all CPU cores
+```
+
+## API Reference
+
+### Single Indicators
+
+| Function | Input | Output |
+|----------|-------|--------|
+| `sma(values, period)` | `&[f64], usize` | `Option<f64>` |
+| `ema(values, period)` | `&[f64], usize` | `Option<f64>` |
+| `rsi(closes, period)` | `&[f64], usize` | `Option<f64>` |
+| `macd(closes, fast, slow, signal)` | `&[f64], usize, usize, usize` | `Option<MacdResult>` |
+| `bollinger_bands(closes, period, std_dev)` | `&[f64], usize, f64` | `Option<BollingerBandsResult>` |
+| `atr(highs, lows, closes, period)` | `&[f64], &[f64], &[f64], usize` | `Option<f64>` |
+| `pivot_points(high, low, close)` | `f64, f64, f64` | `PivotPointsResult` |
+| `volume_trend(volumes)` | `&[f64]` | `&str` |
+| `relative_strength(stock, bench, period)` | `&[f64], &[f64], usize` | `Option<f64>` |
+
+### Batch
+
+| Function | Input | Output |
+|----------|-------|--------|
+| `batch_compute(stocks)` | `&[StockData]` | `Vec<IndicatorSnapshot>` |
+| `batch_compute_parallel(stocks)` | `&[StockData]` | `Vec<IndicatorSnapshot>` |
+
+All functions return `Option` (Rust's null) when there isn't enough data for the calculation. No panics, no NaN.
+
+## Building from Source
+
+```bash
+# Rust library
+cargo build --release
+cargo test
+
+# Node.js native addon
+npm install
+npm run build
+```
+
+## License
+
+MIT

package/build.rs

@@ -0,0 +1,5 @@
+extern crate napi_build;
+
+fn main() {
+    napi_build::setup();
+}

package/index.d.ts

@@ -0,0 +1,66 @@
+/* auto-generated by NAPI-RS */
+/* eslint-disable */
+export declare function batchComputeIndicators(stocks: Array<JsStockData>): Array<JsIndicatorSnapshot>
+
+export declare function calcAtr(highs: Array<number>, lows: Array<number>, closes: Array<number>, period: number): number | null
+
+export declare function calcBollingerBands(closes: Array<number>, period: number, stdDev: number): JsBollingerBands | null
+
+export declare function calcEma(values: Array<number>, period: number): number | null
+
+export declare function calcMacd(closes: Array<number>, fast: number, slow: number, signal: number): JsMacdResult | null
+
+export declare function calcPivotPoints(high: number, low: number, close: number): JsPivotPoints
+
+export declare function calcRelativeStrength(stock: Array<number>, benchmark: Array<number>, period: number): number | null
+
+export declare function calcRsi(closes: Array<number>, period: number): number | null
+
+export declare function calcSma(values: Array<number>, period: number): number | null
+
+export declare function calcVolumeTrend(volumes: Array<number>): string
+
+export interface JsBollingerBands {
+  upper: number
+  middle: number
+  lower: number
+  percentB: number
+}
+
+export interface JsIndicatorSnapshot {
+  symbol: string
+  sma20?: number
+  sma50?: number
+  sma200?: number
+  ema20?: number
+  rsi14?: number
+  macd?: JsMacdResult
+  bollinger?: JsBollingerBands
+  atr14?: number
+  volumeTrend: string
+}
+
+export interface JsMacdResult {
+  value: number
+  signal: number
+  histogram: number
+  crossover: string
+}
+
+export interface JsPivotPoints {
+  r3: number
+  r2: number
+  r1: number
+  pivot: number
+  s1: number
+  s2: number
+  s3: number
+}
+
+export interface JsStockData {
+  symbol: string
+  closes: Array<number>
+  highs: Array<number>
+  lows: Array<number>
+  volumes: Array<number>
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@devanshhq/indica",
+  "version": "0.1.0",
+  "description": "Fast technical analysis indicators for stock markets. Built in Rust.",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "repository": "https://github.com/Devansh-365/indica",
+  "license": "MIT",
+  "keywords": ["trading", "technical-analysis", "indicators", "rust", "napi", "stocks", "nse"],
+  "napi": {
+    "name": "indica",
+    "triples": {
+      "defaults": true
+    }
+  },
+  "scripts": {
+    "build": "napi build --release",
+    "build:debug": "napi build"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^3.0.0"
+  }
+}

package/src/atr.rs

@@ -0,0 +1,66 @@
+use crate::utils::round;
+
+/// Average True Range using Wilder's smoothing.
+/// Requires `period + 1` data points minimum.
+/// Returns `None` if insufficient data.
+pub fn atr(highs: &[f64], lows: &[f64], closes: &[f64], period: usize) -> Option<f64> {
+    let len = closes.len();
+    if len < period + 1 || highs.len() < len || lows.len() < len || period == 0 {
+        return None;
+    }
+
+    // Compute true ranges
+    let true_ranges: Vec<f64> = (1..len)
+        .map(|i| {
+            let hl = highs[i] - lows[i];
+            let hc = (highs[i] - closes[i - 1]).abs();
+            let lc = (lows[i] - closes[i - 1]).abs();
+            hl.max(hc).max(lc)
+        })
+        .collect();
+
+    if true_ranges.len() < period {
+        return None;
+    }
+
+    // Initial ATR = simple average of first `period` true ranges
+    let mut atr_value: f64 = true_ranges[..period].iter().sum::<f64>() / period as f64;
+
+    // Wilder's smoothing
+    for &tr in &true_ranges[period..] {
+        atr_value = (atr_value * (period as f64 - 1.0) + tr) / period as f64;
+    }
+
+    Some(round(atr_value, 2))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn atr_basic() {
+        let highs = vec![48.7, 48.72, 48.9, 48.87, 48.82, 49.05, 49.2, 49.35,
+                         49.92, 50.19, 50.12, 49.66, 49.88, 50.19, 50.36, 50.57];
+        let lows  = vec![47.79, 48.14, 48.39, 48.37, 48.24, 48.64, 48.94, 48.86,
+                         49.50, 49.87, 49.20, 48.90, 49.43, 49.73, 49.26, 50.09];
+        let closes = vec![48.16, 48.61, 48.75, 48.63, 48.74, 49.03, 49.07, 49.32,
+                          49.91, 50.13, 49.53, 49.50, 49.75, 50.03, 49.99, 50.23];
+        let result = atr(&highs, &lows, &closes, 14).unwrap();
+        assert!(result > 0.0);
+        assert!(result < 2.0); // Reasonable range for this data
+    }
+
+    #[test]
+    fn atr_insufficient_data() {
+        assert!(atr(&[1.0; 5], &[1.0; 5], &[1.0; 5], 14).is_none());
+    }
+
+    #[test]
+    fn atr_flat_market() {
+        // All same price = ATR near 0
+        let data = vec![100.0; 20];
+        let result = atr(&data, &data, &data, 14).unwrap();
+        assert_eq!(result, 0.0);
+    }
+}