Add : PineTS.stream() method, an event driven wrapper of PineTS.run to simplify handling live data

Critical fix : live data processing was producing wrong values in ta.* functions due to wrong handling of current vs committed candles

Author: alaa-eddine

README.md

@@ -71,6 +71,33 @@ npm install pinets
 
 ## Usage Examples
 
+### Streaming Data
+
+PineTS provides a convenient event-based interface for streaming live data:
+
+```javascript
+import { PineTS, Provider } from 'pinets';
+
+const pineTS = new PineTS(Provider.Binance, 'BTCUSDT', '1m');
+
+// Start streaming with 1 second interval
+const evt = pineTS.stream(
+    indicator,
+    //assuming that indicator is a pine source code or pineTS function
+    {
+        pageSize: 10,
+        live: true,
+        interval: 1000,
+    }
+);
+
+evt.on('data', (ctx) => {
+    console.log('Update:', ctx.result.close);
+});
+
+// See documentation for full details
+```
+
 ### Option 1: Run Native Pine Script Directly _(Experimental)_
 
 Starting with v0.7.0, you can run original Pine Script code directly:

docs/getting-started.md

@@ -127,44 +127,50 @@ const { result } = await pineTS.run((context) => {
 });
 ```
 
-## Using Pagination for Large Datasets
+## Streaming Data and Pagination
 
-For processing large datasets efficiently or streaming live market data, use pagination:
+For processing large datasets efficiently or handling live data streams, use the `stream()` method:
 
 ```javascript
 import { PineTS, Provider } from 'pinets';
 
-// Initialize with a provider for live streaming capability
-const pineTS = new PineTS(Provider.Binance, 'BTCUSDT', '1h');
+// Initialize with a provider
+const pineTS = new PineTS(Provider.Binance, 'BTCUSDT', '1m', 100);
 
-// Process 200 candles in pages of 50
-const iterator = pineTS.run(
+// Start streaming
+const evt = pineTS.stream(
     (context) => {
-        const ta = context.ta;
         const { close } = context.data;
-
-        const sma = ta.sma(close, 20);
-        return { sma };
+        const sma = context.ta.sma(close, 14);
+        return { close, sma };
     },
-    200,
-    50
+    {
+        pageSize: 50, // Process in chunks of 50
+        live: true, // Continue with live data
+        interval: 2000, // Poll every 2 seconds
+    }
 );
 
-// Process each page as it becomes available
-for await (const page of iterator) {
-    console.log(`Received ${page.result.sma.length} results`);
-    // With a provider and no end date, automatically continues with live data
-}
+// Listen for updates
+evt.on('data', (ctx) => {
+    const { close, sma } = ctx.result;
+    console.log(`Update: Close=${close[close.length - 1]}, SMA=${sma[sma.length - 1]}`);
+});
+
+evt.on('error', (err) => console.error(err));
+
+// To stop streaming later
+// evt.stop();
 ```
 
 **Benefits:**
 
 -   Memory efficient for large datasets
--   Shows progress during processing
--   Automatically streams live market data when using a provider
+-   Event-based interface is easier to integrate
+-   Automatically streams live market data
 -   Perfect for real-time trading bots and dashboards
 
-📖 **For complete pagination documentation and advanced examples, see [Pagination & Live Streaming](../pagination/).**
+📖 **For complete pagination and streaming documentation, see [Pagination & Live Streaming](../pagination/).**
 
 ## Key Differences: PineTS Syntax vs Native Pine Script
 

docs/initialization-and-usage.md

@@ -15,6 +15,7 @@ This guide explains how to initialize PineTS and run indicators or strategies wi
 -   [PineTS Constructor](#pinets-constructor)
 -   [Initialization Options](#initialization-options)
 -   [The run() Method](#the-run-method)
+-   [The stream() Method](#the-stream-method)
 -   [Context Object](#context-object)
 -   [Return Values](#return-values)
 -   [Complete Examples](#complete-examples)
@@ -281,6 +282,56 @@ Returns a `Promise<Context>` object containing:
 
 ---
 
+## The stream() Method
+
+The `stream()` method provides an event-based interface for handling live data streams, making it easy to integrate with real-time applications.
+
+### Syntax
+
+```typescript
+const evt = pineTS.stream(
+    pineTSCode: Function | String,
+    options?: {
+        pageSize?: number,
+        live?: boolean,
+        interval?: number
+    }
+);
+```
+
+### Options
+
+| Option     | Type      | Default           | Description                                                                                    |
+| ---------- | --------- | ----------------- | ---------------------------------------------------------------------------------------------- |
+| `pageSize` | `number`  | `undefined` (all) | Number of bars per chunk. If not specified, processes all available historical data in one go. |
+| `live`     | `boolean` | `true`            | Whether to continue fetching live data after processing historical data.                       |
+| `interval` | `number`  | `1000`            | Polling interval in milliseconds for live data.                                                |
+
+### Usage
+
+The method returns an object with `on()` and `stop()` methods:
+
+```typescript
+// Start streaming
+const evt = pineTS.stream(indicator, { pageSize: 1, live: true, interval: 2000 });
+
+// Handle data updates
+evt.on('data', (context) => {
+    // Process new data
+    console.log('New data:', context.result);
+});
+
+// Handle errors
+evt.on('error', (error) => {
+    console.error('Stream error:', error);
+});
+
+// Stop streaming
+// evt.stop();
+```
+
+---
+
 ## Context Object
 
 The context object is passed to your indicator function and contains all the data and utilities needed for calculations.