@bquery/bquery 1.7.0 → 1.8.2

package/dist/reactive/http.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Imperative HTTP client with Axios-like API, interceptors, retry, timeout,
+ * cancellation, and progress tracking — built on the native Fetch API.
+ *
+ * @module bquery/reactive
+ */
+import { type BqueryFetchParseAs } from '../platform/config';
+/** Configuration for automatic request retries. */
+export interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3). */
+    count: number;
+    /** Delay in ms between retries, or a function receiving the attempt index. */
+    delay?: number | ((attempt: number) => number);
+    /** Predicate deciding whether to retry a given error. Defaults to network / 5xx errors. */
+    retryOn?: (error: HttpError, attempt: number) => boolean;
+    /** Called before each retry attempt with the error and 1-indexed attempt number. */
+    onRetry?: (error: HttpError, attempt: number) => void;
+}
+/** Progress information emitted during upload or download. */
+export interface HttpProgressEvent {
+    /** Bytes transferred so far. */
+    loaded: number;
+    /** Total bytes if known, otherwise 0. */
+    total: number;
+    /** Percentage between 0 and 100, or `undefined` when total is unknown. */
+    percent: number | undefined;
+}
+/** Full request configuration accepted by the HTTP client. */
+export interface HttpRequestConfig extends Omit<RequestInit, 'body' | 'headers' | 'signal'> {
+    /** Request URL (resolved against `baseUrl`). */
+    url?: string;
+    /** Base URL prepended to relative request URLs. */
+    baseUrl?: string;
+    /** Request headers. */
+    headers?: HeadersInit;
+    /** Query parameters appended to the URL. */
+    query?: Record<string, unknown>;
+    /** Request body — plain objects/arrays are JSON-serialised automatically. */
+    body?: BodyInit | Record<string, unknown> | unknown[] | null;
+    /** Request timeout in milliseconds. 0 means no timeout (default). */
+    timeout?: number;
+    /** Response parsing strategy. */
+    parseAs?: BqueryFetchParseAs;
+    /** Custom status validation. Returns `true` for acceptable statuses. Default: `status >= 200 && status < 300`. */
+    validateStatus?: (status: number) => boolean;
+    /** Custom fetch implementation for testing or adapters. */
+    fetcher?: typeof fetch;
+    /** External `AbortSignal` for request cancellation. */
+    signal?: AbortSignal;
+    /** Retry configuration. Pass a number for simple retry count, or a `RetryConfig` object. */
+    retry?: number | RetryConfig;
+    /** Called repeatedly as response body chunks arrive. */
+    onDownloadProgress?: (event: HttpProgressEvent) => void;
+}
+/** Structured HTTP response returned by every client method. */
+export interface HttpResponse<T = unknown> {
+    /** Parsed response data. */
+    data: T;
+    /** HTTP status code. */
+    status: number;
+    /** HTTP status text. */
+    statusText: string;
+    /** Response headers. */
+    headers: Headers;
+    /** Resolved request configuration used for this call. */
+    config: HttpRequestConfig;
+}
+/** Error subclass thrown on failed HTTP requests with rich metadata. */
+export declare class HttpError extends Error {
+    /** HTTP response (available when the server replied). */
+    response?: HttpResponse;
+    /** Resolved request configuration. */
+    config: HttpRequestConfig;
+    /** Original error code string (e.g. `'TIMEOUT'`, `'ABORT'`, `'NETWORK'`). */
+    code: string;
+    constructor(message: string, config: HttpRequestConfig, code: string, response?: HttpResponse);
+}
+/** Single interceptor handler pair. */
+export interface Interceptor<T> {
+    fulfilled?: (value: T) => T | Promise<T>;
+    rejected?: (error: unknown) => unknown;
+}
+/** Manager for adding and removing interceptors. */
+export interface InterceptorManager<T> {
+    /** Register an interceptor. Returns a numeric id for later removal via `eject()`. */
+    use(fulfilled?: (value: T) => T | Promise<T>, rejected?: (error: unknown) => unknown): number;
+    /** Remove a previously registered interceptor by id. */
+    eject(id: number): void;
+    /** Remove all interceptors. */
+    clear(): void;
+}
+/** Imperative HTTP client with interceptors and convenience method shortcuts. */
+export interface HttpClient {
+    /** Send a request using the provided configuration. */
+    request<T = unknown>(config: HttpRequestConfig): Promise<HttpResponse<T>>;
+    /** Send a GET request. */
+    get<T = unknown>(url: string, config?: HttpRequestConfig): Promise<HttpResponse<T>>;
+    /** Send a POST request. */
+    post<T = unknown>(url: string, body?: HttpRequestConfig['body'], config?: HttpRequestConfig): Promise<HttpResponse<T>>;
+    /** Send a PUT request. */
+    put<T = unknown>(url: string, body?: HttpRequestConfig['body'], config?: HttpRequestConfig): Promise<HttpResponse<T>>;
+    /** Send a PATCH request. */
+    patch<T = unknown>(url: string, body?: HttpRequestConfig['body'], config?: HttpRequestConfig): Promise<HttpResponse<T>>;
+    /** Send a DELETE request. */
+    delete<T = unknown>(url: string, config?: HttpRequestConfig): Promise<HttpResponse<T>>;
+    /** Send a HEAD request. */
+    head<T = unknown>(url: string, config?: HttpRequestConfig): Promise<HttpResponse<T>>;
+    /** Send an OPTIONS request. */
+    options<T = unknown>(url: string, config?: HttpRequestConfig): Promise<HttpResponse<T>>;
+    /** Request and response interceptors. */
+    interceptors: {
+        request: InterceptorManager<HttpRequestConfig>;
+        response: InterceptorManager<HttpResponse>;
+    };
+    /** The merged default configuration used by this client. */
+    defaults: HttpRequestConfig;
+}
+/**
+ * Create a preconfigured HTTP client instance with interceptors.
+ *
+ * @param defaults - Default request configuration merged into every request
+ * @returns An `HttpClient` with `.get()`, `.post()`, `.put()`, `.patch()`, `.delete()`, `.head()`, `.options()`
+ *
+ * @example
+ * ```ts
+ * import { createHttp } from '@bquery/bquery/reactive';
+ *
+ * const api = createHttp({
+ *   baseUrl: 'https://api.example.com',
+ *   headers: { authorization: 'Bearer token' },
+ *   timeout: 10_000,
+ * });
+ *
+ * api.interceptors.request.use((config) => {
+ *   config.headers = { ...Object.fromEntries(new Headers(config.headers)), 'x-req-id': crypto.randomUUID() };
+ *   return config;
+ * });
+ *
+ * const { data } = await api.get<User[]>('/users');
+ * ```
+ */
+export declare function createHttp(defaults?: HttpRequestConfig): HttpClient;
+/**
+ * Default HTTP client instance using global bQuery fetch config.
+ *
+ * @example
+ * ```ts
+ * import { http } from '@bquery/bquery/reactive';
+ *
+ * const { data } = await http.get<User[]>('/api/users');
+ * const { data: created } = await http.post('/api/users', { name: 'Ada' });
+ * ```
+ */
+export declare const http: HttpClient;
+/** Options for `createRequestQueue()`. */
+export interface RequestQueueOptions {
+    /** Maximum number of concurrent in-flight requests (default: 6). */
+    concurrency?: number;
+}
+/** Return value of `createRequestQueue()`. */
+export interface RequestQueue {
+    /** Enqueue a request. Returns a promise that resolves when the request completes. */
+    add: <T = unknown>(execute: () => Promise<HttpResponse<T>>) => Promise<HttpResponse<T>>;
+    /** Number of requests currently being processed. */
+    readonly pending: number;
+    /** Number of requests waiting in the queue. */
+    readonly size: number;
+    /** Remove all pending (not yet started) requests from the queue. Their promises will reject. */
+    clear: () => void;
+}
+/**
+ * Create a request queue with a concurrency limit.
+ *
+ * Useful for rate-limiting parallel HTTP requests (e.g. browser connection limits,
+ * API throttling) while maintaining a simple promise-based interface.
+ *
+ * @param options - Queue configuration
+ * @returns A `RequestQueue` with `.add()`, `.clear()`, `.pending`, and `.size`
+ *
+ * @example
+ * ```ts
+ * import { createRequestQueue, createHttp } from '@bquery/bquery/reactive';
+ *
+ * const api = createHttp({ baseUrl: 'https://api.example.com' });
+ * const queue = createRequestQueue({ concurrency: 3 });
+ *
+ * // These will run at most 3 at a time
+ * const results = await Promise.all(
+ *   ids.map(id => queue.add(() => api.get(`/items/${id}`)))
+ * );
+ * ```
+ */
+export declare function createRequestQueue(options?: RequestQueueOptions): RequestQueue;
+//# sourceMappingURL=http.d.ts.map

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

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

package/dist/reactive/index.d.ts

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

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/reactive/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,QAAQ,EACR,MAAM,EACN,KAAK,EACL,QAAQ,EACR,cAAc,EACd,MAAM,EACN,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,MAAM,EACN,YAAY,EACZ,QAAQ,EACR,OAAO,EACP,KAAK,GACN,MAAM,UAAU,CAAC;AAElB,YAAY,EACV,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,SAAS,EACT,UAAU,EACV,YAAY,EACZ,QAAQ,EACR,cAAc,EACd,mBAAmB,EACnB,eAAe,GAChB,MAAM,UAAU,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/reactive/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,QAAQ,EACR,MAAM,EACN,KAAK,EACL,QAAQ,EACR,UAAU,EACV,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,MAAM,EACN,WAAW,EACX,eAAe,EACf,IAAI,EACJ,SAAS,EACT,UAAU,EACV,QAAQ,EACR,YAAY,EACZ,cAAc,EACd,eAAe,EACf,QAAQ,EACR,MAAM,EACN,OAAO,EACP,YAAY,EACZ,cAAc,EACd,QAAQ,EACR,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,EACV,WAAW,EACX,eAAe,EACf,SAAS,EACT,YAAY,EACZ,mBAAmB,EACnB,OAAO,EACP,KAAK,GACN,MAAM,UAAU,CAAC;AAElB,YAAY,EACV,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,SAAS,EACT,WAAW,EACX,UAAU,EACV,UAAU,EACV,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACX,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,QAAQ,EACR,iBAAiB,EACjB,cAAc,EACd,YAAY,EACZ,cAAc,EACd,oBAAoB,EACpB,YAAY,EACZ,mBAAmB,EACnB,mBAAmB,EACnB,UAAU,EACV,WAAW,EACX,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,EACpB,eAAe,EACf,mBAAmB,EACnB,uBAAuB,EACvB,wBAAwB,EACxB,iBAAiB,EACjB,sBAAsB,EACtB,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,eAAe,EACf,0BAA0B,EAC1B,yBAAyB,EACzB,mBAAmB,EACnB,kBAAkB,EAClB,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,EACnB,eAAe,GAChB,MAAM,UAAU,CAAC"}

package/dist/reactive/pagination.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Pagination and infinite-scroll composables for reactive data fetching.
+ *
+ * @module bquery/reactive
+ */
+import { Signal } from './core';
+import { type AsyncDataState, type AsyncDataStatus, type UseFetchOptions } from './async-data';
+/** Options for usePaginatedFetch(). */
+export interface UsePaginatedFetchOptions<TResponse = unknown, TData = TResponse> extends UseFetchOptions<TResponse, TData> {
+    /** Initial page number (default: 1). */
+    initialPage?: number;
+}
+/** Return value of usePaginatedFetch(). */
+export interface PaginatedState<TData> extends AsyncDataState<TData> {
+    /** Current page number signal (writable). */
+    page: Signal<number>;
+    /** Go to the next page. */
+    next: () => Promise<TData | undefined>;
+    /** Go to the previous page (minimum 1). */
+    prev: () => Promise<TData | undefined>;
+    /** Jump to a specific page. */
+    goTo: (page: number) => Promise<TData | undefined>;
+}
+/**
+ * Reactive paginated fetch composable.
+ *
+ * Takes a URL factory receiving the current page number, and exposes
+ * `page`, `next()`, `prev()`, and `goTo()` helpers alongside the
+ * standard `AsyncDataState`.
+ *
+ * @template TResponse - Raw parsed response type
+ * @template TData - Stored response type after optional transformation
+ * @param inputFactory - Function that receives the page number and returns a URL string, URL, or Request
+ * @param options - Fetch and pagination options
+ * @returns Paginated data state
+ *
+ * @example
+ * ```ts
+ * import { usePaginatedFetch } from '@bquery/bquery/reactive';
+ *
+ * const users = usePaginatedFetch<User[]>(
+ *   (page) => `/api/users?page=${page}`,
+ *   { baseUrl: 'https://api.example.com' }
+ * );
+ *
+ * // Navigate pages
+ * await users.next();
+ * await users.prev();
+ * await users.goTo(5);
+ * console.log(users.page.value); // 5
+ * ```
+ */
+export declare const usePaginatedFetch: <TResponse = unknown, TData = TResponse>(inputFactory: (page: number) => string | URL | Request, options?: UsePaginatedFetchOptions<TResponse, TData>) => PaginatedState<TData>;
+/** Options for useInfiniteFetch(). */
+export interface UseInfiniteFetchOptions<TResponse = unknown, TData = TResponse, TCursor = number> extends Omit<UseFetchOptions<TResponse, TData>, 'transform'> {
+    /** Extract the cursor for the next page from a response. */
+    getNextCursor: (lastResponse: TResponse, allPages: TResponse[]) => TCursor | undefined;
+    /** Transform all accumulated pages into the final data shape. */
+    transform?: (pages: TResponse[]) => TData;
+    /** Initial cursor value (default: undefined, meaning first page). */
+    initialCursor?: TCursor;
+}
+/** Return value of useInfiniteFetch(). */
+export interface InfiniteState<TData, TResponse = unknown> {
+    /** All accumulated page data, transformed. */
+    data: Signal<TData | undefined>;
+    /** Raw accumulated pages. */
+    pages: Signal<TResponse[]>;
+    /** Last error encountered. */
+    error: Signal<Error | null>;
+    /** Current lifecycle status. */
+    status: Signal<AsyncDataStatus>;
+    /** Computed boolean that mirrors `status === 'pending'`. */
+    pending: {
+        readonly value: boolean;
+        peek(): boolean;
+    };
+    /** Whether there are more pages to load. */
+    hasMore: {
+        readonly value: boolean;
+        peek(): boolean;
+    };
+    /** Fetch the next page and append it to the accumulated data. */
+    fetchNextPage: () => Promise<TData | undefined>;
+    /** Reset all pages and re-fetch from the initial cursor. */
+    refresh: () => Promise<TData | undefined>;
+    /** Clear all accumulated data. */
+    clear: () => void;
+    /** Dispose reactive watchers and prevent future executions. */
+    dispose: () => void;
+}
+/**
+ * Reactive infinite-scroll / load-more composable.
+ *
+ * Accumulates pages of data and exposes `fetchNextPage()` to load
+ * additional results. Uses a cursor-based approach with `getNextCursor()`
+ * to determine pagination.
+ *
+ * @template TResponse - Raw parsed response type for a single page
+ * @template TData - Transformed accumulated data type
+ * @template TCursor - Cursor type used for pagination
+ * @param inputFactory - Function receiving the cursor and returning a FetchInput
+ * @param options - Fetch and infinite-scroll options
+ * @returns Infinite data state with fetchNextPage(), hasMore, and accumulated pages
+ *
+ * @example
+ * ```ts
+ * import { useInfiniteFetch } from '@bquery/bquery/reactive';
+ *
+ * const feed = useInfiniteFetch<Post[], Post[]>(
+ *   (cursor) => `/api/posts?cursor=${cursor ?? ''}`,
+ *   {
+ *     getNextCursor: (page) => page.length > 0 ? page[page.length - 1].id : undefined,
+ *     transform: (pages) => pages.flat(),
+ *     baseUrl: 'https://api.example.com',
+ *   }
+ * );
+ *
+ * // Load more pages
+ * await feed.fetchNextPage();
+ * console.log(feed.data.value); // All accumulated posts
+ * console.log(feed.hasMore.value); // true if more pages available
+ * ```
+ */
+export declare const useInfiniteFetch: <TResponse = unknown, TData = TResponse[], TCursor = number>(inputFactory: (cursor: TCursor | undefined) => string | URL | Request, options: UseInfiniteFetchOptions<TResponse, TData, TCursor>) => InfiniteState<TData, TResponse>;
+//# sourceMappingURL=pagination.d.ts.map

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

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

package/dist/reactive/polling.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Reactive polling composable for periodic data fetching.
+ *
+ * @module bquery/reactive
+ */
+import { type AsyncDataState, type FetchInput, type UseFetchOptions } from './async-data';
+/** Options for usePolling(). */
+export interface UsePollingOptions<TResponse = unknown, TData = TResponse> extends UseFetchOptions<TResponse, TData> {
+    /** Polling interval in milliseconds. */
+    interval: number;
+    /** Whether polling is initially enabled (default: true). Can be a reactive getter. */
+    enabled?: boolean | (() => boolean);
+    /** Pause polling when the document is hidden (default: true). */
+    pauseOnHidden?: boolean;
+    /** Pause polling when the browser is offline (default: true). */
+    pauseOnOffline?: boolean;
+}
+/** Extended return value from usePolling(). */
+export interface PollingState<TData> extends AsyncDataState<TData> {
+    /** Pause polling. */
+    pause: () => void;
+    /** Resume polling. */
+    resume: () => void;
+    /** Reactive boolean indicating whether polling is currently active. */
+    isActive: {
+        readonly value: boolean;
+        peek(): boolean;
+    };
+}
+/**
+ * Reactive polling composable that periodically fetches data.
+ *
+ * @template TResponse - Raw parsed response type
+ * @template TData - Stored response type after optional transformation
+ * @param input - Request URL, Request object, or lazy input factory
+ * @param options - Polling and fetch options
+ * @returns Extended fetch state with pause(), resume(), and isActive
+ *
+ * @example
+ * ```ts
+ * import { usePolling } from '@bquery/bquery/reactive';
+ *
+ * const notifications = usePolling<Notification[]>('/api/notifications', {
+ *   interval: 30_000,
+ *   pauseOnHidden: true,
+ *   pauseOnOffline: true,
+ * });
+ *
+ * // Manually pause/resume
+ * notifications.pause();
+ * notifications.resume();
+ * ```
+ */
+export declare const usePolling: <TResponse = unknown, TData = TResponse>(input: FetchInput, options: UsePollingOptions<TResponse, TData>) => PollingState<TData>;
+//# sourceMappingURL=polling.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"polling.d.ts","sourceRoot":"","sources":["../../src/reactive/polling.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,EAAY,KAAK,cAAc,EAAE,KAAK,UAAU,EAAE,KAAK,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpG,gCAAgC;AAChC,MAAM,WAAW,iBAAiB,CAAC,SAAS,GAAG,OAAO,EAAE,KAAK,GAAG,SAAS,CAAE,SAAQ,eAAe,CAChG,SAAS,EACT,KAAK,CACN;IACC,wCAAwC;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,sFAAsF;IACtF,OAAO,CAAC,EAAE,OAAO,GAAG,CAAC,MAAM,OAAO,CAAC,CAAC;IACpC,iEAAiE;IACjE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,iEAAiE;IACjE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,+CAA+C;AAC/C,MAAM,WAAW,YAAY,CAAC,KAAK,CAAE,SAAQ,cAAc,CAAC,KAAK,CAAC;IAChE,qBAAqB;IACrB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,sBAAsB;IACtB,MAAM,EAAE,MAAM,IAAI,CAAC;IACnB,uEAAuE;IACvE,QAAQ,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;QAAC,IAAI,IAAI,OAAO,CAAA;KAAE,CAAC;CACxD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,UAAU,GAAI,SAAS,GAAG,OAAO,EAAE,KAAK,GAAG,SAAS,EAC/D,OAAO,UAAU,EACjB,SAAS,iBAAiB,CAAC,SAAS,EAAE,KAAK,CAAC,KAC3C,YAAY,CAAC,KAAK,CAkHpB,CAAC"}

package/dist/reactive/readonly.d.ts

@@ -2,6 +2,11 @@
  * Read-only signal wrappers.
  */
 import type { Signal } from './core';
+declare const READONLY_SIGNAL_BRAND: unique symbol;
+/** @internal */
+type ReadonlySignalWrapper<T> = ReadonlySignal<T> & {
+    readonly [READONLY_SIGNAL_BRAND]: true;
+};
 /**
  * A readonly wrapper around a signal that prevents writes.
  * Provides read-only access to a signal's value while maintaining reactivity.
@@ -14,6 +19,12 @@ export interface ReadonlySignal<T> {
     /** Gets the current value without dependency tracking. */
     peek(): T;
 }
+/**
+ * Determines whether a value is a bQuery readonly signal wrapper.
+ *
+ * @internal
+ */
+export declare const isReadonlySignal: <T>(value: unknown) => value is ReturnType<typeof readonly<T>>;
 /**
  * Creates a read-only view of a signal.
  * Useful for exposing reactive state without allowing modifications.
@@ -22,5 +33,13 @@ export interface ReadonlySignal<T> {
  * @param sig - The signal to wrap
  * @returns A readonly signal wrapper
  */
-export declare const readonly: <T>(sig: Signal<T>) => ReadonlySignal<T>;
+export declare const readonly: <T>(sig: Signal<T>) => ReadonlySignalWrapper<T>;
+/**
+ * Branded readonly wrapper type produced by {@link readonly}.
+ *
+ * Useful for APIs that compose additional behavior on top of a readonly signal
+ * without widening to arbitrary structural `{ value, peek }` objects.
+ */
+export type ReadonlySignalHandle<T> = ReturnType<typeof readonly<T>>;
+export {};
 //# sourceMappingURL=readonly.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"readonly.d.ts","sourceRoot":"","sources":["../../src/reactive/readonly.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAErC;;;;;GAKG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,0DAA0D;IAC1D,IAAI,IAAI,CAAC,CAAC;CACX;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC,CAAC,KAAG,cAAc,CAAC,CAAC,CAO3D,CAAC"}
+{"version":3,"file":"readonly.d.ts","sourceRoot":"","sources":["../../src/reactive/readonly.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAErC,QAAA,MAAM,qBAAqB,EAAE,OAAO,MAAwC,CAAC;AAE7E,gBAAgB;AAChB,KAAK,qBAAqB,CAAC,CAAC,IAAI,cAAc,CAAC,CAAC,CAAC,GAAG;IAClD,QAAQ,CAAC,CAAC,qBAAqB,CAAC,EAAE,IAAI,CAAC;CACxC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC;IAC/B,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAClB,0DAA0D;IAC1D,IAAI,IAAI,CAAC,CAAC;CACX;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,EAAE,OAAO,OAAO,KAAG,KAAK,IAAI,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC,CAAC,CAM1F,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,GAAI,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC,CAAC,KAAG,qBAAqB,CAAC,CAAC,CAuBrC,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,IAAI,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC"}