pinets 0.9.19 → 0.9.20

package/dist/types/Context.class.d.ts

@@ -36,6 +36,10 @@ export declare class Context {
     }[];
     /** Alert mode: 'realtime' = only fire on live bars (TV behavior), 'all' = fire on every bar (backtest). */
     _alertMode: 'realtime' | 'all';
+    /** Name-keyed map of declaration-prop overrides from `Indicator.prop`. Layered on top of
+     *  the source's `indicator()`/`strategy()` call args inside the per-bar handlers
+     *  (see Core.indicator and initializeStrategy). Empty object when no overrides are set. */
+    _propOverrides: Record<string, unknown>;
     /** Monotonically increasing counter, incremented each time a bar starts executing.
      *  Used by alertcondition/AlertHelper to detect re-execution of the same bar. */
     _execTick: number;

package/dist/types/Indicator/Indicator.class.d.ts

@@ -0,0 +1,100 @@
+import type { IPineInput, IPineProp, PreparedScript } from './types';
+/**
+ * The single owner of every per-script artifact. Holds the source, lazily
+ * transpiles + scans inputs on first `prepare()`, and caches the result so
+ * the same Indicator instance can be passed to multiple `pine.run()` calls
+ * without re-transpiling.
+ *
+ * Roles:
+ *   - `source`            — the original Pine string or JS callback.
+ *   - `input`             — live, title-keyed view of input values. Read or
+ *                            mutate per key; the container itself is frozen.
+ *   - `inputs`            — LEGACY title-keyed override map (constructor
+ *                            arg). Kept for back-compat; merged into the
+ *                            prepared inputs by `prepare()`.
+ *   - `prepare(opts?)`    — idempotent: transpiles, scans inputs, runs
+ *                            visible-range static analysis. Caches result.
+ *   - `usesVisibleRange()`— derived from the cached prepare() result.
+ *
+ * For JS-function source the AST scan returns `[]`, so `input` is empty and
+ * per-key writes throw "unknown title". The legacy `inputs` field still
+ * works for that path.
+ */
+export declare class Indicator {
+    readonly source: Function | string;
+    inputs: Record<string, unknown>;
+    readonly input: Record<string, unknown>;
+    readonly prop: Record<string, unknown>;
+    private _prepared;
+    private _inputMeta;
+    private _inputValues;
+    private _explicitOverrides;
+    private _inputProxy;
+    private _propMeta;
+    private _propValues;
+    private _propProxy;
+    private _declarationType;
+    private _sourcePropArgs;
+    private _explicitPropOverrides;
+    constructor(source: Function | string, inputs?: Record<string, unknown>);
+    /**
+     * Normalize ANY accepted run() argument into an Indicator. Raw functions
+     * and strings get wrapped in a throwaway Indicator; existing Indicators
+     * pass through. This is the single entry point used by PineTS's run /
+     * stream / update so the rest of the engine only deals with Indicators.
+     */
+    static from(arg: Indicator | Function | string): Indicator;
+    /**
+     * Idempotent transpile + scan + viewport detection. The result is cached
+     * on the instance, so passing the same Indicator to multiple `pine.run()`
+     * calls produces a single transpilation pass.
+     *
+     * NB: cache is keyed by *instance identity*, not by options. If you need
+     * different debug settings, create a new Indicator.
+     */
+    prepare(opts?: {
+        debug?: boolean;
+        ln?: boolean;
+    }): PreparedScript;
+    /** True iff the script references any built-in in `VIEWPORT_DEPENDENT_BUILTINS`. */
+    usesVisibleRange(): boolean;
+    /**
+     * Title-keyed input map used by the runtime (read by
+     * `input.utils.resolveInput`). Composed at call time so live mutations
+     * to `.input` between `pine.run()` calls are picked up automatically.
+     *
+     * Precedence:
+     *   1. Legacy constructor `inputs`            (back-compat)
+     *   2. Explicit writes to `.input[...]`       (new API; takes priority)
+     *
+     * Defaults are NOT included — the runtime falls back to `defval` when a
+     * title is absent.
+     */
+    getRuntimeInputs(): Record<string, unknown>;
+    /**
+     * AST-parsed input metadata. Lazy. Empty array for JS-function source.
+     */
+    getInputsMeta(): IPineInput[];
+    /**
+     * Schema metadata for declaration props applicable to this script's type.
+     * Includes non-mutable entries (`title`, `shorttitle`) for completeness —
+     * UI builders can render them; writes to those keys via `.prop` still throw.
+     */
+    getPropsMeta(): IPineProp[];
+    /**
+     * Name-keyed map of user-overridden props for the runtime to merge on top
+     * of the source-code's indicator()/strategy() call args. Only explicit
+     * writes via `.prop` are included — source-code values flow through the
+     * normal Pine call path.
+     */
+    getRuntimePropOverrides(): Record<string, unknown>;
+    /**
+     * Detected declaration type, or null if the source code has neither call.
+     * `.prop` falls back to the indicator schema in the null case.
+     */
+    getDeclarationType(): 'indicator' | 'strategy' | null;
+    private _ensureInputsScanned;
+    private _getInputProxy;
+    private _ensurePropsScanned;
+    private _getPropProxy;
+}

package/dist/types/Indicator/inputProxy.d.ts

@@ -0,0 +1,14 @@
+import type { IPineInput } from './types';
+/**
+ * Build the live `.input` view exposed on an `Indicator` instance.
+ * Title-keyed; entries without an explicit `title=` on the Pine source are
+ * excluded (Pine's runtime keys overrides by title, so a title-less input is
+ * not overridable).
+ *
+ * Backing machinery lives in `keyedProxy.ts` and is shared with `.prop`.
+ */
+export declare function buildInputProxy(metas: IPineInput[], onSet?: (title: string) => void): {
+    proxy: Record<string, unknown>;
+    values: Record<string, unknown>;
+    metaByTitle: Map<string, IPineInput>;
+};

package/dist/types/Indicator/keyedProxy.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Generic title/name-keyed Proxy with per-key validation. Shared backend for
+ * both `Indicator.input` (keyed by input title) and `Indicator.prop` (keyed
+ * by declaration arg name).
+ *
+ * Contract:
+ *   - Read:    returns current value (default OR user-overridden) at the key.
+ *   - Write:   validates against the entry's meta — type, options, minval,
+ *              maxval — and stores the override. Invalid writes THROW with
+ *              a tailored message.
+ *   - Delete:  throws.
+ *   - Unknown key write: throws, listing the known keys.
+ *   - Object.keys() / spread / console.log show real keys with current values.
+ */
+export type KeyedType = 'int' | 'float' | 'bool' | 'string' | 'source' | 'color' | 'enum' | 'price' | 'time' | 'session' | 'symbol' | 'timeframe' | 'text_area';
+export interface KeyedSchemaEntry {
+    key: string;
+    type: KeyedType;
+    defval: unknown;
+    options?: unknown[];
+    minval?: number;
+    maxval?: number;
+}
+export interface BuildKeyedProxyResult {
+    proxy: Record<string, unknown>;
+    values: Record<string, unknown>;
+    entryByKey: Map<string, KeyedSchemaEntry>;
+}
+/**
+ * Build a keyed proxy view.
+ *
+ * @param entries  schema entries — defaults seeded into `values`
+ * @param label    display label for error messages, e.g. 'Indicator.input' or 'Indicator.prop'
+ * @param onSet    optional callback fired after a successful write (for explicit-override tracking)
+ * @param seedValues  optional initial values overriding entry defvals (used by .prop to seed
+ *                    source-code defaults on top of spec defaults)
+ * @param keyNoun  noun for the unknown-key message, defaults to 'key'. Inputs use 'input title'.
+ */
+export declare function buildKeyedProxy(entries: KeyedSchemaEntry[], label: string, onSet?: (key: string) => void, seedValues?: Record<string, unknown>, keyNoun?: string): BuildKeyedProxyResult;
+/**
+ * Per-entry write validation. Throws on any rule violation.
+ */
+export declare function validate(entry: KeyedSchemaEntry, value: unknown, label: string): void;

package/dist/types/Indicator/propProxy.d.ts

@@ -0,0 +1,16 @@
+import type { IPineProp } from './types';
+/**
+ * Build the live `.prop` view exposed on an `Indicator` instance.
+ * Name-keyed; non-mutable entries (`title`, `shorttitle`) are excluded.
+ *
+ * `sourceArgs` seeds source-code defaults on top of spec defaults so the
+ * read view matches what TradingView's runtime would see before any user
+ * override. Layer order: spec.defval ← sourceArgs ← user `.prop` writes.
+ *
+ * Backing machinery lives in `keyedProxy.ts` and is shared with `.input`.
+ */
+export declare function buildPropProxy(props: IPineProp[], sourceArgs: Record<string, unknown>, onSet?: (name: string) => void): {
+    proxy: Record<string, unknown>;
+    values: Record<string, unknown>;
+    propByName: Map<string, IPineProp>;
+};

package/dist/types/Indicator/propsSchema.d.ts

@@ -0,0 +1,8 @@
+import type { IPineProp } from './types';
+export declare const INDICATOR_PROPS: IPineProp[];
+export declare const STRATEGY_PROPS: IPineProp[];
+/**
+ * Pick the right schema for a detected declaration type. Returns the
+ * indicator schema when type is unknown (sensible fallback per spec).
+ */
+export declare function propsForDeclaration(type: 'indicator' | 'strategy' | null): IPineProp[];

package/dist/types/Indicator/scanDeclaration.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Detect whether a script is a `strategy()` or `indicator()`, and extract
+ * the actual values passed to that call from source so they can seed
+ * `.prop` defaults.
+ *
+ * Both source kinds are handled:
+ *   - Pine string  → pineToJS() AST → walk for the top-level CallExpression
+ *   - JS function  → acorn.parse(fn.toString()) → walk for CallExpression with
+ *                    callee Identifier matching 'indicator' / 'strategy'
+ *
+ * Enum-typed args are resolved by the "rightmost-identifier rule": for any
+ * `MemberExpression` the rightmost `Identifier` name is the runtime string.
+ * Holds for every Pine-namespace constant accepted by indicator()/strategy()
+ * (format.percent → "percent", currency.USD → "USD",
+ *  strategy.percent_of_equity → "percent_of_equity",
+ *  strategy.commission.percent → "percent").
+ *
+ * Returns `{ type, args }`:
+ *   - type   = 'indicator' | 'strategy' | null
+ *   - args   = name → resolved value extracted from the source call
+ *
+ * If the declaration call isn't found, returns `{ type: null, args: {} }`.
+ * The Indicator class falls back to the indicator schema in that case.
+ */
+export interface ScannedDeclaration {
+    type: 'indicator' | 'strategy' | null;
+    args: Record<string, unknown>;
+}
+export declare function scanDeclaration(source: unknown): ScannedDeclaration;

package/dist/types/Indicator/scanInputs.d.ts

@@ -0,0 +1,5 @@
+import type { IPineInput } from './types';
+/**
+ * Public entry point. Returns `[]` for invalid Pine or for non-string source.
+ */
+export declare function scanInputs(source: unknown): IPineInput[];

package/dist/types/Indicator/types.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Pine Script `input.*` typing classification. Mirrors TradingView's input
+ * widget types 1:1. The bare `input()` wrapper auto-detects from `defval`
+ * and dispatches to one of these — there is no `'auto'` member.
+ *
+ * v6 adds `'enum'`. Everything else exists in both v5 and v6.
+ */
+export type PineInputType = 'int' | 'float' | 'bool' | 'string' | 'source' | 'color' | 'enum' | 'price' | 'time' | 'session' | 'symbol' | 'timeframe' | 'text_area';
+/**
+ * Value of an input's `display=` argument. Stored as the suffix (without the
+ * `display.` prefix), matching what the existing runtime parses into
+ * `InputOptions.display` at the call site.
+ */
+export type PineInputDisplay = 'none' | 'data_window' | 'status_line' | 'all';
+/**
+ * Parsed metadata for a single `input.*` declaration in a Pine script.
+ *
+ * Field presence matches the Pine reference (v6 superset):
+ *   - title, tooltip, group, display, active        — universal (all 14 fns)
+ *   - inline                                         — universal except text_area
+ *   - confirm                                        — universal except bare input()
+ *   - options                                        — enum, float, int, session, string, timeframe
+ *   - minval / maxval / step                         — float, int only
+ *
+ * `defval` is fully resolved at scan time — for enum inputs we resolve
+ * `tz.utc` → "UTC" (the field title) so JS callers see what TradingView's
+ * `str.tostring()` would print, never the AST path.
+ */
+export interface IPineInput {
+    type: PineInputType;
+    defval: unknown;
+    title?: string;
+    tooltip?: string;
+    group?: string;
+    display?: PineInputDisplay;
+    active?: boolean;
+    confirm?: boolean;
+    inline?: string;
+    options?: unknown[];
+    minval?: number;
+    maxval?: number;
+    step?: number;
+}
+/**
+ * Pine Script declaration-arg typing classification (used by `IPineProp`).
+ *
+ * `enum` covers every Pine-namespace constant used as a declaration arg
+ * (e.g. `format.percent`, `currency.USD`, `strategy.percent_of_equity`).
+ * The scanner resolves these to bare strings via the rightmost-identifier
+ * rule, matching what the runtime sees.
+ */
+export type PinePropType = 'string' | 'int' | 'float' | 'bool' | 'enum';
+/**
+ * Schema entry for a single `indicator()` / `strategy()` declaration argument.
+ *
+ * The full set of entries is curated from the Pine v6 reference:
+ *   - https://www.tradingview.com/pine-script-reference/v6/#fun_indicator
+ *   - https://www.tradingview.com/pine-script-reference/v6/#fun_strategy
+ *
+ * `title` and `shorttitle` are present in the schema with `mutable: false`
+ * so UI consumers can render them, but are filtered out of `.prop` writes.
+ *
+ * For enum-typed entries, `options` enumerates the accepted runtime strings.
+ * The schema source file points to the corresponding exported Pine enum
+ * (e.g. `enum format` in Types.ts) so JS callers can import the same source.
+ */
+export interface IPineProp {
+    name: string;
+    type: PinePropType;
+    defval: unknown;
+    options?: unknown[];
+    minval?: number;
+    maxval?: number;
+    mutable: boolean;
+    appliesTo: 'indicator' | 'strategy' | 'both';
+    version?: 5 | 6;
+}
+/**
+ * Result of `Indicator.prepare()`. The single artifact handed to the engine.
+ *
+ * `inputs` is the title-keyed map the runtime already expects — built by
+ * merging each `IPineInput`'s current value (post-user-override) into a
+ * flat `{ [title]: value }` object that `input.utils.resolveInput()` reads.
+ */
+export interface PreparedScript {
+    fn: Function;
+    inputs: Record<string, unknown>;
+    usesVisibleRange: boolean;
+    ltfSlices?: any[];
+}

package/dist/types/Indicator.d.ts

@@ -1,5 +1,3 @@
-export declare class Indicator {
-    source: Function | String;
-    inputs: Record<string, any>;
-    constructor(source: Function | String, inputs?: Record<string, any>);
-}
+export { Indicator } from './Indicator/Indicator.class';
+export { INDICATOR_PROPS, STRATEGY_PROPS, propsForDeclaration } from './Indicator/propsSchema';
+export type { IPineInput, IPineProp, PineInputType, PineInputDisplay, PinePropType, PreparedScript, } from './Indicator/types';

package/dist/types/PineTS.class.d.ts

@@ -28,6 +28,7 @@ export declare class PineTS {
     private _debugSettings;
     private _transpiledCode;
     get transpiledCode(): Function | String;
+    private _currentIndicator;
     private _isSecondaryContext;
     markAsSecondary(): void;
     private _syminfo;
@@ -254,26 +255,6 @@ export declare class PineTS {
      * @private
      */
     private _initializeContext;
-    /**
-     * Transpile the Pine Script code
-     * @private
-     */
-    private _transpileCode;
-    /**
-     * Static analysis on the transpiled function body to detect references to
-     * host-bound built-ins (currently visible-range; extensible via
-     * VIEWPORT_DEPENDENT_BUILTINS). Comments are stripped during pine2js, so
-     * scanning the post-transpile output is comment-safe.
-     *
-     * Why post-transpile (not regex on Pine source): a `chart.left_visible_bar_time`
-     * literal inside a // comment would be a false positive at the source level.
-     * After pine2js, only live code remains.
-     *
-     * Why regex (not AST visitor): `chart` is a reserved namespace in
-     * KNOWN_NAMESPACES — Pine scripts cannot shadow it with a local identifier,
-     * so a whole-word match on `chart.<prop>` is unambiguous.
-     */
-    private _detectViewportUsage;
     /**
      * Execute iterations from startIdx to endIdx, updating the context
      * @private

package/dist/types/index.d.ts

@@ -12,3 +12,5 @@ export type { Kline, PeriodType } from './marketData/types';
 export { computeNextPeriodStart, localTimeToUTC, computeSessionClose, TIMEFRAME_SECONDS, TIMEFRAME_PERIOD_INFO } from './marketData/types';
 export { aggregateCandles, selectSubTimeframe, getAggregationRatio } from './marketData/aggregation';
 export { PineTS, Context, Provider, Indicator, PineRuntimeError };
+export type { IPineInput, IPineProp, PineInputType, PineInputDisplay, PinePropType, PreparedScript } from './Indicator';
+export { INDICATOR_PROPS, STRATEGY_PROPS, propsForDeclaration } from './Indicator';

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pinets",
-    "version": "0.9.19",
+    "version": "0.9.20",
     "description": "Run Pine Script anywhere. PineTS is an open-source transpiler and runtime that brings Pine Script logic to Node.js and the browser with 1:1 syntax compatibility. Reliably write, port, and run indicators or strategies on your own infrastructure.",
     "keywords": [
         "Pine Script",