Skip to content

Commit 8f10a0a

Browse files
NeaByteLabNeaByteLab
committed
feat(project): initial release of forex calculator tools 🎉
- Add backtesting engine for strategy validation - Add core calculators for lot size, profit, and pivot points - Add Deno and Node.js configuration for cross-runtime support - Add JSDoc documentation adhering to project style guide - Add project documentation in README.md and LICENSE - Add strategy simulations for drawdown and expectancy - Add unit test suite for all mathematical tools
0 parents  commit 8f10a0a

22 files changed

Lines changed: 4185 additions & 0 deletions

‎.github/workflows/ci.yaml‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
build-check:
11+
name: Build Check
12+
runs-on: ubuntu-latest
13+
strategy:
14+
matrix:
15+
node-version: [22.x]
16+
17+
steps:
18+
- name: Checkout code
19+
uses: actions/checkout@v4
20+
21+
- name: Setup Node.js ${{ matrix.node-version }}
22+
uses: actions/setup-node@v4
23+
with:
24+
node-version: ${{ matrix.node-version }}
25+
cache: 'npm'
26+
27+
- name: Install dependencies
28+
run: npm ci
29+
30+
- name: Build project
31+
run: npm run build

‎.github/workflows/publish.yml‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
name: Deno Publish
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
jobs:
9+
publish:
10+
runs-on: ubuntu-latest
11+
permissions:
12+
contents: read
13+
id-token: write
14+
15+
steps:
16+
- uses: actions/checkout@v4
17+
- uses: denoland/setup-deno@v2
18+
with:
19+
deno-version: v2.5.4
20+
21+
- name: Check package
22+
run: deno check src/index.ts
23+
24+
- name: Run unit tests
25+
run: deno test --no-check
26+
27+
- name: Publish package
28+
run: deno publish --allow-dirty

‎.gitignore‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# Deno
2+
.deno/
3+
coverage/
4+
deno.lock
5+
6+
# IDE
7+
.vscode/
8+
.idea/
9+
10+
# OS
11+
.DS_Store
12+
Thumbs.db
13+
14+
# Node
15+
dist/
16+
node_modules/

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 NeaByteLab
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 224 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,224 @@
1+
# Forex Calculator [![Module type: CJS+ESM](https://img.shields.io/badge/module%20type-cjs%2Besm-brightgreen)](https://github.com/NeaByteLab/Forex-Calculator) [![npm version](https://img.shields.io/npm/v/@neabyte/forex-calculator.svg)](https://www.npmjs.org/package/@neabyte/forex-calculator) [![JSR](https://jsr.io/badges/@neabyte/forex-calculator)](https://jsr.io/@neabyte/forex-calculator)
2+
3+
Simple and reliable Forex Calculator tools for trading analysis.
4+
5+
## Installation
6+
7+
Choose your preferred package manager:
8+
9+
```bash
10+
# npm package
11+
npm install @neabyte/forex-calculator
12+
13+
# Deno module
14+
deno add jsr:@neabyte/forex-calculator
15+
```
16+
17+
## Usage
18+
19+
### Position Sizing
20+
21+
Calculate optimal lot size based on account risk and stop loss distance.
22+
23+
```typescript
24+
import { calculateLotSize } from '@neabyte/forex-calculator'
25+
26+
const result = calculateLotSize({
27+
pairName: 'XAUUSD',
28+
openPrice: 2000,
29+
stopPrice: 1990,
30+
leverage: 100,
31+
riskUSD: 100
32+
})
33+
console.log(result)
34+
/*
35+
{
36+
info: { symbol: 'XAUUSD', timestamp: '...', type: 'METAL' },
37+
margin: { leverage: '1:100', required: 200 },
38+
position: { lot: 0.1, pipValue: 1, units: 10 },
39+
risk: { amount: 100, stopDistance: 10, stopPoints: 100 }
40+
}
41+
*/
42+
```
43+
44+
### Profit & Loss
45+
46+
Calculate the exact profit or loss in USD and pips for any position.
47+
48+
```typescript
49+
import { calculateProfit } from '@neabyte/forex-calculator'
50+
51+
const result = calculateProfit({
52+
pairName: 'EURUSD',
53+
sidePosition: 'BUY',
54+
lotSize: 1.0,
55+
entryPrice: 1.1,
56+
exitPrice: 1.105
57+
})
58+
console.log(result)
59+
/*
60+
{
61+
isProfit: true,
62+
pips: 50,
63+
profitUSD: 500,
64+
sidePosition: 'BUY',
65+
symbol: 'EURUSD',
66+
type: 'FOREX'
67+
}
68+
*/
69+
```
70+
71+
### Pivot Points
72+
73+
Support for multiple methodologies to find support and resistance.
74+
75+
```typescript
76+
import { calculatePivotPoints } from '@neabyte/forex-calculator'
77+
78+
const result = calculatePivotPoints({
79+
high: 1.1,
80+
low: 1.09,
81+
close: 1.095,
82+
method: 'FIBONACCI'
83+
})
84+
console.log(result)
85+
/*
86+
{
87+
method: 'FIBONACCI',
88+
p: 1.095,
89+
r1: 1.09882,
90+
r2: 1.10118,
91+
r3: 1.105,
92+
s1: 1.09118,
93+
s2: 1.08882,
94+
s3: 1.085
95+
}
96+
*/
97+
```
98+
99+
### Strategy Simulations
100+
101+
Project account growth or analyze risk with built-in simulators.
102+
103+
```typescript
104+
import { simulateCompounding, calculateExpectancy } from '@neabyte/forex-calculator'
105+
106+
// Project compounding growth
107+
const compound = simulateCompounding({
108+
startBalance: 1000,
109+
profitPerTrade: 10,
110+
totalTrades: 2
111+
})
112+
console.log(compound)
113+
/*
114+
[
115+
{ period: 1, startBalance: 1000, endBalance: 1100, profit: 100 },
116+
{ period: 2, startBalance: 1100, endBalance: 1210, profit: 110 }
117+
]
118+
*/
119+
120+
// Calculate mathematical edge
121+
const edge = calculateExpectancy({
122+
winRate: 50,
123+
avgWinUSD: 100,
124+
avgLossUSD: 50
125+
})
126+
console.log(edge) // { expectancy: 25, potentialProfit: 1250, status: 'POSITIVE' }
127+
```
128+
129+
### Backtesting
130+
131+
Simulate trading a strategy over a specific period of time.
132+
133+
```typescript
134+
import { calculateBacktest } from '@neabyte/forex-calculator'
135+
136+
const result = calculateBacktest({
137+
initBalance: 1000,
138+
riskAmount: 10,
139+
tradePerDay: 1,
140+
totalDays: 5,
141+
winRate: 60,
142+
rewardRatio: 2
143+
})
144+
console.log(result.summary)
145+
/*
146+
{
147+
actualWinRate: 60,
148+
finalBalance: 1040,
149+
initBalance: 1000,
150+
isProfitable: true,
151+
netProfit: 40,
152+
totalTrades: 5,
153+
totalWins: 3,
154+
...
155+
}
156+
*/
157+
```
158+
159+
## API Reference
160+
161+
### Core Calculators
162+
163+
- **`calculateLotSize(params)`**: Returns `LotSizeResult`. Calculates margin, lot size, and risk metrics.
164+
- **`calculateProfit(params)`**: Returns `ProfitResult`. Calculates PnL and pip distance.
165+
- **`calculatePivotPoints(params)`**: Returns `PivotResult`. Supports `CLASSIC`, `FIBONACCI`, `CAMARILLA`, `WOODIES`, `DEMARKS`.
166+
167+
### Strategy Simulations
168+
169+
- **`simulateCompounding(params)`**: Project account growth over multiple trades.
170+
- **`calculateDrawdown(params)`**: Analyze potential balance decay during losing streaks.
171+
- **`calculateExpectancy(params)`**: Determine strategy edge (Statistical Expectancy).
172+
173+
### Backtesting
174+
175+
- **`calculateBacktest(params)`**: Comprehensive strategy simulation over a time period.
176+
177+
## Supported Instruments
178+
179+
The library supports a wide range of symbols across different asset classes.
180+
181+
### Forex
182+
183+
| Symbol | Contract Size | Pip Size |
184+
| :--------------------------------------------------------------------------------------------- | :------------ | :------- |
185+
| AUDJPY, CADJPY, CHFJPY, EURJPY, GBPJPY, NZDJPY, USDJPY | 100,000 | 0.01 |
186+
| AUDNZD, AUDUSD, EURAUD, EURGBP, EURNZD, EURUSD, GBPCAD, GBPNZD, GBPUSD, NZDUSD, USDCAD, USDCHF | 100,000 | 0.0001 |
187+
188+
### Metals
189+
190+
| Symbol | Type | Contract Size | Pip Size |
191+
| :----- | :----- | :------------ | :------- |
192+
| XAUUSD | Gold | 100 | 0.1 |
193+
| XAGUSD | Silver | 5000 | 0.01 |
194+
195+
### Indices & Commodities
196+
197+
| Symbol | Contract Size | Pip Size |
198+
| :----------------------------------------- | :------------ | :------- |
199+
| US30, NAS100, SPX500, GER40, JPN225, UK100 | 1 | 1.0 |
200+
| USOIL, UKOIL | 100 | 0.01 |
201+
| XNGUSD | 10,000 | 0.001 |
202+
203+
### Crypto
204+
205+
| Symbol | Contract Size | Pip Size |
206+
| :------------- | :------------ | :------- |
207+
| BTCUSD, ETHUSD | 1 | 1.0 |
208+
| SOLUSD | 1 | 0.01 |
209+
210+
## Error Handling
211+
212+
The library validates inputs and throws clear error messages:
213+
214+
```typescript
215+
try {
216+
calculatePivotPoints({ high: 0, low: 100, close: 105, method: 'CLASSIC' })
217+
} catch (e) {
218+
console.error(e.message) // "Prices must be greater than 0"
219+
}
220+
```
221+
222+
## License
223+
224+
This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.

‎build.config.ts‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
import { defineBuildConfig } from 'unbuild'
2+
import { resolve } from 'node:path'
3+
4+
export default defineBuildConfig({
5+
entries: ['src/index'],
6+
declaration: true,
7+
clean: true,
8+
alias: {
9+
'@app': resolve(__dirname, 'src'),
10+
'@helpers': resolve(__dirname, 'src/helpers')
11+
},
12+
rollup: {
13+
emitCJS: true,
14+
inlineDependencies: true
15+
},
16+
sourcemap: false,
17+
failOnWarn: false
18+
})

0 commit comments

Comments
 (0)