Architecture Guide

This section provides a deep dive into the internal architecture of PineTS. It is intended for contributors and developers who need to understand the transpilation pipeline, runtime execution model, and core design decisions to extend or debug the engine.

Overview

PineTS bridges the gap between Pine Script’s unique time-series semantics and standard JavaScript execution through a three-layer architecture:

┌─────────────────────────────────────────────────┐
│          User PineTS Code (Input)           │
│    (Looks like Pine Script, uses JS syntax) │
└────────────────┬────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────┐
│           Transpiler Layer                  │
│  • AST Parsing (acorn)                      │
│  • Scope Analysis                           │
│  • Code Transformation                      │
│  • Context Variable Management              │
└────────────────┬────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────────────┐
│         Runtime Execution Layer             │
│  • Context Object ($)                       │
│  • Series Management                        │
│  • Namespace Functions (ta, math, etc.)     │
│  • State Management                         │
└─────────────────────────────────────────────────┘

Main Components

1. PineTS Class: Orchestrates market data loading, execution, and pagination
2. Context Class: Maintains execution state, series data, and namespaces
3. Transpiler: Transforms PineTS code into executable JavaScript
4. Namespaces: Provide Pine Script functions (ta.ema, math.abs, etc.)

Documentation Structure

Core Architecture

• Transpiler Architecture: Details on AST parsing, scope analysis, and code transformation.
  • Scope Manager: Variable renaming and unique ID generation
  • Transformers: AST transformation logic
  • Real Examples: Actual transpilation output examples
• Runtime Engine: How the Context, Series, and execution loop work.
  • Context Class: The global state object
  • Series Class: Forward storage with reverse access
  • Execution Flow: Run loop and pagination
• Namespaces: Implementation of ta, math, request, etc.
  • Technical Analysis (ta): TA functions implementation
  • Math (math): Mathematical operations
  • Array (array): Array operations
  • Request (request): Multi-timeframe analysis
  • Input (input): User input handling
• Critical Implementation Details: Deep dives into tuple handling, request.security, and other complex features.
  • Tuple Handling: Double bracket convention
  • Request Security: Secondary context architecture

Developer Resources

• Debugging Guide: Practical debugging techniques and common issues
• Best Practices: Common pitfalls and recommended patterns
• Syntax Evolution: Migration from old to new syntax

Key Design Principles

1. Series-First: Everything is a time-series. The Series class is the fundamental data unit.
2. Forward Storage, Reverse Access: Data is stored chronologically (push to end) but accessed with reverse indexing (close[1] is previous).
3. Incremental Calculation: Functions utilize state to calculate values O(1) per bar rather than recalculating history.
4. State Isolation: Unique IDs ensure that multiple calls to the same function maintain separate internal states.

---

Table of contents

• Transpiler
• Runtime
• Namespaces
• Specifics
• Debugging Guide
• Best Practices
• Syntax Evolution