@junoflow/testkit 0.6.0 → 0.9.0

package/src/time.js

@@ -0,0 +1,131 @@
+import { fail } from './assert.js';
+
+/**
+ * ctx.now()'s TimeResult for one instant in one timezone: a copy of buildNow in
+ * sdk/src/context.ts, which the testkit cannot import (the SDK is not
+ * published). test/time.test.js pins it against values captured from the SDK's
+ * own buildNow, so a change there that is not made here fails the table.
+ */
+export function timeResult(instantMs, timezone) {
+  const d = new Date(instantMs);
+  const fmt = new Intl.DateTimeFormat('en-US', {
+    timeZone: timezone,
+    hour: 'numeric',
+    minute: 'numeric',
+    second: 'numeric',
+    weekday: 'short',
+    month: 'numeric',
+    day: 'numeric',
+    // h23, as the SDK asks: hour12:false selects h24 in some ICU builds and
+    // renders midnight as 24.
+    hourCycle: 'h23',
+  });
+  const parts = Object.fromEntries(
+    fmt.formatToParts(d).map((p) => [p.type, p.value])
+  );
+  const weekdayMap = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
+  const hour = parseInt(parts.hour, 10);
+  const minute = parseInt(parts.minute, 10);
+  return {
+    iso: d.toISOString(),
+    timezone,
+    hour,
+    minute,
+    second: parseInt(parts.second, 10),
+    minute_of_day: hour * 60 + minute,
+    weekday: weekdayMap[parts.weekday] ?? 0,
+    month: parseInt(parts.month, 10),
+    day: parseInt(parts.day, 10),
+  };
+}
+
+/** Fails unless Intl knows the zone; the site setting is an IANA name. */
+export function assertTimezone(timezone) {
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone: timezone });
+  } catch {
+    fail(
+      `h.timezone(${JSON.stringify(timezone)}) — not an IANA timezone name (e.g. "Europe/Stockholm", "UTC")`
+    );
+  }
+}
+
+const WALL =
+  /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?$/;
+const OFFSET = /(?:Z|[+-]\d{2}:?\d{2})$/i;
+
+/** Fails unless iso is something resolveInstant can read. */
+export function assertISO(iso) {
+  if (typeof iso === 'string' && OFFSET.test(iso) && !isNaN(Date.parse(iso)))
+    return;
+  if (typeof iso === 'string' && WALL.test(iso)) return;
+  fail(
+    `h.now(${JSON.stringify(iso)}) — expected an ISO 8601 date-time: wall time in h.timezone() ` +
+      `("2026-10-04T18:42:00") or an instant with an offset ("2026-10-04T16:42:00Z")`
+  );
+}
+
+/**
+ * The instant h.now(iso) names. With an offset it is that instant. Without one
+ * it is a wall-clock time in `timezone`, resolved when the handler asks rather
+ * than when the test sets it, so `h.now(…).timezone(…)` reads in either order.
+ *
+ * A wall time the zone skips (spring forward) or passes twice (fall back) is
+ * refused rather than guessed: a test about the DST night is exactly the test
+ * that must say which instant it means.
+ */
+export function resolveInstant(iso, timezone) {
+  if (OFFSET.test(iso)) return Date.parse(iso);
+  const [, y, mo, d, h, mi, s = '0', ms = '0'] = WALL.exec(iso);
+  const wall = Date.UTC(+y, +mo - 1, +d, +h, +mi, +s, +ms.padEnd(3, '0'));
+
+  // The zone's offset a day either side of the wall time covers both sides of
+  // any transition near it; each offset proposes one instant, and only those
+  // whose wall time reads back as asked are real.
+  const day = 24 * 60 * 60 * 1000;
+  const candidates = new Set();
+  for (const probe of [wall - day, wall, wall + day]) {
+    const t = wall - offsetAt(probe, timezone);
+    if (wallAt(t, timezone) === wall) candidates.add(t);
+  }
+  const found = [...candidates].sort((a, b) => a - b);
+  if (found.length === 1) return found[0];
+  const hint = found.length
+    ? `it happens twice there (${found.map((t) => new Date(t).toISOString()).join(' and ')})`
+    : 'the clocks skip it there';
+  fail(
+    `h.now(${JSON.stringify(iso)}) is not one instant in ${timezone}: ${hint} — ` +
+      'give it an offset, e.g. h.now("2026-10-25T02:30:00+02:00")'
+  );
+}
+
+/** The wall-clock reading at instant t in timezone, as a UTC millisecond count. */
+function wallAt(t, timezone) {
+  const parts = Object.fromEntries(
+    new Intl.DateTimeFormat('en-US', {
+      timeZone: timezone,
+      year: 'numeric',
+      month: 'numeric',
+      day: 'numeric',
+      hour: 'numeric',
+      minute: 'numeric',
+      second: 'numeric',
+      hourCycle: 'h23',
+    })
+      .formatToParts(new Date(t))
+      .map((p) => [p.type, p.value])
+  );
+  return Date.UTC(
+    +parts.year,
+    +parts.month - 1,
+    +parts.day,
+    +parts.hour,
+    +parts.minute,
+    +parts.second,
+    new Date(t).getUTCMilliseconds()
+  );
+}
+
+function offsetAt(t, timezone) {
+  return wallAt(t, timezone) - t;
+}