@luxalgo/vela-pinets 0.2.1

package/dist/index.d.cts

@@ -0,0 +1,93 @@
+import { ScriptingEngine, EngineCapabilities, PreparedScript, ExecutionRequest, ExecutionHandlers, ExecutionSession } from '@luxalgo/vela/plugin';
+
+/**
+ * The in-process PineTS implementation of `ScriptingEngine`. Both the static run
+ * and the live stream go through the shared `runtime` — the same code the
+ * worker-backed `PineWorkerEngine` runs — so this class is just the in-process
+ * wiring to the port. Vela owns market data and passes bars into `execute`;
+ * this engine never fetches.
+ */
+declare class PineEngine implements ScriptingEngine {
+    readonly language = "pine";
+    readonly capabilities: EngineCapabilities;
+    prepare(source: string, instanceId: string): Promise<PreparedScript>;
+    execute(req: ExecutionRequest, handlers: ExecutionHandlers): ExecutionSession;
+}
+
+/** Minimal Worker surface the proxy needs — the real `Worker` satisfies it; tests inject a fake. */
+interface WorkerLike {
+    postMessage(message: unknown): void;
+    addEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+    terminate(): void;
+}
+
+interface PineWorkerOptions {
+    /**
+     * Override the worker source. By default the worker is inlined into the bundle
+     * and spawned from a Blob URL (no separate file, no URL to configure); set this
+     * to load a hosted worker file instead — e.g. under a CSP that blocks `blob:`.
+     */
+    workerUrl?: string;
+    /** Worker factory — tests inject a fake; defaults to the inlined Blob worker. */
+    createWorker?: () => WorkerLike;
+}
+/**
+ * A worker-backed PineTS engine: identical Pine semantics to `PineEngine`, but the
+ * transpile + execution run on a Web Worker, keeping the main thread responsive.
+ * Implements the same `ScriptingEngine` port, so the orchestrator never learns a
+ * worker exists. Secondary fetches (request.security) round-trip back to the main
+ * thread, where the cache + network live.
+ *
+ * Live charts stream: the worker holds ONE persistent PineTS streaming context per
+ * live session, so a tick ships only the forming bar (a tiny `bars` delta) and the
+ * script re-executes incrementally — never a full snapshot + full re-run per tick.
+ * Static sessions (non-live charts, viewport-dependent scripts) run per poke with
+ * the pending-run coalescing below; live messages NEVER enter that bookkeeping —
+ * a live session acks nothing, so counting it would jam the coalescing forever.
+ */
+declare class PineWorkerEngine implements ScriptingEngine {
+    readonly language = "pine";
+    readonly capabilities: EngineCapabilities;
+    private worker;
+    private readonly spawn;
+    private readonly prepares;
+    private readonly sessions;
+    private reqId;
+    private readonly contextWaits;
+    private sessionId;
+    constructor(opts?: PineWorkerOptions);
+    prepare(source: string, instanceId: string): Promise<PreparedScript>;
+    execute(req: ExecutionRequest, handlers: ExecutionHandlers): ExecutionSession;
+    /**
+     * Coalesced bar-change notification: shipping a full bars snapshot + a complete re-run per
+     * tick is wasteful when ticks burst (a gap heal, a fast market) — while ANY run is in flight
+     * for the session, just mark it dirty and re-run ONCE (with a fresh snapshot) when the run
+     * lands. The worker can't read the live bars array, hence the snapshot per posted run.
+     *
+     * `'backfill'` notifications never cross to the worker at all: every posted run ships a
+     * FRESH full snapshot anyway, so intermediate partial-history snapshots buy nothing — the
+     * worker sees the deepened history on the `'complete'` (or next tick) run. This also keeps
+     * the pending-run bookkeeping honest (a posted-but-skipped run would jam the coalescing).
+     */
+    private notifyBars;
+    /** Post a message that triggers exactly one worker run (acked by one `done`/`error`). */
+    private postRun;
+    /** A worker run finished (`done` or `error`): flush a coalesced bar notification, if any. */
+    private runFinished;
+    /** Terminate the worker (no port hook calls this yet; exposed for host cleanup). */
+    terminate(): void;
+    private barsOf;
+    private workerInstance;
+    private post;
+    private onMessage;
+    /**
+     * Answer a worker's secondary-fetch request via the orchestrator's gateway. Any
+     * live session's `fetchSeries` works — they all route to the same chart-level
+     * cache-backed gateway (same provider, neutral by (symbol, timeframe)).
+     */
+    private serveFetch;
+}
+
+export { PineEngine, PineWorkerEngine, type PineWorkerOptions };

package/dist/index.d.ts

@@ -0,0 +1,93 @@
+import { ScriptingEngine, EngineCapabilities, PreparedScript, ExecutionRequest, ExecutionHandlers, ExecutionSession } from '@luxalgo/vela/plugin';
+
+/**
+ * The in-process PineTS implementation of `ScriptingEngine`. Both the static run
+ * and the live stream go through the shared `runtime` — the same code the
+ * worker-backed `PineWorkerEngine` runs — so this class is just the in-process
+ * wiring to the port. Vela owns market data and passes bars into `execute`;
+ * this engine never fetches.
+ */
+declare class PineEngine implements ScriptingEngine {
+    readonly language = "pine";
+    readonly capabilities: EngineCapabilities;
+    prepare(source: string, instanceId: string): Promise<PreparedScript>;
+    execute(req: ExecutionRequest, handlers: ExecutionHandlers): ExecutionSession;
+}
+
+/** Minimal Worker surface the proxy needs — the real `Worker` satisfies it; tests inject a fake. */
+interface WorkerLike {
+    postMessage(message: unknown): void;
+    addEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+    terminate(): void;
+}
+
+interface PineWorkerOptions {
+    /**
+     * Override the worker source. By default the worker is inlined into the bundle
+     * and spawned from a Blob URL (no separate file, no URL to configure); set this
+     * to load a hosted worker file instead — e.g. under a CSP that blocks `blob:`.
+     */
+    workerUrl?: string;
+    /** Worker factory — tests inject a fake; defaults to the inlined Blob worker. */
+    createWorker?: () => WorkerLike;
+}
+/**
+ * A worker-backed PineTS engine: identical Pine semantics to `PineEngine`, but the
+ * transpile + execution run on a Web Worker, keeping the main thread responsive.
+ * Implements the same `ScriptingEngine` port, so the orchestrator never learns a
+ * worker exists. Secondary fetches (request.security) round-trip back to the main
+ * thread, where the cache + network live.
+ *
+ * Live charts stream: the worker holds ONE persistent PineTS streaming context per
+ * live session, so a tick ships only the forming bar (a tiny `bars` delta) and the
+ * script re-executes incrementally — never a full snapshot + full re-run per tick.
+ * Static sessions (non-live charts, viewport-dependent scripts) run per poke with
+ * the pending-run coalescing below; live messages NEVER enter that bookkeeping —
+ * a live session acks nothing, so counting it would jam the coalescing forever.
+ */
+declare class PineWorkerEngine implements ScriptingEngine {
+    readonly language = "pine";
+    readonly capabilities: EngineCapabilities;
+    private worker;
+    private readonly spawn;
+    private readonly prepares;
+    private readonly sessions;
+    private reqId;
+    private readonly contextWaits;
+    private sessionId;
+    constructor(opts?: PineWorkerOptions);
+    prepare(source: string, instanceId: string): Promise<PreparedScript>;
+    execute(req: ExecutionRequest, handlers: ExecutionHandlers): ExecutionSession;
+    /**
+     * Coalesced bar-change notification: shipping a full bars snapshot + a complete re-run per
+     * tick is wasteful when ticks burst (a gap heal, a fast market) — while ANY run is in flight
+     * for the session, just mark it dirty and re-run ONCE (with a fresh snapshot) when the run
+     * lands. The worker can't read the live bars array, hence the snapshot per posted run.
+     *
+     * `'backfill'` notifications never cross to the worker at all: every posted run ships a
+     * FRESH full snapshot anyway, so intermediate partial-history snapshots buy nothing — the
+     * worker sees the deepened history on the `'complete'` (or next tick) run. This also keeps
+     * the pending-run bookkeeping honest (a posted-but-skipped run would jam the coalescing).
+     */
+    private notifyBars;
+    /** Post a message that triggers exactly one worker run (acked by one `done`/`error`). */
+    private postRun;
+    /** A worker run finished (`done` or `error`): flush a coalesced bar notification, if any. */
+    private runFinished;
+    /** Terminate the worker (no port hook calls this yet; exposed for host cleanup). */
+    terminate(): void;
+    private barsOf;
+    private workerInstance;
+    private post;
+    private onMessage;
+    /**
+     * Answer a worker's secondary-fetch request via the orchestrator's gateway. Any
+     * live session's `fetchSeries` works — they all route to the same chart-level
+     * cache-backed gateway (same provider, neutral by (symbol, timeframe)).
+     */
+    private serveFetch;
+}
+
+export { PineEngine, PineWorkerEngine, type PineWorkerOptions };