openalgo-script 0.1.0-alpha.0 → 0.2.0

package/src/core/stdlib/calendar/fields.ts

@@ -0,0 +1,124 @@
+/**
+ * The calendar reads of `stdlib.md` section 12.2, each one an instant and a
+ * zone in and a number out.
+ *
+ * Every one of them is absent rather than a guess when the zone is not one the
+ * runtime holds or the instant is not a number. An unknown zone is OS6005, and
+ * raising it is the engine's to do at the call site, where there is a span to
+ * point at; this tier raises nothing, for the reason the library's own index
+ * gives.
+ */
+import type { Value } from '../values/index.js';
+import { NONE, result } from '../values/index.js';
+
+import type { Civil } from './civil.js';
+import { dateOfDay, dayNumber, dayOfYearOf, weekOfYearOf, weekdayOfDay } from './civil.js';
+import { fieldsIn, instantOf } from './zone.js';
+
+/** Which field of a civil date a read wants. */
+export type DateField =
+  | 'year'
+  | 'month'
+  | 'day'
+  | 'dayOfWeek'
+  | 'dayOfYear'
+  | 'hour'
+  | 'minute'
+  | 'second'
+  | 'weekOfYear';
+
+/** One calendar field of an instant, read in a zone. */
+export function dateField(instant: Value, zone: string | null, field: DateField): Value {
+  const fields = civilAt(instant, zone);
+  if (fields === null) return NONE;
+  switch (field) {
+    case 'year':
+      return result(fields.year);
+    case 'month':
+      return result(fields.month);
+    case 'day':
+      return result(fields.day);
+    case 'hour':
+      return result(fields.hour);
+    case 'minute':
+      return result(fields.minute);
+    case 'second':
+      return result(fields.second);
+    case 'dayOfWeek':
+      return result(weekdayOfDay(dayNumber(fields.year, fields.month, fields.day)));
+    case 'dayOfYear':
+      return result(dayOfYearOf(fields.year, fields.month, fields.day));
+    default:
+      return result(weekOfYearOf(fields.year, fields.month, fields.day));
+  }
+}
+
+/** Which boundary `startOfDay`, `startOfWeek` and `startOfMonth` round back to. */
+export type Boundary = 'day' | 'week' | 'month';
+
+/**
+ * Midnight at the start of the day, the Monday or the first of the month that
+ * holds an instant, in a zone.
+ *
+ * The answer is built as a wall clock reading and then turned back into an
+ * instant, rather than by subtracting a count of milliseconds. Subtracting is
+ * wrong across a clock change, where a local day is twenty three or twenty five
+ * hours long, and it is wrong in a way that shows up twice a year on one chart
+ * and never on another.
+ */
+export function startOf(instant: Value, zone: string | null, boundary: Boundary): Value {
+  const fields = civilAt(instant, zone);
+  if (fields === null || zone === null) return NONE;
+  const midnight = { hour: 0, minute: 0, second: 0 };
+  let civil: Civil;
+  if (boundary === 'month') {
+    civil = { year: fields.year, month: fields.month, day: 1, ...midnight };
+  } else if (boundary === 'day') {
+    civil = { year: fields.year, month: fields.month, day: fields.day, ...midnight };
+  } else {
+    const days = dayNumber(fields.year, fields.month, fields.day);
+    const monday = days - (weekdayOfDay(days) - 1);
+    civil = { ...dateOfDay(monday), ...midnight };
+  }
+  const at = instantOf(civil, zone);
+  return at === null ? NONE : result(at);
+}
+
+/** Whether two instants fall on one calendar day in a zone. */
+export function sameDay(a: Value, b: Value, zone: string | null): boolean | null {
+  const left = civilAt(a, zone);
+  const right = civilAt(b, zone);
+  if (left === null || right === null) return null;
+  return left.year === right.year && left.month === right.month && left.day === right.day;
+}
+
+/** An instant built from calendar fields in a zone, `date.from`. */
+export function instantFrom(
+  year: Value,
+  month: Value,
+  day: Value,
+  hour: Value,
+  minute: Value,
+  second: Value,
+  zone: string | null,
+): Value {
+  if (zone === null) return NONE;
+  if (year === null || month === null || day === null) return NONE;
+  const fields: Civil = {
+    year,
+    month,
+    day,
+    hour: hour ?? 0,
+    minute: minute ?? 0,
+    second: second ?? 0,
+  };
+  if (!Object.values(fields).every((one) => Number.isInteger(one))) return NONE;
+  const at = instantOf(fields, zone);
+  return at === null ? NONE : result(at);
+}
+
+/** The civil fields of an instant, or nothing when either side is unusable. */
+export function civilAt(instant: Value, zone: string | null): Civil | null {
+  if (instant === null || zone === null) return null;
+  return fieldsIn(instant, zone);
+}

package/src/core/stdlib/calendar/format.ts

@@ -0,0 +1,71 @@
+/**
+ * `date.format(t, pattern, zone)`: the closed placeholder set of `stdlib.md`
+ * section 12.3 and nothing else.
+ *
+ * The set is small and closed on purpose, so that two engines cannot differ
+ * about what a pattern means. Every character that is not one of the eight
+ * placeholders is copied through exactly as written, including a letter that
+ * looks like part of one: the scan below takes the longest placeholder that
+ * starts at each position and moves past it, so `MMM` is the month name and the
+ * `MM` inside it is never read a second time.
+ *
+ * Month and weekday abbreviations are English and invariant, for the same
+ * determinism reason `str.upper` is: a name that followed the reader's locale
+ * would make one chart's label depend on who opened it.
+ */
+import type { Civil } from './civil.js';
+import { dayNumber, weekdayOfDay } from './civil.js';
+
+const MONTHS: readonly string[] = [
+  'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec',
+];
+
+const WEEKDAYS: readonly string[] = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'];
+
+/** The placeholders, longest first, which is the order the scan tries them in. */
+const PLACEHOLDERS: readonly string[] = ['yyyy', 'MMM', 'EEE', 'MM', 'dd', 'HH', 'mm', 'ss'];
+
+function pad(value: number, width: number): string {
+  const digits = Math.abs(Math.trunc(value)).toString();
+  const padded = digits.length >= width ? digits : '0'.repeat(width - digits.length) + digits;
+  return value < 0 ? `-${padded}` : padded;
+}
+
+function substitution(token: string, fields: Civil): string {
+  switch (token) {
+    case 'yyyy':
+      return pad(fields.year, 4);
+    case 'MMM':
+      return MONTHS[fields.month - 1] ?? '';
+    case 'EEE':
+      return WEEKDAYS[weekdayOfDay(dayNumber(fields.year, fields.month, fields.day)) - 1] ?? '';
+    case 'MM':
+      return pad(fields.month, 2);
+    case 'dd':
+      return pad(fields.day, 2);
+    case 'HH':
+      return pad(fields.hour, 2);
+    case 'mm':
+      return pad(fields.minute, 2);
+    default:
+      return pad(fields.second, 2);
+  }
+}
+
+/** A pattern rendered against one civil reading, or nothing when there is none. */
+export function renderPattern(pattern: string | null, fields: Civil | null): string | null {
+  if (pattern === null || fields === null) return null;
+  let out = '';
+  let at = 0;
+  while (at < pattern.length) {
+    const token = PLACEHOLDERS.find((one) => pattern.startsWith(one, at));
+    if (token === undefined) {
+      out += pattern[at];
+      at += 1;
+      continue;
+    }
+    out += substitution(token, fields);
+    at += token.length;
+  }
+  return out;
+}

package/src/core/stdlib/calendar/index.ts

@@ -0,0 +1,15 @@
+export type { Civil } from './civil.js';
+export {
+  dateOfDay,
+  dayNumber,
+  dayOfYearOf,
+  weekOfYearOf,
+  weekdayOfDay,
+} from './civil.js';
+
+export { fieldsIn, instantOf, isKnownZone, offsetAt, utcInstantOf } from './zone.js';
+
+export type { Boundary, DateField } from './fields.js';
+export { civilAt, dateField, instantFrom, sameDay, startOf } from './fields.js';
+
+export { renderPattern } from './format.js';

package/src/core/stdlib/calendar/zone.ts

@@ -0,0 +1,161 @@
+/**
+ * Reading an instant in a named zone, and building an instant from one.
+ *
+ * **A zone is an area and location name and never a fixed offset**, which
+ * `stdlib.md` section 12.1 requires and gives the reason for: an offset held
+ * constant is silently wrong for half the year anywhere that observes a
+ * seasonal clock change, and nothing about the wrong half looks wrong.
+ *
+ * **The zone table is the runtime's own and is not carried here.** A table
+ * copied into this repository would be a second copy of a fact that changes
+ * several times a year by government decision, and a stale copy is wrong in the
+ * same invisible way a fixed offset is. The language's own standard date
+ * facilities carry that table, so they are what is asked. Nothing below reads a
+ * clock: the only instants that enter are the ones a script passed in, which is
+ * what `compiled-program.md` section 8.4 requires of everything except
+ * `chart.now()`.
+ *
+ * **Two engines agree only as far as their zone tables do**, and that is stated
+ * rather than hidden. Two engines holding the same table compute the same
+ * instants; two holding tables from different years can differ across a rule
+ * change a government made between them. That is true of every zone-aware
+ * calendar in existence, and the alternative, a table frozen in this package,
+ * is worse: it would be wrong for everyone rather than only across a change.
+ */
+import type { Civil } from './civil.js';
+
+/**
+ * The formatters, kept because building one is expensive and a study asks for
+ * the same zone on every bar.
+ *
+ * This is memoisation and not state: the answer for a zone is the same answer
+ * every time, nothing here is ever read back by a script, and clearing the map
+ * between two bars would change how long a chart took and nothing else. No
+ * state region holds any of it, so `compiled-program.md` section 2.11 has
+ * nothing to copy.
+ */
+const FORMATTERS = new Map<string, Intl.DateTimeFormat | null>();
+
+/**
+ * An area and a location, or the one name that is neither.
+ *
+ * `stdlib.md` section 12.1 requires an area and location name and OS6005 says
+ * in as many words that an abbreviation is not one, because several
+ * abbreviations mean two different offsets in different parts of the world.
+ * Runtimes disagree about which abbreviations they will quietly accept, so the
+ * rule is applied here rather than left to whichever database is installed: a
+ * script refused on one engine has to be refused on every engine. `UTC` is the
+ * one name with no area, and it names one offset everywhere.
+ */
+const AREA_AND_LOCATION = /^[A-Za-z][A-Za-z0-9+_-]*\/[A-Za-z][A-Za-z0-9+_/-]*$/;
+
+function formatterFor(zone: string): Intl.DateTimeFormat | null {
+  const held = FORMATTERS.get(zone);
+  if (held !== undefined) return held;
+  if (zone !== 'UTC' && !AREA_AND_LOCATION.test(zone)) {
+    FORMATTERS.set(zone, null);
+    return null;
+  }
+  let made: Intl.DateTimeFormat | null;
+  try {
+    made = new Intl.DateTimeFormat('en-US', {
+      timeZone: zone,
+      hourCycle: 'h23',
+      era: 'short',
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+    });
+  } catch {
+    // An unknown zone name, which is OS6005 at the call rather than a guess
+    // here. A name this runtime does not hold is not a name this engine can
+    // invent an offset for.
+    made = null;
+  }
+  FORMATTERS.set(zone, made);
+  return made;
+}
+
+/** Whether the runtime's zone table holds this name. */
+export function isKnownZone(zone: string): boolean {
+  return formatterFor(zone) !== null;
+}
+
+/** The civil fields an instant has in a zone, or nothing for an unknown zone. */
+export function fieldsIn(instant: number, zone: string): Civil | null {
+  const formatter = formatterFor(zone);
+  if (formatter === null || !Number.isFinite(instant)) return null;
+  const parts = formatter.formatToParts(new Date(instant));
+  const found: Record<string, string> = {};
+  for (const part of parts) found[part.type] = part.value;
+  const year = Number(found['year']);
+  const month = Number(found['month']);
+  const day = Number(found['day']);
+  const hour = Number(found['hour']);
+  const minute = Number(found['minute']);
+  const second = Number(found['second']);
+  if (!Number.isFinite(year) || !Number.isFinite(month) || !Number.isFinite(day)) return null;
+  if (!Number.isFinite(hour) || !Number.isFinite(minute) || !Number.isFinite(second)) return null;
+  // Before the common era the year is counted backwards and 1 BC is year 0 on
+  // the proleptic numbering the rest of this module uses.
+  const era = found['era'];
+  const signed = era === 'BC' || era === 'B' || era === 'BCE' ? 1 - year : year;
+  return { year: signed, month, day, hour, minute, second };
+}
+
+/** The instant a civil date and time names in UTC, with no zone applied. */
+export function utcInstantOf(fields: Civil): number {
+  const at = new Date(0);
+  // `setUTCFullYear` rather than `Date.UTC`, which reads a two digit year as
+  // nineteen hundred and something.
+  at.setUTCFullYear(fields.year, fields.month - 1, fields.day);
+  at.setUTCHours(fields.hour, fields.minute, fields.second, 0);
+  return at.getTime();
+}
+
+/** How far ahead of UTC a zone was at an instant, in milliseconds. */
+export function offsetAt(instant: number, zone: string): number | null {
+  const fields = fieldsIn(instant, zone);
+  if (fields === null) return null;
+  return utcInstantOf(fields) - instant;
+}
+
+/**
+ * The instant a wall clock reading names in a zone.
+ *
+ * A reading is not an instant until a zone is applied, and the offset to apply
+ * is the offset at the answer rather than at the reading, so this works the
+ * other way round: it takes the two offsets the zone had a day either side,
+ * builds the instant each one implies, and keeps the ones that read back as the
+ * reading it was given.
+ *
+ * Two readings have no single answer and both are settled here rather than left
+ * to an engine. **A reading the clock repeated**, the hour an autumn change
+ * gives back, has two instants that read back correctly, and the answer is the
+ * earlier of them: that is when a session opening at that clock time opens.
+ * **A reading the clock skipped**, the hour a spring change removes, has none,
+ * and the answer is the reading moved forward by the size of the gap, which is
+ * where that hour would have been; absence there would put a hole in a study
+ * one morning a year.
+ */
+export function instantOf(fields: Civil, zone: string): number | null {
+  const naive = utcInstantOf(fields);
+  const day = 86_400_000;
+  const before = offsetAt(naive - day, zone);
+  const after = offsetAt(naive + day, zone);
+  if (before === null || after === null) return null;
+
+  let answer: number | null = null;
+  for (const offset of before === after ? [before] : [before, after]) {
+    const candidate = naive - offset;
+    const actual = offsetAt(candidate, zone);
+    if (actual === null || naive - actual !== candidate) continue;
+    if (answer === null || candidate < answer) answer = candidate;
+  }
+  // No candidate reads back: the reading is inside a gap the clock skipped, and
+  // the offset in force before it is the one that moves it past the gap.
+  return answer ?? naive - before;
+}