@nervur-org/dock 0.5.0 → 0.6.0

package/dock/timer.ts

@@ -1,174 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// The box's clock, and the one being on a device that reads one. A being who
-// could read a clock could not be moved, since the moment she read would be
-// her box's and no other, so the moment reaches every other being the one way
-// anything reaches a being: as an ask at her door, from this faculty, as the
-// occupant she named when she asked to be woken.
-//
-// She arms for the next due moment and for nothing else. Every watcher
-// answers a round with when she is next due, this arms for the earliest of
-// them, and a box whose watchers all say null arms nothing and sleeps until
-// somebody keeps something. So a box with no schedules never ticks, and a
-// home on the edge with a sweep at three in the morning wakes once a night.
-//
-// A round is armed for one moment at a time and never overlaps the one
-// before, and the moment is floored to the minute with half a second after
-// it, since a watcher floors the moment she is handed and a round that fired
-// a hair early would floor to the minute before.
-//
-// One method knows a terrain, `arm`, and a subclass replaces it: a
-// `setTimeout` here, the object's storage alarm on a worker. Nothing else in
-// her reads a platform.
-import type { JsonObject } from 'nervur';
-import { Faculty, type Woke } from './faculty.ts';
-
-const MINUTE = 60_000;
-// A timeout further out than this is not trusted, so the arming is capped and
-// made again when it goes off. It is the base class's own bound and no rule
-// of the faculty: a terrain whose alarm holds a month arms for the month.
-const DAY = 86_400_000;
-
-export class Timer extends Faculty {
-  static override asks = {
-    watch: { description: 'wake me when I say I am next due', input: { type: 'object', properties: { invitation: { type: 'object' }, method: { type: 'string' }, args: { type: 'object' } }, required: ['invitation', 'method'] } },
-    due: { description: 'bring my next round forward to this moment', input: { type: 'object', properties: { at: { type: 'number' } }, required: ['at'] } },
-    now: { description: 'this box’s moment', input: { type: 'object' } },
-  };
-
-  #timeout: ReturnType<typeof setTimeout> | undefined;
-  #stopped = false;
-  #armed: number | null = null;
-  #round: Promise<Woke[]> | null = null;
-
-  // The moment she is armed for, or null while she is asleep. For the
-  // device's own code and for a suite; it crosses no door.
-  get armed(): number | null {
-    return this.#armed;
-  }
-
-  // A watcher says she is due sooner than the box knew. It only ever brings
-  // the round forward: what fires is decided at the tick, in the watcher's
-  // own cells, so an arming that moved later on somebody's word would be a
-  // schedule somebody else held silenced. The door is the whole gate here:
-  // a standing at a faculty comes from `lend` alone, and this adds no second
-  // one.
-  due(args: JsonObject): JsonObject {
-    const at = args.at;
-    if (typeof at !== 'number' || !Number.isFinite(at)) return { error: 'a due carries the moment: { at }' };
-    const when = moment(at);
-    if (this.#armed === null || when < this.#armed) this.#arm(when);
-    return { armed: this.#armed };
-  }
-
-  // Whoever was just filed is ticked at once, and what she answers is what
-  // the box arms for. One move covers a box booting, a home moving in and a
-  // watcher born long after the box was up: she is never waiting for a round
-  // nobody scheduled.
-  protected override async welcomed(id: string): Promise<void> {
-    await this.round(Date.now(), id);
-  }
-
-  // The arming went off. A moment still well ahead is the day's cap this
-  // class put on its own timeout, so it is armed again rather than fired: a
-  // terrain calls this and never has to know how far out the arming was.
-  async rang(): Promise<Woke[]> {
-    if (this.#stopped) return [];
-    if (this.#armed !== null && this.#armed - Date.now() > 1_000) {
-      this.arm(this.#armed);
-      return [];
-    }
-    return this.fire(Date.now());
-  }
-
-  // The moment, read here and handed on. A device's own code may call it at a
-  // moment it names, which is how a suite proves a wake without waiting for
-  // one and how an operator makes a round happen now.
-  fire(now: number): Promise<Woke[]> {
-    return this.round(now);
-  }
-
-  // One round, and never two: a second while one is in flight is handed the
-  // one already running. What every watcher answered decides the next
-  // arming, and a `due` that landed while the round ran is not lost.
-  protected round(now: number, only?: string): Promise<Woke[]> {
-    if (this.#round) return this.#round;
-    const mine = this.#run(now, only);
-    this.#round = mine;
-    return mine.finally(() => {
-      if (this.#round === mine) this.#round = null;
-    });
-  }
-
-  async #run(now: number, only?: string): Promise<Woke[]> {
-    if (only === undefined) this.#arm(null); // the arming is spent, whether it went off or the device called this by hand
-    const woke = await this.woke((w) => ({ ...w.args, now }), only);
-    if (woke === null) {
-      this.stop(); // her ward took her out; there is nobody left to wake
-      return [];
-    }
-    // A moment already gone is no arming. Every watcher works out when she is
-    // next due from the moment she was handed, so a round fired by hand at a
-    // moment that is not this box's answers one that is not this box's
-    // either, and a box that armed for it would run a round for a minute long
-    // past. A round at the box's own moment always names one still ahead.
-    const named = soonest(woke);
-    const said = named !== null && named > Date.now() ? named : null;
-    const held = this.#armed;
-    const at = said === null ? held : held === null ? moment(said) : Math.min(held, moment(said));
-    if (at !== null && at !== this.#armed) this.#arm(at);
-    else if (at === null && this.#armed !== null) this.#arm(null);
-    return woke;
-  }
-
-  #arm(when: number | null): void {
-    if (this.#stopped) return;
-    this.#armed = when;
-    this.arm(when);
-  }
-
-  // The one thing a terrain says about itself: be woken at this moment, or at
-  // no moment at all. A subclass replaces this and nothing else of her.
-  //
-  // Here it is a timeout, capped at a day and armed again when the cap goes
-  // off. The box stays up for its work and never for this, so the handle is
-  // unreferenced.
-  protected arm(when: number | null): void {
-    clearTimeout(this.#timeout);
-    this.#timeout = undefined;
-    if (when === null) return;
-    this.#timeout = setTimeout(() => void this.rang(), Math.min(Math.max(when - Date.now(), 0), DAY));
-    this.#timeout.unref?.();
-  }
-
-  // A being her ward took out reaches nobody, so nothing is left to wake. The
-  // device calls this when it puts the box down.
-  stop(): void {
-    this.#stopped = true;
-    this.#armed = null;
-    this.arm(null);
-  }
-
-  now(): JsonObject {
-    return { now: Date.now() };
-  }
-}
-
-// Half a second past the minute a moment falls in, and never before the
-// moment itself: a watcher floors what she is handed, so a round that fired a
-// hair early would floor to the minute before and fire nothing.
-const moment = (at: number): number => Math.max(at, Math.floor(at / MINUTE) * MINUTE + 500);
-
-// What one round learned. Every watcher says when she is next due, and the
-// box arms for the earliest of them. A watcher who named no moment has
-// nothing to be woken for, and so has one who answered something that is no
-// tally at all.
-function soonest(woke: Woke[]): number | null {
-  let at: number | null = null;
-  for (const w of woke) {
-    if (w.out === null || typeof w.out !== 'object') continue;
-    const next = (w.out as { next?: unknown }).next;
-    if (typeof next !== 'number' || !Number.isFinite(next)) continue;
-    if (at === null || next < at) at = next;
-  }
-  return at;
-}