import { atom } from "../Mutables/atom/atom";
export type WsStatus = "connecting" | "connected" | "disconnected" | "error";
export type WsConfig = {
    /** Auto-reconnect on close/error. Default: true */
    reconnect?: boolean;
    /** Base delay in ms before first reconnect attempt. Default: 1000 */
    reconnectDelay?: number;
    /** Maximum delay cap in ms for exponential backoff. Default: 30_000 */
    reconnectMaxDelay?: number;
    /** Maximum number of reconnect attempts. Default: Infinity */
    reconnectMaxAttempts?: number;
    /** WebSocket sub-protocols */
    protocols?: string | string[];
    /**
     * Called lazily on each (re)connect to produce extra query-string params.
     * e.g. () => ({ token: authToken() })
     */
    auth?: () => Record<string, string>;
    /**
     * If false the socket will not connect automatically on creation.
     * Call `connection.connect()` manually when you are ready.
     * Default: true
     */
    autoConnect?: boolean;
};
type MessageHandler<T> = (data: T) => void;
export type WsConnection<T = unknown> = {
    /** Send a value to the server. Objects are JSON-serialised automatically. */
    send: (data: T | string) => void;
    /**
     * Subscribe to incoming messages.
     * Returns an unsubscribe function.
     * Prefer `onSocket()` inside components — it auto-cleans up on unmount.
     */
    __subscribe: (fn: MessageHandler<T>) => () => void;
    /** Reactive connection status atom. */
    status: ReturnType<typeof atom<WsStatus>>;
    /**
     * Open (or re-open) the connection.
     * Called automatically on creation unless `autoConnect: false` is set.
     * Safe to call after `disconnect()` — it resets the socket so it can
     * connect again.
     */
    connect: () => void;
    /** Close the connection and stop all reconnect attempts. */
    disconnect: () => void;
    /** Internal marker — mirrors __isAtom___, __isEvent___, etc. */
    readonly __isWs___: true;
};
/**
 * Create a WebSocket connection.
 *
 * **Must be called from a component's outer function.**  `ws()` registers a
 * cleanup handler so the reconnect timer, socket, and all message handlers are
 * automatically torn down when the component unmounts.  Calling it at module
 * level or inside an inner function (event handler, timer callback, etc.) is
 * forbidden because there is no active component host to attach the cleanup to.
 *
 * ```ts
 * // ✅ correct — inside a component's outer function
 * const MyComponent = () => {
 *   const sock = ws<ChatMessage>("wss://<your-server>/chat", {
 *     reconnect: true,
 *   });
 *   onSocket((msg) => { messages.update(d => { d.push(msg); }); }, [sock]);
 *   return () => html`...`;
 * };
 *
 * // ❌ wrong — module level, no host, cleanup is never registered
 * const chatSocket = ws<ChatMessage>("wss://<your-server>/chat");
 *
 * // ❌ wrong — inner function, outer function has already returned
 * const MyComponent = () => {
 *   function handleClick() {
 *     const sock = ws("wss://..."); // throws
 *   }
 *   return () => html`<button @click=${handleClick}>…</button>`;
 * };
 * ```
 */
export declare function ws<T = unknown>(url: string, config?: WsConfig): WsConnection<T>;
export {};
//# sourceMappingURL=ws.d.ts.map