@hoox-sh/pynets 0.1.0

package/src/runtime/provider.ts

@@ -0,0 +1,232 @@
+/**
+ * Copyright (C) 2024-2026 jango_blockchained
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ *
+ * Bar source adapters. Hosts feed OHLCV; this module does not invent
+ * foreign market data. Fetch adapters implement `BarProvider`.
+ */
+
+export interface ProviderBar {
+  open?: number;
+  high?: number;
+  low?: number;
+  close?: number;
+  volume?: number;
+  time?: number;
+}
+
+export interface BarProvider {
+  fetch(opts: {
+    symbol: string;
+    timeframe?: string | null;
+    limit?: number;
+  }): Promise<ProviderBar[]>;
+}
+
+/** HTTP / parse failure from `JsonBarProvider`. Hosts should catch this. */
+export class ProviderError extends Error {
+  readonly status?: number;
+
+  constructor(message: string, status?: number) {
+    super(message);
+    this.name = "ProviderError";
+    this.status = status;
+  }
+}
+
+/** In-memory bars — tests and custom feeds. */
+export class MemoryProvider implements BarProvider {
+  constructor(private readonly bars: ProviderBar[]) {}
+
+  async fetch(opts: { limit?: number }): Promise<ProviderBar[]> {
+    const n = opts.limit;
+    if (n == null || n >= this.bars.length) return this.bars.slice();
+    return this.bars.slice(-n);
+  }
+}
+
+/**
+ * In-process foreign-symbol map. Looks up `symbol` then `symbol:timeframe`.
+ * Missing keys return `[]` — no network, no invented data.
+ */
+export class StaticMapProvider implements BarProvider {
+  constructor(private readonly feeds: Record<string, ProviderBar[]>) {}
+
+  async fetch(opts: {
+    symbol: string;
+    timeframe?: string | null;
+    limit?: number;
+  }): Promise<ProviderBar[]> {
+    const tf = opts.timeframe;
+    const keyed = tf != null && tf !== "" ? `${opts.symbol}:${tf}` : undefined;
+    const bars =
+      (keyed !== undefined ? this.feeds[keyed] : undefined) ??
+      this.feeds[opts.symbol] ??
+      [];
+    return sliceTail(bars, opts.limit);
+  }
+}
+
+export interface JsonBarProviderOptions {
+  /** Build a URL from symbol/timeframe/limit. Required unless `fetchBars` is given. */
+  url?: (opts: {
+    symbol: string;
+    timeframe?: string | null;
+    limit?: number;
+  }) => string;
+  /** Injected fetch (defaults to globalThis.fetch). Tests pass a stub. */
+  fetch?: typeof fetch;
+  /** Map a JSON body to ProviderBar[]. Default: `mapJsonBars`. */
+  map?: (json: unknown) => ProviderBar[];
+  /** Optional extra headers */
+  headers?: Record<string, string>;
+  /** Return a JSON body without HTTP. Used instead of `url` when provided. */
+  fetchBars?: (opts: {
+    symbol: string;
+    timeframe?: string | null;
+    limit?: number;
+  }) => Promise<unknown> | unknown;
+}
+
+/**
+ * Generic JSON/OHLCV adapter. Non-OK HTTP and invalid JSON throw
+ * `ProviderError` so hosts can catch. After a successful response,
+ * empty or unrecognized JSON maps to `[]`.
+ */
+export class JsonBarProvider implements BarProvider {
+  private readonly url?: JsonBarProviderOptions["url"];
+  private readonly fetchImpl: typeof fetch;
+  private readonly mapFn: (json: unknown) => ProviderBar[];
+  private readonly headers?: Record<string, string>;
+  private readonly fetchBars?: JsonBarProviderOptions["fetchBars"];
+
+  constructor(opts: JsonBarProviderOptions) {
+    this.url = opts.url;
+    this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    this.mapFn = opts.map ?? mapJsonBars;
+    this.headers = opts.headers;
+    this.fetchBars = opts.fetchBars;
+  }
+
+  async fetch(opts: {
+    symbol: string;
+    timeframe?: string | null;
+    limit?: number;
+  }): Promise<ProviderBar[]> {
+    const json = this.fetchBars
+      ? await this.fetchBars(opts)
+      : await this.getJson(opts);
+    return sliceTail(this.mapFn(json), opts.limit);
+  }
+
+  private async getJson(opts: {
+    symbol: string;
+    timeframe?: string | null;
+    limit?: number;
+  }): Promise<unknown> {
+    if (this.url == null) {
+      throw new ProviderError("JsonBarProvider requires `url` or `fetchBars`");
+    }
+    const href = this.url(opts);
+    const res = await this.fetchImpl(href, {
+      method: "GET",
+      headers: this.headers,
+    });
+    if (!res.ok) {
+      throw new ProviderError(
+        `HTTP ${res.status}${res.statusText ? ` ${res.statusText}` : ""}`.trim(),
+        res.status,
+      );
+    }
+    try {
+      return await res.json();
+    } catch (err) {
+      const detail = err instanceof Error ? err.message : String(err);
+      throw new ProviderError(`invalid JSON: ${detail}`, res.status);
+    }
+  }
+}
+
+const BAR_KEYS = ["open", "high", "low", "close", "volume", "time"] as const;
+
+/**
+ * Accept arrays of `{open,high,low,close,volume,time}` (or `t/o/h/l/c/v`),
+ * tuples `[time, open, high, low, close, volume, ...]`, and `{ bars | data }`
+ * wrappers. Extra trailing tuple fields are ignored. Finite `time`/`t` values
+ * below `1e12` are treated as Unix seconds and stored as milliseconds.
+ * Non-finite numbers omit that field. Unknown shape → `[]`.
+ */
+export function mapJsonBars(json: unknown): ProviderBar[] {
+  const rows = unwrapRows(json);
+  if (rows == null) return [];
+  const out: ProviderBar[] = [];
+  for (const item of rows) {
+    const bar = mapOneBar(item);
+    if (bar != null) out.push(bar);
+  }
+  return out;
+}
+
+function unwrapRows(json: unknown): unknown[] | null {
+  if (Array.isArray(json)) return json;
+  if (json != null && typeof json === "object") {
+    const rec = json as Record<string, unknown>;
+    if (Array.isArray(rec.bars)) return rec.bars;
+    if (Array.isArray(rec.data)) return rec.data;
+  }
+  return null;
+}
+
+function mapOneBar(item: unknown): ProviderBar | null {
+  if (item == null || typeof item !== "object") return null;
+  if (Array.isArray(item)) return mapTupleBar(item);
+  const rec = item as Record<string, unknown>;
+  const bar: ProviderBar = {};
+  assignFinite(bar, "time", rec.time ?? rec.t);
+  assignFinite(bar, "open", rec.open ?? rec.o);
+  assignFinite(bar, "high", rec.high ?? rec.h);
+  assignFinite(bar, "low", rec.low ?? rec.l);
+  assignFinite(bar, "close", rec.close ?? rec.c);
+  assignFinite(bar, "volume", rec.volume ?? rec.v);
+  return hasBarField(bar) ? bar : null;
+}
+
+function mapTupleBar(item: unknown[]): ProviderBar | null {
+  if (item.length < 5) return null;
+  const bar: ProviderBar = {};
+  assignFinite(bar, "time", item[0]);
+  assignFinite(bar, "open", item[1]);
+  assignFinite(bar, "high", item[2]);
+  assignFinite(bar, "low", item[3]);
+  assignFinite(bar, "close", item[4]);
+  if (item.length > 5) assignFinite(bar, "volume", item[5]);
+  return hasBarField(bar) ? bar : null;
+}
+
+function assignFinite(
+  bar: ProviderBar,
+  key: (typeof BAR_KEYS)[number],
+  value: unknown,
+): void {
+  const n = asFinite(value);
+  if (n === undefined) return;
+  bar[key] = key === "time" ? normalizeBarTime(n) : n;
+}
+
+/** Unix seconds (`< 1e12`) → milliseconds; already-ms values are unchanged. */
+function normalizeBarTime(msOrSec: number): number {
+  return msOrSec < 1e12 ? msOrSec * 1000 : msOrSec;
+}
+
+function asFinite(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function hasBarField(bar: ProviderBar): boolean {
+  return BAR_KEYS.some((key) => bar[key] !== undefined);
+}
+
+function sliceTail(bars: ProviderBar[], limit?: number): ProviderBar[] {
+  if (limit == null || limit >= bars.length) return bars.slice();
+  return bars.slice(-limit);
+}

package/src/runtime/request.ts

@@ -0,0 +1,372 @@
+/**
+ * Copyright (C) 2024-2026 jango_blockchained
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ *
+ * `request.*` stubs matching Python foreign-na policy:
+ * same-symbol simple OHLCV passthrough, including HTF last-close;
+ * foreign / missing fundamentals → na. HTF *value* passthrough;
+ * no invented foreign data. Forward-fill of the last completed HTF bar
+ * is the host's job (`bucketIndex` / `shouldForwardFill`).
+ * Lower-TF request without a feed is na — no invented intra-bar array.
+ * Interpret should call this from `evalCall`; this module is host-agnostic.
+ */
+
+export type Cell = number | null;
+
+export interface SecurityArgs {
+  symbol?: string | null;
+  timeframe?: string | null;
+  expression?: unknown;
+}
+
+/** Chart identity passed into `resolveRequest`. */
+export interface RequestHost {
+  symbol: string;
+  timeframe?: string | null;
+}
+
+/**
+ * Named or positional args for `resolveRequest`.
+ * Security uses `symbol` / `timeframe` / `sameSymbolValue`;
+ * currency uses `from`/`to` (or `from_currency`/`to_currency`);
+ * seed uses `seed`.
+ */
+export interface RequestNamedArgs {
+  symbol?: string | null;
+  timeframe?: string | null;
+  expression?: unknown;
+  sameSymbolValue?: Cell;
+  from?: string | null;
+  to?: string | null;
+  from_currency?: string | null;
+  to_currency?: string | null;
+  seed?: unknown;
+}
+
+export type RequestArgs = readonly unknown[] | RequestNamedArgs;
+
+const REQUEST_FNS = new Set([
+  "request.security",
+  "request.security_lower_tf",
+  "request.dividends",
+  "request.earnings",
+  "request.splits",
+  "request.financial",
+  "request.economic",
+  "request.quandl",
+  "request.currency_rate",
+  "request.seed",
+  "request.footprint",
+]);
+
+/** Last `request.seed` value (Python stores it on evaluator context). */
+let lastSeed: number | null = null;
+
+const MINUTES_PER_HOUR = 60;
+const MINUTES_PER_DAY = 1440;
+const MINUTES_PER_WEEK = 10080;
+const MINUTES_PER_MONTH = 43200; // 30-day month
+
+/** Bare / alias tokens used as chart periods. */
+const NAMED_TF_MINUTES: Record<string, number> = {
+  H: MINUTES_PER_HOUR,
+  "1H": MINUTES_PER_HOUR,
+  D: MINUTES_PER_DAY,
+  "1D": MINUTES_PER_DAY,
+  W: MINUTES_PER_WEEK,
+  "1W": MINUTES_PER_WEEK,
+  M: MINUTES_PER_MONTH,
+  MO: MINUTES_PER_MONTH,
+  "1M": MINUTES_PER_MONTH,
+  "1MO": MINUTES_PER_MONTH,
+};
+
+export function isRequestBuiltin(fname: string | null | undefined): boolean {
+  return fname != null && REQUEST_FNS.has(fname);
+}
+
+/**
+ * Pine timeframe → minutes. `"1"` `"5"` `"15"` `"60"` `"1h"` `"240"`
+ * `"1D"` `"1W"` (and aliases `D`/`W`/`H`) → minutes; unknown → `null`.
+ */
+export function timeframeMinutes(tf: string | null | undefined): number | null {
+  if (tf == null) return null;
+  const raw = tf.trim();
+  if (raw === "") return null;
+  if (/^\d+$/.test(raw)) {
+    const n = Number(raw);
+    return n > 0 ? n : null;
+  }
+  const u = raw.toUpperCase();
+  const named = NAMED_TF_MINUTES[u];
+  if (named != null) return named;
+  const m = /^(\d+)(MO|H|D|W|M)$/.exec(u);
+  if (m == null) return null;
+  const n = Number(m[1]);
+  if (!(n > 0)) return null;
+  switch (m[2]) {
+    case "MO":
+      return n * MINUTES_PER_MONTH;
+    case "H":
+      return n * MINUTES_PER_HOUR;
+    case "D":
+      return n * MINUTES_PER_DAY;
+    case "W":
+      return n * MINUTES_PER_WEEK;
+    case "M":
+      return n; // "15M" is minutes; "1M" is monthly via NAMED_TF_MINUTES
+    default:
+      return null;
+  }
+}
+
+/** Chart cell: finite number stays; NaN / Inf / non-number → na. */
+function finiteCell(value: Cell): Cell {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+/**
+ * Same-symbol last-close → `sameSymbolValue` (same TF, empty TF, or HTF).
+ * Foreign ticker → na. Does not invent foreign closes.
+ *
+ * Empty / missing request symbol is the chart. Null / empty request TF is
+ * the host TF (passthrough). Non-finite host samples resolve to na.
+ *
+ * HTF *value* passthrough: when request TF minutes > host TF minutes the
+ * current host sample is returned; forward-fill of last completed HTF bar
+ * is the host's job. Different TF on the same symbol is allowed.
+ */
+export function resolveSecurity(
+  hostSymbol: string,
+  hostTimeframe: string | null,
+  args: SecurityArgs,
+  sameSymbolValue: Cell,
+): Cell {
+  const a = args ?? {};
+  if (!sameSymbol(a.symbol, hostSymbol ?? "")) return null;
+  const value = finiteCell(sameSymbolValue);
+  const reqMin = timeframeMinutes(a.timeframe);
+  const hostMin = timeframeMinutes(hostTimeframe);
+  // HTF last-close (req minutes > host): passthrough; host forward-fills.
+  if (reqMin != null && hostMin != null && reqMin > hostMin) {
+    return value;
+  }
+  return value;
+}
+
+/** Minutes rank of a TF token; unknown / empty / na → null. */
+export function timeframeRank(tf: string | null | undefined): number | null {
+  return timeframeMinutes(tf);
+}
+
+/** True when both TFs are known and *req* minutes > *host* minutes. */
+export function isHigherTimeframe(
+  req: string | null | undefined,
+  host: string | null | undefined,
+): boolean {
+  const reqMin = timeframeMinutes(req);
+  const hostMin = timeframeMinutes(host);
+  return reqMin != null && hostMin != null && reqMin > hostMin;
+}
+
+/** True when both TFs are known and *req* minutes < *host* minutes. */
+export function isLowerTimeframe(
+  req: string | null | undefined,
+  host: string | null | undefined,
+): boolean {
+  const reqMin = timeframeMinutes(req);
+  const hostMin = timeframeMinutes(host);
+  return reqMin != null && hostMin != null && reqMin < hostMin;
+}
+
+/**
+ * `request.security_lower_tf` without a lower-TF feed is na.
+ * Same-symbol + finer request TF → null (no invented intra-bar array).
+ * Foreign → null. Same TF (or not-finer) → `resolveSecurity` scalar.
+ */
+export function resolveSecurityLowerTf(
+  hostSymbol: string,
+  hostTimeframe: string | null,
+  args: SecurityArgs,
+  sameSymbolValue: Cell,
+): Cell {
+  const a = args ?? {};
+  if (!sameSymbol(a.symbol, hostSymbol ?? "")) return null;
+  if (isLowerTimeframe(a.timeframe, hostTimeframe)) return null;
+  return resolveSecurity(hostSymbol, hostTimeframe, a, sameSymbolValue);
+}
+
+/** HTF bucket: floor(timeMs / (tfMinutes * 60 * 1000)); non-finite → null. */
+export function bucketIndex(barTimeMs: number, tfMinutes: number): number | null {
+  if (!Number.isFinite(barTimeMs) || !Number.isFinite(tfMinutes) || tfMinutes <= 0) {
+    return null;
+  }
+  return Math.floor(barTimeMs / (tfMinutes * 60 * 1000));
+}
+
+/** True when the HTF bucket changed (new HTF bar started). */
+export function shouldForwardFill(
+  prevBucket: number | null,
+  curBucket: number | null,
+): boolean {
+  return prevBucket != null && curBucket != null && prevBucket !== curBucket;
+}
+
+/**
+ * Empty / missing request symbol is the chart. Compare case-insensitively after
+ * stripping an exchange prefix (`NASDAQ:AAPL` ≡ `AAPL`).
+ */
+function sameSymbol(
+  requestSymbol: string | null | undefined,
+  hostSymbol: string,
+): boolean {
+  const req = (requestSymbol ?? "").trim();
+  if (req === "") return true;
+  return bareTicker(req) === bareTicker(hostSymbol);
+}
+
+function bareTicker(symbol: string): string {
+  const s = symbol.trim().toUpperCase();
+  const colon = s.lastIndexOf(":");
+  return colon >= 0 ? s.slice(colon + 1) : s;
+}
+
+/** Missing / foreign fundamentals, economic, quandl, footprint → na. */
+export function resolveForeignNa(): Cell {
+  return null;
+}
+
+/**
+ * `request.currency_rate`. Identical codes (including `USDUSD`) → 1.0.
+ * Cross rates have no feed here → na (do not invent Python mock FX).
+ */
+export function resolveCurrencyRate(
+  from: string | null | undefined,
+  to?: string | null,
+): Cell {
+  const [a, b] = currencyPair(from, to);
+  if (a !== "" && a === b) return 1;
+  return null;
+}
+
+/** `request.seed` — record the seed (Python returns None). */
+export function resolveSeed(seed?: unknown): Cell {
+  lastSeed = coerceSeed(seed ?? 0);
+  return null;
+}
+
+export function lastRequestSeed(): number | null {
+  return lastSeed;
+}
+
+/**
+ * Dispatch a `request.*` name. Security keeps `resolveSecurity` semantics;
+ * lower-TF without a feed is na; currency is 1.0 only for identical codes;
+ * everything else is na.
+ */
+export function resolveRequest(
+  fname: string,
+  host: RequestHost,
+  args: RequestArgs = {},
+): Cell | unknown {
+  if (fname === "request.security") {
+    const { sec, value } = securityFromArgs(args);
+    return resolveSecurity(host.symbol, host.timeframe ?? null, sec, value);
+  }
+  if (fname === "request.security_lower_tf") {
+    const { sec, value } = securityFromArgs(args);
+    return resolveSecurityLowerTf(host.symbol, host.timeframe ?? null, sec, value);
+  }
+  if (fname === "request.currency_rate") {
+    const [from, to] = currencyFromArgs(args);
+    return resolveCurrencyRate(from, to);
+  }
+  if (fname === "request.seed") {
+    return resolveSeed(seedFromArgs(args));
+  }
+  return resolveForeignNa();
+}
+
+function isNamedArgs(args: RequestArgs): args is RequestNamedArgs {
+  return !Array.isArray(args);
+}
+
+function securityFromArgs(args: RequestArgs): { sec: SecurityArgs; value: Cell } {
+  if (!isNamedArgs(args)) {
+    return {
+      sec: {
+        symbol: asOptString(args[0]),
+        timeframe: asOptString(args[1]),
+        expression: args[2],
+      },
+      value: asCell(args[2]),
+    };
+  }
+  return {
+    sec: {
+      symbol: args.symbol,
+      timeframe: args.timeframe,
+      expression: args.expression,
+    },
+    value: args.sameSymbolValue ?? null,
+  };
+}
+
+function currencyFromArgs(args: RequestArgs): [string | null, string | null] {
+  if (!isNamedArgs(args)) {
+    return [asOptString(args[0]), asOptString(args[1])];
+  }
+  const from = args.from ?? args.from_currency ?? null;
+  const to = args.to ?? args.to_currency ?? null;
+  return [from, to];
+}
+
+function seedFromArgs(args: RequestArgs): unknown {
+  if (!isNamedArgs(args)) return args[0] ?? 0;
+  return args.seed ?? 0;
+}
+
+function currencyPair(
+  from: string | null | undefined,
+  to: string | null | undefined,
+): [string, string] {
+  const a = (from ?? "").trim().toUpperCase();
+  const b = (to ?? "").trim().toUpperCase();
+  if (b !== "") return [a, b];
+  const slash = a.indexOf("/");
+  if (slash >= 0) return [a.slice(0, slash), a.slice(slash + 1)];
+  if (/^[A-Z]{6}$/.test(a)) return [a.slice(0, 3), a.slice(3)];
+  return [a, b];
+}
+
+function coerceSeed(seed: unknown): number {
+  if (typeof seed === "number" && Number.isFinite(seed)) return Math.trunc(seed);
+  if (typeof seed === "string") {
+    const n = Number(seed);
+    if (seed.trim() !== "" && Number.isFinite(n)) return Math.trunc(n);
+    return stringHash(seed);
+  }
+  if (seed == null) return 0;
+  return stringHash(String(seed));
+}
+
+/** Deterministic stand-in for Python `hash(str) & 0xFFFFFFFF`. */
+function stringHash(s: string): number {
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 16777619);
+  }
+  return h >>> 0;
+}
+
+function asOptString(value: unknown): string | null {
+  if (value == null) return null;
+  return typeof value === "string" ? value : String(value);
+}
+
+function asCell(value: unknown): Cell {
+  if (value == null) return null;
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  return null;
+}

package/src/runtime/series.ts

@@ -0,0 +1,44 @@
+/**
+ * Copyright (C) 2024-2026 jango_blockchained
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ *
+ * Pine series lookback polarity matches Python `PineSeries` / TradingView:
+ *   get(0) = current bar, get(1) = previous bar, OOB / negative → na (null).
+ */
+export const NA = null;
+export type Na = null;
+export type Cell = number | Na;
+
+export class PineSeries {
+  private readonly data: Cell[] = [];
+
+  push(value: Cell): void {
+    this.data.push(value);
+  }
+
+  setCurrent(value: Cell): void {
+    if (this.data.length === 0) this.data.push(value);
+    else this.data[this.data.length - 1] = value;
+  }
+
+  get current(): Cell {
+    return this.data.length === 0 ? NA : this.data[this.data.length - 1]!;
+  }
+
+  /** `offset` bars ago. `0` is current; negative / non-finite / OOB is `na`. */
+  get(offset: number): Cell {
+    if (typeof offset !== "number" || !Number.isFinite(offset) || offset < 0) return NA;
+    const n = this.data.length;
+    if (n === 0) return NA;
+    const idx = n - 1 - Math.trunc(offset);
+    if (idx < 0 || idx >= n) return NA;
+    const v = this.data[idx];
+    if (v == null) return NA;
+    if (typeof v === "number" && !Number.isFinite(v)) return NA;
+    return v;
+  }
+
+  get length(): number {
+    return this.data.length;
+  }
+}