@bquery/bquery 1.7.0 → 1.8.1

package/dist/reactive/rest.d.ts

@@ -0,0 +1,293 @@
+/**
+ * REST resource composable for CRUD operations with optimistic updates,
+ * form submission, and reactive caching built on the bQuery fetch layer.
+ *
+ * @module bquery/reactive
+ */
+import { Signal } from './core';
+import { type AsyncDataStatus, type UseFetchOptions } from './async-data';
+import { type HttpClient, type HttpRequestConfig, type HttpResponse } from './http';
+/** HTTP method shortcuts available on a resource. */
+export interface ResourceActions<T> {
+    /** Fetch the resource (GET). */
+    fetch: () => Promise<T | undefined>;
+    /** Create a new item (POST). */
+    create: (body: Partial<T> | Record<string, unknown>) => Promise<T | undefined>;
+    /** Replace the resource (PUT). */
+    update: (body: Partial<T> | Record<string, unknown>) => Promise<T | undefined>;
+    /** Partially update the resource (PATCH). */
+    patch: (body: Partial<T> | Record<string, unknown>) => Promise<T | undefined>;
+    /** Delete the resource (DELETE). */
+    remove: () => Promise<void>;
+}
+/** Options for `useResource()`. */
+export interface UseResourceOptions<T = unknown> extends Omit<UseFetchOptions<T>, 'method' | 'body'> {
+    /** Enable optimistic updates for mutating operations (default: false). */
+    optimistic?: boolean;
+    /** Called after any successful mutation (create / update / patch / remove). */
+    onMutationSuccess?: (data: T | undefined, action: string) => void;
+    /** Called after a failed mutation, receives the error and action name. */
+    onMutationError?: (error: Error, action: string) => void;
+}
+/** Return value of `useResource()`. */
+export interface UseResourceReturn<T> {
+    /** Reactive resource data. */
+    data: Signal<T | undefined>;
+    /** Last error. */
+    error: Signal<Error | null>;
+    /** Lifecycle status for the initial fetch. */
+    status: Signal<AsyncDataStatus>;
+    /** Whether the initial fetch is pending. */
+    pending: {
+        readonly value: boolean;
+        peek(): boolean;
+    };
+    /** Whether any mutation is in progress. */
+    isMutating: {
+        readonly value: boolean;
+        peek(): boolean;
+    };
+    /** CRUD actions. */
+    actions: ResourceActions<T>;
+    /** Refresh the resource (re-GET). */
+    refresh: () => Promise<T | undefined>;
+    /** Clear data, error, and status. */
+    clear: () => void;
+    /** Dispose all reactive state and prevent future operations. */
+    dispose: () => void;
+}
+/**
+ * Reactive REST resource composable providing CRUD operations.
+ *
+ * Binds a base URL to a resource and exposes `fetch`, `create`, `update`,
+ * `patch`, and `remove` helpers with optional optimistic updates.
+ *
+ * @template T - Resource data type
+ * @param url - Resource endpoint URL or getter
+ * @param options - Fetch and resource options
+ * @returns Reactive resource state with CRUD actions
+ *
+ * @example
+ * ```ts
+ * import { useResource } from '@bquery/bquery/reactive';
+ *
+ * const user = useResource<User>('/api/users/1', {
+ *   baseUrl: 'https://api.example.com',
+ *   optimistic: true,
+ * });
+ *
+ * // Read
+ * await user.actions.fetch();
+ *
+ * // Update
+ * await user.actions.patch({ name: 'Ada' });
+ *
+ * // Delete
+ * await user.actions.remove();
+ * ```
+ */
+export declare const useResource: <T = unknown>(url: string | URL | (() => string | URL), options?: UseResourceOptions<T>) => UseResourceReturn<T>;
+/** Options for `useSubmit()`. */
+export interface UseSubmitOptions<TResponse = unknown> extends Omit<UseFetchOptions<TResponse>, 'body' | 'immediate'> {
+    /** HTTP method (default: `'POST'`). */
+    method?: string;
+}
+/** Return value of `useSubmit()`. */
+export interface UseSubmitReturn<TResponse = unknown> {
+    /** Last response data. */
+    data: Signal<TResponse | undefined>;
+    /** Last error. */
+    error: Signal<Error | null>;
+    /** Current status. */
+    status: Signal<AsyncDataStatus>;
+    /** Whether the submission is pending. */
+    pending: {
+        readonly value: boolean;
+        peek(): boolean;
+    };
+    /** Submit data to the endpoint. */
+    submit: (body: Record<string, unknown> | FormData | BodyInit) => Promise<TResponse | undefined>;
+    /** Reset state. */
+    clear: () => void;
+}
+/**
+ * Reactive form submission composable.
+ *
+ * Provides a `submit()` function that sends data to an endpoint with
+ * reactive status, data, and error signals.
+ *
+ * @template TResponse - Response data type
+ * @param url - Submission endpoint URL
+ * @param options - Fetch options (method defaults to POST)
+ * @returns Reactive submission state with `submit()` and `clear()`
+ *
+ * @example
+ * ```ts
+ * import { useSubmit } from '@bquery/bquery/reactive';
+ *
+ * const form = useSubmit<{ id: number }>('/api/users', {
+ *   baseUrl: 'https://api.example.com',
+ *   headers: { 'x-csrf': token },
+ * });
+ *
+ * const result = await form.submit({ name: 'Ada', email: 'ada@example.com' });
+ * console.log(form.status.value); // 'success'
+ * ```
+ */
+export declare const useSubmit: <TResponse = unknown>(url: string | URL, options?: UseSubmitOptions<TResponse>) => UseSubmitReturn<TResponse>;
+/** Typed CRUD methods for a REST endpoint. */
+export interface RestClient<T = unknown> {
+    /** GET all items. */
+    list: (config?: HttpRequestConfig) => Promise<HttpResponse<T[]>>;
+    /** GET a single item by ID. */
+    get: (id: string | number, config?: HttpRequestConfig) => Promise<HttpResponse<T>>;
+    /** POST a new item. */
+    create: (body: Partial<T> | Record<string, unknown>, config?: HttpRequestConfig) => Promise<HttpResponse<T>>;
+    /** PUT (full replace) an item by ID. */
+    update: (id: string | number, body: Partial<T> | Record<string, unknown>, config?: HttpRequestConfig) => Promise<HttpResponse<T>>;
+    /** PATCH (partial update) an item by ID. */
+    patch: (id: string | number, body: Partial<T> | Record<string, unknown>, config?: HttpRequestConfig) => Promise<HttpResponse<T>>;
+    /** DELETE an item by ID. */
+    remove: (id: string | number, config?: HttpRequestConfig) => Promise<HttpResponse<void>>;
+    /** The underlying HttpClient instance. */
+    http: HttpClient;
+}
+/**
+ * Create a typed REST client for a specific API resource.
+ *
+ * Wraps `createHttp()` and maps standard CRUD operations to their
+ * conventional REST endpoints (`GET /`, `GET /:id`, `POST /`, `PUT /:id`,
+ * `PATCH /:id`, `DELETE /:id`).
+ *
+ * @template T - Resource item type
+ * @param baseUrl - Base URL of the resource (e.g. `https://api.example.com/users`)
+ * @param defaults - Default request configuration merged into every call
+ * @returns Typed REST client with `list`, `get`, `create`, `update`, `patch`, `remove`
+ *
+ * @example
+ * ```ts
+ * import { createRestClient } from '@bquery/bquery/reactive';
+ *
+ * interface User { id: number; name: string; email: string }
+ *
+ * const users = createRestClient<User>('https://api.example.com/users', {
+ *   headers: { authorization: '******' },
+ *   timeout: 10_000,
+ * });
+ *
+ * const { data: allUsers } = await users.list();
+ * const { data: user } = await users.get(1);
+ * const { data: created } = await users.create({ name: 'Ada' });
+ * await users.update(1, { name: 'Ada', email: 'ada@example.com' });
+ * await users.patch(1, { email: 'new@example.com' });
+ * await users.remove(1);
+ * ```
+ */
+export declare const createRestClient: <T = unknown>(baseUrl: string, defaults?: HttpRequestConfig) => RestClient<T>;
+/** Extract a unique identifier from an item. */
+export type IdExtractor<T> = (item: T) => string | number;
+/** Options for `useResourceList()`. */
+export interface UseResourceListOptions<T = unknown> extends Omit<UseFetchOptions<T[]>, 'method' | 'body'> {
+    /** Extract the unique ID from each item (default: `item.id`). */
+    getId?: IdExtractor<T>;
+    /** Enable optimistic list mutations (default: false). */
+    optimistic?: boolean;
+    /** Called after a successful list mutation. */
+    onMutationSuccess?: (action: string) => void;
+    /** Called after a failed list mutation. */
+    onMutationError?: (error: Error, action: string) => void;
+}
+/** CRUD actions for a list resource. */
+export interface ResourceListActions<T> {
+    /** Refresh the list (GET). */
+    fetch: () => Promise<T[] | undefined>;
+    /** Add a new item to the list (POST). */
+    add: (body: Partial<T> | Record<string, unknown>) => Promise<T | undefined>;
+    /** Update an existing item (PUT) by ID. */
+    update: (id: string | number, body: Partial<T> | Record<string, unknown>) => Promise<T | undefined>;
+    /** Partially update an existing item (PATCH) by ID. */
+    patch: (id: string | number, body: Partial<T> | Record<string, unknown>) => Promise<T | undefined>;
+    /** Remove an item from the list (DELETE) by ID. */
+    remove: (id: string | number) => Promise<void>;
+}
+/** Return value of `useResourceList()`. */
+export interface UseResourceListReturn<T> {
+    /** Reactive list data. */
+    data: Signal<T[] | undefined>;
+    /** Last error. */
+    error: Signal<Error | null>;
+    /** Lifecycle status. */
+    status: Signal<AsyncDataStatus>;
+    /** Whether the list fetch is pending. */
+    pending: {
+        readonly value: boolean;
+        peek(): boolean;
+    };
+    /** Whether any mutation is in progress. */
+    isMutating: {
+        readonly value: boolean;
+        peek(): boolean;
+    };
+    /** CRUD actions. */
+    actions: ResourceListActions<T>;
+    /** Refresh the list. */
+    refresh: () => Promise<T[] | undefined>;
+    /** Clear data, error, and status. */
+    clear: () => void;
+    /** Dispose all reactive state. */
+    dispose: () => void;
+}
+/**
+ * Reactive list/collection CRUD composable with optimistic add, remove, and update.
+ *
+ * Fetches a list of items and provides typed CRUD helpers that update the
+ * reactive array optimistically or after server confirmation.
+ *
+ * @template T - Item type
+ * @param url - List endpoint URL or getter
+ * @param options - Fetch and list options
+ * @returns Reactive list state with CRUD actions
+ *
+ * @example
+ * ```ts
+ * import { useResourceList } from '@bquery/bquery/reactive';
+ *
+ * interface Todo { id: number; title: string; done: boolean }
+ *
+ * const todos = useResourceList<Todo>('/api/todos', {
+ *   baseUrl: 'https://api.example.com',
+ *   optimistic: true,
+ *   getId: (t) => t.id,
+ * });
+ *
+ * await todos.actions.add({ title: 'Buy milk', done: false });
+ * await todos.actions.patch(1, { done: true });
+ * await todos.actions.remove(1);
+ * ```
+ */
+export declare const useResourceList: <T = unknown>(url: string | URL | (() => string | URL), options?: UseResourceListOptions<T>) => UseResourceListReturn<T>;
+/**
+ * Deduplicate identical in-flight requests or operations keyed by `key`.
+ *
+ * If an operation with the same key is already in flight, reuse its promise
+ * instead of starting a new one. Once the operation completes, the entry is removed.
+ *
+ * @param key - Cache key for the in-flight operation (for HTTP, typically URL + serialized query)
+ * @param execute - The operation function to run if no duplicate is in flight
+ * @returns The shared result promise for callers using the same key concurrently
+ *
+ * @example
+ * ```ts
+ * import { deduplicateRequest, createHttp } from '@bquery/bquery/reactive';
+ *
+ * const api = createHttp({ baseUrl: 'https://api.example.com' });
+ *
+ * // Both calls share the same in-flight operation
+ * const [a, b] = await Promise.all([
+ *   deduplicateRequest('/users', () => api.get('/users')),
+ *   deduplicateRequest('/users', () => api.get('/users')),
+ * ]);
+ * ```
+ */
+export declare function deduplicateRequest<T>(key: string, execute: () => Promise<T>): Promise<T>;
+//# sourceMappingURL=rest.d.ts.map

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

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

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"}