@owlmeans/client-socket 0.1.18-rc.5 → 0.1.18-rc.50

package/build/hooks.js

@@ -0,0 +1,66 @@
+import { clientRequestHelper } from '@owlmeans/client-entrypoint';
+import { useContext, useValue } from '@owlmeans/client';
+import { AUTH_QUERY } from '@owlmeans/auth';
+import { useEffect, useMemo, useState } from 'react';
+import { SOCKET_STATUS } from './consts.js';
+import { socketClientHelper } from './helper.js';
+/**
+ * Open a socket through a declared entrypoint protocol.
+ *
+ * String aliases remain an adapter input for dynamically addressed integrations, while
+ * application callers pass their immutable protocol declaration and receive its bound client
+ * entrypoint here at the transport boundary.
+ *
+ * Re-opens on its own after a network drop (see `ws()`). `null` until the first attempt opens,
+ * and again once the retry budget elapses without one ever opening — dialed afresh on the next
+ * `SocketStatusService.retry()`. A screen that must tell those two apart reads
+ * `useSocketStatus()` (from `./status.js`) alongside this.
+ */
+export const useWs = (module, request, options) => {
+    const ctx = useContext();
+    const mod = useMemo(() => ctx.entrypoint(module), [module]);
+    const [failed, setFailed] = useState(false);
+    const [dial, setDial] = useState(0);
+    const connection = useValue(async (cancel) => {
+        const _request = clientRequestHelper.provideRequest(mod.alias, mod.path());
+        Object.assign(_request, request);
+        try {
+            const conn = await socketClientHelper.ws(mod, _request, options);
+            if (cancel?.current) {
+                // The component unmounted while the handshake (or its retries) were still in flight —
+                // there is no `useEffect` cleanup coming for this value, so close it here instead of
+                // leaving a live socket and its retry timers attached to nothing.
+                void conn.close();
+                return null;
+            }
+            return conn;
+        }
+        catch {
+            if (!cancel?.current)
+                setFailed(true);
+            return null;
+        }
+    }, [
+        mod.alias,
+        request?.query?.[AUTH_QUERY],
+        request?.params ? JSON.stringify(request.params) : undefined,
+        dial
+    ]);
+    useEffect(() => {
+        if (!failed || !ctx.hasService(SOCKET_STATUS))
+            return;
+        return ctx.socketStatus().onRetry(() => {
+            setFailed(false);
+            setDial(n => n + 1);
+        });
+    }, [failed]);
+    useEffect(() => {
+        if (connection != null) {
+            return () => {
+                void connection.close();
+            };
+        }
+    }, [connection]);
+    return connection;
+};
+//# sourceMappingURL=hooks.js.map

package/build/hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.js","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,mBAAmB,EAAE,MAAM,6BAA6B,CAAA;AAKxF,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC3C,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAA;AACpD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAEhD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,CACnB,MAAoC,EAAE,OAAuC,EAAE,OAAmB,EAC/E,EAAE;IACrB,MAAM,GAAG,GAAG,UAAU,EAAE,CAAA;IACxB,MAAM,GAAG,GAAG,OAAO,CACjB,GAAG,EAAE,CAAC,GAAG,CAAC,UAAU,CAAmB,MAAM,CAAC,EAC9C,CAAC,MAAM,CAAC,CACT,CAAA;IACD,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAA;IAC3C,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAA;IACnC,MAAM,UAAU,GAAG,QAAQ,CAAoB,KAAK,EAAE,MAAM,EAAE,EAAE;QAC9D,MAAM,QAAQ,GAAG,mBAAmB,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,EAAE,CAAC,CAAA;QAC1E,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;QAChC,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,kBAAkB,CAAC,EAAE,CAAC,GAAG,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAA;YAChE,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;gBACpB,sFAAsF;gBACtF,qFAAqF;gBACrF,kEAAkE;gBAClE,KAAK,IAAI,CAAC,KAAK,EAAE,CAAA;gBACjB,OAAO,IAAI,CAAA;YACb,CAAC;YACD,OAAO,IAAI,CAAA;QACb,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,MAAM,EAAE,OAAO;gBAAE,SAAS,CAAC,IAAI,CAAC,CAAA;YACrC,OAAO,IAAI,CAAA;QACb,CAAC;IACH,CAAC,EAAE;QACD,GAAG,CAAC,KAAK;QACT,OAAO,EAAE,KAAK,EAAE,CAAC,UAAU,CAAC;QAC5B,OAAO,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS;QAC5D,IAAI;KACL,CAAC,CAAA;IAEF,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,CAAC,MAAM,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,aAAa,CAAC;YAAE,OAAM;QACrD,OAAQ,GAA4C,CAAC,YAAY,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;YAC/E,SAAS,CAAC,KAAK,CAAC,CAAA;YAChB,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;QACrB,CAAC,CAAC,CAAA;IACJ,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAA;IAEZ,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,UAAU,IAAI,IAAI,EAAE,CAAC;YACvB,OAAO,GAAG,EAAE;gBACV,KAAK,UAAU,CAAC,KAAK,EAAE,CAAA;YACzB,CAAC,CAAA;QACH,CAAC;IACH,CAAC,EAAE,CAAC,UAAU,CAAC,CAAC,CAAA;IAEhB,OAAO,UAAU,CAAA;AACnB,CAAC,CAAA"}

package/build/index.d.ts

@@ -1,3 +1,7 @@
 export type * from './types.js';
+export type * from './helper/types.js';
+export * from './consts.js';
 export * from './helper.js';
+export * from './hooks.js';
+export * from './status.js';
 //# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,mBAAmB,mBAAmB,CAAA;AACtC,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA"}

package/build/index.js

@@ -1,2 +1,5 @@
+export * from './consts.js';
 export * from './helper.js';
+export * from './hooks.js';
+export * from './status.js';
 //# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,aAAa,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA"}

package/build/status.d.ts

@@ -0,0 +1,30 @@
+import type { Config, Context, SocketConnectionState, SocketStatusService, SocketStatusServiceAppend } from './types.js';
+/**
+ * Aggregates the coarse health of every `ws()`/`useWs()` connection an app has open into one
+ * worst-of-all state. A page with several sockets (thinking stream, file watch, notifications…)
+ * still shows one dialog, not one per socket — so the aggregate, not any single connection, is
+ * what a UI like `SocketReloadDialog` reads.
+ */
+export declare const createSocketStatusService: (alias?: string) => SocketStatusService;
+/**
+ * Register the shared socket-status aggregator. Idempotent, and cheap enough for a host package
+ * (`@owlmeans/web-panel`) to call unconditionally on every context: every `ws()`/`useWs()`
+ * connection reports itself here if — and only if — the context carries this service, so an app
+ * that never calls this behaves exactly as it did before reconnect support existed.
+ */
+export declare const appendSocketStatus: <C extends Config = Config, T extends Context<C> = Context<C>>(ctx: T, alias?: string) => T & SocketStatusServiceAppend;
+/**
+ * The worst state across every live `ws()`/`useWs()` connection, or `'online'` if the app never
+ * registered the status service (`appendSocketStatus`) or has not finished initializing yet.
+ */
+export declare const useSocketStatus: () => SocketConnectionState;
+/**
+ * `retry` revives every lost connection now (`SocketStatusService.retry()`); `retrying` is true
+ * from any retry — this one, or the service's own on tab activation — until the aggregate settles
+ * back on `'online'` or `'lost'`.
+ */
+export declare const useSocketRetry: () => {
+    retry: () => void;
+    retrying: boolean;
+};
+//# sourceMappingURL=status.d.ts.map

package/build/status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"status.d.ts","sourceRoot":"","sources":["../src/status.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,MAAM,EAAE,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,yBAAyB,EACvF,MAAM,YAAY,CAAA;AAInB;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,WAAW,MAAM,KAAmB,mBA6DzE,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,OACxF,CAAC,UAAS,MAAM,KACpB,CAAC,GAAG,yBAON,CAAA;AAgCD;;;GAGG;AACH,eAAO,MAAM,eAAe,QAAO,qBAWlC,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,QAAO;IAAE,KAAK,EAAE,MAAM,IAAI,CAAC;IAAC,QAAQ,EAAE,OAAO,CAAA;CAcvE,CAAA"}

package/build/status.js

@@ -0,0 +1,151 @@
+import { createService } from '@owlmeans/context';
+import { useContext } from '@owlmeans/client';
+import { useCallback, useEffect, useState } from 'react';
+import { RANK } from './consts.local.js';
+import { SOCKET_STATUS } from './consts.js';
+/**
+ * Aggregates the coarse health of every `ws()`/`useWs()` connection an app has open into one
+ * worst-of-all state. A page with several sockets (thinking stream, file watch, notifications…)
+ * still shows one dialog, not one per socket — so the aggregate, not any single connection, is
+ * what a UI like `SocketReloadDialog` reads.
+ */
+export const createSocketStatusService = (alias = SOCKET_STATUS) => {
+    const states = new Map();
+    const revivers = new Map();
+    const listeners = new Set();
+    const retryListeners = new Set();
+    let current = 'online';
+    const recompute = () => {
+        let worst = 'online';
+        for (const state of states.values()) {
+            if (RANK[state] > RANK[worst])
+                worst = state;
+        }
+        if (worst !== current) {
+            current = worst;
+            listeners.forEach(listener => listener(current));
+        }
+    };
+    // Connections still retrying are nudged too, so one whose older budget is about to run out does
+    // not report `'lost'` right after its lost siblings were revived.
+    const retry = () => {
+        const pending = [...states].filter(([, state]) => state !== 'online');
+        pending.forEach(([id]) => revivers.get(id)?.());
+        if (!pending.some(([, state]) => state === 'lost'))
+            return false;
+        retryListeners.forEach(listener => listener());
+        return true;
+    };
+    // A backgrounded tab is where sockets die unnoticed (throttled timers, a sleeping machine), so
+    // the moment it is looked at again is the moment to retry — before anyone reaches for a button.
+    const watchActivation = () => {
+        if (typeof document === 'undefined' || typeof window === 'undefined')
+            return;
+        document.addEventListener('visibilitychange', () => {
+            if (document.visibilityState === 'visible')
+                retry();
+        });
+        window.addEventListener('focus', () => { retry(); });
+        window.addEventListener('online', () => { retry(); });
+    };
+    return createService(alias, {
+        report: (id, state, revive) => {
+            states.set(id, state);
+            if (revive != null)
+                revivers.set(id, revive);
+            else
+                revivers.delete(id);
+            recompute();
+        },
+        release: (id) => { states.delete(id); revivers.delete(id); recompute(); },
+        state: () => current,
+        subscribe: listener => {
+            listeners.add(listener);
+            return () => { listeners.delete(listener); };
+        },
+        retry,
+        onRetry: listener => {
+            retryListeners.add(listener);
+            return () => { retryListeners.delete(listener); };
+        },
+    }, service => async () => {
+        watchActivation();
+        service.initialized = true;
+    });
+};
+/**
+ * Register the shared socket-status aggregator. Idempotent, and cheap enough for a host package
+ * (`@owlmeans/web-panel`) to call unconditionally on every context: every `ws()`/`useWs()`
+ * connection reports itself here if — and only if — the context carries this service, so an app
+ * that never calls this behaves exactly as it did before reconnect support existed.
+ */
+export const appendSocketStatus = (ctx, alias = SOCKET_STATUS) => {
+    const _ctx = ctx;
+    if (!ctx.hasService(alias)) {
+        ctx.registerService(createSocketStatusService(alias));
+    }
+    _ctx.socketStatus = () => ctx.service(alias);
+    return _ctx;
+};
+const readSocketStatusService = (ctx) => {
+    try {
+        return typeof ctx.hasService === 'function' && ctx.hasService(SOCKET_STATUS)
+            ? ctx.socketStatus?.() ?? null : null;
+    }
+    catch {
+        // Registered but not yet run through the context's OWN `init()` — a component that renders
+        // as a sibling of the router (as `SocketReloadDialog` does) mounts before that finishes,
+        // since `context.configure().init()` runs from the router's effect, not before React's
+        // first commit. Treat it as "not ready yet" rather than crash the render.
+        return null;
+    }
+};
+/** The status service once the context can hand it out; `null` while it cannot, or never will. */
+const useStatusService = () => {
+    const ctx = useContext();
+    const [service, setService] = useState(() => readSocketStatusService(ctx));
+    useEffect(() => {
+        if (service != null)
+            return;
+        let cancelled = false;
+        void ctx.waitForInitialized?.().then(() => { if (!cancelled)
+            setService(readSocketStatusService(ctx)); });
+        return () => { cancelled = true; };
+    }, [ctx, service]);
+    return service;
+};
+/**
+ * The worst state across every live `ws()`/`useWs()` connection, or `'online'` if the app never
+ * registered the status service (`appendSocketStatus`) or has not finished initializing yet.
+ */
+export const useSocketStatus = () => {
+    const service = useStatusService();
+    const [state, setState] = useState(() => service?.state() ?? 'online');
+    useEffect(() => {
+        if (service == null)
+            return;
+        setState(service.state());
+        return service.subscribe(setState);
+    }, [service]);
+    return state;
+};
+/**
+ * `retry` revives every lost connection now (`SocketStatusService.retry()`); `retrying` is true
+ * from any retry — this one, or the service's own on tab activation — until the aggregate settles
+ * back on `'online'` or `'lost'`.
+ */
+export const useSocketRetry = () => {
+    const service = useStatusService();
+    const [retrying, setRetrying] = useState(false);
+    useEffect(() => {
+        if (service == null)
+            return;
+        const stopRetry = service.onRetry(() => setRetrying(service.state() === 'reconnecting'));
+        const stopState = service.subscribe(state => { if (state !== 'reconnecting')
+            setRetrying(false); });
+        return () => { stopRetry(); stopState(); };
+    }, [service]);
+    const retry = useCallback(() => { service?.retry(); }, [service]);
+    return { retry, retrying };
+};
+//# sourceMappingURL=status.js.map

package/build/status.js.map

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

package/build/types.d.ts

@@ -1,7 +1,82 @@
 import type { ClientConfig } from '@owlmeans/client-context';
 import type { ClientContext } from '@owlmeans/client';
+import type { AbstractRequest } from '@owlmeans/entrypoint';
+import type { InitializedService } from '@owlmeans/context';
 export interface Config extends ClientConfig {
+    socket?: SocketClientSettings;
 }
 export interface Context<C extends Config = Config> extends ClientContext<C> {
 }
+/**
+ * How aggressively a dropped socket is retried, and when the carrier gives up on it.
+ *
+ * The delay grows geometrically from `minDelay` to `maxDelay` (±`jitter`, a fraction of the
+ * computed delay) and stays there. `budget` is measured from the connection's FIRST failed
+ * attempt in an outage — a socket that opens and drops again right away does not get a fresh
+ * budget — and `stableAfter` is how long a reopened socket must stay up before the attempt
+ * counter and the outage clock reset, so a flapping link is never read as "recovered" between
+ * two drops a second apart.
+ */
+export interface ReconnectPolicy {
+    /** First retry delay, in ms. Default 200. */
+    minDelay: number;
+    /** Delay ceiling, in ms — the backoff never grows past this. Default 3000. */
+    maxDelay: number;
+    /** Geometric growth factor applied to the delay after every failed attempt. Default 2. */
+    factor: number;
+    /** Randomization applied to each computed delay, as a fraction of it. Default 0.1 (±10%). */
+    jitter: number;
+    /** Total time, in ms, the carrier keeps retrying before it reports the socket lost. Default
+     *  600000 (10 minutes). */
+    budget: number;
+    /** Retry window, in ms, of an outage restarted on a lost socket by `SocketStatusService.retry()`
+     *  (a "Try again" press, the tab coming back) — short, so a retry that cannot succeed reports
+     *  `'lost'` again while someone is still looking. Default 15000. */
+    reviveBudget: number;
+    /** How long a reopened socket must stay open before the attempt count and the outage clock
+     *  reset, in ms. Default 10000. */
+    stableAfter: number;
+    /** Heartbeat ping interval, in ms. Default 30000. */
+    heartbeat: number;
+    /** How long to wait for ANY inbound frame after a ping before treating the socket as dead and
+     *  forcing it closed, in ms. Default 10000. */
+    pongTimeout: number;
+}
+export interface SocketClientSettings {
+    /** `false` disables reconnection outright — a dropped socket is reported gone and stays gone,
+     *  the pre-reconnect-support behaviour. Anything else merges over the defaults. */
+    reconnect?: false | Partial<ReconnectPolicy>;
+}
+export interface ConnectOptions {
+    reconnect?: false | Partial<ReconnectPolicy>;
+}
+export interface WsOptions extends ConnectOptions {
+    /**
+     * Run before every connection attempt, the first one included, given the request that will be
+     * turned into the socket URL — where a caller refreshes a token or other query/param value
+     * that may have changed since the previous attempt.
+     */
+    beforeConnect?: (request: AbstractRequest<any>) => void | Promise<void>;
+}
+/** The coarse health of a socket connection — the worst of everything a status service tracks. */
+export type SocketConnectionState = 'online' | 'reconnecting' | 'lost';
+export interface SocketStatusService extends InitializedService {
+    /** Record this connection's current state under `id` — call again to update it. `revive` is
+     *  how `retry()` brings it back (`'lost'`) or hurries it (`'reconnecting'`); every report
+     *  replaces the previous one. */
+    report: (id: string, state: SocketConnectionState, revive?: () => void) => void;
+    /** Stop tracking `id` (the connection closed on purpose). */
+    release: (id: string) => void;
+    /** The worst state across every tracked connection; `'online'` when none are tracked. */
+    state: () => SocketConnectionState;
+    subscribe: (listener: (state: SocketConnectionState) => void) => () => void;
+    /** Revive every `'lost'` connection and hurry every `'reconnecting'` one, then tell `onRetry`
+     *  listeners. `false` (and no listener call) when nothing was lost. Also fires by itself when a
+     *  browser tab becomes visible, its window gains focus, or the network comes back online. */
+    retry: () => boolean;
+    onRetry: (listener: () => void) => () => void;
+}
+export interface SocketStatusServiceAppend {
+    socketStatus: () => SocketStatusService;
+}
 //# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAErD,MAAM,WAAW,MAAO,SAAQ,YAAY;CAAI;AAEhD,MAAM,WAAW,OAAO,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC;CAAI"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAA;AACrD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAA;AAE3D,MAAM,WAAW,MAAO,SAAQ,YAAY;IAC1C,MAAM,CAAC,EAAE,oBAAoB,CAAA;CAC9B;AAED,MAAM,WAAW,OAAO,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC;CAAI;AAEhF;;;;;;;;;GASG;AACH,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAA;IAChB,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAA;IAChB,0FAA0F;IAC1F,MAAM,EAAE,MAAM,CAAA;IACd,6FAA6F;IAC7F,MAAM,EAAE,MAAM,CAAA;IACd;+BAC2B;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd;;wEAEoE;IACpE,YAAY,EAAE,MAAM,CAAA;IACpB;uCACmC;IACnC,WAAW,EAAE,MAAM,CAAA;IACnB,qDAAqD;IACrD,SAAS,EAAE,MAAM,CAAA;IACjB;mDAC+C;IAC/C,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,oBAAoB;IACnC;uFACmF;IACnF,SAAS,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;CAC7C;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;CAC7C;AAED,MAAM,WAAW,SAAU,SAAQ,cAAc;IAC/C;;;;OAIG;IACH,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,eAAe,CAAC,GAAG,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACxE;AAED,kGAAkG;AAClG,MAAM,MAAM,qBAAqB,GAAG,QAAQ,GAAG,cAAc,GAAG,MAAM,CAAA;AAEtE,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;IAC7D;;qCAEiC;IACjC,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,qBAAqB,EAAE,MAAM,CAAC,EAAE,MAAM,IAAI,KAAK,IAAI,CAAA;IAC/E,6DAA6D;IAC7D,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,IAAI,CAAA;IAC7B,yFAAyF;IACzF,KAAK,EAAE,MAAM,qBAAqB,CAAA;IAClC,SAAS,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,KAAK,MAAM,IAAI,CAAA;IAC3E;;iGAE6F;IAC7F,KAAK,EAAE,MAAM,OAAO,CAAA;IACpB,OAAO,EAAE,CAAC,QAAQ,EAAE,MAAM,IAAI,KAAK,MAAM,IAAI,CAAA;CAC9C;AAED,MAAM,WAAW,yBAAyB;IACxC,YAAY,EAAE,MAAM,mBAAmB,CAAA;CACxC"}

package/build/utils/connection.d.ts

@@ -1,4 +1,13 @@
-import type { Config, Context } from '../types.js';
-import type { Connection } from '@owlmeans/socket';
-export declare const makeConnection: <C extends Config = Config, T extends Context<C> = Context<C>>(conn: WebSocket, _context: T) => Connection;
+import type { ManagedConnection, ManagedConnectionOptions } from './types.js';
+/**
+ * Build a `Connection` whose transport survives a dropped WebSocket.
+ *
+ * The connection MODEL (`createBasicConnection()`) is created exactly once and never replaced —
+ * every `observe`/`listen` a caller registered keeps firing across a reconnect, because only the
+ * underlying `WebSocket` is swapped underneath it. A server's own subscriptions do NOT survive a
+ * new TCP connection, so a caller whose server sets up state only after an in-band
+ * `authenticated` frame (as this platform's handlers do) must replay that frame itself on
+ * `SocketSystemEvent.Reconnected` — this carrier only re-opens the pipe.
+ */
+export declare const makeConnection: (opts: ManagedConnectionOptions) => ManagedConnection;
 //# sourceMappingURL=connection.d.ts.map

package/build/utils/connection.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/utils/connection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,aAAa,CAAA;AAClD,OAAO,KAAK,EAAE,UAAU,EAA4B,MAAM,kBAAkB,CAAA;AAG5E,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,MAAM,GAAG,MAAM,EAAE,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,QACnF,SAAS,YAAY,CAAC,KAC3B,UAkDF,CAAA"}
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/utils/connection.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAA;AAI7E;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,SAAU,wBAAwB,KAAG,iBAqQ/D,CAAA"}