@superblocksteam/shared 0.9618.2 → 0.9619.1

package/dist-esm/socket/heartbeat.d.ts

@@ -1,268 +0,0 @@
-/**
- * A paced liveness beat over a request channel.
- *
- * Every long-lived socket in this repo eventually needs the same thing: proof
- * that the peer is still answering, cheaply, for as long as the connection is
- * held. The naive version - an interval that fires a request and counts the
- * failures - is wrong in three ways that only show up under load, and each one
- * was found the hard way:
- *
- *   1. A request inherits the channel's own budget, which is the whole
- *      caller-facing operation (minutes). A beat that borrows it cannot report a
- *      miss inside any window a caller waits in, so it holds its own deadline.
- *   2. Without an in-flight guard, a peer that stopped answering collects a new
- *      pending request every interval, none of which can ever be reconciled.
- *      The answer paces the beats, not the interval.
- *   3. A beat's response shares the socket with bulk pushes, so a large transfer
- *      head-of-line blocks the answer past any sane deadline while the
- *      connection is perfectly healthy. Acting on that kills a busy socket and,
- *      where the caller reconnects, re-sends the same payload and does it again.
- *
- * The third is the subtle one, and it takes two guards, because neither is
- * sufficient alone. Inbound traffic during the beat's own wait proves the
- * connection is alive - but a bulk RPC response is a single websocket message,
- * and no receive event fires until its last byte lands, so that cannot be the
- * only guard. A single missed beat therefore also gets grace: a transfer merely
- * has to finish inside one extra interval for the next answer to get through.
- *
- * Both guards answer to one bound. Inbound data proves the receive path, not
- * that the request channel answers, so no amount of either excuse may let a
- * wedged channel hide forever: once
- * {@link SocketHeartbeatOptions.maxConsecutiveUnanswered} beats in a row have
- * gone unanswered, the next silence is believed whatever the reason, and the
- * grace is bypassed with it.
- *
- * Extracted from the browser editor's dev-server heartbeat, which learned all
- * of the above the hard way and is the first thing to beat with it.
- */
-/** Why a beat settled the way it did. */
-export type BeatOutcome = 
-/** Answered. The peer is there and the channel works. */
-'success'
-/** A definite answer that was an error. It arrived, so the channel works. */
- | 'refused'
-/** Unanswered, but the socket was provably delivering data. Excused. */
- | 'lapse'
-/** Unanswered and believed, but held back so a slow transfer can catch up. */
- | 'grace'
-/** Unanswered and believed. The caller should act on this one. */
- | 'miss';
-/**
- * Running account of the beat, readable at any time and reported when a socket
- * dies.
- *
- * A socket can die before any beat settles, so `sent` counts beats issued
- * rather than outcomes observed: unanswered beats are the strongest evidence
- * there is that the peer was gone, and an account built from settled outcomes
- * alone would report the most telling deaths as having nothing to say.
- */
-export type HeartbeatAccount = {
-    /**
-     * Consecutive believed silences. Only an unanswered beat that nothing excused
-     * counts here, so this is what decides when the beat is lost - and why a
-     * refusal, which is an answer, can never close a connection on its own.
-     */
-    readonly failures: number;
-    /**
-     * Unanswered beats excused because the socket was provably delivering data at
-     * the time. Purely diagnostic: this is the difference between a dead
-     * connection and a live one whose request channel went quiet, which no close
-     * code can tell apart.
-     *
-     * Cleared by an answered beat or a new connection, not by a refusal - see
-     * {@link HeartbeatAccount.unanswered}.
-     */
-    readonly lapses: number;
-    readonly lastError?: string;
-    /**
-     * Why the peer refused, kept apart from {@link HeartbeatAccount.lastError}.
-     *
-     * A refusal is the only outcome where the peer said why, and it clears none
-     * of the counts around it - so a silence after one leaves `refusals` standing
-     * while overwriting `lastError` with its own generic cause. A report reading
-     * only `lastError` would then attribute a timeout's message to the refusal.
-     * Cleared by an answered beat, which settles the whole account.
-     */
-    readonly lastRefusalError?: string;
-    readonly lastReceivedAt?: number;
-    readonly lastSuccessAt?: number;
-    /**
-     * When the beat still waiting for its answer went out, or absent if none is.
-     *
-     * `sent` says a beat was issued and {@link HeartbeatAccount.lastSuccessAt}
-     * says one was answered; neither says whether the last one came back. Without
-     * this, a socket that answered a beat and then went silent is indistinguishable
-     * from one answering right up to the close.
-     *
-     * Deliberately survives {@link SocketHeartbeat.stop}, which is the first thing
-     * a caller does with a dead connection: the account is read after the socket
-     * is gone, no settle is coming for a retired beat, and clearing the stamp on
-     * the way out would erase the only record that a beat was outstanding.
-     */
-    readonly pendingSince?: number;
-    /**
-     * Consecutive beats answered with an error. Kept apart from
-     * {@link HeartbeatAccount.failures} because a refusal proves the channel
-     * works: it belongs in the report, never in the decision to give up on a
-     * connection.
-     */
-    readonly refusals: number;
-    /** Every beat issued, including one still waiting. */
-    readonly sent: number;
-    /**
-     * Beats that got no answer, excused or not. This is what the deferral bound is
-     * measured against, so it is also what says how long a silence had been
-     * tolerated when the beat was finally believed.
-     *
-     * Saturates at {@link SocketHeartbeatOptions.maxConsecutiveUnanswered}, so
-     * the run it reports can never exceed the bound it is measured against -
-     * beats keep going out after the alarm is raised, and an unbounded count
-     * would describe a silence longer than the one that was acted on.
-     *
-     * Cleared only by a definite success, proof of life, or a new connection. A
-     * refusal leaves it standing: it answers one beat, and were it to clear the
-     * run, a channel alternating between timing out and refusing could defer the
-     * bound forever while inbound traffic excused every silence.
-     */
-    readonly unanswered: number;
-};
-export interface SocketHeartbeatOptions {
-    /** Issues one beat. The cheapest authorized round trip the channel offers. */
-    beat: () => Promise<unknown>;
-    /** Gap between beats. A beat still in flight when one is due skips it. */
-    intervalMs: number;
-    /** How long one beat waits for its answer before it counts as unanswered. */
-    timeoutMs: number;
-    /**
-     * Consecutive genuine misses before the beat is declared lost. Defaults to
-     * {@link DEFAULT_MAX_CONSECUTIVE_MISSES}.
-     */
-    maxConsecutiveMisses?: number;
-    /**
-     * Consecutive unanswered beats to tolerate before neither proof of life nor
-     * grace may excuse another. Defaults to
-     * {@link DEFAULT_MAX_CONSECUTIVE_UNANSWERED}.
-     */
-    maxConsecutiveUnanswered?: number;
-    /**
-     * Renders a rejection for the account. Channels that reject with plain
-     * objects rather than `Error`s need this, or the cause reads
-     * `[object Object]`.
-     */
-    describeError?: (error: unknown) => string;
-    /**
-     * Whether a rejection means the beat went unanswered, as opposed to being
-     * refused. Only an unanswered beat can lapse or be believed: a refusal is a
-     * definite answer about the peer, and treating it as silence would hide the
-     * very thing it reports. Defaults to recognizing this heartbeat's own
-     * deadline.
-     */
-    isUnanswered?: (error: unknown) => boolean;
-    /**
-     * The beat is lost: enough consecutive beats went unanswered that the peer
-     * cannot be assumed to be there.
-     *
-     * Edge-triggered. It fires on the beat that crosses the threshold and stays
-     * quiet until proof of life re-arms it, because the counters it reports are
-     * an account read at socket death - resetting them to re-arm the alarm would
-     * erase the evidence the death report is built from.
-     *
-     * Throwing from here says the loss could not be acted on - the socket lookup
-     * failed, the close was rejected - and re-arms the alarm, because the
-     * connection this was meant to tear down is still there. A caller that
-     * swallows its own failure instead gets one alarm for a teardown that never
-     * happened.
-     *
-     * A refusal never reaches this. The peer answered, so whatever is wrong is
-     * not the connection, and tearing one down over an application-level refusal
-     * would replace a working channel with an outage.
-     */
-    onLost: (account: HeartbeatAccount) => void;
-    /** Every settled beat, for telemetry. Receives the account at settle time. */
-    onOutcome?: (outcome: BeatOutcome, durationMs: number, account: HeartbeatAccount) => void;
-    /**
-     * Whether the channel can carry a beat at all right now - an authorized
-     * credential, an open socket. A gate that is closed skips the beat entirely
-     * rather than counting it, because a channel with nothing to protect yet has
-     * neither missed nor answered anything.
-     */
-    shouldBeat?: () => boolean;
-}
-export declare const DEFAULT_MAX_CONSECUTIVE_MISSES = 2;
-export declare const DEFAULT_MAX_CONSECUTIVE_UNANSWERED = 8;
-export declare class SocketHeartbeat {
-    private readonly options;
-    private inFlight;
-    private intervalTimer;
-    /**
-     * Identifies the current chain of scheduled beats.
-     *
-     * Separate from {@link epoch} on purpose: a reset means a new connection, not
-     * a new cadence, so retiring an in-flight beat must not also unhook the
-     * interval that would have issued the next one.
-     */
-    private intervalToken;
-    /** Whether the alarm has already been raised for the current run of misses. */
-    private lost;
-    /**
-     * Bumped by every start, stop and reset.
-     *
-     * A deadline armed for a previous connection fires after a reconnect - an
-     * intentional close does not reject the request it was waiting on - and
-     * letting it tick the new run's counters would condemn a healthy socket on
-     * the strength of a dead one's silence.
-     */
-    private epoch;
-    private state;
-    constructor(options: SocketHeartbeatOptions);
-    /** A snapshot, so a caller holding it cannot be surprised by a later beat. */
-    get account(): HeartbeatAccount;
-    /**
-     * Begins beating on a fresh account, replacing any cadence already running.
-     *
-     * Returns the way to stop *this* cadence. The disposer is inert once a later
-     * start has replaced it, which matters whenever one heartbeat is shared
-     * across successive connections: a superseded connection's teardown arrives
-     * late, and an unguarded stop would silently take the live connection's beat
-     * down with it.
-     */
-    start(): () => void;
-    stop(): void;
-    /**
-     * Starts the account over for a new connection, without touching the
-     * interval.
-     *
-     * Separate from {@link start} because a caller may learn it has a new
-     * connection before it is ready to beat on one, and the old socket's armed
-     * deadline has to stop counting the moment that happens rather than when the
-     * first new beat goes out.
-     */
-    reset(): void;
-    /**
-     * Beats once, now, outside the interval.
-     *
-     * For callers with a reason to check immediately - a user who just came back
-     * to the keyboard - rather than waiting out a cadence sized for idle
-     * connections. Safe alongside a running interval: the in-flight guard means
-     * one of the two simply skips.
-     */
-    beatNow(): Promise<void>;
-    /**
-     * Stamps inbound traffic. Call this for every message the socket delivers:
-     * it is what lets a beat starved behind a bulk transfer be told apart from
-     * one starved by a peer that is gone.
-     */
-    recordReceive(): void;
-    /** Retires whatever is in flight, so its settle cannot touch the next run. */
-    private invalidate;
-    private schedule;
-    private fire;
-    private settle;
-    private recordAnswer;
-    private recordRejection;
-    /** Traffic that arrived while this beat was waiting, not merely at some point. */
-    private receivedSince;
-    private get maxConsecutiveMisses();
-    private get maxConsecutiveUnanswered();
-}
-//# sourceMappingURL=heartbeat.d.ts.map

package/dist-esm/socket/heartbeat.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../../src/socket/heartbeat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,yCAAyC;AACzC,MAAM,MAAM,WAAW;AACrB,yDAAyD;AACvD,SAAS;AACX,6EAA6E;GAC3E,SAAS;AACX,wEAAwE;GACtE,OAAO;AACT,8EAA8E;GAC5E,OAAO;AACT,kEAAkE;GAChE,MAAM,CAAC;AAEX;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;;;OAQG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;OAQG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B,CAAC;AAEF,MAAM,WAAW,sBAAsB;IACrC,8EAA8E;IAC9E,IAAI,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,SAAS,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,MAAM,CAAC;IAClC;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC;IAC3C;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAC3C;;;;;;;;;;;;;;;;;;OAkBG;IACH,MAAM,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC5C,8EAA8E;IAC9E,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;IAC1F;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC;CAC5B;AAED,eAAO,MAAM,8BAA8B,IAAI,CAAC;AAChD,eAAO,MAAM,kCAAkC,IAAI,CAAC;AAyCpD,qBAAa,eAAe;IAwBP,OAAO,CAAC,QAAQ,CAAC,OAAO;IAvB3C,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,aAAa,CAAoB;IACzC;;;;;;OAMG;IACH,OAAO,CAAC,aAAa,CAAK;IAC1B,+EAA+E;IAC/E,OAAO,CAAC,IAAI,CAAS;IACrB;;;;;;;OAOG;IACH,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,KAAK,CAAkC;gBAEX,OAAO,EAAE,sBAAsB;IAEnE,8EAA8E;IAC9E,IAAW,OAAO,IAAI,gBAAgB,CAErC;IAED;;;;;;;;OAQG;IACI,KAAK,IAAI,MAAM,IAAI;IAYnB,IAAI,IAAI,IAAI;IASnB;;;;;;;;OAQG;IACI,KAAK,IAAI,IAAI;IAKpB;;;;;;;OAOG;IACU,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrC;;;;OAIG;IACI,aAAa,IAAI,IAAI;IAI5B,8EAA8E;IAC9E,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,QAAQ;YAeF,IAAI;IAgClB,OAAO,CAAC,MAAM;IA6Bd,OAAO,CAAC,YAAY;IAYpB,OAAO,CAAC,eAAe;IA4CvB,kFAAkF;IAClF,OAAO,CAAC,aAAa;IAIrB,OAAO,KAAK,oBAAoB,GAE/B;IAED,OAAO,KAAK,wBAAwB,GAEnC;CACF"}

package/dist-esm/socket/heartbeat.js

@@ -1,308 +0,0 @@
-/**
- * A paced liveness beat over a request channel.
- *
- * Every long-lived socket in this repo eventually needs the same thing: proof
- * that the peer is still answering, cheaply, for as long as the connection is
- * held. The naive version - an interval that fires a request and counts the
- * failures - is wrong in three ways that only show up under load, and each one
- * was found the hard way:
- *
- *   1. A request inherits the channel's own budget, which is the whole
- *      caller-facing operation (minutes). A beat that borrows it cannot report a
- *      miss inside any window a caller waits in, so it holds its own deadline.
- *   2. Without an in-flight guard, a peer that stopped answering collects a new
- *      pending request every interval, none of which can ever be reconciled.
- *      The answer paces the beats, not the interval.
- *   3. A beat's response shares the socket with bulk pushes, so a large transfer
- *      head-of-line blocks the answer past any sane deadline while the
- *      connection is perfectly healthy. Acting on that kills a busy socket and,
- *      where the caller reconnects, re-sends the same payload and does it again.
- *
- * The third is the subtle one, and it takes two guards, because neither is
- * sufficient alone. Inbound traffic during the beat's own wait proves the
- * connection is alive - but a bulk RPC response is a single websocket message,
- * and no receive event fires until its last byte lands, so that cannot be the
- * only guard. A single missed beat therefore also gets grace: a transfer merely
- * has to finish inside one extra interval for the next answer to get through.
- *
- * Both guards answer to one bound. Inbound data proves the receive path, not
- * that the request channel answers, so no amount of either excuse may let a
- * wedged channel hide forever: once
- * {@link SocketHeartbeatOptions.maxConsecutiveUnanswered} beats in a row have
- * gone unanswered, the next silence is believed whatever the reason, and the
- * grace is bypassed with it.
- *
- * Extracted from the browser editor's dev-server heartbeat, which learned all
- * of the above the hard way and is the first thing to beat with it.
- */
-export const DEFAULT_MAX_CONSECUTIVE_MISSES = 2;
-export const DEFAULT_MAX_CONSECUTIVE_UNANSWERED = 8;
-/** Keeps a Node timer from holding the process open; a no-op in a browser. */
-function unref(timer) {
-    timer.unref?.();
-}
-/** This heartbeat's own deadline, so a rejection it raised is recognizable. */
-class BeatTimeoutError extends Error {
-    constructor(timeoutMs) {
-        super(`beat timed out after ${timeoutMs}ms`);
-        this.name = 'BeatTimeoutError';
-    }
-}
-function describeUnknownError(error) {
-    if (error instanceof Error) {
-        return error.message;
-    }
-    if (typeof error === 'object' && error !== null) {
-        const { message } = error;
-        if (typeof message === 'string' && message.length > 0) {
-            return message;
-        }
-        try {
-            return JSON.stringify(error);
-        }
-        catch {
-            return String(error);
-        }
-    }
-    return String(error);
-}
-const emptyAccount = () => ({ failures: 0, lapses: 0, refusals: 0, sent: 0, unanswered: 0 });
-export class SocketHeartbeat {
-    options;
-    inFlight = false;
-    intervalTimer;
-    /**
-     * Identifies the current chain of scheduled beats.
-     *
-     * Separate from {@link epoch} on purpose: a reset means a new connection, not
-     * a new cadence, so retiring an in-flight beat must not also unhook the
-     * interval that would have issued the next one.
-     */
-    intervalToken = 0;
-    /** Whether the alarm has already been raised for the current run of misses. */
-    lost = false;
-    /**
-     * Bumped by every start, stop and reset.
-     *
-     * A deadline armed for a previous connection fires after a reconnect - an
-     * intentional close does not reject the request it was waiting on - and
-     * letting it tick the new run's counters would condemn a healthy socket on
-     * the strength of a dead one's silence.
-     */
-    epoch = 0;
-    state = emptyAccount();
-    constructor(options) {
-        this.options = options;
-    }
-    /** A snapshot, so a caller holding it cannot be surprised by a later beat. */
-    get account() {
-        return { ...this.state };
-    }
-    /**
-     * Begins beating on a fresh account, replacing any cadence already running.
-     *
-     * Returns the way to stop *this* cadence. The disposer is inert once a later
-     * start has replaced it, which matters whenever one heartbeat is shared
-     * across successive connections: a superseded connection's teardown arrives
-     * late, and an unguarded stop would silently take the live connection's beat
-     * down with it.
-     */
-    start() {
-        this.stop();
-        this.reset();
-        this.schedule();
-        const token = this.intervalToken;
-        return () => {
-            if (token === this.intervalToken) {
-                this.stop();
-            }
-        };
-    }
-    stop() {
-        this.invalidate();
-        this.intervalToken += 1;
-        if (this.intervalTimer) {
-            clearTimeout(this.intervalTimer);
-            this.intervalTimer = undefined;
-        }
-    }
-    /**
-     * Starts the account over for a new connection, without touching the
-     * interval.
-     *
-     * Separate from {@link start} because a caller may learn it has a new
-     * connection before it is ready to beat on one, and the old socket's armed
-     * deadline has to stop counting the moment that happens rather than when the
-     * first new beat goes out.
-     */
-    reset() {
-        this.invalidate();
-        this.state = emptyAccount();
-    }
-    /**
-     * Beats once, now, outside the interval.
-     *
-     * For callers with a reason to check immediately - a user who just came back
-     * to the keyboard - rather than waiting out a cadence sized for idle
-     * connections. Safe alongside a running interval: the in-flight guard means
-     * one of the two simply skips.
-     */
-    async beatNow() {
-        await this.fire(this.epoch);
-    }
-    /**
-     * Stamps inbound traffic. Call this for every message the socket delivers:
-     * it is what lets a beat starved behind a bulk transfer be told apart from
-     * one starved by a peer that is gone.
-     */
-    recordReceive() {
-        this.state.lastReceivedAt = Date.now();
-    }
-    /** Retires whatever is in flight, so its settle cannot touch the next run. */
-    invalidate() {
-        this.epoch += 1;
-        this.inFlight = false;
-        this.lost = false;
-    }
-    schedule() {
-        const token = this.intervalToken;
-        this.intervalTimer = setTimeout(() => {
-            if (token !== this.intervalToken) {
-                return;
-            }
-            // Rescheduled before the beat is issued rather than after it settles, so
-            // the interval stays the gap between beats instead of drifting by however
-            // long each answer took.
-            this.schedule();
-            void this.fire(this.epoch);
-        }, this.options.intervalMs);
-        unref(this.intervalTimer);
-    }
-    async fire(armedEpoch) {
-        if (this.inFlight || this.options.shouldBeat?.() === false) {
-            return;
-        }
-        this.inFlight = true;
-        this.state.sent += 1;
-        const sentAt = Date.now();
-        this.state.pendingSince = sentAt;
-        let deadline;
-        try {
-            await Promise.race([
-                this.options.beat(),
-                new Promise((_, reject) => {
-                    deadline = setTimeout(() => reject(new BeatTimeoutError(this.options.timeoutMs)), this.options.timeoutMs);
-                    unref(deadline);
-                })
-            ]);
-            this.settle(armedEpoch, sentAt, undefined);
-        }
-        catch (error) {
-            this.settle(armedEpoch, sentAt, error ?? new Error('beat failed'));
-        }
-        finally {
-            if (deadline !== undefined) {
-                clearTimeout(deadline);
-            }
-            // Only this epoch's beat owns the guard. Releasing it after a reset would
-            // let a stale settle admit a second concurrent beat.
-            if (armedEpoch === this.epoch) {
-                this.inFlight = false;
-            }
-        }
-    }
-    settle(armedEpoch, sentAt, error) {
-        if (armedEpoch !== this.epoch) {
-            // A beat belonging to a connection that is already gone. It says nothing
-            // about the current one, so it is neither counted nor reported.
-            return;
-        }
-        const durationMs = Date.now() - sentAt;
-        // Nothing is outstanding any more: this beat is the one that was, and a
-        // stale-epoch beat returned above without touching the current run's stamp.
-        delete this.state.pendingSince;
-        const outcome = error === undefined ? this.recordAnswer() : this.recordRejection(error, sentAt);
-        const account = this.account;
-        this.options.onOutcome?.(outcome, durationMs, account);
-        if (outcome === 'miss' && !this.lost) {
-            this.lost = true;
-            try {
-                this.options.onLost(account);
-            }
-            catch {
-                // The caller could not act on the loss, so the connection it meant to
-                // tear down is still there and still not answering. Re-arm, or the one
-                // alarm this run gets has been spent on a teardown that never happened.
-                // Swallowed rather than rethrown: `settle` already runs inside the
-                // beat's own catch, and throwing from here escapes `fire` as an
-                // unhandled rejection.
-                this.lost = false;
-            }
-        }
-    }
-    recordAnswer() {
-        this.state.failures = 0;
-        this.state.lapses = 0;
-        this.state.refusals = 0;
-        this.state.unanswered = 0;
-        this.state.lastSuccessAt = Date.now();
-        this.lost = false;
-        delete this.state.lastError;
-        delete this.state.lastRefusalError;
-        return 'success';
-    }
-    recordRejection(error, sentAt) {
-        const describe = this.options.describeError ?? describeUnknownError;
-        if (!(this.options.isUnanswered ?? ((cause) => cause instanceof BeatTimeoutError))(error)) {
-            // A definite answer, and recorded as one: a peer that answers is
-            // reachable, so a refusal must never close a connection over what is an
-            // application-level problem.
-            //
-            // It answers this beat and no others, so every count of what went
-            // missing is left exactly as it stands. Clearing `failures` would spend
-            // a refusal on the grace meant for a starved pong; clearing `unanswered`
-            // would hand a channel that alternates between timing out and refusing
-            // an unlimited deferral, because where inbound traffic excuses every
-            // silence that counter is the only thing left that can end one.
-            this.state.refusals += 1;
-            this.state.lastError = describe(error);
-            // Kept apart because the next unanswered beat overwrites `lastError`
-            // without clearing `refusals`, and the peer's own reason is the one thing
-            // in this account that was stated rather than inferred.
-            this.state.lastRefusalError = this.state.lastError;
-            return 'refused';
-        }
-        // Saturating rather than growing: this is what the caller reports as the
-        // length of the silence that killed the connection, and beats keep going
-        // out after the alarm is raised - the caller still has a socket to tear
-        // down - so an unbounded count would report a run longer than the bound it
-        // is measured against.
-        this.state.unanswered = Math.min(this.state.unanswered + 1, this.maxConsecutiveUnanswered);
-        // The cause of every unanswered beat, excused or not. A lapse that leaves
-        // this stale would have the log for an excused timeout name whatever failed
-        // before it.
-        this.state.lastError = describe(error);
-        const excusable = this.state.unanswered < this.maxConsecutiveUnanswered;
-        if (excusable && this.receivedSince(sentAt)) {
-            this.state.lapses += 1;
-            // Traffic during the beat's own wait proves the connection is alive, which
-            // clears an earlier suspicion as surely as an answer would.
-            this.state.failures = 0;
-            this.lost = false;
-            return 'lapse';
-        }
-        this.state.failures += 1;
-        return excusable && this.state.failures < this.maxConsecutiveMisses ? 'grace' : 'miss';
-    }
-    /** Traffic that arrived while this beat was waiting, not merely at some point. */
-    receivedSince(sentAt) {
-        return this.state.lastReceivedAt !== undefined && this.state.lastReceivedAt >= sentAt;
-    }
-    get maxConsecutiveMisses() {
-        return this.options.maxConsecutiveMisses ?? DEFAULT_MAX_CONSECUTIVE_MISSES;
-    }
-    get maxConsecutiveUnanswered() {
-        return this.options.maxConsecutiveUnanswered ?? DEFAULT_MAX_CONSECUTIVE_UNANSWERED;
-    }
-}
-//# sourceMappingURL=heartbeat.js.map

package/dist-esm/socket/heartbeat.js.map

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

package/dist-esm/socket/heartbeat.test.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=heartbeat.test.d.ts.map

package/dist-esm/socket/heartbeat.test.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"heartbeat.test.d.ts","sourceRoot":"","sources":["../../src/socket/heartbeat.test.ts"],"names":[],"mappings":""}