@bquery/bquery 1.6.0 → 1.8.1

package/dist/reactive/scope.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Reactive effect scopes for grouped disposal.
+ *
+ * An `EffectScope` collects all effects, computed values, and watches created
+ * inside its `run()` callback so they can be disposed together with a single
+ * `stop()` call. Scopes nest — an inner scope is collected by its parent.
+ *
+ * @module bquery/reactive
+ */
+import type { CleanupFn } from './internals';
+/**
+ * A scope that collects reactive resources for grouped disposal.
+ *
+ * @example
+ * ```ts
+ * import { effectScope, signal, effect, computed } from '@bquery/bquery/reactive';
+ *
+ * const scope = effectScope();
+ *
+ * scope.run(() => {
+ *   const count = signal(0);
+ *   effect(() => console.log(count.value));
+ *   const doubled = computed(() => count.value * 2);
+ * });
+ *
+ * scope.stop(); // All effects and computed values disposed
+ * ```
+ */
+export interface EffectScope {
+    /** Whether the scope has not yet been stopped. */
+    readonly active: boolean;
+    /**
+     * Executes `fn` inside this scope, collecting any reactive resources
+     * (effects, computed values, watches, nested scopes) created during the call.
+     *
+     * `run()` is synchronous-only. Do not pass an async function or a function
+     * that returns a Promise — resources created after an `await` cannot be
+     * collected reliably.
+     *
+     * @template T - Return type of the provided function
+     * @param fn - Function to run inside the scope
+     * @returns The return value of `fn`
+     * @throws {Error} If the scope has already been stopped
+     */
+    run<T>(fn: () => T): T;
+    /**
+     * Disposes all collected resources and marks the scope as inactive.
+     * Calling `stop()` on an already-stopped scope is a safe no-op.
+     */
+    stop(): void;
+}
+/** @internal */
+export declare const hasScopeDisposer: (scope: EffectScope | undefined) => scope is EffectScope & {
+    _addDisposer(fn: CleanupFn): void;
+};
+/**
+ * Returns the currently active scope, or `undefined` if none.
+ * @internal
+ */
+export declare const getActiveScope: () => EffectScope | undefined;
+/**
+ * Creates a new effect scope for grouped disposal of reactive resources.
+ *
+ * All `effect()`, `computed()`, `watch()`, and nested `effectScope()` calls
+ * made inside `scope.run(fn)` are automatically collected. Calling
+ * `scope.stop()` disposes them all at once.
+ *
+ * `run()` is synchronous-only. Create the scope outside async flows when
+ * needed, but keep the callback itself synchronous so cleanup registration
+ * stays deterministic.
+ *
+ * @returns A new {@link EffectScope}
+ *
+ * @example
+ * ```ts
+ * import { effectScope, signal, effect, onScopeDispose } from '@bquery/bquery/reactive';
+ *
+ * const scope = effectScope();
+ *
+ * scope.run(() => {
+ *   const count = signal(0);
+ *
+ *   effect(() => console.log(count.value));
+ *
+ *   onScopeDispose(() => {
+ *     console.log('Custom cleanup');
+ *   });
+ * });
+ *
+ * scope.stop(); // logs "Custom cleanup", all effects stopped
+ * ```
+ */
+export declare const effectScope: () => EffectScope;
+/**
+ * Returns the currently active {@link EffectScope}, or `undefined` if
+ * code is not running inside any scope's `run()` callback.
+ *
+ * @returns The active scope, or `undefined`
+ *
+ * @example
+ * ```ts
+ * import { effectScope, getCurrentScope } from '@bquery/bquery/reactive';
+ *
+ * const scope = effectScope();
+ * scope.run(() => {
+ *   console.log(getCurrentScope() !== undefined); // true
+ * });
+ *
+ * console.log(getCurrentScope()); // undefined
+ * ```
+ */
+export declare const getCurrentScope: () => EffectScope | undefined;
+/**
+ * Registers a cleanup callback on the currently active scope.
+ *
+ * The callback runs when the scope is stopped. This is useful for
+ * registering arbitrary cleanup (e.g. event listeners, timers)
+ * alongside effects and computed values.
+ *
+ * @param fn - Cleanup function to run when the scope stops
+ * @throws {Error} If called outside an active scope
+ *
+ * @example
+ * ```ts
+ * import { effectScope, onScopeDispose } from '@bquery/bquery/reactive';
+ *
+ * const scope = effectScope();
+ *
+ * scope.run(() => {
+ *   const controller = new AbortController();
+ *   fetch('/api/data', { signal: controller.signal });
+ *
+ *   onScopeDispose(() => controller.abort());
+ * });
+ *
+ * scope.stop(); // abort() is called
+ * ```
+ */
+export declare const onScopeDispose: (fn: CleanupFn) => void;
+//# sourceMappingURL=scope.d.ts.map

package/dist/reactive/scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope.d.ts","sourceRoot":"","sources":["../../src/reactive/scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAM7C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAEzB;;;;;;;;;;;;OAYG;IACH,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAEvB;;;OAGG;IACH,IAAI,IAAI,IAAI,CAAC;CACd;AAcD,gBAAgB;AAChB,eAAO,MAAM,gBAAgB,GAC3B,OAAO,WAAW,GAAG,SAAS,KAC7B,KAAK,IAAI,WAAW,GAAG;IAAE,YAAY,CAAC,EAAE,EAAE,SAAS,GAAG,IAAI,CAAA;CACW,CAAC;AA2BzE;;;GAGG;AACH,eAAO,MAAM,cAAc,QAAO,WAAW,GAAG,SAQ/C,CAAC;AA8DF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,WAAW,QAAO,WAU9B,CAAC;AAEF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,eAAe,QAAO,WAAW,GAAG,SAA6B,CAAC;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,cAAc,GAAI,IAAI,SAAS,KAAG,IAQ9C,CAAC"}

package/dist/reactive/signal.d.ts

@@ -8,14 +8,28 @@ export { createUseFetch, useAsyncData, useFetch } from './async-data';
 export { Computed, computed } from './computed';
 export { Signal, signal } from './core';
 export { effect } from './effect';
+export { createHttp, createRequestQueue, http, HttpError } from './http';
 export { linkedSignal } from './linked';
+export { useInfiniteFetch, usePaginatedFetch } from './pagination';
 export { persistedSignal } from './persisted';
+export { usePolling } from './polling';
 export { readonly } from './readonly';
+export { createRestClient, deduplicateRequest, useResource, useResourceList, useSubmit, } from './rest';
+export { effectScope, getCurrentScope, onScopeDispose } from './scope';
 export { isComputed, isSignal } from './type-guards';
+export { toValue } from './to-value';
 export { untrack } from './untrack';
 export { watch } from './watch';
+export { useEventSource, useWebSocket, useWebSocketChannel } from './websocket';
 export type { CleanupFn, Observer } from './internals';
-export type { AsyncDataState, AsyncDataStatus, AsyncWatchSource, FetchInput, UseAsyncDataOptions, UseFetchOptions, } from './async-data';
+export type { AsyncDataState, AsyncDataStatus, AsyncWatchSource, FetchInput, UseAsyncDataOptions, UseFetchOptions, UseFetchRetryConfig, } from './async-data';
+export type { HttpClient, HttpProgressEvent, HttpRequestConfig, HttpResponse, Interceptor, InterceptorManager, RequestQueue, RequestQueueOptions, RetryConfig, } from './http';
+export type { InfiniteState, PaginatedState, UseInfiniteFetchOptions, UsePaginatedFetchOptions, } from './pagination';
+export type { PollingState, UsePollingOptions } from './polling';
+export type { IdExtractor, ResourceListActions, RestClient, UseResourceListOptions, UseResourceListReturn, UseResourceOptions, UseResourceReturn, UseSubmitOptions, UseSubmitReturn, } from './rest';
+export type { EffectScope } from './scope';
 export type { LinkedSignal } from './linked';
-export type { ReadonlySignal } from './readonly';
+export type { MaybeSignal } from './to-value';
+export type { ReadonlySignal, ReadonlySignalHandle } from './readonly';
+export type { ChannelMessage, ChannelSubscription, EventSourceStatus, UseEventSourceOptions, UseEventSourceReturn, UseWebSocketChannelOptions, UseWebSocketChannelReturn, UseWebSocketOptions, UseWebSocketReturn, WebSocketHeartbeatConfig, WebSocketReconnectConfig, WebSocketSerializer, WebSocketStatus, } from './websocket';
 //# sourceMappingURL=signal.d.ts.map

package/dist/reactive/signal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"signal.d.ts","sourceRoot":"","sources":["../../src/reactive/signal.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAEhC,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvD,YAAY,EACV,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,mBAAmB,EACnB,eAAe,GAChB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"signal.d.ts","sourceRoot":"","sources":["../../src/reactive/signal.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AACtE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AACxC,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,SAAS,GACV,MAAM,QAAQ,CAAC;AAChB,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAEhF,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvD,YAAY,EACV,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,UAAU,EACV,mBAAmB,EACnB,eAAe,EACf,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,YAAY,EACZ,mBAAmB,EACnB,WAAW,GACZ,MAAM,QAAQ,CAAC;AAChB,YAAY,EACV,aAAa,EACb,cAAc,EACd,uBAAuB,EACvB,wBAAwB,GACzB,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AACjE,YAAY,EACV,WAAW,EACX,mBAAmB,EACnB,UAAU,EACV,sBAAsB,EACtB,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,GAChB,MAAM,QAAQ,CAAC;AAChB,YAAY,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AACvE,YAAY,EACV,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,EACrB,oBAAoB,EACpB,0BAA0B,EAC1B,yBAAyB,EACzB,mBAAmB,EACnB,kBAAkB,EAClB,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACnB,eAAe,GAChB,MAAM,aAAa,CAAC"}

package/dist/reactive/to-value.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Utility to unwrap reactive or plain values.
+ */
+import { Computed } from './computed';
+import { Signal } from './core';
+import { readonly } from './readonly';
+/**
+ * A value that may be a raw value, a Signal, a `readonly()` wrapper, or a Computed.
+ *
+ * Useful for APIs that accept both reactive and plain inputs.
+ *
+ * Readonly wrappers are limited to the values returned by {@link readonly}. This keeps
+ * the type aligned with runtime behavior, where arbitrary structural `{ value, peek }`
+ * objects are intentionally returned unchanged.
+ *
+ * @template T - The underlying value type
+ *
+ * @example
+ * ```ts
+ * function useTitle(title: MaybeSignal<string>) {
+ *   document.title = toValue(title);
+ * }
+ *
+ * useTitle('Hello');               // plain string
+ * useTitle(signal('Hello'));       // reactive signal
+ * useTitle(computed(() => 'Hi')); // computed value
+ * ```
+ */
+export type MaybeSignal<T> = T | Signal<T> | ReturnType<typeof readonly<T>> | Computed<T>;
+/**
+ * Extracts the current value from a Signal, a bQuery `readonly()` wrapper, a
+ * Computed, or returns the raw value as-is. This eliminates repetitive
+ * `isSignal(x) ? x.value : x` patterns throughout user code.
+ *
+ * Reading a Signal or Computed via `toValue()` uses `.value`, so the
+ * read **does** participate in reactive tracking when called inside
+ * an effect or computed.
+ *
+ * @template T - The underlying value type
+ * @param source - A plain value, Signal, bQuery readonly wrapper, or Computed
+ * @returns The unwrapped value
+ *
+ * @example
+ * ```ts
+ * import { signal, computed, toValue } from '@bquery/bquery/reactive';
+ *
+ * const count = signal(5);
+ * const doubled = computed(() => count.value * 2);
+ *
+ * toValue(42);      // 42
+ * toValue(count);   // 5
+ * toValue(doubled); // 10
+ * toValue(null);    // null
+ * ```
+ */
+export declare const toValue: <T>(source: MaybeSignal<T>) => T;
+//# sourceMappingURL=to-value.d.ts.map

package/dist/reactive/to-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"to-value.d.ts","sourceRoot":"","sources":["../../src/reactive/to-value.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,EAAE,QAAQ,EAAoB,MAAM,YAAY,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;AAE1F;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,EAAE,QAAQ,WAAW,CAAC,CAAC,CAAC,KAAG,CAYnD,CAAC"}

package/dist/reactive/websocket.d.ts

@@ -0,0 +1,285 @@
+/**
+ * Reactive WebSocket composable with auto-reconnect, heartbeat,
+ * message history, and signal-based connection state.
+ *
+ * @module bquery/reactive
+ */
+import { Signal } from './core';
+/** Connection status for a WebSocket. */
+export type WebSocketStatus = 'CONNECTING' | 'OPEN' | 'CLOSING' | 'CLOSED';
+/** Connection status for an EventSource. */
+export type EventSourceStatus = 'CONNECTING' | 'OPEN' | 'CLOSED';
+/** Configuration for automatic reconnection. */
+export interface WebSocketReconnectConfig {
+    /** Maximum number of reconnection attempts. Use `0` to disable reconnection (default: Infinity / unlimited). */
+    maxAttempts?: number;
+    /** Base delay in ms between reconnects (default: 1000). */
+    delay?: number;
+    /** Maximum delay in ms between reconnects (default: 30000). */
+    maxDelay?: number;
+    /** Multiply factor for exponential backoff (default: 2). */
+    factor?: number;
+    /** Custom predicate — return `false` to prevent a reconnect attempt. */
+    shouldReconnect?: (event: CloseEvent, attempts: number) => boolean;
+}
+/** Reconnect configuration supported by `useEventSource()`. */
+export type EventSourceReconnectConfig = Pick<WebSocketReconnectConfig, 'maxAttempts' | 'delay' | 'maxDelay' | 'factor'>;
+/** Configuration for keep-alive heartbeats. */
+export interface WebSocketHeartbeatConfig {
+    /** Outgoing ping message (default: `'ping'`). */
+    message?: string | ArrayBufferLike | Blob | ArrayBufferView;
+    /** Interval in ms between heartbeat pings (default: 30 000). */
+    interval?: number;
+    /** Time in ms to wait for a pong before assuming the connection is dead (default: 10 000). */
+    pongTimeout?: number;
+    /** Expected response message. If set, only messages matching this value reset the pong timer. */
+    responseMessage?: string;
+}
+/** Serializer/deserializer for typed messaging. */
+export interface WebSocketSerializer<TSend = unknown, TReceive = unknown> {
+    /** Serialize a value before sending over the wire. Default: `JSON.stringify`. */
+    serialize?: (data: TSend) => string | ArrayBufferLike | Blob | ArrayBufferView;
+    /** Deserialize an incoming message. Default: `JSON.parse`. */
+    deserialize?: (event: MessageEvent) => TReceive;
+}
+/** Full configuration accepted by `useWebSocket()`. */
+export interface UseWebSocketOptions<TSend = unknown, TReceive = unknown> extends WebSocketSerializer<TSend, TReceive> {
+    /** Sub-protocols to request during the WebSocket handshake. */
+    protocols?: string | string[];
+    /** Open the connection immediately (default: true). */
+    immediate?: boolean;
+    /** Automatically reconnect on unexpected close (default: true). Pass `false` or config. */
+    autoReconnect?: boolean | WebSocketReconnectConfig;
+    /** Keep-alive heartbeat configuration. Pass `true` for defaults or a config object. */
+    heartbeat?: boolean | WebSocketHeartbeatConfig;
+    /** Maximum number of messages to keep in `history` (default: 0 = disabled). */
+    historySize?: number;
+    /** Called when the connection opens. */
+    onOpen?: (event: Event) => void;
+    /** Called when a message is received (after deserialization). */
+    onMessage?: (data: TReceive, event: MessageEvent) => void;
+    /** Called when the connection closes. */
+    onClose?: (event: CloseEvent) => void;
+    /** Called when a connection error occurs. */
+    onError?: (event: Event) => void;
+    /** Called after a successful reconnection. Receives the reconnection attempt count. */
+    onReconnect?: (attempts: number) => void;
+}
+/** Return value of `useWebSocket()`. */
+export interface UseWebSocketReturn<TSend = unknown, TReceive = unknown> {
+    /** Reactive connection status. */
+    status: {
+        readonly value: WebSocketStatus;
+        peek(): WebSocketStatus;
+    };
+    /** Reactive last received message (deserialized). */
+    data: Signal<TReceive | undefined>;
+    /** Last error event. */
+    error: Signal<Event | null>;
+    /** Rolling message history (newest last). */
+    history: Signal<TReceive[]>;
+    /** Computed boolean — `true` when the socket is `OPEN`. */
+    isConnected: {
+        readonly value: boolean;
+        peek(): boolean;
+    };
+    /** Number of reconnection attempts since last successful open. */
+    reconnectAttempts: Signal<number>;
+    /** Round-trip latency in ms measured via heartbeat pings (requires `heartbeat` option). */
+    latency: Signal<number>;
+    /** Timestamp of the last unexpected disconnection, or 0 if never disconnected. */
+    lastDisconnectedAt: Signal<number>;
+    /**
+     * Send a message.
+     *
+     * If the socket is not `OPEN`, the message is queued and sent once a
+     * connection is (re)established, subject to the configured options.
+     */
+    send: (data: TSend) => void;
+    /**
+     * Send raw data without serialization.
+     *
+     * Uses the same queuing behavior as {@link send}: data is queued when the
+     * socket is not `OPEN` and flushed once a connection is (re)established.
+     */
+    sendRaw: (data: string | ArrayBufferLike | Blob | ArrayBufferView) => void;
+    /** Manually open / reconnect the WebSocket. */
+    open: () => void;
+    /** Gracefully close the connection. */
+    close: (code?: number, reason?: string) => void;
+    /** Tear down all resources (close + remove listeners + stop reconnect/heartbeat). */
+    dispose: () => void;
+}
+/**
+ * Reactive WebSocket composable with auto-reconnect, heartbeat,
+ * typed messaging, and signal-based connection state.
+ *
+ * @template TSend - Type of outgoing messages (serialized via `serialize`)
+ * @template TReceive - Type of incoming messages (deserialized via `deserialize`)
+ * @param url - WebSocket URL (`ws://` or `wss://`) or a getter returning one
+ * @param options - Connection, reconnect, heartbeat, and serialization options
+ * @returns Reactive WebSocket state with `send()`, `open()`, `close()`, and `dispose()`
+ *
+ * @example
+ * ```ts
+ * import { useWebSocket } from '@bquery/bquery/reactive';
+ *
+ * const ws = useWebSocket<{ type: string; payload: unknown }>('wss://api.example.com/ws', {
+ *   autoReconnect: { maxAttempts: 5, delay: 2000 },
+ *   heartbeat: true,
+ *   historySize: 50,
+ *   onMessage: (data) => console.log('Received:', data),
+ * });
+ *
+ * ws.send({ type: 'subscribe', payload: { channel: 'updates' } });
+ *
+ * // Reactive state
+ * effect(() => {
+ *   console.log('Connected:', ws.isConnected.value);
+ *   console.log('Last message:', ws.data.value);
+ * });
+ *
+ * // Cleanup
+ * ws.dispose();
+ * ```
+ */
+export declare const useWebSocket: <TSend = string, TReceive = string>(url: string | URL | (() => string | URL), options?: UseWebSocketOptions<TSend, TReceive>) => UseWebSocketReturn<TSend, TReceive>;
+/** Default channel message format used by `useWebSocketChannel()`. */
+export interface ChannelMessage<T = unknown> {
+    /** Channel / topic name. */
+    channel: string;
+    /** Message payload. */
+    data: T;
+}
+/** Configuration for `useWebSocketChannel()`. */
+export interface UseWebSocketChannelOptions<TSend = unknown, TReceive = unknown> {
+    /**
+     * Extract the channel name from an incoming deserialized message.
+     * Default: reads `(msg as ChannelMessage).channel`.
+     */
+    getChannel?: (msg: TReceive) => string | undefined;
+    /**
+     * Wrap a payload + channel into the wire format before sending.
+     * Default: `{ channel, data }`.
+     */
+    wrap?: (channel: string, data: TSend) => TReceive;
+}
+/** A single channel subscription returned by `subscribe()`. */
+export interface ChannelSubscription<TReceive = unknown> {
+    /** Reactive last message received on this channel. */
+    data: Signal<TReceive | undefined>;
+    /** Unsubscribe from this channel. */
+    unsubscribe: () => void;
+}
+/** Return value of `useWebSocketChannel()`. */
+export interface UseWebSocketChannelReturn<TSend = unknown, TReceive = unknown> {
+    /** Subscribe to a topic. Multiple subscriptions to the same channel share a signal. */
+    subscribe: (channel: string) => ChannelSubscription<TReceive>;
+    /** Publish a message to a channel. */
+    publish: (channel: string, data: TSend) => void;
+    /** The underlying `useWebSocket` return for direct access. */
+    ws: UseWebSocketReturn<TReceive, TReceive>;
+}
+/**
+ * Topic-based channel multiplexer over a single WebSocket connection.
+ *
+ * Builds on `useWebSocket()` and routes incoming messages to per-channel
+ * reactive signals based on a configurable channel extractor.
+ *
+ * @template TSend - Type of outgoing message payloads
+ * @template TReceive - Type of incoming deserialized messages
+ * @param url - WebSocket URL
+ * @param wsOptions - All `useWebSocket` options
+ * @param channelOptions - Channel routing configuration
+ * @returns Channel multiplexer with `subscribe()`, `publish()`, and the underlying `ws`
+ *
+ * @example
+ * ```ts
+ * import { useWebSocketChannel } from '@bquery/bquery/reactive';
+ *
+ * const chat = useWebSocketChannel('wss://chat.example.com/ws');
+ *
+ * const general = chat.subscribe('general');
+ * const updates = chat.subscribe('updates');
+ *
+ * effect(() => console.log('General:', general.data.value));
+ *
+ * chat.publish('general', { text: 'Hello!' });
+ * ```
+ */
+export declare const useWebSocketChannel: <TSend = unknown, TReceive = unknown>(url: string | URL | (() => string | URL), wsOptions?: UseWebSocketOptions<TReceive, TReceive>, channelOptions?: UseWebSocketChannelOptions<TSend, TReceive>) => UseWebSocketChannelReturn<TSend, TReceive>;
+/** Configuration for `useEventSource()`. */
+export interface UseEventSourceOptions<TData = unknown> {
+    /** Whether to open the connection immediately (default: true). */
+    immediate?: boolean;
+    /** Automatically reconnect on error (default: true). Pass a reconnect config to customize delay and attempt limits. */
+    autoReconnect?: boolean | EventSourceReconnectConfig;
+    /** Event names to listen for besides the default `message` event. */
+    events?: string[];
+    /** Deserializer for incoming event data. Default: `JSON.parse` with string fallback. */
+    deserialize?: (data: string) => TData;
+    /** EventSource init options (e.g. `withCredentials`). */
+    eventSourceInit?: EventSourceInit;
+    /** Called when the connection opens. */
+    onOpen?: (event: Event) => void;
+    /** Called when a message is received. */
+    onMessage?: (data: TData, event: MessageEvent) => void;
+    /** Called when an error occurs. */
+    onError?: (event: Event) => void;
+}
+/** Return value of `useEventSource()`. */
+export interface UseEventSourceReturn<TData = unknown> {
+    /** Current connection status (`CONNECTING`, `OPEN`, `CLOSED`). */
+    status: {
+        readonly value: EventSourceStatus;
+        peek(): EventSourceStatus;
+    };
+    /** Last received data (deserialized). */
+    data: Signal<TData | undefined>;
+    /** Last event name that delivered data. */
+    eventName: Signal<string | undefined>;
+    /** Last error event. */
+    error: Signal<Event | null>;
+    /** Computed boolean — `true` when the EventSource is open. */
+    isConnected: {
+        readonly value: boolean;
+        peek(): boolean;
+    };
+    /** Manually open / reconnect the EventSource. */
+    open: () => void;
+    /** Close the connection. */
+    close: () => void;
+    /** Tear down all resources. */
+    dispose: () => void;
+}
+/**
+ * Reactive Server-Sent Events (SSE) composable.
+ *
+ * Wraps the native `EventSource` API with reactive signals, auto-reconnect,
+ * and typed deserialization.
+ *
+ * @template TData - Type of deserialized event data
+ * @param url - SSE endpoint URL or a getter returning one
+ * @param options - EventSource options
+ * @returns Reactive EventSource state with `open()`, `close()`, and `dispose()`
+ *
+ * @example
+ * ```ts
+ * import { useEventSource } from '@bquery/bquery/reactive';
+ *
+ * const sse = useEventSource<{ type: string; message: string }>('/api/events', {
+ *   events: ['notification', 'update'],
+ *   onMessage: (data) => console.log('Event:', data),
+ * });
+ *
+ * effect(() => {
+ *   if (sse.data.value) {
+ *     console.log(`[${sse.eventName.value}]`, sse.data.value);
+ *   }
+ * });
+ *
+ * sse.dispose();
+ * ```
+ */
+export declare const useEventSource: <TData = unknown>(url: string | URL | (() => string | URL), options?: UseEventSourceOptions<TData>) => UseEventSourceReturn<TData>;
+//# sourceMappingURL=websocket.d.ts.map

package/dist/reactive/websocket.d.ts.map

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