oakscriptjs 0.8.1 → 0.9.0

package/dist/esm/time/timezone.js

@@ -0,0 +1,144 @@
+/**
+ * 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;
+/** False when `name` is a wrong-case spelling of a time zone name (`Intl` matches names case-insensitively). */
+function hasTimeZoneCase(name) {
+    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;
+}
+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();
+function resolveZone(timezone) {
+    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;
+        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, time) {
+    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, time) {
+    const wholeSecond = Math.floor(time / 1000) * 1000;
+    const f = {};
+    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;
+}
+/** Offset of `timezone` from UTC at `time`, in milliseconds (local = UTC + offset). */
+export function zoneOffset(time, timezone) {
+    return offsetAt(resolveZone(timezone), time);
+}
+/** Splits a UNIX time (ms) into calendar fields in `timezone`. */
+export function zonedFields(time, timezone) {
+    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, year, month, day, hour = 0, minute = 0, second = 0) {
+    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;
+}
+//# sourceMappingURL=timezone.js.map

package/dist/esm/time/timezone.js.map

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

package/dist/esm/timeframe/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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';
+/**
+ * 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 declare function in_seconds(timeframe: simple_string): int;
+/**
+ * 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 declare function from_seconds(seconds: int): simple_string;
+/** 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 declare function info(timeframe: simple_string): TimeframeInfo;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/timeframe/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/timeframe/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,GAAG,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAqB5D;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,aAAa,GAAG,GAAG,CAaxD;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,GAAG,GAAG,aAAa,CAiBxD;AAED,0FAA0F;AAC1F,MAAM,WAAW,aAAa;IAC5B,6FAA6F;IAC7F,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,OAAO,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;;GAMG;AACH,wBAAgB,IAAI,CAAC,SAAS,EAAE,aAAa,GAAG,aAAa,CAkB5D"}

package/dist/esm/timeframe/index.js

@@ -0,0 +1,131 @@
+/**
+ * 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").
+ */
+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 = {
+    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) {
+    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) {
+    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`;
+}
+/**
+ * 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) {
+    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',
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/esm/timeframe/index.js.map

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