oakscriptjs 0.8.1 → 0.9.0

package/dist/esm/runtime/series.d.ts

@@ -0,0 +1,362 @@
+/**
+ * @fileoverview Simplified Series class for lazy time-series computation
+ * Represents a time-series of values with lazy evaluation
+ * @module runtime/series
+ */
+import type { Bar } from '../types/index.js';
+/**
+ * Function that computes a value for each bar
+ */
+export type SeriesExtractor = (bar: Bar, index: number, data: Bar[]) => number;
+/**
+ * BarData - Versioned wrapper around Bar[] array for cache invalidation
+ *
+ * This class wraps a Bar[] array and tracks a version number that increments
+ * whenever the data is mutated. Series objects reference this to detect when
+ * their cached values need to be recomputed.
+ *
+ * @example
+ * ```typescript
+ * const barData = new BarData(bars);
+ * const close = Series.fromBars(barData, 'close');
+ * const values1 = close.toArray(); // Computes and caches
+ *
+ * barData.push(newBar); // Increments version
+ * const values2 = close.toArray(); // Detects stale cache, recomputes
+ * ```
+ */
+export declare class BarData {
+    private _bars;
+    private _version;
+    /**
+     * Create a new BarData wrapper
+     * @param bars - Initial bar data (defaults to empty array)
+     */
+    constructor(bars?: Bar[]);
+    /**
+     * Get the current version number
+     * Version increments whenever data is mutated
+     */
+    get version(): number;
+    /**
+     * Get the underlying bar array
+     * Note: Direct mutations to this array will NOT increment version
+     * Use the provided mutation methods instead
+     */
+    get bars(): Bar[];
+    /**
+     * Get the number of bars
+     */
+    get length(): number;
+    /**
+     * Add a new bar to the end
+     * @param bar - Bar to add
+     */
+    push(bar: Bar): void;
+    /**
+     * Remove and return the last bar
+     * @returns The removed bar, or undefined if empty
+     */
+    pop(): Bar | undefined;
+    /**
+     * Replace a bar at a specific index
+     * @param index - Index to update
+     * @param bar - New bar data
+     */
+    set(index: number, bar: Bar): void;
+    /**
+     * Update the last bar (useful for real-time/streaming updates)
+     * @param bar - New bar data
+     */
+    updateLast(bar: Bar): void;
+    /**
+     * Replace all bars with new data
+     * @param bars - New bar array
+     */
+    setAll(bars: Bar[]): void;
+    /**
+     * Manually increment version (for advanced use cases)
+     * Call this after direct mutations to the bars array
+     */
+    invalidate(): void;
+    /**
+     * Get a bar at a specific index
+     * @param index - Bar index
+     * @returns Bar at that index, or undefined
+     */
+    at(index: number): Bar | undefined;
+    /**
+     * Create a BarData from an existing Bar array
+     * @param bars - Bar array
+     * @returns New BarData instance
+     */
+    static from(bars: Bar[]): BarData;
+}
+/**
+ * Series - represents a time-series of values with lazy evaluation
+ *
+ * Series are lazy - they don't compute values until needed.
+ * Operations on Series return new Series with composed extractors.
+ *
+ * Now supports automatic cache invalidation via BarData versioning
+ * and memory-efficient closure chain breaking via materialize().
+ *
+ * @example
+ * ```typescript
+ * // Basic usage (backward compatible)
+ * const close = Series.fromBars(bars, 'close');
+ * const open = Series.fromBars(bars, 'open');
+ * const range = close.sub(open);  // Creates new Series, doesn't compute yet
+ * const values = range.toArray(); // Now computes for all bars
+ *
+ * // With automatic cache invalidation
+ * const barData = new BarData(bars);
+ * const close = Series.fromBars(barData, 'close');
+ * const values1 = close.toArray(); // Computes and caches
+ * barData.push(newBar); // Version increments
+ * const values2 = close.toArray(); // Detects stale cache, recomputes
+ *
+ * // Breaking closure chains for memory efficiency
+ * const complex = a.add(b).mul(c).div(d).sub(e);
+ * const materialized = complex.materialize(); // Breaks closure chain
+ * ```
+ */
+export declare class Series {
+    private extractor;
+    private dataSource;
+    private cached;
+    private cachedVersion;
+    /**
+     * Create a new Series
+     *
+     * @param data - Bar data (Bar[] or BarData)
+     * @param extractor - Function to extract/compute value for each bar
+     */
+    constructor(data: Bar[] | BarData, extractor: SeriesExtractor);
+    /**
+     * Get the underlying bar data
+     * @returns Bar array
+     */
+    get bars(): Bar[];
+    /**
+     * Get the underlying BarData source
+     * @returns BarData instance
+     */
+    get barData(): BarData;
+    /**
+     * Create Series from bar data by extracting a specific field
+     * @param bars - Bar data (Bar[] or BarData)
+     * @param field - Field to extract ('open', 'high', 'low', 'close', 'volume')
+     * @returns Series with extracted field values
+     */
+    static fromBars(bars: Bar[] | BarData, field: 'open' | 'high' | 'low' | 'close' | 'volume'): Series;
+    /**
+     * Create a constant series (same value for all bars)
+     * @param bars - Bar data (Bar[] or BarData)
+     * @param value - Constant value
+     * @returns Series with constant value
+     */
+    static constant(bars: Bar[] | BarData, value: number): Series;
+    /**
+     * Create series from array of values
+     * @param bars - Bar data (Bar[] or BarData) for time alignment
+     * @param values - Array of values
+     * @returns Series
+     * @throws When read on other bars with a different length than `values` (e.g. a series computed on the
+     *   chart bars and read inside a `request.security` expression, which runs on the higher-timeframe bars)
+     */
+    static fromArray(bars: Bar[] | BarData, values: number[]): Series;
+    /**
+     * Add two series or a series and a number
+     * @param other - Series or number to add
+     * @returns New Series representing the sum
+     */
+    add(other: Series | number): Series;
+    /**
+     * Subtract two series or subtract a number from a series
+     * @param other - Series or number to subtract
+     * @returns New Series representing the difference
+     */
+    sub(other: Series | number): Series;
+    /**
+     * Multiply two series or a series by a number
+     * @param other - Series or number to multiply
+     * @returns New Series representing the product
+     */
+    mul(other: Series | number): Series;
+    /**
+     * Raise the series to a power (PineScript math.pow on a series)
+     * @param exponent - Series or number exponent
+     * @returns New Series representing base ** exponent
+     */
+    pow(exponent: Series | number): Series;
+    /**
+     * Divide two series or a series by a number
+     * @param other - Series or number to divide by
+     * @returns New Series representing the quotient
+     */
+    div(other: Series | number): Series;
+    /**
+     * Modulo operation
+     * @param other - Series or number for modulo
+     * @returns New Series representing the remainder
+     */
+    mod(other: Series | number): Series;
+    /**
+     * Negation
+     * @returns New Series with negated values
+     */
+    neg(): Series;
+    /**
+     * Greater than comparison
+     * @param other - Series or number to compare
+     * @returns New Series with 1 where true, 0 where false
+     */
+    gt(other: Series | number): Series;
+    /**
+     * Greater than or equal comparison
+     * @param other - Series or number to compare
+     * @returns New Series with 1 where true, 0 where false
+     */
+    gte(other: Series | number): Series;
+    /**
+     * Less than comparison
+     * @param other - Series or number to compare
+     * @returns New Series with 1 where true, 0 where false
+     */
+    lt(other: Series | number): Series;
+    /**
+     * Less than or equal comparison
+     * @param other - Series or number to compare
+     * @returns New Series with 1 where true, 0 where false
+     */
+    lte(other: Series | number): Series;
+    /**
+     * Equality comparison
+     * @param other - Series or number to compare
+     * @returns New Series with 1 where true, 0 where false
+     */
+    eq(other: Series | number): Series;
+    /**
+     * Not equal comparison
+     * @param other - Series or number to compare
+     * @returns New Series with 1 where true, 0 where false
+     */
+    neq(other: Series | number): Series;
+    /**
+     * Logical AND
+     * @param other - Series or number (truthy/falsy)
+     * @returns New Series with 1 where both true, 0 otherwise
+     */
+    and(other: Series | number): Series;
+    /**
+     * Logical OR
+     * @param other - Series or number (truthy/falsy)
+     * @returns New Series with 1 where either true, 0 otherwise
+     */
+    or(other: Series | number): Series;
+    /**
+     * Logical NOT
+     * @returns New Series with inverted boolean values
+     */
+    not(): Series;
+    /**
+     * Bar-by-bar conditional selection (ternary operator for Series)
+     * Uses this Series as the condition (truthy = nonzero, falsy = zero/NaN)
+     *
+     * @param trueValue - Value or Series to use when condition is truthy
+     * @param falseValue - Value or Series to use when condition is falsy
+     * @returns New Series with bar-by-bar selected values
+     *
+     * @example
+     * ```typescript
+     * // PineScript: result = condition ? trueVal : falseVal
+     * const result = condition.iff(trueVal, falseVal);
+     *
+     * // Example: RSI formula uses ternary for edge cases
+     * // rsi = down == 0 ? 100 : up == 0 ? 0 : formula
+     * const rsi = down.eq(0).iff(100, up.eq(0).iff(0, formula));
+     * ```
+     */
+    iff(trueValue: Series | number, falseValue: Series | number): Series;
+    /**
+     * Access previous bars (like close[1] in PineScript)
+     * @param offset - Number of bars back (0 or more)
+     * @returns New Series with offset values
+     * @throws RangeError when `offset` is negative
+     */
+    offset(offset: number): Series;
+    /**
+     * Compute all values for the series
+     *
+     * Now includes automatic cache invalidation:
+     * - Checks if dataSource version has changed since cache was computed
+     * - Recomputes if version mismatch detected
+     * - Stores version when cache is created
+     *
+     * @returns Array of computed values
+     */
+    toArray(): number[];
+    /**
+     * Materialize this Series by eagerly computing values and breaking closure chain
+     *
+     * This method addresses the closure chain memory leak issue:
+     * - Computes all values immediately
+     * - Creates a new Series that stores values directly
+     * - Breaks references to parent Series objects
+     * - Useful for complex expressions to free intermediate Series memory
+     *
+     * @example
+     * ```typescript
+     * // Without materialize: keeps a, b, c, d in memory via closures
+     * const result = a.add(b).mul(c).div(d).sub(e);
+     *
+     * // With materialize: breaks chain, frees a, b, c memory
+     * const result = a.add(b).mul(c).materialize().div(d).sub(e);
+     * ```
+     *
+     * @returns New Series with computed values and no closure dependencies
+     */
+    materialize(): Series;
+    /**
+     * Invalidate cache (when data changes)
+     *
+     * Note: With BarData versioning, manual invalidation is rarely needed.
+     * The cache is automatically invalidated when the underlying BarData changes.
+     * This method is kept for backward compatibility and advanced use cases.
+     *
+     * @internal
+     */
+    _invalidate(): void;
+    /**
+     * Compute all values (alias for toArray)
+     * @returns Array of computed values
+     * @internal
+     */
+    _compute(): number[];
+    /**
+     * Get value at specific index
+     * @param index - Bar index
+     * @returns Value at that index
+     */
+    get(index: number): number;
+    /**
+     * Get the last value (most recent bar)
+     * @returns Most recent value
+     */
+    last(): number;
+    /**
+     * Get number of values
+     * @returns Length of series
+     */
+    length(): number;
+    /**
+     * Convert series to time-value pairs for charting
+     * @returns Array of { time, value } objects
+     */
+    toTimeValuePairs(): Array<{
+        time: any;
+        value: number;
+    }>;
+}
+//# sourceMappingURL=series.d.ts.map

package/dist/esm/runtime/series.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"series.d.ts","sourceRoot":"","sources":["../../../src/runtime/series.ts"],"names":[],"mappings":"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"}