@toa.io/extensions.cadence 1.0.0-alpha.284

package/source/types.ts

@@ -0,0 +1,41 @@
+/** What one component declares under `cadence:`, by the operation each one calls. */
+export type Declaration = Record<string, Pulse>
+
+export interface Pulse {
+  /** seconds one whole cycle takes */
+  cycle: number
+
+  /** intervals the cycle is split into; the gap between calls is `cycle / intervals` */
+  intervals: number
+}
+
+/** `context.delay` — a call to be made later, answering the id that cancels it. */
+export interface Delay {
+  (endpoint: string, request: object | null, options: Options): Promise<string>
+
+  /** Raises where the id was never issued. */
+  cancel: (id: string) => Promise<void>
+}
+
+export interface Options {
+  /** milliseconds from now */
+  interval: number
+
+  /**
+   * Milliseconds the call may be late and still be made, or `null` for no bound at all.
+   *
+   * Stated rather than defaulted, because only the caller knows whether a late call is still
+   * the right call: an unpaid order expires on time or not at all, and a report is wanted
+   * whenever it can be had. Nothing else in the system can tell those apart.
+   *
+   * An upper bound on lateness, not a promise of timeliness. It is bounded below by how often
+   * a dispatcher scans, so a bound shorter than that is one nothing can honour.
+   */
+  overdue: number | null
+}
+
+/** What an application states under `cadence:` in its context. */
+export interface Annotation {
+  /** seconds between passes over the calls waiting to be made */
+  discreteness?: number
+}

package/transpiled/Aspect.d.ts

@@ -0,0 +1,26 @@
+import { Connector } from '@toa.io/core';
+import type { Local } from './Local.js';
+/**
+ * `context.delay(endpoint, request, delay)` — a call to be made later, handed to the component
+ * that keeps them.
+ *
+ * It is not transactional with the caller's state. A crash between committing a change and
+ * handing over the call it should have scheduled loses the call, and there is no way for this
+ * to know. Where the semantics allow it, hand the call over first.
+ *
+ * @implements {toa.core.extensions.Aspect}
+ */
+export declare class Aspect extends Connector {
+    readonly name = "delay";
+    private readonly metronome;
+    constructor(metronome: Local);
+    invoke(method: string, ...args: any[]): Promise<unknown>;
+    /** Answers the id the call was given, which is what cancels it. */
+    private delay;
+    /**
+     * Tombstones the row, which is the prototype's `terminate`. An id that was never issued has
+     * nothing to terminate and raises; one whose call has already been made has a row still, and
+     * terminating it again is not an error.
+     */
+    private cancel;
+}

package/transpiled/Aspect.js

@@ -0,0 +1,46 @@
+import { Connector } from '@toa.io/core';
+/**
+ * `context.delay(endpoint, request, delay)` — a call to be made later, handed to the component
+ * that keeps them.
+ *
+ * It is not transactional with the caller's state. A crash between committing a change and
+ * handing over the call it should have scheduled loses the call, and there is no way for this
+ * to know. Where the semantics allow it, hand the call over first.
+ *
+ * @implements {toa.core.extensions.Aspect}
+ */
+export class Aspect extends Connector {
+    name = 'delay';
+    metronome;
+    constructor(metronome) {
+        super();
+        this.metronome = metronome;
+        this.depends(metronome);
+    }
+    // named rather than forwarded, so that the connector's lifecycle is not reachable from an
+    // algorithm — the same reason the atom aspect names its own
+    async invoke(method, ...args) {
+        switch (method) {
+            case 'delay': return await this.delay(args[0], args[1], args[2]);
+            case 'cancel': return await this.cancel(args[0]);
+            default: throw new Error(`Delay aspect has no '${method}' method`);
+        }
+    }
+    /** Answers the id the call was given, which is what cancels it. */
+    async delay(endpoint, request, options) {
+        const input = { endpoint, interval: options.interval, overdue: options.overdue };
+        // a call that takes no request carries none, rather than a null one
+        if (request !== null && request !== undefined)
+            input.request = request;
+        return await this.metronome.invoke('delay', { input });
+    }
+    /**
+     * Tombstones the row, which is the prototype's `terminate`. An id that was never issued has
+     * nothing to terminate and raises; one whose call has already been made has a row still, and
+     * terminating it again is not an error.
+     */
+    async cancel(id) {
+        return await this.metronome.invoke('terminate', { query: { id }, input: null });
+    }
+}
+//# sourceMappingURL=Aspect.js.map

package/transpiled/Aspect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Aspect.js","sourceRoot":"","sources":["../source/Aspect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAWxC;;;;;;;;;GASG;AACH,MAAM,OAAO,MAAO,SAAQ,SAAS;IACnB,IAAI,GAAG,OAAO,CAAA;IAEb,SAAS,CAAO;IAEjC,YAAoB,SAAgB;QAClC,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,SAAS,GAAG,SAAS,CAAA;QAE1B,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAA;IACzB,CAAC;IAED,0FAA0F;IAC1F,4DAA4D;IACrD,KAAK,CAAC,MAAM,CAAE,MAAc,EAAE,GAAG,IAAW;QACjD,QAAQ,MAAM,EAAE,CAAC;YACf,KAAK,OAAO,EAAE,OAAO,MAAM,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;YAChE,KAAK,QAAQ,EAAE,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;YAChD,SAAS,MAAM,IAAI,KAAK,CAAC,wBAAwB,MAAM,UAAU,CAAC,CAAA;QACpE,CAAC;IACH,CAAC;IAED,mEAAmE;IAC3D,KAAK,CAAC,KAAK,CAAE,QAAgB,EAAE,OAAsB,EAC3D,OAAgB;QAChB,MAAM,KAAK,GAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAA;QAEvF,oEAAoE;QACpE,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS;YAAE,KAAK,CAAC,OAAO,GAAG,OAAO,CAAA;QAEtE,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;IACxD,CAAC;IAED;;;;OAIG;IACK,KAAK,CAAC,MAAM,CAAE,EAAU;QAC9B,OAAO,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,WAAW,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;IACjF,CAAC;CACF"}

package/transpiled/Composition.d.ts

@@ -0,0 +1,14 @@
+import { Connector } from '@toa.io/core';
+import type { Host } from './Factory.js';
+/** The components this extension ships, which run inside its own service. */
+export declare function components(): Components;
+export declare class Composition extends Connector {
+    private readonly host;
+    constructor(host: Host);
+    protected open(): Promise<void>;
+}
+interface Components {
+    labels: string[];
+    paths: string[];
+}
+export {};

package/transpiled/Composition.js

@@ -0,0 +1,30 @@
+import { readdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { Connector } from '@toa.io/core';
+/** The components this extension ships, which run inside its own service. */
+export function components() {
+    const labels = [];
+    const paths = [];
+    for (const entry of entries()) {
+        labels.push(entry.name.replace('.', '-'));
+        paths.push(resolve(ROOT, entry.name));
+    }
+    return { labels, paths };
+}
+export class Composition extends Connector {
+    host;
+    constructor(host) {
+        super();
+        this.host = host;
+    }
+    async open() {
+        const composition = await this.host.composition(components().paths);
+        await composition.connect();
+        this.depends(composition);
+    }
+}
+function entries() {
+    return readdirSync(ROOT, { withFileTypes: true }).filter((entry) => entry.isDirectory());
+}
+const ROOT = resolve(import.meta.dirname, '../components/');
+//# sourceMappingURL=Composition.js.map

package/transpiled/Composition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Composition.js","sourceRoot":"","sources":["../source/Composition.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAA;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAIxC,6EAA6E;AAC7E,MAAM,UAAU,UAAU;IACxB,MAAM,MAAM,GAAa,EAAE,CAAA;IAC3B,MAAM,KAAK,GAAa,EAAE,CAAA;IAE1B,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,EAAE,CAAC;QAC9B,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;QACzC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAA;IACvC,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,CAAA;AAC1B,CAAC;AAED,MAAM,OAAO,WAAY,SAAQ,SAAS;IACvB,IAAI,CAAM;IAE3B,YAAoB,IAAU;QAC5B,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;IAEkB,KAAK,CAAC,IAAI;QAC3B,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,CAAA;QAEnE,MAAM,WAAW,CAAC,OAAO,EAAE,CAAA;QAE3B,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAA;IAC3B,CAAC;CACF;AAED,SAAS,OAAO;IACd,OAAO,WAAW,CAAC,IAAI,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAA;AAC1F,CAAC;AAOD,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,IAAI,CAAC,OAAO,EAAE,gBAAgB,CAAC,CAAA"}

package/transpiled/Dispatcher.d.ts

@@ -0,0 +1,63 @@
+import { Connector, Locator } from '@toa.io/core';
+import type { Local } from './Local.js';
+import type { atomicity } from '@toa.io/core';
+/**
+ * Makes the calls that were put off.
+ *
+ * Two tiers, which is what a store polled rarely and a call due to the second need between
+ * them: the rows are the record, and one scan primes the next interval of them into timers.
+ * A crash loses the timers and nothing else — the next scan reads what is overdue along with
+ * what is upcoming, so a dispatcher that died mid-interval costs a delay and not a call.
+ *
+ * Partitioned by lane exactly as the outbox is, so every replica scans and dispatches its own
+ * share of every interval rather than taking turns at whole ones.
+ */
+export declare class Dispatcher extends Connector {
+    private readonly metronome;
+    private readonly resolve;
+    private readonly atom;
+    /** rows in this replica's hands — a timer set for them, or a call of theirs on its way */
+    private readonly armed;
+    /** ids called and not yet removed, held until a scan settles them */
+    private called;
+    /** what it has called through, so that each is torn down with it */
+    private readonly targets;
+    /** milliseconds between passes, and how far ahead each one reaches */
+    private readonly discreteness;
+    private timer?;
+    private off?;
+    private scanning;
+    private closing;
+    constructor(metronome: Local, resolve: (locator: Locator) => Local, atom: atomicity.Atom);
+    protected open(): Promise<void>;
+    protected close(): Promise<void>;
+    /** One scan at a time: a slow one must not have another started underneath it. */
+    private tick;
+    /**
+     * What this replica owns has changed. Timers for lanes it no longer holds are dropped —
+     * whoever holds them now will arm them — and a scan runs at once rather than at the next
+     * interval, so lanes just acquired are not left waiting.
+     */
+    private adopt;
+    /** What is armed for a lane this replica no longer holds: whoever holds it now will arm it. */
+    private disarm;
+    private scan;
+    /**
+     * A row already armed is left alone: a scan reads what it read before, because a row stays
+     * until its call has been made.
+     */
+    private arm;
+    /**
+     * The call goes out before the row is removed, never the other way round: a crash in between
+     * makes the call twice, and the other order would lose it. It travels as a task, so the
+     * broker holds it if the target is not there to take it.
+     */
+    private dispatch;
+    /**
+     * A remote is resolved once per target and held: it opens a connection, and one nothing
+     * depends on would outlive the dispatcher that made it.
+     */
+    private target;
+    /** One write for many rows, which is why the ids are held rather than settled one by one. */
+    private settle;
+}

package/transpiled/Dispatcher.js

@@ -0,0 +1,170 @@
+import { console } from 'openspan';
+import { Connector, Locator } from '@toa.io/core';
+import { BATCH, DISCRETENESS, LANES, number } from './const.js';
+/**
+ * Makes the calls that were put off.
+ *
+ * Two tiers, which is what a store polled rarely and a call due to the second need between
+ * them: the rows are the record, and one scan primes the next interval of them into timers.
+ * A crash loses the timers and nothing else — the next scan reads what is overdue along with
+ * what is upcoming, so a dispatcher that died mid-interval costs a delay and not a call.
+ *
+ * Partitioned by lane exactly as the outbox is, so every replica scans and dispatches its own
+ * share of every interval rather than taking turns at whole ones.
+ */
+export class Dispatcher extends Connector {
+    metronome;
+    resolve;
+    atom;
+    /** rows in this replica's hands — a timer set for them, or a call of theirs on its way */
+    armed = new Map();
+    /** ids called and not yet removed, held until a scan settles them */
+    called = new Set();
+    /** what it has called through, so that each is torn down with it */
+    targets = new Set();
+    /** milliseconds between passes, and how far ahead each one reaches */
+    discreteness;
+    timer;
+    off;
+    scanning = false;
+    closing = false;
+    constructor(metronome, resolve, atom) {
+        super();
+        this.metronome = metronome;
+        this.resolve = resolve;
+        this.atom = atom;
+        this.discreteness = number('TOA_CADENCE_DISCRETENESS', DISCRETENESS * 1000);
+        this.depends(metronome);
+        this.depends(atom);
+    }
+    async open() {
+        this.timer = setInterval(() => { this.tick(); }, this.discreteness);
+        this.timer.unref();
+        // a lane changing hands is when its rows become this replica's, or stop being
+        this.off = this.atom.onassigned(() => { this.adopt(); });
+    }
+    async close() {
+        this.closing = true;
+        this.off?.();
+        clearInterval(this.timer);
+        for (const { timer } of this.armed.values())
+            clearTimeout(timer);
+        this.armed.clear();
+        await this.settle();
+    }
+    /** One scan at a time: a slow one must not have another started underneath it. */
+    tick() {
+        if (this.scanning || this.closing)
+            return;
+        this.scanning = true;
+        void this.scan()
+            .catch((error) => { console.error('Delayed calls scan failed', { error }); })
+            .finally(() => { this.scanning = false; });
+    }
+    /**
+     * What this replica owns has changed. Timers for lanes it no longer holds are dropped —
+     * whoever holds them now will arm them — and a scan runs at once rather than at the next
+     * interval, so lanes just acquired are not left waiting.
+     */
+    adopt() {
+        // nothing owned is nothing held: what was armed under a claim this replica no longer has
+        // belongs to whoever has it now, and firing it anyway is the call twice
+        this.disarm(this.atom.slots(LANES) ?? []);
+        this.tick();
+    }
+    /** What is armed for a lane this replica no longer holds: whoever holds it now will arm it. */
+    disarm(lanes) {
+        for (const [id, { timer, lane }] of this.armed) {
+            if (lanes.includes(lane))
+                continue;
+            clearTimeout(timer);
+            this.armed.delete(id);
+        }
+    }
+    async scan() {
+        const lanes = this.atom.slots(LANES);
+        if (lanes === null || lanes.length === 0)
+            return;
+        await this.settle();
+        const now = Date.now();
+        const until = now + this.discreteness;
+        const rows = await this.metronome.invoke('enumerate', {
+            query: {
+                // a call nothing was running to make in time has expired, and is simply not read
+                criteria: `lane=in=(${lanes.join(',')});due<${until};expires>${now}`,
+                sort: ['due:asc'],
+                limit: BATCH
+            }
+        });
+        for (const row of rows)
+            this.arm(row);
+    }
+    /**
+     * A row already armed is left alone: a scan reads what it read before, because a row stays
+     * until its call has been made.
+     */
+    arm(row) {
+        if (this.armed.has(row.id) || this.called.has(row.id))
+            return;
+        const timer = setTimeout(() => { void this.dispatch(row); }, Math.max(row.due - Date.now(), 0));
+        timer.unref();
+        this.armed.set(row.id, { timer, lane: row.lane });
+    }
+    /**
+     * The call goes out before the row is removed, never the other way round: a crash in between
+     * makes the call twice, and the other order would lose it. It travels as a task, so the
+     * broker holds it if the target is not there to take it.
+     */
+    async dispatch(row) {
+        if (this.closing) {
+            this.armed.delete(row.id);
+            return;
+        }
+        const [namespace, name, endpoint] = row.endpoint.split('.');
+        const local = this.target(new Locator(name, namespace));
+        /*
+         * Attempted before it is made, not after it comes back. One attempt is what a dispatcher
+         * has to give: what it can tell about a failure is nothing, and a request the target's
+         * schema no longer fits never becomes one it does.
+         */
+        this.called.add(row.id);
+        /*
+         * The call travels as a task, so what raises here is this side of it: a stored request the
+         * target's contract no longer fits, an endpoint it no longer has, a broker that refused the
+         * enqueue. What the operation itself does with it happens in the target's own process and
+         * never comes back.
+         *
+         * Skipped, as a pulse skips: reported, and the row settled on the attempt either way.
+         */
+        await local.invoke(endpoint, { input: null, ...row.request, task: true })
+            .catch((error) => {
+            console.error('Delayed call failed', { endpoint: row.endpoint, id: row.id, error });
+        })
+            // held for as long as the call is, so `armed` answers what this replica has in hand
+            // rather than what it has a timer for
+            .finally(() => { this.armed.delete(row.id); });
+    }
+    /**
+     * A remote is resolved once per target and held: it opens a connection, and one nothing
+     * depends on would outlive the dispatcher that made it.
+     */
+    target(locator) {
+        const local = this.resolve(locator);
+        if (!this.targets.has(local)) {
+            this.targets.add(local);
+            this.depends(local);
+        }
+        return local;
+    }
+    /** One write for many rows, which is why the ids are held rather than settled one by one. */
+    async settle() {
+        if (this.called.size === 0)
+            return;
+        const ids = [...this.called];
+        await this.metronome.invoke('settle', { query: { ids }, input: null });
+        // held until the write comes back, so that one which does not leaves them to a later scan
+        for (const id of ids)
+            this.called.delete(id);
+    }
+}
+//# sourceMappingURL=Dispatcher.js.map

package/transpiled/Dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Dispatcher.js","sourceRoot":"","sources":["../source/Dispatcher.ts"],"names":[],"mappings":"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"}

package/transpiled/Factory.d.ts

@@ -0,0 +1,22 @@
+import { Connector, Locator } from '@toa.io/core';
+import type { extensions } from '@toa.io/core';
+export declare class Factory implements extensions.Factory {
+    private readonly host;
+    /** one per component, however much of this extension calls through it */
+    private readonly locals;
+    constructor(host: Host);
+    /**
+     * What runs beside a component. Its own component gets the dispatcher; everyone else gets a
+     * timer per operation they declared a cadence for.
+     *
+     * A tenant is created before the components of its composition are, which is why nothing here
+     * reaches for one.
+     */
+    tenant(locator: Locator, declaration: object): Connector;
+    /** `context.delay` — for every component but the one that keeps the calls. */
+    aspect(locator: Locator): extensions.Aspect | extensions.Aspect[];
+    service(): Connector;
+    private metronome;
+    private local;
+}
+export type Host = extensions.Host;

package/transpiled/Factory.js

@@ -0,0 +1,56 @@
+import { Connector, Locator } from '@toa.io/core';
+import { Composition } from './Composition.js';
+import { COMPONENT, NAMESPACE } from './const.js';
+import { Aspect } from './Aspect.js';
+import { Dispatcher } from './Dispatcher.js';
+import { Local } from './Local.js';
+import { Pulse } from './Pulse.js';
+export class Factory {
+    host;
+    /** one per component, however much of this extension calls through it */
+    locals = {};
+    constructor(host) {
+        this.host = host;
+    }
+    /**
+     * What runs beside a component. Its own component gets the dispatcher; everyone else gets a
+     * timer per operation they declared a cadence for.
+     *
+     * A tenant is created before the components of its composition are, which is why nothing here
+     * reaches for one.
+     */
+    tenant(locator, declaration) {
+        if (mine(locator))
+            return new Dispatcher(this.metronome(), (target) => this.local(target), this.host.atom(locator.id));
+        const tenant = new Connector();
+        const pulses = declaration;
+        // `cadence: ~` is a component that only delays calls
+        if (pulses === null)
+            return tenant;
+        const local = this.local(locator);
+        const atom = this.host.atom(locator.id);
+        for (const [endpoint, { cycle, intervals }] of Object.entries(pulses))
+            tenant.depends(new Pulse({ locator, endpoint, cycle, intervals }, local, atom));
+        return tenant;
+    }
+    /** `context.delay` — for every component but the one that keeps the calls. */
+    aspect(locator) {
+        if (mine(locator))
+            return [];
+        return new Aspect(this.metronome());
+    }
+    service() {
+        return new Composition(this.host);
+    }
+    metronome() {
+        return this.local(new Locator(COMPONENT, NAMESPACE));
+    }
+    local(locator) {
+        return (this.locals[locator.id] ??= new Local(this.host, locator));
+    }
+}
+/** Whether this is a component the extension ships rather than one of the application's. */
+function mine(locator) {
+    return locator.namespace === NAMESPACE;
+}
+//# sourceMappingURL=Factory.js.map

package/transpiled/Factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Factory.js","sourceRoot":"","sources":["../source/Factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AACjD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAIlC,MAAM,OAAO,OAAO;IACD,IAAI,CAAM;IAE3B,yEAAyE;IACxD,MAAM,GAA0B,EAAE,CAAA;IAEnD,YAAoB,IAAU;QAC5B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;IAED;;;;;;OAMG;IACI,MAAM,CAAE,OAAgB,EAAE,WAAmB;QAClD,IAAI,IAAI,CAAC,OAAO,CAAC;YACf,OAAO,IAAI,UAAU,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,EACpE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAA;QAE/B,MAAM,MAAM,GAAG,IAAI,SAAS,EAAE,CAAA;QAC9B,MAAM,MAAM,GAAG,WAAiC,CAAA;QAEhD,qDAAqD;QACrD,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,MAAM,CAAA;QAElC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QACjC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;QAEvC,KAAK,MAAM,CAAC,QAAQ,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;YACnE,MAAM,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAA;QAEjF,OAAO,MAAM,CAAA;IACf,CAAC;IAED,8EAA8E;IACvE,MAAM,CAAE,OAAgB;QAC7B,IAAI,IAAI,CAAC,OAAO,CAAC;YAAE,OAAO,EAAE,CAAA;QAE5B,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,CAAA;IACrC,CAAC;IAEM,OAAO;QACZ,OAAO,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACnC,CAAC;IAEO,SAAS;QACf,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,OAAO,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC,CAAA;IACtD,CAAC;IAEO,KAAK,CAAE,OAAgB;QAC7B,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,KAAK,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAA;IACpE,CAAC;CACF;AAED,4FAA4F;AAC5F,SAAS,IAAI,CAAE,OAAgB;IAC7B,OAAO,OAAO,CAAC,SAAS,KAAK,SAAS,CAAA;AACxC,CAAC"}

package/transpiled/Local.d.ts

@@ -0,0 +1,18 @@
+import { Connector } from '@toa.io/core';
+import type { Host } from './Factory.js';
+import type { Locator, Reply, Request } from '@toa.io/core';
+/**
+ * The component a tenant belongs to, as something to call.
+ *
+ * Resolved on the first call and not before: a tenant is created ahead of the components of its
+ * composition, so at that point there is nothing to look up yet. A pulse calls at a boundary,
+ * which is long after everything is up.
+ */
+export declare class Local extends Connector {
+    private readonly host;
+    private readonly locator;
+    private remote?;
+    constructor(host: Host, locator: Locator);
+    invoke(endpoint: string, request: Request): Promise<Reply>;
+    private locate;
+}

package/transpiled/Local.js

@@ -0,0 +1,29 @@
+import { Connector } from '@toa.io/core';
+/**
+ * The component a tenant belongs to, as something to call.
+ *
+ * Resolved on the first call and not before: a tenant is created ahead of the components of its
+ * composition, so at that point there is nothing to look up yet. A pulse calls at a boundary,
+ * which is long after everything is up.
+ */
+export class Local extends Connector {
+    host;
+    locator;
+    remote;
+    constructor(host, locator) {
+        super();
+        this.host = host;
+        this.locator = locator;
+    }
+    async invoke(endpoint, request) {
+        this.remote ??= this.locate();
+        return await (await this.remote).invoke(endpoint, request);
+    }
+    async locate() {
+        const remote = await this.host.remote(this.locator);
+        this.depends(remote);
+        await remote.connect();
+        return remote;
+    }
+}
+//# sourceMappingURL=Local.js.map

package/transpiled/Local.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Local.js","sourceRoot":"","sources":["../source/Local.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAIxC;;;;;;GAMG;AACH,MAAM,OAAO,KAAM,SAAQ,SAAS;IACjB,IAAI,CAAM;IACV,OAAO,CAAS;IACzB,MAAM,CAAkB;IAEhC,YAAoB,IAAU,EAAE,OAAgB;QAC9C,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;QAChB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;IACxB,CAAC;IAEM,KAAK,CAAC,MAAM,CAAE,QAAgB,EAAE,OAAgB;QACrD,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,EAAE,CAAA;QAE7B,OAAO,MAAM,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;IAC5D,CAAC;IAEO,KAAK,CAAC,MAAM;QAClB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QAEnD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;QAEpB,MAAM,MAAM,CAAC,OAAO,EAAE,CAAA;QAEtB,OAAO,MAAM,CAAA;IACf,CAAC;CACF"}

package/transpiled/Pulse.d.ts

@@ -0,0 +1,64 @@
+import { Connector } from '@toa.io/core';
+import type { Local } from './Local.js';
+import type { Locator, atomicity } from '@toa.io/core';
+/**
+ * A recurring call to an operation of its own component, on the cadence its manifest states.
+ *
+ * Nothing is stored. The cycle is split into `n` intervals and the current one is a function of
+ * the clock, so every replica computes the same `i` without talking to any other; the one that
+ * owns `i` is the one that calls. An interval no replica was alive for is not made up
+ * afterwards — the operation is expected to select by what is still due rather than by where
+ * the cycle has reached.
+ */
+export declare class Pulse extends Connector {
+    private readonly endpoint;
+    private readonly label;
+    /** milliseconds one whole cycle takes */
+    private readonly cycle;
+    /** intervals the cycle is split into */
+    private readonly n;
+    private readonly local;
+    private readonly atom;
+    /** span options, built once */
+    private readonly options;
+    /**
+     * The ordinal of the interval this process has already handled, so an early wake-up is not a
+     * second call. An ordinal and not an index: with one interval per cycle the index never
+     * changes, and comparing it would suppress every call after the first.
+     */
+    private fired;
+    private timer?;
+    /** the call in flight, awaited on close */
+    private firing?;
+    private closing;
+    constructor(definition: Definition, local: Local, atom: atomicity.Atom);
+    /**
+     * How many intervals have passed since the epoch, `now` included. Against the cycle rather
+     * than by adding up gaps, so a cycle that does not divide evenly into its intervals neither
+     * drifts nor accumulates error.
+     *
+     * The arithmetic is exact rather than double: `now` is milliseconds since 1970 and `n` may be
+     * as large as the cycle has seconds, so their product leaves the range a double is exact in
+     * for a long cycle cut finely. It is evaluated once per interval, where this costs nothing.
+     */
+    ordinal(now: number): number;
+    /** Which of the cycle's intervals `now` falls in. */
+    index(now: number): number;
+    /** When the interval `now` falls in gives way to the next one. */
+    boundary(now: number): number;
+    protected open(): Promise<void>;
+    protected close(): Promise<void>;
+    private arm;
+    private tick;
+    /**
+     * Nothing queues here. A call still running when the next boundary arrives means the work
+     * does not fit the gap, and starting a second one would only make that worse.
+     */
+    private fire;
+}
+export interface Definition {
+    locator: Locator;
+    endpoint: string;
+    cycle: number;
+    intervals: number;
+}