@lacspace/market 1.0.0 → 1.0.1

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 (2) hide show
  1. package/README.md +111 -0
  2. package/package.json +1 -1
package/README.md ADDED
@@ -0,0 +1,111 @@
1
+ <div align="center">
2
+
3
+ # @lacspace/market
4
+
5
+ **The money & mechanics toolkit every stock-market app re-implements — including a real Indian brokerage & charges calculator.**
6
+
7
+ [![npm version](https://img.shields.io/npm/v/@lacspace/market?color=%2316a34a&label=npm)](https://www.npmjs.com/package/@lacspace/market)
8
+ [![install size](https://packagephobia.com/badge?p=@lacspace/market)](https://packagephobia.com/result?p=@lacspace/market)
9
+ [![minzipped](https://img.shields.io/bundlephobia/minzip/@lacspace/market?label=minzip)](https://bundlephobia.com/package/@lacspace/market)
10
+ [![types](https://img.shields.io/badge/types-included-blue)](https://www.npmjs.com/package/@lacspace/market)
11
+ [![license](https://img.shields.io/npm/l/@lacspace/market?color=green)](https://github.com/lacspace/npm-packages/blob/main/LICENSE)
12
+
13
+ </div>
14
+
15
+ > P&L, returns, CAGR, **XIRR**, tick-size rounding, circuit limits, risk-based position sizing — plus the thing nobody packages: a **full Indian brokerage & statutory charges breakdown** (STT, GST, SEBI, stamp duty, exchange txn) with discount-broker presets.
16
+
17
+ - 💸 **Charges calculator** — the exact Zerodha-style breakdown traders actually see
18
+ - 📊 P&L, `changePercent`, `pnlPercent`, `cagr`, `xirr`, `averagePrice`
19
+ - 🎯 `positionSize` (risk-based), `roundToTick`, `circuitLimits`
20
+ - 🇮🇳 `formatINR` with lakh/crore grouping
21
+ - ⚡ Zero dependencies · 🌍 isomorphic · 📦 ESM + CJS · fully typed
22
+
23
+ ## Install
24
+
25
+ ```bash
26
+ npm install @lacspace/market # or pnpm add / yarn add / bun add
27
+ ```
28
+
29
+ ## The charges calculator ✨
30
+
31
+ ```ts
32
+ import { charges } from "@lacspace/market";
33
+
34
+ charges({ segment: "intraday", buy: 100, sell: 102, qty: 500 });
35
+ // {
36
+ // turnover: 101000, brokerage: 30.3, stt: 12.75, exchangeTxn: 3,
37
+ // sebi: 0.1, stamp: 1.5, gst: 6.01, dp: 0,
38
+ // totalCharges: 53.66, grossPnl: 1000, netPnl: 946.34, breakeven: 0.11
39
+ // }
40
+
41
+ charges({ segment: "delivery", buy: 1000, sell: 1100, qty: 10 });
42
+ charges({ segment: "options", buy: 120, sell: 150, qty: 75 });
43
+ ```
44
+
45
+ Rates default to an Indian discount broker (Zerodha-style, FY2024–25). Statutory rates change — override any field and always verify against the live rate card:
46
+
47
+ ```ts
48
+ import { charges, IN_DISCOUNT_BROKER } from "@lacspace/market";
49
+
50
+ charges(input, {
51
+ ...IN_DISCOUNT_BROKER,
52
+ segments: {
53
+ ...IN_DISCOUNT_BROKER.segments,
54
+ delivery: { ...IN_DISCOUNT_BROKER.segments.delivery, brokeragePct: 0.001 },
55
+ },
56
+ });
57
+ ```
58
+
59
+ ## Returns & P&L
60
+
61
+ ```ts
62
+ import { pnl, pnlPercent, changePercent, cagr, xirr } from "@lacspace/market";
63
+
64
+ pnl({ buy: 100, sell: 112, qty: 50 }); // 600
65
+ pnlPercent({ buy: 100, sell: 112 }); // 12
66
+ changePercent(2950, 2900); // 1.72 (LTP vs prev close)
67
+ cagr(100000, 200000, 3); // 0.2599 (25.99% a year)
68
+
69
+ xirr([
70
+ { amount: -10000, date: "2024-01-01" },
71
+ { amount: -5000, date: "2024-06-01" },
72
+ { amount: 17000, date: "2025-01-01" },
73
+ ]); // ≈ annualised return, irregular cash flows
74
+ ```
75
+
76
+ ## Trade mechanics
77
+
78
+ ```ts
79
+ import { averagePrice, positionSize, roundToTick, circuitLimits, formatINR } from "@lacspace/market";
80
+
81
+ averagePrice([{ price: 100, qty: 10 }, { price: 110, qty: 10 }]); // 105
82
+ positionSize({ capital: 100000, riskPercent: 1, entry: 500, stop: 480 }); // 50 shares
83
+ roundToTick(101.23); // 101.25 (nearest ₹0.05)
84
+ circuitLimits(100, 10); // { upper: 110, lower: 90 }
85
+ formatINR(1234567.5); // "₹12,34,567.50"
86
+ ```
87
+
88
+ ## API
89
+
90
+ | Function | Description |
91
+ | --- | --- |
92
+ | `charges(input, config?)` | full brokerage + statutory breakdown |
93
+ | `pnl` / `pnlPercent` / `changePercent` | profit & loss |
94
+ | `cagr(begin, end, years)` | compound annual growth rate |
95
+ | `xirr(cashflows, guess?)` | irregular-cashflow annualised return |
96
+ | `averagePrice(trades)` | volume-weighted average |
97
+ | `positionSize({...})` | risk-based whole-share sizing |
98
+ | `roundToTick(price, tick?)` | snap to exchange tick |
99
+ | `circuitLimits(prevClose, %)` | upper / lower circuit |
100
+ | `formatINR(n, opts?)` | Indian lakh/crore currency string |
101
+
102
+ ## The Lacspace StockKit
103
+
104
+ | Package | For |
105
+ | --- | --- |
106
+ | [`@lacspace/indicators`](https://www.npmjs.com/package/@lacspace/indicators) | Technical indicators |
107
+ | **`@lacspace/market`** | Money & charges (this package) |
108
+ | [`@lacspace/market-clock`](https://www.npmjs.com/package/@lacspace/market-clock) | Is the market open? holidays |
109
+ | [`@lacspace/paper-trade`](https://www.npmjs.com/package/@lacspace/paper-trade) | Headless paper-trading engine |
110
+
111
+ <div align="center"><sub>Built with care by <a href="https://lacspace.com">Lacspace</a> · powers <a href="https://stockyatra.com">StockYatra</a> · MIT licensed · <a href="https://github.com/lacspace/npm-packages">source</a></sub></div>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lacspace/market",
3
- "version": "1.0.0",
3
+ "version": "1.0.1",
4
4
  "description": "Stock-market money math — P&L, returns, CAGR, XIRR, tick-size rounding, circuit limits, position sizing and an Indian brokerage & charges calculator (STT, GST, SEBI, stamp). Zero-dependency.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",