ident

16.1 KB

1. // hl:time — the clock AND time as an event source. JS twin of
2. // plugins/time/time.zig, and the one file BOTH other realms run: the JavaScript
3. // transpiler target copies it into `hl-modules/time.js`, and hl:web serves it to
4. // the BROWSER as `hl-time.js` (hl:time declares no `"realm": "server"`, so a
5. // client handler may reach it — plugins/web/web_framework.hl `packagePaths`).
6. //
7. // Parity contract with the native plugin:
8. // now() → epoch milliseconds, integer-valued
9. // timestamp(ms?) → "YYYY-MM-DDTHH:MM:SS.mmmZ", exactly 24 chars, UTC.
10. // No argument (or a non-number) means "now"; an epoch-ms
11. // argument renders THAT instant, which is what makes the
12. // call testable — timestamp(0) is always the epoch.
13. // monotonic() → nanoseconds off a monotonic counter. Origin arbitrary;
14. // only differences are meaningful.
15. // every(s) → a repeating Timer; `on t.tick()` until `t.stop()`
16. // after(s) → a one-shot Timer, `s` seconds from now
17. // until(epochMs) → a one-shot Timer at that instant
18. // sleep(s) → BLOCKING. Yes, in a browser too — see below.
19. // offset / local / fromLocal / localTimestamp / isZone → time zones, ticket #5
20. // (the section below says how Intl stands in for TZif)
22. export function now() { return Date.now(); }
24. export function timestamp(ms) {
25. // Date#toISOString already emits exactly the native format for in-range
26. // instants. Pre-epoch values are clamped the same way the native plugin
27. // clamps them (std.time.epoch is u64-only, so 1970 is the floor on both
28. // sides and the two targets must agree on what happens below it).
29. let t = typeof ms === 'number' && Number.isFinite(ms) ? Math.trunc(ms) : Date.now();
30. if (t < 0) t = 0;
31. return new Date(t).toISOString();
32. }
34. export function monotonic() {
35. // process.hrtime.bigint() is Node's CLOCK_MONOTONIC. Converted to a plain
36. // Number because Hybriel has no bigint; same f64 caveat as the native side
37. // (exact for the first ~104 days of counter uptime).
38. if (typeof process !== 'undefined' && process.hrtime && process.hrtime.bigint) {
39. return Number(process.hrtime.bigint());
40. }
41. // Browser/other host fallback: performance.now() is ms with sub-ms
42. // resolution off a monotonic origin.
43. return Math.round(performance.now() * 1e6);
44. }
46. // ═══════════════════════════════════════════════════════════════════════════
47. // TIME ZONES (ticket #5) — the twin of the TIME ZONES half of time.zig
48. // ═══════════════════════════════════════════════════════════════════════════
49. //
50. // The native plugin reads the system's TZif files; this half asks Intl, which
51. // every browser and Node carry. The ONLY question put to Intl is the offset in
52. // force at an instant; `local`, `fromLocal` and `localTimestamp` are the same
53. // arithmetic time.zig runs, step for step, so the two realms cannot drift on
54. // anything but the zone data itself.
55. //
56. // THE OFFSET FROM INTL. `formatToParts` hands back the wall clock; the offset is
57. // that reading minus UTC. Only the DAY and the time of day are read, never the
58. // year: Intl's `en-US` calendar is Julian before 1582 and prints an era-less
59. // |year| before year 1, and an offset is always under a day, so "same day of
60. // the month, next, or previous" is all the date there is to know.
62. const MAX_MS = 8.64e15;
63. const BAD_INSTANT = 'hl:time: pass the instant in epoch milliseconds (what now() returns)';
64. const zoneFormats = new Map();
66. function floorDiv(a, b) { return Math.floor(a / b); }
67. function mod(a, b) { return a - Math.floor(a / b) * b; }
69. function daysFromCivil(y0, m, d) {
70. const y = m <= 2 ? y0 - 1 : y0;
71. const era = floorDiv(y, 400);
72. const yoe = y - era * 400;
73. const mp = mod(m + 9, 12);
74. const doy = floorDiv(153 * mp + 2, 5);
75. const doe = yoe * 365 + floorDiv(yoe, 4) - floorDiv(yoe, 100) + doy;
76. return era * 146097 + doe - 719468 + (d - 1);
77. }
79. function civilFromDays(z0) {
80. const z = z0 + 719468;
81. const era = floorDiv(z, 146097);
82. const doe = z - era * 146097;
83. const yoe = floorDiv(doe - floorDiv(doe, 1460) + floorDiv(doe, 36524) - floorDiv(doe, 146096), 365);
84. const doy = doe - (365 * yoe + floorDiv(yoe, 4) - floorDiv(yoe, 100));
85. const mp = floorDiv(5 * doy + 2, 153);
86. const d = doy - floorDiv(153 * mp + 2, 5) + 1;
87. const m = mp < 10 ? mp + 3 : mp - 9;
88. return { y: m <= 2 ? yoe + era * 400 + 1 : yoe + era * 400, m, d };
89. }
91. /** The same shape rule as time.zig's `plausibleName`: Intl also takes offsets
92. * ('+01:00') and is case-blind, and the system database is neither. */
93. function plausibleName(name) {
94. if (typeof name !== 'string' || name.length === 0 || name.length > 64) return false;
95. if (!/^[A-Za-z][A-Za-z0-9/_+-]*$/.test(name)) return false;
96. if (name.includes('//') || name.endsWith('/')) return false;
97. if (name.startsWith('posix/') || name.startsWith('right/')) return false;
98. return name !== 'posixrules' && name !== 'localtime' && name !== 'Factory';
99. }
101. function zoneFormat(name) {
102. if (zoneFormats.has(name)) return zoneFormats.get(name);
103. let f = null;
104. if (plausibleName(name)) {
105. try {
106. f = new Intl.DateTimeFormat('en-US', {
107. timeZone: name, hourCycle: 'h23',
108. day: 'numeric', hour: 'numeric', minute: 'numeric', second: 'numeric',
109. });
110. // a case variant of a real name ('europe/vienna') is accepted by Intl
111. // and unknown to the file system — refuse it on this side as well
112. const resolved = f.resolvedOptions().timeZone;
113. if (resolved !== name && resolved.toLowerCase() === name.toLowerCase()) f = null;
114. } catch { f = null; }
115. }
116. if (zoneFormats.size < 4096) zoneFormats.set(name, f);
117. return f;
118. }
120. function zoneArg(zone) {
121. if (typeof zone !== 'string') throw new Error("hl:time: pass the time zone as an IANA name, e.g. 'Europe/Vienna'");
122. const f = zoneFormat(zone);
123. if (!f) throw new Error(`hl:time: unknown time zone '${zone.length > 64 ? zone.slice(0, 64) : zone}'`);
124. return f;
125. }
127. function instantArg(ms) {
128. if (typeof ms !== 'number' || !(ms <= MAX_MS && ms >= -MAX_MS)) throw new Error(BAD_INSTANT);
129. return Math.floor(ms);
130. }
132. function offsetAtMs(f, ms) {
133. const secs = floorDiv(ms, 1000);
134. let day = 0, wall = 0;
135. for (const p of f.formatToParts(secs * 1000)) {
136. const v = Number(p.value);
137. if (p.type === 'day') day = v;
138. else if (p.type === 'hour') wall += v * 3600;
139. else if (p.type === 'minute') wall += v * 60;
140. else if (p.type === 'second') wall += v;
141. }
142. const utcDays = floorDiv(secs, 86400);
143. let off = wall - (secs - utcDays * 86400);
144. if (day !== civilFromDays(utcDays).d) off += off < 0 ? 86400 : -86400;
145. return off;
146. }
148. /** Seconds east of UTC in force in `zone` at the instant `ms`. */
149. export function offset(ms, zone) {
150. const t = instantArg(ms);
151. return offsetAtMs(zoneArg(zone), t);
152. }
154. /** The wall-clock reading in `zone` at `ms` — time.zig `hl_time_local`. */
155. export function local(ms, zone) {
156. const t = instantArg(ms);
157. const off = offsetAtMs(zoneArg(zone), t);
158. const lt = t + off * 1000;
159. const days = floorDiv(lt, 86400000);
160. const inDay = lt - days * 86400000;
161. const c = civilFromDays(days);
162. return {
163. year: c.y, month: c.m, day: c.d,
164. hour: floorDiv(inDay, 3600000), minute: mod(floorDiv(inDay, 60000), 60), second: mod(floorDiv(inDay, 1000), 60),
165. millisecond: mod(inDay, 1000), weekday: mod(days + 3, 7) + 1,
166. offset: off,
167. };
168. }
170. const BAD_FIELDS = 'hl:time fromLocal: every field must be a Number (year is required)';
172. function fieldNumber(o, key, dflt) {
173. const v = o[key];
174. if (v === undefined || v === null) return dflt;
175. if (typeof v !== 'number' || !(Math.abs(v) < 1e12)) throw new Error(BAD_FIELDS);
176. return Math.floor(v);
177. }
179. /** The instant a wall-clock reading in `zone` names — time.zig `fromWall`:
180. * a FOLD answers the earlier instant, a GAP moves forward by its length. */
181. export function fromLocal(fields, zone) {
182. if (fields === null || typeof fields !== 'object') {
183. throw new Error('hl:time fromLocal: pass the fields as { year, month, day, hour, minute, second, millisecond }');
184. }
185. const f = zoneArg(zone);
186. const y = fieldNumber(fields, 'year', NaN);
187. if (Number.isNaN(y)) throw new Error(BAD_FIELDS);
188. const mo = fieldNumber(fields, 'month', 1), d = fieldNumber(fields, 'day', 1);
189. const h = fieldNumber(fields, 'hour', 0), mi = fieldNumber(fields, 'minute', 0);
190. const s = fieldNumber(fields, 'second', 0), milli = fieldNumber(fields, 'millisecond', 0);
191. const m0 = mo - 1;
192. const wall = daysFromCivil(y + floorDiv(m0, 12), mod(m0, 12) + 1, d) * 86400000 +
193. h * 3600000 + mi * 60000 + s * 1000 + milli;
194. if (Math.abs(wall) > MAX_MS + 86400000) throw new Error(BAD_INSTANT);
195. const before = offsetAtMs(f, wall - 86400000);
196. const after = offsetAtMs(f, wall + 86400000);
197. const a = wall - before * 1000, b = wall - after * 1000;
198. const aOk = offsetAtMs(f, a) === before, bOk = offsetAtMs(f, b) === after;
199. const ms = aOk && bOk ? Math.min(a, b) : aOk ? a : bOk ? b : a;
200. if (Math.abs(ms) > MAX_MS) throw new Error(BAD_INSTANT);
201. return ms;
202. }
204. const pad = (n, w) => String(n).padStart(w, '0');
206. /** ISO-8601 in `zone`: "YYYY-MM-DDTHH:MM:SS.mmm+HH:MM" (":SS" on the offset only
207. * when it has seconds, i.e. local mean time). */
208. export function localTimestamp(ms, zone) {
209. const t = instantArg(ms);
210. const off = offsetAtMs(zoneArg(zone), t);
211. const lt = t + off * 1000;
212. const days = floorDiv(lt, 86400000);
213. const inDay = lt - days * 86400000;
214. const c = civilFromDays(days);
215. const year = c.y >= 0 && c.y <= 9999 ? pad(c.y, 4) : (c.y < 0 ? '-' : '+') + pad(Math.abs(c.y), 6);
216. const a = Math.abs(off);
217. return year + '-' + pad(c.m, 2) + '-' + pad(c.d, 2) + 'T' +
218. pad(floorDiv(inDay, 3600000), 2) + ':' + pad(floorDiv(inDay, 60000) % 60, 2) + ':' +
219. pad(floorDiv(inDay, 1000) % 60, 2) + '.' + pad(inDay % 1000, 3) +
220. (off < 0 ? '-' : '+') + pad(floorDiv(a, 3600), 2) + ':' + pad(floorDiv(a, 60) % 60, 2) +
221. (a % 60 !== 0 ? ':' + pad(a % 60, 2) : '');
222. }
224. /** True when this realm's zone database (Intl) knows the name. */
225. export function isZone(name) {
226. return typeof name === 'string' && zoneFormat(name) !== null;
227. }
229. // ═══════════════════════════════════════════════════════════════════════════
230. // TIME AS AN EVENT SOURCE (mission 254)
231. // ═══════════════════════════════════════════════════════════════════════════
232. //
233. // THE FLOOR IS THE SAME NUMBER AS THE NATIVE PLUGIN'S, and this is the realm
234. // that sets it. Server-side a timerfd carries nanoseconds and the event loop
235. // blocks on it, so there is no floor there at all; the browser has one, and it
236. // was MEASURED rather than quoted from the spec — tests/browser/tests/66-timers.mjs
237. // drives a real page and prints the number it measured on every run. HTML's
238. // timer nesting rule clamps a chained `setTimeout(…, 0)` to 4ms from the fifth
239. // nesting level, and a `setInterval` asked for 1ms delivers ~4ms periods.
240. //
241. // The same `on t.tick()` handler is meant to run in both realms, so `every(0.001)`
242. // must not mean two different things depending on where it ran: both sides raise
243. // anything below the floor to it. (plugins/time/time.zig FLOOR_NS = 4_000_000.)
244. export const TIMER_FLOOR_SECONDS = 0.004;
246. /** Monotonic milliseconds, fractional. `performance` is a global in Node ≥16 and
247. * in every browser; `Date.now()` is the last-resort fallback and is not
248. * monotonic, which only costs accuracy across a clock adjustment. */
249. function monoMs() {
250. if (typeof performance !== 'undefined' && performance.now) return performance.now();
251. return Date.now();
252. }
254. /** ONE ARMED TIMER — the twin of plugins/time/Timer.hl.
255. *
256. * `on t.tick()` reaches this through `__hlOn`, which is the ONE registration
257. * protocol both JS realms use: the transpiler target's `hlScopedBus`
258. * (js/src/runtime/runtime.js) and hl:web's client runtime (hl-core.js
259. * `__hlBindSources`) each end up calling it with the event name and a handler.
260. * A plugin object is not an hl class instance and has no `constructor.__events__`,
261. * so it could not otherwise be the target of an instance-scoped handler.
262. *
263. * SCHEDULED FROM THE ORIGIN, like the native half: each round's delay is
264. * computed against `origin + n × period`, never `period` from where the last
265. * handler finished, so the handler's own runtime does not accumulate. A round
266. * the host was too busy to deliver is SKIPPED rather than queued — a periodic
267. * timer that owes you a backlog is a stampede.
268. *
269. * A CHAINED `setTimeout` RATHER THAN `setInterval`, for the same reason: the
270. * chain lets each delay be recomputed from the origin, and `setInterval`'s
271. * behaviour when a callback overruns its period differs between hosts. */
272. class HlTimer {
273. constructor(seconds, repeating) {
274. this.seconds = Math.max(TIMER_FLOOR_SECONDS, Number(seconds) || 0);
275. this.repeating = !!repeating;
276. this.running = true;
277. this.count = 0;
278. this.__handlers = new Map();
279. this.__origin = monoMs();
280. this.__n = 0;
281. this.__h = null;
282. this.__arm();
283. }
285. __arm() {
286. const period = this.seconds * 1000;
287. this.__n += 1;
288. const due = this.__origin + this.__n * period;
289. this.__h = setTimeout(() => this.__fire(), Math.max(0, due - monoMs()));
290. }
292. __fire() {
293. this.__h = null;
294. if (!this.running) return;
295. this.count += 1;
296. const ev = { count: this.count, at: Date.now() };
297. if (this.repeating) {
298. // skip whatever the host was too busy to deliver, keeping the phase
299. const period = this.seconds * 1000;
300. const now = monoMs();
301. while (this.__origin + this.__n * period <= now) this.__n += 1;
302. this.__n -= 1;
303. this.__arm();
304. } else {
305. // A SPENT ONE-SHOT RETIRES ITSELF before the tick is delivered — the
306. // same rule as the native half (mission 249: a source that will never
307. // speak again must not keep the program alive; in Node that is
308. // literally true, an un-cleared timer keeps the process running).
309. this.running = false;
310. }
311. const list = this.__handlers.get('tick');
312. if (list) for (const fn of list.slice()) fn(ev);
313. }
315. /** The registration protocol — see the class comment. */
316. __hlOn(event, fn) {
317. let list = this.__handlers.get(event);
318. if (!list) { list = []; this.__handlers.set(event, list); }
319. list.push(fn);
320. return this;
321. }
323. /** Stop an interval. True when this call was the one that stopped it. */
324. stop() {
325. if (!this.running) return false;
326. this.running = false;
327. if (this.__h !== null) { clearTimeout(this.__h); this.__h = null; }
328. return true;
329. }
330. }
332. /** A REPEATING timer: `on t.tick()` fires every `seconds` until `t.stop()`. */
333. export function every(seconds) { return new HlTimer(seconds, true); }
335. /** A ONE-SHOT: `on t.tick()` fires once, `seconds` from now, and retires. */
336. export function after(seconds) { return new HlTimer(seconds, false); }
338. /** A ONE-SHOT AT AN INSTANT. `epochMs` is what `now()` answers; an instant
339. * already past fires immediately (at the floor). */
340. export function until(epochMs) {
341. const delay = (Number(epochMs) - Date.now()) / 1000;
342. return new HlTimer(delay > 0 ? delay : 0, false);
343. }
345. /** BLOCK for `seconds`. The creator's ruling: a basic tool for tests and
346. * debugging, and it blocks — inside a server, `after()` is the thing to use.
347. *
348. * `Atomics.wait` is the only real block JavaScript has, and it is FORBIDDEN on
349. * a browser's main thread (it throws TypeError). So the browser gets a spin on
350. * the monotonic clock instead, which is the same observable behaviour — the tab
351. * is frozen for the duration — reached a different way. That is what a blocking
352. * sleep IS; the docs say so beside it rather than pretending otherwise. */
353. export function sleep(seconds) {
354. const ms = Number(seconds) * 1000;
355. if (!(ms > 0)) return false;
356. try {
357. if (typeof SharedArrayBuffer !== 'undefined' && typeof Atomics !== 'undefined') {
358. Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
359. return true;
360. }
361. } catch { /* main thread — fall through to the spin */ }
362. const until_ = monoMs() + ms;
363. while (monoMs() < until_) { /* the block */ }
364. return true;
365. }