@bquery/bquery 1.6.0 → 1.8.1

package/src/reactive/scope.ts

@@ -0,0 +1,276 @@
+/**
+ * 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';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * 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 scope stack
+// ---------------------------------------------------------------------------
+
+/** @internal */
+interface ScopeInternal extends EffectScope {
+  /** @internal – Register a cleanup callback to run when the scope stops. */
+  _addDisposer(fn: CleanupFn): void;
+}
+
+const scopeStack: ScopeInternal[] = [];
+
+/** @internal */
+export const hasScopeDisposer = (
+  scope: EffectScope | undefined
+): scope is EffectScope & { _addDisposer(fn: CleanupFn): void } =>
+  typeof scope === 'object' && scope !== null && '_addDisposer' in scope;
+
+const isPromiseLike = (value: unknown): value is PromiseLike<unknown> =>
+  (typeof value === 'object' || typeof value === 'function') &&
+  value !== null &&
+  typeof (value as { then?: unknown }).then === 'function';
+
+/**
+ * Best-effort detection for native async functions so `run()` can reject them
+ * before invocation. Transpiled async functions may not preserve this shape, so
+ * promise-like return values are still checked after execution as a fallback.
+ * @internal
+ */
+const isAsyncFunction = (value: unknown): value is (...args: never[]) => Promise<unknown> => {
+  const constructorName =
+    typeof (value as { constructor?: unknown }).constructor === 'function'
+      ? (value as { constructor: { name?: unknown } }).constructor.name
+      : undefined;
+
+  return (
+    typeof value === 'function' &&
+    ((Symbol.toStringTag in value &&
+      (value as { [Symbol.toStringTag]?: unknown })[Symbol.toStringTag] === 'AsyncFunction') ||
+      constructorName === 'AsyncFunction')
+  );
+};
+
+/**
+ * Returns the currently active scope, or `undefined` if none.
+ * @internal
+ */
+export const getActiveScope = (): EffectScope | undefined => {
+  for (let i = scopeStack.length - 1; i >= 0; i--) {
+    if (scopeStack[i].active) {
+      return scopeStack[i];
+    }
+  }
+
+  return undefined;
+};
+
+// ---------------------------------------------------------------------------
+// EffectScope implementation
+// ---------------------------------------------------------------------------
+
+class EffectScopeImpl implements ScopeInternal {
+  private disposers: CleanupFn[] = [];
+  private _active = true;
+
+  get active(): boolean {
+    return this._active;
+  }
+
+  /** @internal */
+  _addDisposer(fn: CleanupFn): void {
+    if (this._active) {
+      this.disposers.push(fn);
+    }
+  }
+
+  run<T>(fn: () => T): T {
+    if (!this._active) {
+      throw new Error('bQuery reactive: Cannot run in a stopped effectScope');
+    }
+    if (isAsyncFunction(fn)) {
+      throw new Error('bQuery reactive: effectScope.run() only supports synchronous callbacks');
+    }
+
+    scopeStack.push(this);
+    try {
+      const result = fn();
+      if (isPromiseLike(result)) {
+        this.stop();
+        throw new Error('bQuery reactive: effectScope.run() only supports synchronous callbacks');
+      }
+      return result;
+    } finally {
+      scopeStack.pop();
+    }
+  }
+
+  stop(): void {
+    if (!this._active) return;
+    this._active = false;
+
+    // Dispose in reverse order (LIFO) to mirror creation order
+    for (let i = this.disposers.length - 1; i >= 0; i--) {
+      try {
+        this.disposers[i]();
+      } catch (error) {
+        console.error('bQuery reactive: Error in scope cleanup', error);
+      }
+    }
+    this.disposers.length = 0;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * 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 const effectScope = (): EffectScope => {
+  const scope = new EffectScopeImpl();
+
+  // If created inside another scope, auto-collect as a nested scope
+  const parent = getActiveScope();
+  if (hasScopeDisposer(parent)) {
+    parent._addDisposer(() => scope.stop());
+  }
+
+  return scope;
+};
+
+/**
+ * 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 const getCurrentScope = (): EffectScope | undefined => getActiveScope();
+
+/**
+ * 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 const onScopeDispose = (fn: CleanupFn): void => {
+  const scope = getActiveScope();
+  if (!scope || !scope.active || !hasScopeDisposer(scope)) {
+    throw new Error(
+      'bQuery reactive: onScopeDispose() must be called inside an active effectScope'
+    );
+  }
+  scope._addDisposer(fn);
+};

package/src/reactive/signal.ts

@@ -9,12 +9,25 @@ 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 {
@@ -24,6 +37,53 @@ export type {
   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';

package/src/reactive/to-value.ts

@@ -0,0 +1,71 @@
+/**
+ * Utility to unwrap reactive or plain values.
+ */
+
+import { Computed } from './computed';
+import { Signal } from './core';
+import { readonly, isReadonlySignal } 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 const toValue = <T>(source: MaybeSignal<T>): T => {
+  if (source instanceof Signal || source instanceof Computed) {
+    return source.value;
+  }
+
+  if (isReadonlySignal<T>(source)) {
+    return source.value;
+  }
+
+  // Remaining values are plain `T` inputs. Structural readonly-like objects that are not
+  // branded bQuery wrappers intentionally fall through and are returned unchanged.
+  return source as T;
+};