@ggts-sh/spec 0.43.0

package/src/temporal-parse.ts

@@ -0,0 +1,259 @@
+/**
+ * Value-level temporal parsing: named engines (ISO / period / ordered), epoch,
+ * and the parseTemporal dispatcher. Exact format: temporal-parse-format.ts.
+ * Calendar foundation + public types: temporal-parse-core.ts.
+ *
+ * Column inference and authoring helpers live in temporal-column.ts and
+ * temporal.ts (facade). Public package exports re-export from temporal.ts.
+ */
+
+import {
+  DEFAULT_PARTS,
+  MONTH_DAY_REFERENCE_YEAR,
+  partsToEpoch,
+  temporalParseFailure,
+  timezoneValidationFailure,
+  withMetadata,
+  type DateParts,
+  type TemporalParseOptions,
+  type TemporalParseResult,
+  type TemporalParserName,
+  type TemporalParserSpec,
+  type TemporalPrecision,
+} from "./temporal-parse-core.js";
+import { exactFormatConfigurationError, parseExactFormat } from "./temporal-parse-format.js";
+
+// Stable public import path: re-export foundation surface from this module.
+export {
+  MONTH_DAY_REFERENCE_YEAR,
+  TEMPORAL_PARSER_NAMES,
+  TemporalParseError,
+  temporalParseFailure,
+  temporalImplementation,
+  type TemporalDisambiguation,
+  type TemporalKind,
+  type TemporalScaleKind,
+  type TemporalParseOptions,
+  type TemporalParseResult,
+  type TemporalParserName,
+  type TemporalParserSpec,
+  type TemporalPrecision,
+} from "./temporal-parse-core.js";
+export { TemporalParserSpecSchema } from "./temporal-parse-schema.js";
+
+const ISO_RE =
+  /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,9}))?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+const YEAR_RE = /^\d{4}$/;
+const YM_RE = /^(\d{4})[-/.](\d{1,2})$/;
+const MY_RE = /^(\d{1,2})[-/.](\d{4})$/;
+const YQ_RE = /^(\d{4})[-/.]?Q([1-4])$/i;
+// Bare month-day, ISO recurring `--MM-DD`, or a full date whose year is dropped.
+const MD_RE = /^(?:--)?(?:(\d{4})[-/.])?(\d{1,2})[-/.](\d{1,2})$/;
+const ORDERED_DATE_RE =
+  /^(\d{1,4})([-/.])(\d{1,4})\2(\d{1,4})(?:[T ](\d{2}):(\d{2})(?::(\d{2}))?)?$/;
+
+function parseISO(value: string, options: TemporalParseOptions): TemporalParseResult {
+  const match = ISO_RE.exec(value);
+  if (match === null)
+    return temporalParseFailure("expected strict ISO YYYY-MM-DD with an optional time and offset");
+  const hasTime = match[4] !== undefined;
+  const fraction = match[7];
+  const parts: DateParts = {
+    year: Number(match[1]),
+    month: Number(match[2]),
+    day: Number(match[3]),
+    hour: Number(match[4] ?? 0),
+    minute: Number(match[5] ?? 0),
+    second: Number(match[6] ?? 0),
+    millisecond: fraction === undefined ? 0 : Number(fraction.padEnd(3, "0").slice(0, 3)),
+  };
+  let precision: TemporalPrecision = "date";
+  if (hasTime) {
+    precision = "minute";
+    if (match[6] !== undefined) precision = "second";
+    if (fraction !== undefined) precision = "millisecond";
+  }
+  return withMetadata(
+    partsToEpoch(parts, options, match[8], hasTime ? "datetime" : "date"),
+    hasTime ? "datetime" : "date",
+    precision,
+  );
+}
+
+function parsePeriod(
+  value: string,
+  parser: "year" | "ym" | "my" | "yq",
+  options: TemporalParseOptions,
+): TemporalParseResult {
+  if (parser === "year") {
+    if (!YEAR_RE.test(value)) return temporalParseFailure("expected exactly four year digits");
+    return withMetadata(
+      partsToEpoch({ year: Number(value), ...DEFAULT_PARTS }, options, undefined, "date"),
+      "date",
+      "year",
+    );
+  }
+  const match =
+    parser === "ym" ? YM_RE.exec(value) : parser === "my" ? MY_RE.exec(value) : YQ_RE.exec(value);
+  if (match === null) return temporalParseFailure(`value does not match ${parser}`);
+  const year = Number(parser === "my" ? match[2] : match[1]);
+  const month =
+    parser === "yq"
+      ? (Number(match[2]) - 1) * 3 + 1
+      : Number(parser === "my" ? match[1] : match[2]);
+  return withMetadata(
+    partsToEpoch(
+      { year, month, day: 1, hour: 0, minute: 0, second: 0, millisecond: 0 },
+      options,
+      undefined,
+      "date",
+    ),
+    "date",
+    parser === "yq" ? "quarter" : "month",
+  );
+}
+
+/**
+ * Month-day without a year: `MM-DD`, ISO recurring `--MM-DD`, or a full date
+ * whose year is discarded. Everything resolves into MONTH_DAY_REFERENCE_YEAR,
+ * so the same calendar day from any two years is the same instant.
+ *
+ * Month and day survive; day-of-year does not. That is deliberate — projecting
+ * day-of-year moves every leap-year observation by a day.
+ */
+function parseMonthDay(value: string, options: TemporalParseOptions): TemporalParseResult {
+  const match = MD_RE.exec(value);
+  if (match === null)
+    return temporalParseFailure(
+      "expected MM-DD, --MM-DD, or a full date to take the month-day from",
+    );
+  return withMetadata(
+    partsToEpoch(
+      {
+        year: MONTH_DAY_REFERENCE_YEAR,
+        month: Number(match[2]),
+        day: Number(match[3]),
+        hour: 0,
+        minute: 0,
+        second: 0,
+        millisecond: 0,
+      },
+      options,
+      undefined,
+      "date",
+    ),
+    "date",
+    "date",
+  );
+}
+
+/** Ordered date-family base names (ymd/ydm/…); used by parseOrdered and column auto candidates. */
+export const DATE_ORDERS = new Set(["ymd", "ydm", "mdy", "myd", "dmy", "dym"]);
+
+function parseOrdered(
+  value: string,
+  parser: TemporalParserName,
+  options: TemporalParseOptions,
+): TemporalParseResult {
+  const [order, timePrecision] = parser.split("_") as [string, string | undefined];
+  if (!DATE_ORDERS.has(order)) return temporalParseFailure(`unsupported ordered parser ${parser}`);
+  const match = ORDERED_DATE_RE.exec(value);
+  if (match === null) return temporalParseFailure(`value does not match ${parser}`);
+  const values = [Number(match[1]), Number(match[3]), Number(match[4])];
+  const mapped: Record<string, number> = {};
+  for (let index = 0; index < order.length; index++) mapped[order[index]!] = values[index]!;
+  const hasMinute = match[5] !== undefined;
+  const hasSecond = match[7] !== undefined;
+  if (timePrecision === undefined && hasMinute)
+    return temporalParseFailure(`${parser} does not accept a time`);
+  if (timePrecision === "hm" && (!hasMinute || hasSecond))
+    return temporalParseFailure(`${parser} requires hour and minute only`);
+  if (timePrecision === "hms" && !hasSecond)
+    return temporalParseFailure(`${parser} requires hour, minute, and second`);
+  const parts: DateParts = {
+    year: mapped["y"]!,
+    month: mapped["m"]!,
+    day: mapped["d"]!,
+    hour: Number(match[5] ?? 0),
+    minute: Number(match[6] ?? 0),
+    second: Number(match[7] ?? 0),
+    millisecond: 0,
+  };
+  const precision: TemporalPrecision =
+    timePrecision === "hm" ? "minute" : timePrecision === "hms" ? "second" : "date";
+  return withMetadata(
+    partsToEpoch(parts, options, undefined, timePrecision === undefined ? "date" : "datetime"),
+    timePrecision === undefined ? "date" : "datetime",
+    precision,
+  );
+}
+
+/** Returns a stable reason when parser options are invalid independent of data. */
+export function temporalParserConfigurationError(
+  parser: TemporalParserSpec | "auto",
+  options: TemporalParseOptions = {},
+): string | null {
+  const timezoneFailure = timezoneValidationFailure(options.timezone);
+  if (timezoneFailure !== null && !timezoneFailure.ok) return timezoneFailure.reason;
+  if (parser === "auto" || typeof parser === "string" || "epoch" in parser) return null;
+  return exactFormatConfigurationError(parser.format, options);
+}
+
+export function parseTemporal(
+  value: unknown,
+  parser: TemporalParserSpec,
+  options: TemporalParseOptions = {},
+): TemporalParseResult {
+  const timezoneFailure = timezoneValidationFailure(options.timezone);
+  if (timezoneFailure !== null) return timezoneFailure;
+  if (value instanceof Date) {
+    const epochMs = value.getTime();
+    return Number.isFinite(epochMs)
+      ? { ok: true, epochMs, kind: "datetime", precision: "millisecond" }
+      : temporalParseFailure("invalid Date value");
+  }
+  if (typeof parser === "object" && "epoch" in parser) {
+    return parseEpoch(value, parser.epoch);
+  }
+  if (typeof value !== "string" || value.trim() !== value)
+    return temporalParseFailure("expected an exact temporal string");
+  if (typeof parser === "object") return parseExactFormat(value, parser.format, options);
+  if (parser === "iso") return parseISO(value, options);
+  if (parser === "md") return parseMonthDay(value, options);
+  if (parser === "year" || parser === "ym" || parser === "my" || parser === "yq") {
+    return parsePeriod(value, parser, options);
+  }
+  return parseOrdered(value, parser, options);
+}
+
+function parseEpoch(value: unknown, unit: "seconds" | "milliseconds"): TemporalParseResult {
+  if (
+    (typeof value !== "number" && typeof value !== "string") ||
+    (typeof value === "string" && value.trim() === "")
+  ) {
+    return temporalParseFailure(`expected epoch ${unit}`);
+  }
+  const numeric = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(numeric)) return temporalParseFailure(`expected finite epoch ${unit}`);
+  const epochMs = unit === "seconds" ? numeric * 1000 : numeric;
+  return Number.isFinite(new Date(epochMs).getTime())
+    ? { ok: true, epochMs, kind: "datetime", precision: "millisecond" }
+    : temporalParseFailure("instant is outside the supported range");
+}
+
+function fnv1a(value: string): string {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < value.length; index++) {
+    const codePoint = value.codePointAt(index)!;
+    hash ^= codePoint;
+    hash = Math.imul(hash, 0x01000193);
+    if (codePoint > 0xffff) index++;
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+export function canonicalTemporalParserKey(parser: TemporalParserSpec): string {
+  if (typeof parser === "string") return `name:${parser}`;
+  if ("epoch" in parser) return `epoch:${parser.epoch}`;
+  return `format:${fnv1a(parser.format)}:${JSON.stringify(parser.format)}`;
+}

package/src/temporal-polyfill.ts

@@ -0,0 +1,27 @@
+/**
+ * Sole module that statically imports `@js-temporal/polyfill`.
+ *
+ * Lean chart graphs (`@ggts-sh/core/render` + `@ggts-sh/spec/portable`) must
+ * never import this file — identity / numeric charts then keep Temporal out of
+ * the client bundle. Full temporal paths call {@link ensureTemporalPolyfill}
+ * (via `installTemporal` / agent `validate()`) before parsing non-UTC zones.
+ *
+ * Lifecycle (Hadley lesson 13; meanings in CONTRIBUTING.md): tags collected
+ * into lifecycle.json by scripts/gen-lifecycle.ts.
+ */
+// @lifecycle-default experimental
+import { Temporal as PolyfillTemporal } from "@js-temporal/polyfill";
+
+import { registerTemporalPolyfill } from "./temporal-parse-core.js";
+
+let ensured = false;
+
+/** Register the package polyfill when native `globalThis.Temporal` is absent. Idempotent. */
+export function ensureTemporalPolyfill(): void {
+  if (ensured) return;
+  ensured = true;
+  registerTemporalPolyfill(PolyfillTemporal);
+}
+
+// Side-effect for direct importers of this module (tests / explicit installs).
+ensureTemporalPolyfill();

package/src/temporal-ticks.ts

@@ -0,0 +1,312 @@
+/**
+ * Calendar-aligned temporal tick generation for portable interval strings.
+ * Interval parse/schemas: temporal-interval.ts. Facade: temporal-guides.ts.
+ */
+
+import {
+  temporalImplementation,
+  type TemporalDisambiguation,
+  type TemporalScaleKind,
+} from "./temporal-parse.js";
+import {
+  MAX_TEMPORAL_MAJOR_TICKS,
+  parseTemporalInterval,
+  TemporalIntervalError,
+  type TemporalInterval,
+  type TemporalIntervalUnit,
+  type TemporalWeekStart,
+} from "./temporal-interval.js";
+
+interface TemporalTickOptions {
+  kind: TemporalScaleKind;
+  timezone?: string;
+  weekStart?: TemporalWeekStart;
+  disambiguation?: TemporalDisambiguation;
+  maxTicks?: number;
+}
+
+const FIXED_UNIT_MS: Readonly<Partial<Record<TemporalIntervalUnit, number>>> = {
+  millisecond: 1,
+  second: 1_000,
+  minute: 60_000,
+};
+const HOUR_MS = 3_600_000;
+const DAY_MS = 86_400_000;
+
+const WEEKDAY_NUMBER: Readonly<Record<TemporalWeekStart, number>> = {
+  monday: 1,
+  tuesday: 2,
+  wednesday: 3,
+  thursday: 4,
+  friday: 5,
+  saturday: 6,
+  sunday: 7,
+};
+
+function fixedIntervalTicks(
+  min: number,
+  max: number,
+  intervalMs: number,
+  limit: number,
+  key: string,
+  offsetMs = 0,
+): number[] {
+  const first = Math.ceil((min - offsetMs) / intervalMs) * intervalMs + offsetMs;
+  const result: number[] = [];
+  for (let value = first; value <= max; value += intervalMs) {
+    if (result.length >= limit) {
+      throw new TemporalIntervalError(key, `tick count exceeds the ${limit}-tick limit`);
+    }
+    result.push(value);
+    if (!Number.isSafeInteger(value + intervalMs) && value + intervalMs <= max) {
+      throw new TemporalIntervalError(key, "tick progression exceeds safe epoch arithmetic");
+    }
+  }
+  return result;
+}
+
+function utcEpoch(year: number, monthIndex: number, day = 1): number {
+  const date = new Date(0);
+  date.setUTCHours(0, 0, 0, 0);
+  date.setUTCFullYear(year, monthIndex, day);
+  return date.getTime();
+}
+
+function utcCalendarTicks(
+  min: number,
+  max: number,
+  interval: TemporalInterval,
+  weekStart: number,
+  limit: number,
+): number[] {
+  if (interval.unit === "hour") {
+    return fixedIntervalTicks(min, max, HOUR_MS * interval.step, limit, interval.key);
+  }
+  if (interval.unit === "day") {
+    return fixedIntervalTicks(min, max, DAY_MS * interval.step, limit, interval.key);
+  }
+  if (interval.unit === "week") {
+    // Epoch day zero was Thursday (Temporal day 4). Align to the requested weekday.
+    const offsetDays = (weekStart - 4 + 7) % 7;
+    return fixedIntervalTicks(
+      min,
+      max,
+      DAY_MS * 7 * interval.step,
+      limit,
+      interval.key,
+      offsetDays * DAY_MS,
+    );
+  }
+
+  const start = new Date(min);
+  let cursor: number;
+  let add: (value: number) => number;
+  if (interval.unit === "month" || interval.unit === "quarter") {
+    const stepMonths = interval.step * (interval.unit === "quarter" ? 3 : 1);
+    const absoluteMonth = start.getUTCFullYear() * 12 + start.getUTCMonth();
+    let aligned = Math.floor(absoluteMonth / stepMonths) * stepMonths;
+    cursor = utcEpoch(Math.floor(aligned / 12), aligned % 12);
+    if (cursor < min) aligned += stepMonths;
+    cursor = utcEpoch(Math.floor(aligned / 12), aligned % 12);
+    add = (value) => {
+      const date = new Date(value);
+      const next = date.getUTCFullYear() * 12 + date.getUTCMonth() + stepMonths;
+      return utcEpoch(Math.floor(next / 12), next % 12);
+    };
+  } else {
+    let year = Math.floor(start.getUTCFullYear() / interval.step) * interval.step;
+    cursor = utcEpoch(year, 0);
+    if (cursor < min) year += interval.step;
+    cursor = utcEpoch(year, 0);
+    add = (value) => utcEpoch(new Date(value).getUTCFullYear() + interval.step, 0);
+  }
+
+  const result: number[] = [];
+  while (cursor <= max) {
+    if (result.length >= limit) {
+      throw new TemporalIntervalError(interval.key, `tick count exceeds the ${limit}-tick limit`);
+    }
+    result.push(cursor);
+    cursor = add(cursor);
+  }
+  return result;
+}
+
+/**
+ * Generate bounded, calendar-aligned epoch-millisecond ticks for one explicit
+ * temporal interval. Date-kind ticks always use UTC civil boundaries.
+ */
+export function temporalIntervalTicks(
+  min: number,
+  max: number,
+  intervalInput: string | TemporalInterval,
+  options: TemporalTickOptions,
+): number[] {
+  const interval =
+    typeof intervalInput === "string" ? parseTemporalInterval(intervalInput) : intervalInput;
+  const limit = options.maxTicks ?? MAX_TEMPORAL_MAJOR_TICKS;
+  if (!Number.isFinite(min) || !Number.isFinite(max) || max < min || limit < 1) return [];
+
+  const fixedMs = FIXED_UNIT_MS[interval.unit];
+  if (fixedMs !== undefined) {
+    return fixedIntervalTicks(min, max, fixedMs * interval.step, limit, interval.key);
+  }
+
+  const timezone =
+    options.kind === "date" || options.kind === "time" ? "UTC" : (options.timezone ?? "UTC");
+  const weekStart = WEEKDAY_NUMBER[options.weekStart ?? "monday"];
+  if (timezone === "UTC" || timezone === "Etc/UTC" || timezone === "Z") {
+    return utcCalendarTicks(min, max, interval, weekStart, limit);
+  }
+  return zonedCalendarTicks(min, max, interval, timezone, weekStart, limit);
+}
+
+function zonedCalendarTicks(
+  min: number,
+  max: number,
+  interval: TemporalInterval,
+  timezone: string,
+  weekStart: number,
+  limit: number,
+): number[] {
+  const Temporal = temporalImplementation();
+  const current = Temporal.Instant.fromEpochMilliseconds(min).toZonedDateTimeISO(timezone);
+  const parts = {
+    year: current.year,
+    month: current.month,
+    day: current.day,
+    hour: current.hour,
+    minute: current.minute,
+    second: current.second,
+    millisecond: current.millisecond,
+  };
+
+  const absoluteCivilDay = Math.floor(utcEpoch(parts.year, parts.month - 1, parts.day) / DAY_MS);
+  const plainAtCivilDay = (day: number) => {
+    const date = new Date(day * DAY_MS);
+    return Temporal.PlainDateTime.from({
+      year: date.getUTCFullYear(),
+      month: date.getUTCMonth() + 1,
+      day: date.getUTCDate(),
+      hour: 0,
+      minute: 0,
+      second: 0,
+      millisecond: 0,
+    });
+  };
+
+  let plain;
+  switch (interval.unit) {
+    case "hour": {
+      const hour = Math.floor(parts.hour / interval.step) * interval.step;
+      plain = Temporal.PlainDateTime.from({ ...parts, hour, minute: 0, second: 0, millisecond: 0 });
+      break;
+    }
+    case "day": {
+      const alignedDay = Math.floor(absoluteCivilDay / interval.step) * interval.step;
+      plain = plainAtCivilDay(alignedDay);
+      break;
+    }
+    case "week": {
+      // Epoch day zero was Thursday (Temporal day 4). Match the UTC path's
+      // weekday offset and multi-week phase in local civil-date space.
+      const offsetDays = (weekStart - 4 + 7) % 7;
+      const stepDays = interval.step * 7;
+      const alignedDay =
+        Math.floor((absoluteCivilDay - offsetDays) / stepDays) * stepDays + offsetDays;
+      plain = plainAtCivilDay(alignedDay);
+      break;
+    }
+    case "month":
+    case "quarter": {
+      const stepMonths = interval.step * (interval.unit === "quarter" ? 3 : 1);
+      const absoluteMonth = parts.year * 12 + parts.month - 1;
+      const alignedMonth = Math.floor(absoluteMonth / stepMonths) * stepMonths;
+      const monthIndex = ((alignedMonth % 12) + 12) % 12;
+      plain = Temporal.PlainDateTime.from({
+        ...parts,
+        year: Math.floor(alignedMonth / 12),
+        month: monthIndex + 1,
+        day: 1,
+        hour: 0,
+        minute: 0,
+        second: 0,
+        millisecond: 0,
+      });
+      break;
+    }
+    case "year": {
+      const year = Math.floor(parts.year / interval.step) * interval.step;
+      plain = Temporal.PlainDateTime.from({
+        ...parts,
+        year,
+        month: 1,
+        day: 1,
+        hour: 0,
+        minute: 0,
+        second: 0,
+        millisecond: 0,
+      });
+      break;
+    }
+    default:
+      return [];
+  }
+
+  const advancePlain = (value: typeof plain): typeof plain => {
+    switch (interval.unit) {
+      case "hour":
+        return value.add({ hours: interval.step });
+      case "day":
+        return value.add({ days: interval.step });
+      case "week":
+        return value.add({ weeks: interval.step });
+      case "month":
+        return value.add({ months: interval.step });
+      case "quarter":
+        return value.add({ months: interval.step * 3 });
+      case "year":
+        return value.add({ years: interval.step });
+      default:
+        return value;
+    }
+  };
+  const project = (value: typeof plain) =>
+    value.toZonedDateTime(timezone, { disambiguation: "compatible" });
+
+  // Generated civil boundaries are synthetic, not parsed source values. Advance
+  // the aligned civil cursor before each projection so a gap adjustment (for
+  // example 02:00 -> 03:00) cannot shift every later multi-hour boundary.
+  // Source parsing has already applied the author's disambiguation contract.
+  let cursor = plain;
+  let tick = project(cursor);
+  if (tick.epochMilliseconds < min) {
+    cursor = advancePlain(cursor);
+    tick = project(cursor);
+  }
+
+  const result: number[] = [];
+  let stalled = 0;
+  while (tick.epochMilliseconds <= max) {
+    const epoch = tick.epochMilliseconds;
+    if (epoch >= min && result.at(-1) !== epoch) {
+      if (result.length >= limit) {
+        throw new TemporalIntervalError(interval.key, `tick count exceeds the ${limit}-tick limit`);
+      }
+      result.push(epoch);
+    }
+    const nextCursor = advancePlain(cursor);
+    const next = project(nextCursor);
+    if (next.epochMilliseconds <= epoch) {
+      stalled += 1;
+      if (stalled >= 2) {
+        throw new TemporalIntervalError(interval.key, "calendar progression did not advance");
+      }
+    } else {
+      stalled = 0;
+    }
+    cursor = nextCursor;
+    tick = next;
+  }
+  return result;
+}