@deepentropy/oakscriptjs@0.1.2

Built and signed on GitHub Actions

Built and signed on GitHub Actions

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397
# OakScriptJS

**JavaScript mirror of the PineScript API - Calculation & Indicator Functions**

OakScriptJS is a TypeScript/JavaScript library that mirrors PineScript's calculation and indicator API, maintaining exact function signatures and behavior. This library focuses on the computational core of PineScript - technical analysis, mathematics, and data manipulation - making it perfect for building custom trading engines, backtesting systems, or analysis tools in JavaScript/TypeScript.

## Scope

**This library includes:**
- ✅ Technical Analysis (`ta.*`) - All indicators and calculations
- ✅ Mathematics (`math.*`) - All mathematical operations
- ✅ Arrays (`array.*`) - Array manipulation and operations
- ✅ Matrices (`matrix.*`) - Matrix operations
- ✅ Strings (`str.*`) - String manipulation
- ✅ Time (`time.*`) - Time calculations and conversions
- ✅ Color (`color.*`) - Color data structures and manipulation
- ✅ **Drawing Objects** (`line.*`, `box.*`, `label.*`, `linefill.*`) - Computational features only

**This library does NOT include:**
- ❌ Rendering functions (`plot.*`, `table.*`)
- ❌ UI/Input functions (`input.*`)
- ❌ Strategy execution (`strategy.*`)
- ❌ Data fetching (`request.*`)
- ❌ Alert systems (`alert.*`, `alertcondition.*`)

## Why Include Drawing Objects?

While drawing objects (`line`, `box`, `label`, `linefill`) are primarily visual in TradingView, they have **genuine computational value**:

- **`line.get_price()`** - Calculate trend line prices using linear interpolation for breakout detection
- **`box` getters** - Detect gap fills, range breakouts, and pattern recognition
- **`label` & `linefill`** - Primarily annotations, but useful for algorithmic context

These objects are implemented **without rendering** - focusing purely on their computational aspects.

## Why These Limitations?

The excluded namespaces require external infrastructure (rendering engines, UI frameworks, data feeds, backtesting systems) that are specific to TradingView's platform. OakScriptJS focuses on what can be accurately replicated in pure JavaScript: calculations and data transformations.

## Features

- **Exact API Match**: Function signatures match PineScript exactly
- **Type Safety**: Full TypeScript support with type definitions
- **Performance Optimized**: Efficient implementations for technical analysis
- **Calculation-Focused**: All computational functions from PineScript
- **Well Tested**: Extensive test coverage ensuring accuracy
- **Zero Dependencies**: Lightweight with no external runtime dependencies

## Priorities

1. **Exact same signature as PineScript API** - Maintains 100% compatibility
2. **Accuracy** - Produces results matching PineScript calculations
3. **Performance** - Optimized for speed and efficiency

## Installation

### JSR (Recommended)

```bash
# npm
npx jsr add @deepentropy/oakscriptjs

# pnpm (10.9+)
pnpm add jsr:@deepentropy/oakscriptjs

# yarn (4.9+)
yarn add jsr:@deepentropy/oakscriptjs

# Deno
deno add jsr:@deepentropy/oakscriptjs

# Bun
bunx jsr add @deepentropy/oakscriptjs
```

### npm (Coming Soon)

```bash
npm install @deepentropy/oakscriptjs
```

## Quick Start

```typescript
import { ta, math, line, box, createContext } from '@deepentropy/oakscriptjs';

// Calculate Simple Moving Average
const prices = [10, 12, 11, 13, 15, 14, 16, 18, 17, 19];
const sma20 = ta.sma(prices, 5);

// Calculate RSI
const rsi = ta.rsi(prices, 14);

// Calculate MACD
const [macdLine, signalLine, histogram] = ta.macd(prices, 12, 26, 9);

// Use math functions
const max = math.max(10, 20, 30); // 30
const avg = math.avg(10, 20, 30); // 20

// NEW: Use drawing objects for computational analysis
const trendLine = line.new(0, 100, 50, 150);
const priceAt25 = line.get_price(trendLine, 25); // 125 (linear interpolation)

// Detect gap with box
const gapBox = box.new(10, 120, 15, 110);
const gapTop = box.get_top(gapBox);
const gapBottom = box.get_bottom(gapBox);
const gapFilled = prices[20] > gapBottom && prices[20] < gapTop;
```

## Use Cases

OakScriptJS is perfect for:
- **Custom Trading Engines** - Build your own backtesting or execution system
- **Analysis Tools** - Create technical analysis applications
- **Data Processing** - Calculate indicators on market data
- **Algorithm Development** - Develop and test trading algorithms
- **Educational Projects** - Learn about technical indicators

## Supported Namespaces

### Technical Analysis (`ta`) ✅

Complete implementation of PineScript's technical analysis functions:

- **Moving Averages**: `sma()`, `ema()`, `wma()`, `vwma()`, `swma()`, etc.
- **Oscillators**: `rsi()`, `stoch()`, `cci()`, `macd()`, `mfi()`, etc.
- **Volatility**: `bb()`, `atr()`, `stdev()`, `variance()`, etc.
- **Momentum**: `mom()`, `roc()`, `percentrank()`, etc.
- **Regression**: `linreg()`, `correlation()`, etc.
- **Crossovers**: `crossover()`, `crossunder()`, `cross()`
- **Other**: `change()`, `tr()`, `supertrend()`, and many more

### Math (`math`) ✅

Mathematical functions and operations:

- **Basic**: `abs()`, `ceil()`, `floor()`, `round()`
- **Min/Max**: `min()`, `max()`, `avg()`
- **Powers**: `sqrt()`, `pow()`, `exp()`, `log()`, `log10()`
- **Trigonometry**: `sin()`, `cos()`, `tan()`, `asin()`, `acos()`, `atan()`, `atan2()`
- **Utilities**: `sum()`, `sign()`, `random()`, `todegrees()`, `toradians()`

### Array (`array`) ✅

Array manipulation functions:

- **Creation**: `new_array()`, `from()`
- **Access**: `get()`, `set()`, `size()`
- **Modification**: `push()`, `pop()`, `shift()`, `unshift()`, `insert()`, `remove()`
- **Analysis**: `sum()`, `avg()`, `min()`, `max()`, `median()`, `stdev()`, `variance()`
- **Operations**: `sort()`, `reverse()`, `slice()`, `concat()`, `includes()`, `indexof()`

### Matrix (`matrix`) ✅

Matrix operations for advanced calculations:

- **Creation**: `new()`, `copy()`
- **Operations**: `mult()`, `add()`, `transpose()`
- **Access**: `get()`, `set()`, `row()`, `col()`

### String (`str`) ✅

String manipulation functions:

- **Conversion**: `tostring()`, `tonumber()`
- **Manipulation**: `substring()`, `split()`, `concat()`, `replace()`
- **Case**: `upper()`, `lower()`
- **Search**: `contains()`, `pos()`, `startswith()`, `endswith()`
- **Formatting**: `format()`, `trim()`

### Time (`time`) ✅

Time calculations and conversions:

- **Conversions**: Convert between timestamps and time components
- **Calculations**: Work with timeframes and time-based logic

### Color (`color`) ✅

Color creation and manipulation:

- **Creation**: `rgb()`, `from_hex()`, `new_color()`
- **Components**: `r()`, `g()`, `b()`, `t()`
- **Predefined Colors**: `red`, `green`, `blue`, `yellow`, etc.

### Drawing Objects ✅

**NEW**: Drawing objects with computational features (no rendering):

#### Line (`line`) - High Computational Value

- **Creation**: `new()` - Create trend lines with coordinates
- **Computation**: `get_price()` - Linear interpolation for breakout detection
- **Getters**: `get_x1()`, `get_y1()`, `get_x2()`, `get_y2()`
- **Setters**: `set_x1()`, `set_y1()`, `set_xy1()`, `set_color()`, `set_style()`, etc.
- **Operations**: `copy()`, `delete()`

#### Box (`box`) - High Computational Value

- **Creation**: `new()` - Create rectangles for ranges
- **Computation**: `get_top()`, `get_bottom()`, `get_left()`, `get_right()` - Gap detection & range analysis
- **Setters**: `set_top()`, `set_bottom()`, `set_bgcolor()`, `set_border_color()`, etc.
- **Operations**: `copy()`, `delete()`

#### Label (`label`) - Annotation

- **Creation**: `new()` - Create labels at coordinates
- **Getters**: `get_x()`, `get_y()`, `get_text()`
- **Setters**: `set_xy()`, `set_text()`, `set_color()`, `set_style()`, etc.
- **Operations**: `copy()`, `delete()`

#### Linefill (`linefill`) - Annotation

- **Creation**: `new()` - Fill between two lines
- **Getters**: `get_line1()`, `get_line2()`
- **Setters**: `set_color()`
- **Operations**: `delete()`

## API Documentation

### ta.sma(source, length)

Simple Moving Average

```typescript
ta.sma(source: series_float, length: simple_int): series_float
```

**Parameters:**
- `source` - Source series (e.g., close prices)
- `length` - Number of bars to average

**Returns:** Series of SMA values

### ta.ema(source, length)

Exponential Moving Average

```typescript
ta.ema(source: series_float, length: simple_int): series_float
```

### ta.rsi(source, length)

Relative Strength Index

```typescript
ta.rsi(source: series_float, length: simple_int): series_float
```

### ta.macd(source, fastLength, slowLength, signalLength)

Moving Average Convergence Divergence

```typescript
ta.macd(
  source: series_float,
  fastLength: simple_int,
  slowLength: simple_int,
  signalLength: simple_int
): [series_float, series_float, series_float]
```

**Returns:** `[macdLine, signalLine, histogram]`

### ta.bb(source, length, mult)

Bollinger Bands

```typescript
ta.bb(
  source: series_float,
  length: simple_int,
  mult: simple_float
): [series_float, series_float, series_float]
```

**Returns:** `[basis, upper, lower]`

## Examples

See the `/examples` directory for complete examples:

- `basic-indicators.ts` - Basic indicator calculations
- `strategy-example.ts` - Trading strategy implementation
- `custom-indicator.ts` - Building custom indicators

## Type System

OakScriptJS uses TypeScript types that mirror PineScript's type system:

```typescript
type int = number;
type float = number;
type bool = boolean;
type series<T> = T[];
type series_float = series<float>;
type series_bool = series<bool>;
```

## Development

### Setup

```bash
npm install
```

### Build

```bash
npm run build
```

### Test

```bash
npm test
npm run test:watch
npm run test:coverage
```

### Lint

```bash
npm run lint
npm run lint:fix
```

### Format

```bash
npm run format
npm run format:check
```

## Project Structure

```
oakscriptjs/
├── src/
│   ├── ta/          # Technical analysis functions
│   ├── math/        # Mathematical functions
│   ├── array/       # Array operations
│   ├── str/         # String operations
│   ├── color/       # Color functions
│   ├── types/       # Type definitions
│   ├── utils/       # Internal utilities
│   └── index.ts     # Main entry point
├── tests/           # Test files
├── examples/        # Usage examples
└── dist/           # Built output
```

## Roadmap

**Included Namespaces:**
- [ ] Complete `matrix` namespace implementation
- [ ] Complete `time` namespace implementation
- [x] `ta` namespace - Core indicators implemented
- [x] `math` namespace - Complete
- [x] `array` namespace - Complete
- [x] `str` namespace - Complete
- [x] `color` namespace - Complete
- [x] **`line`, `box`, `label`, `linefill`** - Drawing objects (computational features only)

**Improvements:**
- [ ] Performance benchmarks
- [ ] Comprehensive documentation site
- [ ] Additional technical indicators
- [ ] More test coverage

**Explicitly Excluded** (require external infrastructure):
- ❌ `plot`, `table` - Rendering functions
- ❌ `input` - UI controls
- ❌ `strategy` - Strategy execution engine
- ❌ `request` - Data fetching
- ❌ `alert`, `alertcondition` - Alert system

## Contributing

Contributions are welcome! Please ensure:

1. Maintain exact PineScript API signatures
2. Add tests for new functionality
3. Follow the existing code style
4. Update documentation

## License

MIT

## Acknowledgments

This library is inspired by TradingView's PineScript language. It is not affiliated with or endorsed by TradingView.