@abloatai/transaction 0.37.0

package/dist/transport/commitFrames.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Builds the outgoing frames the sync WebSocket sends on the commit path, and
+ * provides the single place claim events are traced. These are stateless
+ * helpers that hold no socket state, so both the transport and its frame
+ * dispatch can share them.
+ */
+import type { CommitMessage } from '../wire/index.js';
+import type { CommitAck as CanonicalCommitAck } from '../wire/commit.js';
+import type { OnStaleMode, StaleNotification, ReadDependency, TrackDependency } from '../coordination/schema.js';
+import type { ClaimAcquired, ClaimGranted, ClaimQueued, ClaimLost, ClaimRejection, ClaimExpired } from '../coordination/schema.js';
+import type { Logger } from '../logger.js';
+import type { SocketObservability } from '../observability.js';
+/**
+ * The value a commit acknowledgement resolves to. `notifications` is present
+ * only when a guarded write (`onStale: 'notify'`) met a concurrent change; it
+ * carries the advisory signal that lets the writer self-heal, and the same
+ * signal also arrives on the `conflict:notified` event.
+ */
+export type CommitAck = CanonicalCommitAck;
+/**
+ * The slice of a queued client mutation the commit frame reads — a structural
+ * port, so the reactive engine's fatter `MutationOperation` satisfies it
+ * without this module importing the consumer package.
+ */
+export interface CommitFrameOperation {
+    readonly type: string;
+    readonly model: string;
+    readonly id: string;
+    readonly input?: Record<string, unknown>;
+    readonly transactionId?: string;
+    readonly readAt?: number | null;
+    readonly onStale?: OnStaleMode | null;
+    readonly fenceToken?: number | null;
+}
+/**
+ * Converts the client's list of {@link CommitFrameOperation} values into the wire
+ * {@link CommitMessage} the server accepts. This is the one place the loosely
+ * typed operation — its `type` is a string, and it carries client-only
+ * `options` the server never reads — becomes the strict wire contract. Mapping
+ * each field by hand means a change to {@link WireCommitOperation} fails to compile
+ * here; the single `as` cast narrows the validated `type` to the wire union and
+ * is the only place that loosening happens.
+ */
+export declare function buildCommitFrame(operations: readonly CommitFrameOperation[], clientTxId: string, reads?: readonly ReadDependency[] | null, track?: readonly TrackDependency[] | null): CommitMessage;
+/**
+ * Defensively validate the optional `notifications` array off a commit ack.
+ * Untrusted wire data — a malformed entry is dropped rather than throwing,
+ * so a bad notification never sinks an otherwise-successful commit.
+ */
+export declare function parseNotifications(raw: unknown): StaleNotification[] | undefined;
+/** The reporting ports a claim trace writes through — supplied by the caller
+ *  (the frame dispatch passes its session's own ports). */
+export interface ClaimTracePorts {
+    readonly logger: Logger;
+    readonly observability: SocketObservability;
+}
+/**
+ * Which frame reports each phase of a claim's life.
+ *
+ * The correspondence is real and was previously implicit: six dispatch handlers
+ * each passed their own payload alongside a phase they picked by hand, and
+ * nothing checked that the two matched. Stating it once means a caller cannot
+ * label a rejection as an acquisition.
+ *
+ * Every value is the `z.infer` of the schema the dispatcher parsed with, so no
+ * field is restated here — this maps existing types, it does not describe them.
+ */
+interface ClaimFrameByPhase {
+    acquired: ClaimAcquired;
+    granted: ClaimGranted;
+    queued: ClaimQueued;
+    lost: ClaimLost;
+    rejected: ClaimRejection;
+    expired: ClaimExpired;
+}
+/**
+ * The single place claim events are traced. Every `claim_*` frame passes
+ * through here, so a developer debugging a collision gets one consistent record
+ * — a console line and a structured capture — without each frame case
+ * re-deriving the row and holder shape.
+ *
+ * The payload arrives already validated against its frame's schema, so this
+ * reads it as the shape it is rather than re-narrowing an untyped record. That
+ * distinction is not cosmetic: while this took `Record<string, unknown>` it
+ * read `actor`, `participantKind`, and `description` off frames that carry none
+ * of them, and every one of those reads silently produced `undefined` because a
+ * string key never has to exist.
+ */
+export declare function recordClaim<P extends keyof ClaimFrameByPhase>(ports: ClaimTracePorts, phase: P, payload: ClaimFrameByPhase[P]): void;
+export {};
+//# sourceMappingURL=commitFrames.d.ts.map

package/dist/transport/commitFrames.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commitFrames.d.ts","sourceRoot":"","sources":["../../src/transport/commitFrames.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,aAAa,EAAuB,MAAM,kBAAkB,CAAC;AAC3E,OAAO,KAAK,EAAE,SAAS,IAAI,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACzE,OAAO,KAAK,EACV,WAAW,EACX,iBAAiB,EACjB,cAAc,EACd,eAAe,EAChB,MAAM,2BAA2B,CAAC;AAKnC,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,WAAW,EACX,SAAS,EACT,cAAc,EACd,YAAY,EACb,MAAM,2BAA2B,CAAC;AAKnC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAC;AAE/D;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,kBAAkB,CAAC;AAE3C;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IACtC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,SAAS,oBAAoB,EAAE,EAC3C,UAAU,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,SAAS,cAAc,EAAE,GAAG,IAAI,EACxC,KAAK,CAAC,EAAE,SAAS,eAAe,EAAE,GAAG,IAAI,GACxC,aAAa,CAoBf;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,iBAAiB,EAAE,GAAG,SAAS,CAQhF;AAED;2DAC2D;AAC3D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,mBAAmB,CAAC;CAC7C;AAED;;;;;;;;;;GAUG;AACH,UAAU,iBAAiB;IACzB,QAAQ,EAAE,aAAa,CAAC;IACxB,OAAO,EAAE,YAAY,CAAC;IACtB,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,cAAc,CAAC;IACzB,OAAO,EAAE,YAAY,CAAC;CACvB;AAaD;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,CAAC,SAAS,MAAM,iBAAiB,EAC3D,KAAK,EAAE,eAAe,EACtB,KAAK,EAAE,CAAC,EACR,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAC5B,IAAI,CA0DN"}

package/dist/transport/commitFrames.js

@@ -0,0 +1,135 @@
+/**
+ * Builds the outgoing frames the sync WebSocket sends on the commit path, and
+ * provides the single place claim events are traced. These are stateless
+ * helpers that hold no socket state, so both the transport and its frame
+ * dispatch can share them.
+ */
+import { claimEventReasonSchema, staleNotificationSchema, } from '../coordination/schema.js';
+import { formatClaim } from '../coordination/trace.js';
+import { modelTarget } from '../coordination/locator.js';
+/**
+ * Converts the client's list of {@link CommitFrameOperation} values into the wire
+ * {@link CommitMessage} the server accepts. This is the one place the loosely
+ * typed operation — its `type` is a string, and it carries client-only
+ * `options` the server never reads — becomes the strict wire contract. Mapping
+ * each field by hand means a change to {@link WireCommitOperation} fails to compile
+ * here; the single `as` cast narrows the validated `type` to the wire union and
+ * is the only place that loosening happens.
+ */
+export function buildCommitFrame(operations, clientTxId, reads, track) {
+    const payload = {
+        operations: operations.map((op) => ({
+            type: op.type,
+            model: op.model,
+            id: op.id,
+            input: op.input,
+            transactionId: op.transactionId,
+            readAt: op.readAt,
+            onStale: op.onStale,
+            fenceToken: op.fenceToken,
+        })),
+        clientTxId,
+    };
+    // The batch premise: the rows or groups the writer read before committing.
+    if (reads && reads.length > 0)
+        payload.reads = [...reads];
+    // Durable premises the writer is registering: the rows or groups it
+    // wants to keep hearing about after this commit, delivered on a future receipt.
+    if (track && track.length > 0)
+        payload.track = [...track];
+    return { type: 'commit', payload };
+}
+/**
+ * Defensively validate the optional `notifications` array off a commit ack.
+ * Untrusted wire data — a malformed entry is dropped rather than throwing,
+ * so a bad notification never sinks an otherwise-successful commit.
+ */
+export function parseNotifications(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    const out = [];
+    for (const entry of raw) {
+        const parsed = staleNotificationSchema.safeParse(entry);
+        if (parsed.success)
+            out.push(parsed.data);
+    }
+    return out.length > 0 ? out : undefined;
+}
+// The phases this map covers and the phases a ClaimEvent can report are the
+// same set. Adding one to either without the other stops compiling here.
+const _phaseCoverage = true;
+void _phaseCoverage;
+/**
+ * The single place claim events are traced. Every `claim_*` frame passes
+ * through here, so a developer debugging a collision gets one consistent record
+ * — a console line and a structured capture — without each frame case
+ * re-deriving the row and holder shape.
+ *
+ * The payload arrives already validated against its frame's schema, so this
+ * reads it as the shape it is rather than re-narrowing an untyped record. That
+ * distinction is not cosmetic: while this took `Record<string, unknown>` it
+ * read `actor`, `participantKind`, and `description` off frames that carry none
+ * of them, and every one of those reads silently produced `undefined` because a
+ * string key never has to exist.
+ */
+export function recordClaim(ports, phase, payload) {
+    // Widened so the members can be told apart with `in`. The parameter above
+    // stays correlated to `phase`, which is what the widening cannot undo.
+    const frame = payload;
+    const target = 'target' in frame ? frame.target : undefined;
+    // The holder rides on the rejection and queued frames, with a summary of
+    // their claim beside it. Collecting it is the whole of "name the
+    // counterparty" — the wire has carried it all along and this projection used
+    // to flatten it into one string alongside the cause.
+    const counterparty = {
+        ...('heldBy' in frame && frame.heldBy !== undefined
+            ? { actor: frame.heldBy }
+            : {}),
+        ...('heldByKind' in frame && frame.heldByKind !== undefined
+            ? { participantKind: frame.heldByKind }
+            : {}),
+        ...('heldByClaimId' in frame && frame.heldByClaimId !== undefined
+            ? { claimId: frame.heldByClaimId }
+            : {}),
+        ...('heldByExpiresAt' in frame && frame.heldByExpiresAt !== undefined
+            ? { expiresAt: frame.heldByExpiresAt }
+            : {}),
+        ...('heldByClaim' in frame && frame.heldByClaim?.description !== undefined
+            ? { description: frame.heldByClaim.description }
+            : {}),
+    };
+    // `reason` is a plain string on the wire, which is frozen, so an older server
+    // may send a word the closed set does not list. One that parses becomes the
+    // typed reason; one that does not is absent rather than passed off as prose.
+    const parsedReason = 'reason' in frame ? claimEventReasonSchema.safeParse(frame.reason) : undefined;
+    const event = {
+        phase,
+        claimId: frame.claimId,
+        ...(target ? modelTarget(target) : {}),
+        ...(target?.field !== undefined ? { field: target.field } : {}),
+        // No claim frame names an actor of its own; the only participant one
+        // carries is the holder that blocked it.
+        ...('heldBy' in frame && frame.heldBy !== undefined
+            ? { actor: frame.heldBy }
+            : {}),
+        ...('position' in frame ? { position: frame.position } : {}),
+        ...(parsedReason?.success ? { reason: parsedReason.data } : {}),
+        ...('policyReason' in frame && frame.policyReason !== undefined
+            ? { policyReason: frame.policyReason }
+            : {}),
+        ...(Object.keys(counterparty).length > 0 ? { heldBy: counterparty } : {}),
+    };
+    const message = formatClaim(event);
+    // A rejection or lost lease is the collision a developer is actively
+    // debugging → warn (shows at the default log level). The routine events
+    // (acquired/queued/granted/expired) are debug-only so they never drown the
+    // console until you opt in with `new Ablo({ debug: true })`.
+    const isCollision = phase === 'rejected' || phase === 'lost';
+    if (isCollision)
+        ports.logger.warn(message);
+    else
+        ports.logger.debug(message);
+    ports.observability.breadcrumb(message, 'sync.coordination', isCollision ? 'warning' : 'info');
+    ports.observability.captureClaim(event);
+}
+//# sourceMappingURL=commitFrames.js.map

package/dist/transport/commitFrames.js.map

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

package/dist/transport/connectionManager.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Owns the sync engine's connection lifecycle: the state machine that carries a
+ * client from a healthy connection, through a dropout, and back to live. It
+ * watches the browser's online/offline and visibility events, probes real
+ * connectivity and session validity with {@link probeNetwork}, applies retry
+ * backoff with a ceiling and jitter, and runs a watchdog for the cases where
+ * the browser never fires an event (VPN flips, captive portals). When it
+ * decides to recover, it drives the reconnect sequence — bootstrap, then
+ * WebSocket connect — through the {@link ConnectionCallbacks.onReconnect}
+ * callback and reacts to the outcome.
+ *
+ * It deliberately does not perform the bootstrap, local-storage, or object-pool
+ * work itself; that lives in the embedding store, which the manager reaches
+ * only through its callbacks. One manager is created per store, started on the
+ * first successful connect and disposed on teardown.
+ *
+ * This is a plain state machine, not a reactive object: it lives in the
+ * settlement core, which carries no reactivity runtime (ADR 0016). A consumer
+ * that wants to render recovery progress mirrors the transitions through
+ * {@link ConnectionCallbacks.onStateChange} into its own observable state —
+ * which is what the reactive engine's store does.
+ *
+ *   CONNECTED ──(socket drop)──► PROBING_NETWORK ──► RECONNECTING ──► CONNECTED
+ *        │                              │                  │
+ *   (network lost)                      ▼                  ▼
+ *        ▼                        SESSION_EXPIRED       BACKOFF ──► PROBING_NETWORK
+ *     OFFLINE ──(online)──► PROBING_NETWORK
+ *        │
+ *        ▼
+ *   WAITING_FOR_NETWORK
+ *
+ * Three behaviors are worth calling out. A network return or tab focus during a
+ * backoff delay jumps straight to probing instead of waiting out the full
+ * interval. Reaching the retry ceiling while the browser reports offline parks
+ * in `waiting_for_network` rather than hard-reloading a browser that has no
+ * network. And a socket drop (close code 1006) goes straight to probing rather
+ * than the passive `offline` state — 1006 is generated locally and carries no
+ * connectivity signal, so on a healthy machine no online/offline event ever
+ * fires; only a genuine operating-system network loss parks in `offline` to
+ * wait for the `online` event.
+ */
+import { type ProbeResult } from './networkProbe.js';
+import type { AuthTokenGetter } from '../auth/credentialSource.js';
+import type { CredentialRefreshOutcome } from './credentialLifecycle.js';
+import { type Logger } from '../logger.js';
+import { type TransportObservability } from '../observability.js';
+export type ConnectionState = 'connected' | 'offline' | 'probing_network' | 'validating_session' | 'refreshing_credential' | 'reconnecting' | 'backoff' | 'waiting_for_network' | 'auth_blocked' | 'session_expired';
+export type ConnectionEvent = {
+    type: 'NETWORK_LOST';
+} | {
+    type: 'NETWORK_ONLINE';
+} | {
+    type: 'TAB_VISIBLE';
+} | {
+    type: 'WS_CONNECTED';
+} | {
+    type: 'WS_DISCONNECTED';
+} | {
+    type: 'WS_SESSION_ERROR';
+} | {
+    type: 'WS_HANDSHAKE_FAILED';
+} | {
+    type: 'PROBE_SUCCESS';
+    sessionValid: boolean;
+} | {
+    type: 'PROBE_AUTH_BLOCKED';
+}
+/** The probe saw an expired ephemeral access key (`access_credential_expiry`).
+ *  Recoverable: re-mint a fresh `ek_`/`rk_` and re-probe — never a sign-out. */
+ | {
+    type: 'PROBE_CREDENTIAL_STALE';
+} | {
+    type: 'PROBE_FAILED';
+}
+/** A fresh access credential is available (the re-mint succeeded, or one was
+ *  pushed in via `setAuthToken`). Re-probe so a parked connection picks it up. */
+ | {
+    type: 'CREDENTIAL_REFRESHED';
+} | {
+    type: 'RECONNECT_SUCCESS';
+} | {
+    type: 'RECONNECT_FAILED';
+} | {
+    type: 'BACKOFF_ELAPSED';
+} | {
+    type: 'BOOTSTRAP_FAILED_SESSION';
+} | {
+    type: 'MANUAL_RETRY';
+};
+export interface ConnectionCallbacks {
+    /** Run bootstrap + WebSocket reconnect. Returns the outcome. */
+    onReconnect: () => Promise<'success' | 'session_error' | 'network_error'>;
+    /**
+     * Re-mints the short-lived access credential (the `ek_`/`rk_`) and pushes it
+     * into the credential source, then reports the outcome. Invoked in the
+     * `refreshing_credential` state — that is, when a probe found the access key
+     * stale (`PROBE_CREDENTIAL_STALE`). The three outcomes map onto recovery:
+     *   - `'refreshed'`     → a fresh credential is in place; re-probe and reconnect.
+     *   - `'session_error'` → the long-lived login itself is gone (the mint
+     *                          returned null, a 401/403); terminal, so sign out.
+     *   - `'network_error'` → the mint endpoint was unreachable (offline, 5xx, or
+     *                          a throw); transient, so back off and retry rather
+     *                          than sign out.
+     * Optional: a deployment with no re-mint path (for example a static `apiKey`)
+     * omits it, and the state machine falls back to a plain re-probe.
+     */
+    onRefreshCredential?: () => Promise<CredentialRefreshOutcome>;
+    /** Called when the session is confirmed expired — route to signin. */
+    onSessionExpired: () => void;
+    /** Called to tear down the WebSocket when entering a dead state. */
+    onDisconnectWebSocket: () => void;
+    /**
+     * Fires on every state transition. It lets the embedding store mirror
+     * recovery progress into its visible `syncStatus`, so the UI can show
+     * "Reconnecting…" instead of a sticky "offline" while the machine cycles
+     * through `probing_network` → `reconnecting` → `backoff`. Optional; when
+     * omitted, the state machine is simply opaque to the UI.
+     */
+    onStateChange?: (next: ConnectionState, prev: ConnectionState) => void;
+}
+export interface ConnectionManagerOptions {
+    /**
+     * Sync-server base URL used for probes. Falls back to the env-based
+     * default of `probeNetwork`.
+     */
+    baseUrl?: string;
+    /**
+     * Current bearer credential for authenticated probes. Read lazily so token
+     * refreshes pushed through `Ablo.setAuthToken()` are used by the next probe
+     * without recreating the manager.
+     */
+    getAuthToken?: AuthTokenGetter;
+    /** Override retry ceilings / jitter. Production should leave defaults. */
+    backoff?: Partial<typeof DEFAULT_BACKOFF>;
+    /** Where transitions are logged. Defaults to silent. */
+    logger?: Logger;
+    /** Where dead-end states are reported. Defaults to silent. */
+    observability?: TransportObservability;
+}
+declare const DEFAULT_BACKOFF: {
+    readonly BASE_MS: 2000;
+    readonly MAX_MS: 30000;
+    readonly MAX_ATTEMPTS: 8;
+    readonly JITTER: 0.15;
+};
+export declare class ConnectionManager {
+    state: ConnectionState;
+    offlineSince: Date | null;
+    attempt: number;
+    lastProbeResult: ProbeResult | null;
+    private callbacks;
+    private backoffTimer;
+    private debounceTimer;
+    private watchdogTimer;
+    private stuckCycles;
+    /** Consecutive access-key re-mints in the current recovery cycle; reset on
+     *  reaching `connected`. See {@link MAX_CREDENTIAL_REFRESH_ATTEMPTS}. */
+    private credentialRefreshAttempts;
+    private disposed;
+    private readonly baseUrl?;
+    private readonly getAuthToken?;
+    private readonly backoff;
+    private readonly logger;
+    private readonly observability;
+    private handleBrowserOnline;
+    private handleBrowserOffline;
+    private handleVisibilityChange;
+    constructor(options?: ConnectionManagerOptions);
+    start(callbacks: ConnectionCallbacks): void;
+    dispose(): void;
+    send(event: ConnectionEvent): void;
+    private transition;
+    private onEnterState;
+    /**
+     * FSM effects are fire-and-forget by design (`onEnterState` is sync). Each
+     * effect catches its own operational failures and maps them onto an FSM
+     * event, so a rejection here means the machine wedged mid-transition
+     * (`send()` or a transition listener threw) with no retry timer armed past
+     * it — capture it instead of losing the reconnect loop silently.
+     */
+    private captureEffectFailure;
+    private runProbe;
+    /**
+     * Re-mint the short-lived access key on `refreshing_credential`. Delegates to
+     * the `onRefreshCredential` callback (which mints a fresh `ek_`/`rk_` from the
+     * still-valid login and pushes it into the credential source) and maps its
+     * tri-state outcome onto the FSM:
+     *   - `refreshed`     → `CREDENTIAL_REFRESHED` → re-probe & reconnect.
+     *   - `session_error` → `BOOTSTRAP_FAILED_SESSION` → sign out (login is gone).
+     *   - `network_error` → `RECONNECT_FAILED` → back off & retry (never sign out).
+     *
+     * A bounded attempt counter guards against a hot loop where the server keeps
+     * reporting the key stale even after a "successful" re-mint (e.g. a clock skew
+     * or a mint that returns an already-rejected key): after
+     * `MAX_CREDENTIAL_REFRESH_ATTEMPTS` we fall through to `auth_blocked` (stop,
+     * no sign-out) rather than spin. The counter resets once we reach `connected`.
+     *
+     * When no refresher is wired (e.g. a static `apiKey` deployment), we re-probe
+     * directly — the credential source's own scheduler owns refresh there.
+     */
+    private runRefreshCredential;
+    private runReconnect;
+    private scheduleBackoff;
+    private setupBrowserListeners;
+    private removeBrowserListeners;
+    private startWatchdog;
+    get isConnected(): boolean;
+    get isOffline(): boolean;
+    get isReconnecting(): boolean;
+    get isSessionExpired(): boolean;
+    get offlineDuration(): string | null;
+    private clearBackoffTimer;
+    private clearDebounceTimer;
+}
+export {};
+//# sourceMappingURL=connectionManager.d.ts.map

package/dist/transport/connectionManager.d.ts.map

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