@bquery/bquery 1.7.0 → 1.8.1

package/src/reactive/index.ts

@@ -9,16 +9,35 @@ export {
   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';
@@ -27,11 +46,52 @@ 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';

package/src/reactive/pagination.ts

@@ -0,0 +1,317 @@
+/**
+ * Pagination and infinite-scroll composables for reactive data fetching.
+ *
+ * @module bquery/reactive
+ */
+
+import { computed } from './computed';
+import { Signal, signal } from './core';
+import {
+  useFetch,
+  type AsyncDataState,
+  type AsyncDataStatus,
+  type UseFetchOptions,
+} from './async-data';
+
+// ---------------------------------------------------------------------------
+// usePaginatedFetch
+// ---------------------------------------------------------------------------
+
+/** 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 const usePaginatedFetch = <TResponse = unknown, TData = TResponse>(
+  inputFactory: (page: number) => string | URL | Request,
+  options: UsePaginatedFetchOptions<TResponse, TData> = {}
+): PaginatedState<TData> => {
+  const { initialPage = 1, ...fetchOptions } = options;
+  const page = signal(initialPage);
+
+  const state = useFetch<TResponse, TData>(() => inputFactory(page.value), {
+    ...fetchOptions,
+    watch: fetchOptions.watch,
+  });
+
+  const next = async (): Promise<TData | undefined> => {
+    page.value = page.peek() + 1;
+    return state.execute();
+  };
+
+  const prev = async (): Promise<TData | undefined> => {
+    const current = page.peek();
+    if (current > 1) {
+      page.value = current - 1;
+    }
+    return state.execute();
+  };
+
+  const goTo = async (target: number): Promise<TData | undefined> => {
+    page.value = Math.max(1, target);
+    return state.execute();
+  };
+
+  return {
+    ...state,
+    page,
+    next,
+    prev,
+    goTo,
+  };
+};
+
+// ---------------------------------------------------------------------------
+// useInfiniteFetch
+// ---------------------------------------------------------------------------
+
+/** 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 const useInfiniteFetch = <TResponse = unknown, TData = TResponse[], TCursor = number>(
+  inputFactory: (cursor: TCursor | undefined) => string | URL | Request,
+  options: UseInfiniteFetchOptions<TResponse, TData, TCursor>
+): InfiniteState<TData, TResponse> => {
+  const {
+    getNextCursor,
+    transform: transformPages,
+    initialCursor,
+    immediate = true,
+    // Keep these callbacks on the infinite-fetch layer instead of forwarding
+    // them into the inner per-page useFetch() instance.
+    onSuccess: infiniteOnSuccess,
+    onError: infiniteOnError,
+    ...fetchOptions
+  } = options;
+
+  const pages = signal<TResponse[]>([]);
+  const data = signal<TData | undefined>(options.defaultValue);
+  const error = signal<Error | null>(null);
+  const status = signal<AsyncDataStatus>('idle');
+  const pending = computed(() => status.value === 'pending');
+  const nextCursor = signal<TCursor | undefined>(initialCursor);
+  const hasMore = computed(() => pages.value.length === 0 || nextCursor.value !== undefined);
+
+  let disposed = false;
+  let executionId = 0;
+
+  const applyTransform = (allPages: TResponse[]): TData => {
+    if (transformPages) {
+      return transformPages(allPages);
+    }
+    return allPages as unknown as TData;
+  };
+
+  const fetchNextPage = async (): Promise<TData | undefined> => {
+    if (disposed) return data.peek();
+
+    const currentExecution = ++executionId;
+    status.value = 'pending';
+    error.value = null;
+
+    try {
+      const cursor = nextCursor.peek();
+      const input = inputFactory(cursor);
+      const pageState = useFetch<TResponse>(input, {
+        ...(fetchOptions as UseFetchOptions<TResponse>),
+        immediate: false,
+        watch: undefined,
+      });
+
+      const pageData = await pageState.execute();
+      const pageError = pageState.error.peek();
+      pageState.dispose();
+
+      if (disposed || currentExecution !== executionId) return data.peek();
+
+      // Check if the inner fetch encountered an error
+      if (pageError) {
+        error.value = pageError;
+        status.value = 'error';
+        infiniteOnError?.(pageError);
+        return data.peek();
+      }
+
+      if (pageData !== undefined) {
+        const typedPageData = pageData as TResponse;
+        const newPages: TResponse[] = [...pages.peek(), typedPageData];
+        pages.value = newPages;
+
+        const newCursor = getNextCursor(typedPageData, newPages);
+        nextCursor.value = newCursor;
+
+        const transformed = applyTransform(newPages);
+        data.value = transformed;
+        status.value = 'success';
+        infiniteOnSuccess?.(transformed);
+        return transformed;
+      }
+
+      status.value = 'success';
+      return data.peek();
+    } catch (caught) {
+      if (disposed || currentExecution !== executionId) return data.peek();
+
+      const normalizedError = caught instanceof Error ? caught : new Error(String(caught));
+      error.value = normalizedError;
+      status.value = 'error';
+      infiniteOnError?.(normalizedError);
+      return data.peek();
+    }
+  };
+
+  const refresh = async (): Promise<TData | undefined> => {
+    pages.value = [];
+    nextCursor.value = initialCursor;
+    data.value = options.defaultValue;
+    error.value = null;
+    status.value = 'idle';
+    executionId += 1;
+    return fetchNextPage();
+  };
+
+  const clear = (): void => {
+    executionId += 1;
+    pages.value = [];
+    nextCursor.value = initialCursor;
+    data.value = options.defaultValue;
+    error.value = null;
+    status.value = 'idle';
+  };
+
+  const dispose = (): void => {
+    if (disposed) return;
+    disposed = true;
+    executionId += 1;
+  };
+
+  if (immediate) {
+    void fetchNextPage();
+  }
+
+  return {
+    data,
+    pages,
+    error,
+    status,
+    pending,
+    hasMore,
+    fetchNextPage,
+    refresh,
+    clear,
+    dispose,
+  };
+};

package/src/reactive/polling.ts

@@ -0,0 +1,179 @@
+/**
+ * Reactive polling composable for periodic data fetching.
+ *
+ * @module bquery/reactive
+ */
+
+import { computed } from './computed';
+import { effect } from './effect';
+import { signal } from './core';
+import { untrack } from './untrack';
+import { useFetch, 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 const usePolling = <TResponse = unknown, TData = TResponse>(
+  input: FetchInput,
+  options: UsePollingOptions<TResponse, TData>
+): PollingState<TData> => {
+  const {
+    interval,
+    enabled: enabledOption = true,
+    pauseOnHidden = true,
+    pauseOnOffline = true,
+    immediate = true,
+    ...fetchOptions
+  } = options;
+
+  if (!Number.isFinite(interval) || interval < 1) {
+    throw new Error('Polling interval must be a finite number of at least 1');
+  }
+
+  const manuallyPaused = signal(false);
+  const documentHidden = signal(false);
+  const browserOffline = signal(false);
+
+  const enabledGetter = typeof enabledOption === 'function' ? enabledOption : () => enabledOption;
+
+  const isActive = computed(
+    () =>
+      enabledGetter() &&
+      !manuallyPaused.value &&
+      !(pauseOnHidden && documentHidden.value) &&
+      !(pauseOnOffline && browserOffline.value)
+  );
+
+  // Create the underlying useFetch with immediate control
+  const fetchState = useFetch<TResponse, TData>(input, {
+    ...fetchOptions,
+    immediate: immediate && enabledGetter(),
+  });
+
+  let intervalId: ReturnType<typeof setInterval> | undefined;
+  let cleanups: Array<() => void> = [];
+
+  const startPolling = (): void => {
+    stopPolling();
+    intervalId = setInterval(() => {
+      void fetchState.execute();
+    }, interval);
+  };
+
+  const stopPolling = (): void => {
+    if (intervalId !== undefined) {
+      clearInterval(intervalId);
+      intervalId = undefined;
+    }
+  };
+
+  // Watch isActive and start/stop polling accordingly
+  const stopWatcher = effect(() => {
+    const active = isActive.value;
+    untrack(() => {
+      if (active) {
+        startPolling();
+      } else {
+        stopPolling();
+      }
+    });
+  });
+
+  // Listen for visibility changes
+  if (pauseOnHidden && typeof document !== 'undefined') {
+    documentHidden.value = document.hidden;
+    const onVisibilityChange = (): void => {
+      documentHidden.value = document.hidden;
+    };
+    document.addEventListener('visibilitychange', onVisibilityChange);
+    cleanups.push(() => document.removeEventListener('visibilitychange', onVisibilityChange));
+  }
+
+  // Listen for online/offline changes
+  if (pauseOnOffline && typeof window !== 'undefined') {
+    const onOnline = (): void => {
+      browserOffline.value = false;
+    };
+    const onOffline = (): void => {
+      browserOffline.value = true;
+    };
+    window.addEventListener('online', onOnline);
+    window.addEventListener('offline', onOffline);
+    cleanups.push(() => {
+      window.removeEventListener('online', onOnline);
+      window.removeEventListener('offline', onOffline);
+    });
+    browserOffline.value =
+      typeof navigator !== 'undefined' && navigator.onLine !== undefined
+        ? !navigator.onLine
+        : false;
+  }
+
+  const originalDispose = fetchState.dispose;
+
+  const dispose = (): void => {
+    stopPolling();
+    stopWatcher();
+    for (const cleanup of cleanups) cleanup();
+    cleanups = [];
+    originalDispose();
+  };
+
+  return {
+    ...fetchState,
+    pause: () => {
+      manuallyPaused.value = true;
+    },
+    resume: () => {
+      manuallyPaused.value = false;
+    },
+    isActive,
+    dispose,
+  };
+};

package/src/reactive/readonly.ts

@@ -4,6 +4,13 @@
 
 import type { Signal } from './core';
 
+const READONLY_SIGNAL_BRAND: unique symbol = Symbol('bquery.readonlySignal');
+
+/** @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.
@@ -17,6 +24,19 @@ export interface ReadonlySignal<T> {
   peek(): T;
 }
 
+/**
+ * Determines whether a value is a bQuery readonly signal wrapper.
+ *
+ * @internal
+ */
+export const isReadonlySignal = <T>(value: unknown): value is ReturnType<typeof readonly<T>> => {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    Object.prototype.hasOwnProperty.call(value, READONLY_SIGNAL_BRAND)
+  );
+};
+
 /**
  * Creates a read-only view of a signal.
  * Useful for exposing reactive state without allowing modifications.
@@ -25,11 +45,35 @@ export interface ReadonlySignal<T> {
  * @param sig - The signal to wrap
  * @returns A readonly signal wrapper
  */
-export const readonly = <T>(sig: Signal<T>): ReadonlySignal<T> => ({
-  get value(): T {
-    return sig.value;
-  },
-  peek(): T {
-    return sig.peek();
-  },
-});
+export const readonly = <T>(sig: Signal<T>): ReadonlySignalWrapper<T> =>
+  Object.defineProperties(
+    {},
+    {
+      value: {
+        get(): T {
+          return sig.value;
+        },
+        enumerable: true,
+      },
+      peek: {
+        value(): T {
+          return sig.peek();
+        },
+        enumerable: true,
+      },
+      [READONLY_SIGNAL_BRAND]: {
+        value: true,
+        enumerable: false,
+        configurable: false,
+        writable: false,
+      },
+    }
+  ) as 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>>;