oakscriptjs 0.8.1 → 0.9.0

package/src/text/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Text namespace
+ * PineScript `text.format_*` constants for `label.set_text_formatting` and `box.set_text_formatting`.
+ *
+ * The values are flags that add up, as in PineScript (`text.format_bold + text.format_italic`).
+ * They are the values PineScript uses for drawn labels and boxes.
+ */
+
+/** No formatting. */
+export const format_none = 0;
+/** Bold text. */
+export const format_bold = 1;
+/** Italic text. */
+export const format_italic = 2;

package/src/time/datestring.ts

@@ -0,0 +1,96 @@
+/**
+ * Date strings of `timestamp(dateString)`: IETF RFC 2822 and ISO 8601.
+ *
+ * Accepted forms (case-insensitive), all with an optional time zone at the end:
+ * - "2020-02-20", "2020-2-5", "2020/02/20", "2020-02-20 14:48", "2020-02-20 9:30:15"
+ * - "2020-02-20T14:48:00", "2020-02-20T14:48:00.250", "2020-02-20T14:48:00+05:30"
+ * - "20 Feb 2020", "5-Jan-2024", "Thu, 20 Feb 2020 14:48:00", "20 February 2020 14:48"
+ * - "Feb 20 2020 14:48:05", "Jan 5, 2024 09:30"
+ *
+ * Time zones: "UT", "UTC", "GMT", "+0530", "-05:00", "GMT+5", "UTC-0300", and the RFC 2822
+ * names EST, EDT, CST, CDT, MST, MDT, PST, PDT. After a "T" time, only numeric offsets.
+ * Without a time the time is 00:00. Without a time zone the time zone is GMT+0.
+ * "24:00" is midnight at the end of the day.
+ *
+ * "Z", "2024-01-01T09:30:00 GMT", "24:30" and "09:30:60" are compile errors in PineScript, and
+ * errors here.
+ */
+
+const MONTHS = ['jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec'];
+const FULL_MONTHS = [
+  'january', 'february', 'march', 'april', 'may', 'june',
+  'july', 'august', 'september', 'october', 'november', 'december',
+];
+
+/** RFC 2822 obsolete zone names, in hours from UTC. */
+const ZONE_NAMES: Record<string, number> = {
+  ut: 0, utc: 0, gmt: 0,
+  est: -5, edt: -4, cst: -6, cdt: -5, mst: -7, mdt: -6, pst: -8, pdt: -7,
+};
+
+const TIME = String.raw`(\d{1,2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3})\d*)?)?`;
+const ZONE = String.raw`(ut|utc|gmt|[ecmp][sd]t|(?:utc|gmt)?\s*[+-]\d{1,2}(?::?\d{2})?)`;
+const NUMERIC_ZONE = String.raw`([+-]\d{2}(?::?\d{2})?)`;
+const DATE = String.raw`(\d{4})([-/])(\d{1,2})\2(\d{1,2})`;
+const WEEKDAY = String.raw`(?:[a-z]{3,9},?\s+)?`;
+
+const ISO_T = new RegExp(String.raw`^${DATE}t${TIME}\s*${NUMERIC_ZONE}?$`, 'i');
+const ISO = new RegExp(String.raw`^${DATE}(?:\s+${TIME})?\s*${ZONE}?$`, 'i');
+const DAY_FIRST = new RegExp(String.raw`^${WEEKDAY}(\d{1,2})(?:\s+|-)([a-z]+)\.?,?(?:\s+|-)(\d{4})(?:,?\s+${TIME})?\s*${ZONE}?$`, 'i');
+const MONTH_FIRST = new RegExp(String.raw`^${WEEKDAY}([a-z]+)\.?\s+(\d{1,2}),?\s+(\d{4})(?:,?\s+${TIME})?\s*${ZONE}?$`, 'i');
+
+/** Month number (1-12) of an English month name or its prefix of 3+ letters ("Sep", "Sept", "September"). */
+function monthNumber(name: string): number {
+  const lower = name.toLowerCase();
+  const i = FULL_MONTHS.findIndex((full, k) => lower.startsWith(MONTHS[k]!) && full.startsWith(lower));
+  return i + 1;
+}
+
+/** Zone offset in minutes from UTC. */
+function zoneMinutes(zone: string | undefined): number {
+  if (!zone) return 0;
+  const lower = zone.toLowerCase().replace(/\s+/g, '');
+  const named = ZONE_NAMES[lower];
+  if (named !== undefined) return named * 60;
+  const m = /^(?:utc|gmt)?([+-])(\d{1,2})(?::?(\d{2}))?$/.exec(lower);
+  if (!m) return NaN;
+  const minutes = Number(m[2]) * 60 + (m[3] ? Number(m[3]) : 0);
+  return m[1] === '-' ? -minutes : minutes;
+}
+
+/**
+ * Parses a PineScript date string into a UNIX time in milliseconds.
+ * @throws SyntaxError when the string is not in a supported form
+ */
+export function parseDateString(dateString: string): number {
+  const text = dateString.trim();
+  let year: string, month: number, day: string;
+  let rest: Array<string | undefined>;
+
+  let m: RegExpExecArray | null;
+  if ((m = ISO_T.exec(text) ?? ISO.exec(text))) {
+    [year, month, day] = [m[1]!, Number(m[3]), m[4]!];
+    rest = m.slice(5);
+  } else if ((m = DAY_FIRST.exec(text))) {
+    [day, month, year] = [m[1]!, monthNumber(m[2]!), m[3]!];
+    rest = m.slice(4);
+  } else if ((m = MONTH_FIRST.exec(text))) {
+    [month, day, year] = [monthNumber(m[1]!), m[2]!, m[3]!];
+    rest = m.slice(4);
+  } else {
+    throw new SyntaxError(`Invalid date string "${dateString}": use RFC 2822 or ISO 8601 ("20 Feb 2020", "2020-02-20T14:48:00")`);
+  }
+
+  const [hour = '0', minute = '0', second = '0', millis = '0', zone] = rest;
+  const d = Number(day);
+  const h = Number(hour);
+  const mi = Number(minute);
+  const s = Number(second);
+  const offset = zoneMinutes(zone);
+  const endOfDay = h === 24 && mi === 0 && s === 0 && Number(millis) === 0;
+  if (month < 1 || month > 12 || d < 1 || d > 31 || (h > 23 && !endOfDay) || mi > 59 || s > 59 || Number.isNaN(offset)) {
+    throw new SyntaxError(`Invalid date string "${dateString}": a field is out of range`);
+  }
+  const ms = Number(millis.padEnd(3, '0'));
+  return Date.UTC(Number(year), month - 1, d, h, mi, s, ms) - offset * 60_000;
+}

package/src/time/index.ts

@@ -0,0 +1,161 @@
+/**
+ * Time namespace
+ * Mirrors PineScript's time and calendar functions.
+ *
+ * Every function takes an explicit time zone: UTC/GMT offset notation ("UTC-5",
+ * "GMT+0530", "UTC+05:30") or an IANA name ("America/New_York"). The PineScript
+ * default time zone (the exchange time zone, `syminfo.timezone`) is not known here.
+ */
+
+import type { int, simple_int } from '../types/index.js';
+import { zonedFields, zonedToUnix } from './timezone.js';
+import { parseDateString } from './datestring.js';
+import { inSession as sessionContains } from './session.js';
+
+/**
+ * Returns the current time in milliseconds
+ */
+export function now(): int {
+  return Date.now();
+}
+
+/**
+ * Returns the UNIX time (ms) of a date and time.
+ *
+ * - `timestamp(dateString)`: RFC 2822 or ISO 8601 date string ("20 Feb 2020",
+ *   "2020-02-20T14:48:00", "2024-01-01 09:30 +0000", "04 Dec 1995 00:12:00 GMT+5").
+ *   Without a time the time is 00:00; without a time zone the time zone is GMT+0.
+ * - `timestamp(timezone, year, month, day, hour?, minute?, second?)`: calendar fields in `timezone`.
+ *   A wall-clock time that occurs twice resolves to the later instant; a missing one is
+ *   shifted forward by the gap (as in PineScript).
+ * - `timestamp(year, month, day, hour?, minute?, second?)`: calendar fields in the time zone
+ *   of the host. PineScript reads them in the exchange time zone, which is not known here:
+ *   use the `timezone` form for PineScript values.
+ *
+ * Out-of-range fields roll over (month 13 is January of the next year).
+ *
+ * @example
+ * ```typescript
+ * time.timestamp('2024-01-02');                                // 1704153600000
+ * time.timestamp('America/New_York', 2024, 1, 2, 9, 30);       // 1704205800000
+ * ```
+ */
+export function timestamp(dateString: string): int;
+export function timestamp(
+  timezone: string,
+  year: simple_int,
+  month: simple_int,
+  day: simple_int,
+  hour?: simple_int,
+  minute?: simple_int,
+  second?: simple_int
+): int;
+export function timestamp(
+  year: simple_int,
+  month: simple_int,
+  day: simple_int,
+  hour?: simple_int,
+  minute?: simple_int,
+  second?: simple_int
+): int;
+export function timestamp(first: string | simple_int, ...rest: Array<simple_int | undefined>): int {
+  if (typeof first === 'string') {
+    if (rest.length === 0) return parseDateString(first);
+    const [year, month, day, hour, minute, second] = rest as [number, number, number, number?, number?, number?];
+    return zonedToUnix(first, year, month, day, hour ?? 0, minute ?? 0, second ?? 0);
+  }
+  const [month, day, hour, minute, second] = rest as [number, number, number?, number?, number?];
+  return new Date(first, month - 1, day, hour || 0, minute || 0, second || 0).getTime();
+}
+
+// ── Calendar fields ──────────────────────────────────────────────────────────
+
+function field(time: number, timezone: string, pick: (f: ReturnType<typeof zonedFields>) => number): int {
+  return Number.isNaN(time) ? NaN : pick(zonedFields(time, timezone));
+}
+
+/**
+ * Year of a UNIX time (ms) in `timezone`.
+ */
+export function year(time: int, timezone: string): int {
+  return field(time, timezone, (f) => f.year);
+}
+
+/**
+ * Month (1-12) of a UNIX time (ms) in `timezone`.
+ */
+export function month(time: int, timezone: string): int {
+  return field(time, timezone, (f) => f.month);
+}
+
+/**
+ * Day of the month (1-31) of a UNIX time (ms) in `timezone`.
+ */
+export function dayofmonth(time: int, timezone: string): int {
+  return field(time, timezone, (f) => f.day);
+}
+
+/**
+ * Day of the week of a UNIX time (ms) in `timezone`: 1 = Sunday, 2 = Monday ... 7 = Saturday
+ * (PineScript `dayofweek.sunday` ... `dayofweek.saturday`).
+ */
+export function dayofweek(time: int, timezone: string): int {
+  return field(time, timezone, (f) => f.dayOfWeek);
+}
+
+/**
+ * Week number of the year of a UNIX time (ms) in `timezone`.
+ *
+ * Weeks start on Monday and follow ISO 8601: week 1 is the week that contains the
+ * first Thursday of the year, so the first days of January can be in week 52 or 53
+ * of the previous year. The PineScript reference does not define the rule.
+ */
+export function weekofyear(time: int, timezone: string): int {
+  return field(time, timezone, (f) => {
+    const date = Date.UTC(f.year, f.month - 1, f.day);
+    const mondayBased = (f.dayOfWeek + 5) % 7; // Monday = 0 ... Sunday = 6
+    const thursday = new Date(date + (3 - mondayBased) * 86_400_000);
+    const yearStart = Date.UTC(thursday.getUTCFullYear(), 0, 1);
+    return 1 + Math.floor((thursday.getTime() - yearStart) / (7 * 86_400_000));
+  });
+}
+
+/**
+ * Hour (0-23) of a UNIX time (ms) in `timezone`.
+ */
+export function hour(time: int, timezone: string): int {
+  return field(time, timezone, (f) => f.hour);
+}
+
+/**
+ * Minute (0-59) of a UNIX time (ms) in `timezone`.
+ */
+export function minute(time: int, timezone: string): int {
+  return field(time, timezone, (f) => f.minute);
+}
+
+/**
+ * Second (0-59) of a UNIX time (ms) in `timezone`.
+ */
+export function second(time: int, timezone: string): int {
+  return field(time, timezone, (f) => f.second);
+}
+
+// ── Sessions ─────────────────────────────────────────────────────────────────
+
+/**
+ * True when a bar opening at `time` is inside `session`, with the session hours read in `timezone`.
+ *
+ * This is the session test of PineScript `time(timeframe, session, timezone)`, which returns
+ * `na` for bars outside the session: `na(time("1", "0930-1600", "America/New_York"))` is
+ * `!time.inSession(barTime, "0930-1600", "America/New_York")`.
+ *
+ * Session format: "HHmm-HHmm", several periods separated by commas, optional days after
+ * ":" (1 = Sunday ... 7 = Saturday), e.g. "0930-1600:23456" or "1000-1100,1400-1500".
+ * Without days, one period covers every day and several periods cover Monday to Friday.
+ * A period includes its start and excludes its end. An overnight period ("1800-0930")
+ * belongs to the day it ends. "0000-0000" and "24x7" cover the whole day.
+ */
+export function inSession(time: int, session: string, timezone: string): boolean {
+  return sessionContains(time, session, timezone);
+}

package/src/time/session.ts

@@ -0,0 +1,79 @@
+/**
+ * Session strings ("0930-1600", "0930-1600:23456", "1000-1100,1400-1500:23456", "24x7").
+ *
+ * Format `<periods>[:<days>]`:
+ * - a period is "HHmm-HHmm"; several periods are separated by commas
+ * - days are digits 1 (Sunday) to 7 (Saturday). Without days, a single period covers every
+ *   day, and several periods cover Monday to Friday ("23456"), as in PineScript
+ * - an end before the start is an overnight period that ends on the next day, and it
+ *   belongs to the day it ends: "1700-1700:23456" starts Sunday 17:00 and covers Monday
+ * - "0000-0000" and "24x7" are the 24-hour session of every day
+ */
+
+import { zonedFields } from './timezone.js';
+
+interface Period {
+  /** Minutes after midnight, 0-1439 */
+  start: number;
+  end: number;
+}
+
+interface ParsedSession {
+  periods: Period[];
+  /** Included days, indexed 1 (Sunday) to 7 (Saturday) */
+  days: boolean[];
+}
+
+const PERIOD = /^(\d{2})(\d{2})-(\d{2})(\d{2})$/;
+
+const sessions = new Map<string, ParsedSession>();
+
+function parseSession(session: string): ParsedSession {
+  let parsed = sessions.get(session);
+  if (parsed) return parsed;
+
+  const invalid = () => new SyntaxError(`Invalid session "${session}": expected "HHmm-HHmm[,HHmm-HHmm...][:days]"`);
+  const text = session.trim() === '24x7' ? '0000-0000' : session.replace(/\s+/g, '');
+  const [periodText = '', dayText, extra] = text.split(':');
+  if (extra !== undefined || periodText === '') throw invalid();
+
+  const periods = periodText.split(',').map((p) => {
+    const m = PERIOD.exec(p);
+    if (!m) throw invalid();
+    const [h1, m1, h2, m2] = [m[1], m[2], m[3], m[4]].map(Number) as [number, number, number, number];
+    if (h1 > 23 || h2 > 23 || m1 > 59 || m2 > 59) throw invalid();
+    return { start: h1 * 60 + m1, end: h2 * 60 + m2 };
+  });
+
+  const dayDigits = dayText ?? (periods.length > 1 ? '23456' : '1234567');
+  if (!/^[1-7]+$/.test(dayDigits)) throw invalid();
+  const days = new Array<boolean>(8).fill(false);
+  for (const d of dayDigits) days[Number(d)] = true;
+
+  parsed = { periods, days };
+  sessions.set(session, parsed);
+  return parsed;
+}
+
+/**
+ * True when `time` falls inside `session`, with the session hours read in `timezone`.
+ * A period includes its start minute and excludes its end minute.
+ */
+export function inSession(time: number, session: string, timezone: string): boolean {
+  if (Number.isNaN(time)) return false;
+  const { periods, days } = parseSession(session);
+  const f = zonedFields(time, timezone);
+  const minute = f.hour * 60 + f.minute;
+  const nextDay = (f.dayOfWeek % 7) + 1;
+
+  for (const { start, end } of periods) {
+    if (start < end || (start === 0 && end === 0)) {
+      if (minute >= start && (minute < end || end === 0) && days[f.dayOfWeek]) return true;
+    } else {
+      // Overnight (24 hours when start === end): the part from `start` belongs to the next day.
+      if (minute >= start && days[nextDay]) return true;
+      if (minute < end && days[f.dayOfWeek]) return true;
+    }
+  }
+  return false;
+}

package/src/time/timezone.ts

@@ -0,0 +1,180 @@
+/**
+ * Time zone resolution for the calendar functions.
+ *
+ * PineScript accepts two time zone notations:
+ * - UTC/GMT offset notation: "UTC", "UTC-5", "UTC+05:30", "GMT+0530", "GMT+05:30:00", up to ±18:00
+ * - IANA time zone database names, case-sensitive: "America/New_York", "Etc/UTC", "US/Eastern", "CET"
+ *
+ * "utc+2", "america/new_york", "UTC+5:3", "UTC+5:30:15", "GMT+18:01", "EST", "MST" and "HST" are
+ * errors in PineScript, and so here.
+ *
+ * Offsets of IANA zones (daylight saving time and historical changes included)
+ * come from the host's `Intl.DateTimeFormat`, so no time zone data ships with the library.
+ */
+
+const MS_PER_SECOND = 1000;
+const MS_PER_DAY = 86_400_000;
+const MAX_OFFSET_SECONDS = 18 * 3600;
+
+const OFFSET_NOTATION = /^(?:UTC|GMT)(?:([+-])(\d{1,2})(?::?(\d{2})(?::?(\d{2}))?)?)?$/;
+
+/** Time zone database names that PineScript rejects although `Intl` accepts them. */
+const REJECTED_NAMES = new Set(['EST', 'MST', 'HST']);
+
+let canonicalNames: Map<string, string> | undefined;
+
+/** False when `name` is a wrong-case spelling of a time zone name (`Intl` matches names case-insensitively). */
+function hasTimeZoneCase(name: string): boolean {
+  if (name.split('/').some((segment) => !/^[A-Z]/.test(segment))) return false;
+  canonicalNames ??= new Map(Intl.supportedValuesOf('timeZone').map((n) => [n.toLowerCase(), n]));
+  const canonical = canonicalNames.get(name.toLowerCase());
+  return canonical === undefined || canonical === name;
+}
+
+type Zone =
+  | { readonly kind: 'fixed'; readonly offsetMs: number }
+  | {
+      readonly kind: 'iana';
+      readonly format: Intl.DateTimeFormat;
+      /** Offset of each UTC hour (`floor(time / 1 h)`); null for an hour with an offset change inside */
+      readonly hours: Map<number, number | null>;
+    };
+
+const MS_PER_HOUR = 3_600_000;
+/** Cached hours per zone before the cache restarts (about 11 years of hours) */
+const MAX_CACHED_HOURS = 100_000;
+
+const zones = new Map<string, Zone>();
+
+function resolveZone(timezone: string): Zone {
+  let zone = zones.get(timezone);
+  if (zone) return zone;
+
+  const invalid = () =>
+    new RangeError(
+      `Invalid time zone "${timezone}": use UTC/GMT offset notation ("UTC-5", "GMT+0530") or an IANA name ("America/New_York")`
+    );
+  const m = OFFSET_NOTATION.exec(timezone);
+  if (m) {
+    const [, sign, h = '0', mi = '0', s] = m;
+    const minutes = Number(mi);
+    const seconds = s === undefined ? 0 : Number(s);
+    if (minutes > 59 || seconds > 59 || (s !== undefined && h.length !== 2)) throw invalid();
+    const offsetSeconds = Number(h) * 3600 + minutes * 60 + seconds;
+    if (offsetSeconds > MAX_OFFSET_SECONDS) throw invalid();
+    zone = { kind: 'fixed', offsetMs: (sign === '-' ? -offsetSeconds : offsetSeconds) * MS_PER_SECOND };
+  } else {
+    if (REJECTED_NAMES.has(timezone) || !hasTimeZoneCase(timezone)) throw invalid();
+    let format: Intl.DateTimeFormat;
+    try {
+      format = new Intl.DateTimeFormat('en-US', {
+        timeZone: timezone,
+        hourCycle: 'h23',
+        year: 'numeric',
+        month: 'numeric',
+        day: 'numeric',
+        hour: 'numeric',
+        minute: 'numeric',
+        second: 'numeric',
+      });
+    } catch {
+      throw invalid();
+    }
+    zone = { kind: 'iana', format, hours: new Map() };
+  }
+  zones.set(timezone, zone);
+  return zone;
+}
+
+/**
+ * Offset of the zone from UTC at instant `time`, in milliseconds (local = UTC + offset).
+ * An offset change happens at most once in a UTC hour, so when the first and the last second of the hour have the
+ * same offset, the whole hour has it: it is computed once and cached.
+ */
+function offsetAt(zone: Zone, time: number): number {
+  if (zone.kind === 'fixed') return zone.offsetMs;
+  const hour = Math.floor(time / MS_PER_HOUR);
+  let offset = zone.hours.get(hour);
+  if (offset === undefined) {
+    const first = formattedOffset(zone.format, hour * MS_PER_HOUR);
+    const last = formattedOffset(zone.format, hour * MS_PER_HOUR + MS_PER_HOUR - MS_PER_SECOND);
+    offset = first === last ? first : null;
+    if (zone.hours.size >= MAX_CACHED_HOURS) zone.hours.clear();
+    zone.hours.set(hour, offset);
+  }
+  return offset ?? formattedOffset(zone.format, time);
+}
+
+/** Offset of the zone at instant `time` (whole second), from the host's `Intl` time zone data. */
+function formattedOffset(format: Intl.DateTimeFormat, time: number): number {
+  const wholeSecond = Math.floor(time / 1000) * 1000;
+  const f: Record<string, number> = {};
+  for (const part of format.formatToParts(wholeSecond)) {
+    if (part.type !== 'literal') f[part.type] = Number(part.value);
+  }
+  const local = Date.UTC(f.year!, f.month! - 1, f.day!, f.hour!, f.minute!, f.second!);
+  return local - wholeSecond;
+}
+
+/** Calendar fields of a UNIX time in a time zone. */
+export interface ZonedFields {
+  year: number;
+  /** 1-12 */
+  month: number;
+  /** 1-31 */
+  day: number;
+  hour: number;
+  minute: number;
+  second: number;
+  /** 1 = Sunday ... 7 = Saturday (PineScript dayofweek numbering) */
+  dayOfWeek: number;
+}
+
+/** Offset of `timezone` from UTC at `time`, in milliseconds (local = UTC + offset). */
+export function zoneOffset(time: number, timezone: string): number {
+  return offsetAt(resolveZone(timezone), time);
+}
+
+/** Splits a UNIX time (ms) into calendar fields in `timezone`. */
+export function zonedFields(time: number, timezone: string): ZonedFields {
+  const local = new Date(time + offsetAt(resolveZone(timezone), time));
+  return {
+    year: local.getUTCFullYear(),
+    month: local.getUTCMonth() + 1,
+    day: local.getUTCDate(),
+    hour: local.getUTCHours(),
+    minute: local.getUTCMinutes(),
+    second: local.getUTCSeconds(),
+    dayOfWeek: local.getUTCDay() + 1,
+  };
+}
+
+/**
+ * Converts a wall-clock date and time in `timezone` to a UNIX time (ms).
+ * Out-of-range fields roll over like `Date.UTC` (month 13 is January of the next year).
+ *
+ * As in PineScript: wall-clock times that occur twice (end of daylight saving time)
+ * resolve to the later instant, and wall-clock times that do not exist (start of
+ * daylight saving time) are shifted forward by the length of the gap.
+ */
+export function zonedToUnix(
+  timezone: string,
+  year: number,
+  month: number,
+  day: number,
+  hour: number = 0,
+  minute: number = 0,
+  second: number = 0
+): number {
+  const zone = resolveZone(timezone);
+  const local = Date.UTC(year, month - 1, day, hour, minute, second);
+  if (zone.kind === 'fixed') return local - zone.offsetMs;
+
+  // At most one offset transition happens within a day of `local`: the offsets
+  // one day before and one day after are the two candidates.
+  const before = offsetAt(zone, local - MS_PER_DAY);
+  const after = offsetAt(zone, local + MS_PER_DAY);
+  const candidates = [local - before, local - after].filter((t) => local - offsetAt(zone, t) === t);
+  if (candidates.length) return Math.max(...candidates);
+  return local - before;
+}

package/src/timeframe/index.ts

@@ -0,0 +1,144 @@
+/**
+ * Timeframe namespace
+ * Mirrors PineScript's timeframe string functions.
+ *
+ * Timeframe strings: a multiplier and a unit letter, "S" seconds, "D" days,
+ * "W" weeks, "M" months, "T" ticks, no letter for minutes ("60" is one hour, "1H" is not valid).
+ * Without a multiplier, 1 is used ("D" is "1D").
+ */
+
+import type { int, simple_string } from '../types/index.js';
+
+const SECONDS_PER_MINUTE = 60;
+const SECONDS_PER_DAY = 86_400;
+const SECONDS_PER_WEEK = 604_800;
+/** PineScript uses 365/12 days (30.4167) for one month. */
+const SECONDS_PER_MONTH = 2_628_003;
+/** From 365 days, `from_seconds` returns "12M". */
+const SECONDS_365_DAYS = 365 * SECONDS_PER_DAY;
+
+const UNIT_SECONDS: Record<string, number> = {
+  S: 1,
+  '': SECONDS_PER_MINUTE,
+  D: SECONDS_PER_DAY,
+  W: SECONDS_PER_WEEK,
+  M: SECONDS_PER_MONTH,
+};
+
+/** Second-based timeframes that `from_seconds` can return. */
+const SECOND_TIMEFRAMES = [1, 5, 10, 15, 30];
+
+/**
+ * Converts a timeframe string into seconds.
+ *
+ * As in PineScript: months count 2,628,003 seconds (365/12 days), any multiplier is
+ * accepted ("13M", "1441", "7S"), and tick timeframes ("1T") give NaN.
+ *
+ * @param timeframe - Timeframe string, e.g. "1", "60", "1D", "W", "3M", "30S"
+ * @returns Number of seconds in the timeframe
+ * @throws RangeError for an empty string (the chart timeframe is not known here) and for
+ *   strings that are not timeframes ("1H", "1d")
+ *
+ * @example
+ * ```typescript
+ * timeframe.in_seconds('60');  // 3600
+ * timeframe.in_seconds('1D');  // 86400
+ * timeframe.in_seconds('M');   // 2628003
+ * ```
+ */
+export function in_seconds(timeframe: simple_string): int {
+  const text = timeframe.trim();
+  if (text === '') {
+    throw new RangeError('timeframe.in_seconds() needs a timeframe: the chart timeframe is not known here');
+  }
+  // Multiplier before the unit ("30S"), or after it ("S30"), as PineScript accepts both.
+  const before = /^(\d*)([SDWMT]?)$/.exec(text);
+  const after = before ? null : /^([SDWMT])(\d+)$/.exec(text);
+  if (!before && !after) throw new RangeError(`Invalid timeframe "${timeframe}"`);
+  const [digits, unit] = before ? [before[1]!, before[2]!] : [after![2]!, after![1]!];
+  if (unit === 'T') return NaN;
+  const multiplier = digits === '' ? 1 : Number(digits);
+  return multiplier * UNIT_SECONDS[unit]!;
+}
+
+/**
+ * Converts a number of seconds into a valid timeframe string.
+ *
+ * PineScript rules:
+ * - when no valid timeframe has exactly this duration, the next higher one is returned:
+ *   1 second or less gives "1S", 2-5 seconds give "5S", 31-60 seconds give "1",
+ *   604,799 seconds give "7D"
+ * - when several timeframes have exactly this duration, the larger unit is used:
+ *   604,800 seconds give "1W", not "7D"; months are used for exact multiples of 2,628,003 seconds
+ * - from 31,536,000 seconds (365 days) the result is "12M"
+ *
+ * @param seconds - Number of seconds
+ * @returns Timeframe string
+ *
+ * @example
+ * ```typescript
+ * timeframe.from_seconds(3600);    // "60"
+ * timeframe.from_seconds(86400);   // "1D"
+ * timeframe.from_seconds(604800);  // "1W"
+ * ```
+ */
+export function from_seconds(seconds: int): simple_string {
+  if (Number.isNaN(seconds)) throw new RangeError('timeframe.from_seconds() needs a number of seconds');
+  if (seconds >= SECONDS_365_DAYS) return '12M';
+
+  // Exact durations, larger unit first.
+  if (seconds > 0) {
+    if (seconds % SECONDS_PER_MONTH === 0) return `${seconds / SECONDS_PER_MONTH}M`;
+    if (seconds % SECONDS_PER_WEEK === 0) return `${seconds / SECONDS_PER_WEEK}W`;
+    if (seconds % SECONDS_PER_DAY === 0) return `${seconds / SECONDS_PER_DAY}D`;
+    if (seconds % SECONDS_PER_MINUTE === 0 && seconds < SECONDS_PER_DAY) return `${seconds / SECONDS_PER_MINUTE}`;
+  }
+
+  // Next higher valid timeframe.
+  const second = SECOND_TIMEFRAMES.find((m) => seconds <= m);
+  if (second !== undefined) return `${second}S`;
+  if (seconds < SECONDS_PER_DAY) return `${Math.ceil(seconds / SECONDS_PER_MINUTE)}`;
+  return `${Math.ceil(seconds / SECONDS_PER_DAY)}D`;
+}
+
+/** Properties of a chart timeframe, as PineScript's `timeframe.*` variables give them. */
+export interface TimeframeInfo {
+  /** Timeframe string with its multiplier: "1D", "60", "1S" (PineScript `timeframe.period`) */
+  period: string;
+  multiplier: number;
+  isintraday: boolean;
+  isdaily: boolean;
+  isweekly: boolean;
+  ismonthly: boolean;
+  isminutes: boolean;
+  isseconds: boolean;
+  isticks: boolean;
+  isdwm: boolean;
+}
+
+/**
+ * Describes a chart timeframe like PineScript's `timeframe.*` variables.
+ * The period always carries its multiplier: "D" becomes "1D".
+ *
+ * @param timeframe - Chart timeframe string, e.g. "5", "60", "D", "1W", "30S"
+ * @throws RangeError for strings that are not timeframes
+ */
+export function info(timeframe: simple_string): TimeframeInfo {
+  const text = timeframe.trim();
+  const m = /^(\d*)([SDWMT]?)$/.exec(text);
+  if (!m || text === '') throw new RangeError(`Invalid timeframe "${timeframe}"`);
+  const unit = m[2]!;
+  const multiplier = m[1] === '' ? 1 : Number(m[1]);
+  return {
+    period: unit === '' ? String(multiplier) : `${multiplier}${unit}`,
+    multiplier,
+    isintraday: unit === '' || unit === 'S' || unit === 'T',
+    isdaily: unit === 'D',
+    isweekly: unit === 'W',
+    ismonthly: unit === 'M',
+    isminutes: unit === '',
+    isseconds: unit === 'S',
+    isticks: unit === 'T',
+    isdwm: unit === 'D' || unit === 'W' || unit === 'M',
+  };
+}