katanakit-js 3.2.2 → 4.0.3

package/dist/core/services/query.service.d.ts

@@ -1,136 +1,93 @@
-import type { ApiError, FetchResult } from "../../types/index.js";
-/** Status of a cached query. */
-export type QueryStatus = "idle" | "loading" | "success" | "error";
-/** Serializable query key — array of primitives or nested arrays/objects. */
-export type QueryKey = readonly unknown[];
-/** Fetcher function that returns a Safe Result. */
-export type QueryFn<T> = () => Promise<FetchResult<T>>;
-/** Configuration for a single query. */
-export interface QueryConfig<T = unknown> {
-    queryKey: QueryKey;
-    queryFn: QueryFn<T>;
-    /** Time in ms before cached data is considered stale (default: 0). */
-    staleTime?: number;
-    /** Time in ms to keep unused data in cache (default: 5 min). */
-    cacheTime?: number;
-    /** Number of retry attempts on failure (default: 3). */
-    retry?: number;
-    /** Base delay in ms for exponential backoff (default: 1000). */
-    retryDelay?: number;
-    /** Refetch when the window/tab regains focus (default: true). */
-    refetchOnWindowFocus?: boolean;
-    /** Refetch when the network reconnects (default: true). */
-    refetchOnReconnect?: boolean;
-    /** Whether the query is enabled (default: true). */
-    enabled?: boolean;
-    /** Called on successful fetch. */
-    onSuccess?: (data: T) => void;
-    /** Called on error. */
-    onError?: (error: ApiError) => void;
-}
-/** Reactive state of a query. */
-export interface QueryState<T = unknown> {
-    status: QueryStatus;
-    data: T | null;
-    error: ApiError | null;
-    isLoading: boolean;
-    isSuccess: boolean;
-    isError: boolean;
-    isStale: boolean;
-    dataUpdatedAt: number;
-    errorUpdatedAt: number;
-    fetchCount: number;
-}
-/** Observer (subscriber) that listens to query state changes. */
-export type QueryObserver<T = unknown> = (state: QueryState<T>) => void;
-/** Configuration for a mutation. */
-export interface MutationConfig<TData = unknown, TVariables = unknown> {
-    mutationFn: (variables: TVariables) => Promise<FetchResult<TData>>;
-    onSuccess?: (data: TData, variables: TVariables) => void;
-    onError?: (error: ApiError, variables: TVariables) => void;
-    onSettled?: (data: TData | null, error: ApiError | null, variables: TVariables) => void;
-}
-/** State of a mutation. */
-export interface MutationState<TData = unknown> {
-    status: "idle" | "loading" | "success" | "error";
-    data: TData | null;
-    error: ApiError | null;
-    isLoading: boolean;
-    isSuccess: boolean;
-    isError: boolean;
-}
-/** Default configuration for all queries. */
-export interface QueryClientConfig {
-    defaultOptions?: {
-        queries?: Partial<Omit<QueryConfig, "queryKey" | "queryFn">>;
-    };
-}
-export declare class QueryClient {
-    private cache;
-    private defaults;
-    constructor(config?: QueryClientConfig);
-    /**
-     * Fetches data for a query key, using the cache when possible.
-     * Returns the cached data immediately if fresh, then optionally
-     * refetches in the background (stale-while-revalidate).
-     */
-    fetchQuery<T>(config: QueryConfig<T>): Promise<T>;
-    /**
-     * Prefetches data into the cache without returning it.
-     * Useful for anticipatory fetching.
-     */
-    prefetchQuery<T>(config: QueryConfig<T>): Promise<void>;
-    /**
-     * Returns the cached data for a query key, or undefined if not cached.
-     */
-    getQueryData<T>(queryKey: QueryKey): T | undefined;
-    /**
-     * Sets query data directly in the cache (optimistic updates).
-     */
-    setQueryData<T>(queryKey: QueryKey, updater: T | ((old: T | undefined) => T)): void;
-    /**
-     * Marks queries matching the filter as stale and optionally refetches
-     * active queries.
-     */
-    invalidateQueries(filters?: {
-        queryKey?: QueryKey;
-    }): Promise<void>;
-    /**
-     * Removes a query from the cache.
-     */
-    removeQueries(queryKey: QueryKey): void;
-    /**
-     * Clears the entire cache.
-     */
-    clear(): void;
-    /**
-     * Returns the current state of a cached query (reactive signal).
-     * Subscribes to future updates.
-     */
-    getQueryState<T>(queryKey: QueryKey): QueryState<T> | undefined;
-    /**
-     * Subscribes to state changes for a specific query.
-     * Returns an unsubscribe function.
-     */
-    subscribe<T>(queryKey: QueryKey, observer: QueryObserver<T>): () => void;
-    /**
-     * Cancels an in-flight request for a query.
-     */
-    cancelQueries(queryKey: QueryKey): void;
-    private mergeDefaults;
-    private createEntry;
-    private isStale;
-    private executeFetch;
-    private notifyObservers;
-}
+import { QueryClient, type QueryClientConfig, type QueryFunctionContext } from "@tanstack/query-core";
+import type { FetchResult } from "../../types/index.js";
 /**
- * Returns the global {@link QueryClient} singleton.
- * Creates one with default options on first call.
+ * Query engine — a thin facade over {@link https://tanstack.com/query | TanStack Query Core}.
+ *
+ * The full `@tanstack/query-core` API is re-exported from here (and therefore
+ * from `katanakit-js`), so consumers get TanStack's cache, retries, stale-while-
+ * revalidate, focus/reconnect refetch, garbage collection and infinite queries
+ * without installing TanStack separately.
+ */
+export * from "@tanstack/query-core";
+/**
+ * Creates a **new** {@link QueryClient}. Use this on the server (SSR) to get one
+ * client per request and avoid sharing a process-global cache across users.
+ *
+ * @param config - TanStack {@link QueryClientConfig} (caches, default options).
+ * @returns A fresh {@link QueryClient}.
+ *
+ * @example
+ * ```ts
+ * // Server: one client per request, then dehydrate/hydrate.
+ * const client = useCreateQueryClient();
+ * await client.prefetchQuery({ queryKey, queryFn });
+ * const state = dehydrate(client);
+ * ```
+ */
+export declare function useCreateQueryClient(config?: QueryClientConfig): QueryClient;
+/**
+ * Returns the shared {@link QueryClient} singleton, creating one on first call.
+ *
+ * This is a **process-global** instance: it is the right default in the browser,
+ * but on the server it would leak cached data across requests. Use
+ * {@link useCreateQueryClient} per request when running under SSR.
+ *
+ * @returns The shared {@link QueryClient}.
+ *
+ * @example
+ * ```ts
+ * import { useQueryClient } from "katanakit-js";
+ *
+ * const client = useQueryClient();
+ * await client.invalidateQueries({ queryKey: ["users"] });
+ * ```
  */
 export declare function useQueryClient(): QueryClient;
 /**
- * Initialises the global {@link QueryClient} singleton with custom options.
- * Must be called before any `useQuery` call.
+ * Replaces the shared {@link QueryClient} singleton with a configured instance.
+ * The previous client's caches are cleared before swapping.
+ *
+ * @param config - TanStack {@link QueryClientConfig} (caches, default options).
+ * @returns The newly created {@link QueryClient}.
+ *
+ * @example
+ * ```ts
+ * import { useInitQueryClient } from "katanakit-js";
+ *
+ * useInitQueryClient({
+ *   defaultOptions: { queries: { staleTime: 60_000, retry: 2 } },
+ * });
+ * ```
+ */
+export declare function useInitQueryClient(config?: QueryClientConfig): QueryClient;
+/**
+ * Bridges a KatanaKit Safe Result fetcher into a TanStack `queryFn`.
+ *
+ * TanStack expects `queryFn` to resolve with data and **throw** on failure;
+ * KatanaKit returns `{ data, error, ok }`. This adapter unwraps the Safe Result
+ * so the two fit together. Throws a real `Error` (with `status`) so `instanceof`
+ * checks and error boundaries work; the upstream response body is **not** placed
+ * on the thrown error.
+ *
+ * Receives TanStack's {@link QueryFunctionContext}, so you can forward
+ * `signal` for real request cancellation.
+ *
+ * @typeParam T - The resolved data type.
+ * @param fn - A function returning a Safe Result (e.g. `() => useGetApi(...)`).
+ * @returns A `queryFn` that throws on error.
+ *
+ * @example
+ * ```ts
+ * import { useSafeQueryFn, useGetApi, useFetch } from "katanakit-js";
+ *
+ * // Simple: the Safe Result gate.
+ * queryFn: useSafeQueryFn(() => useGetApi("pokeapi", "pokemonById", { params: { id } }))
+ *
+ * // With cancellation: forward TanStack's AbortSignal into the request.
+ * queryFn: useSafeQueryFn(({ signal }) =>
+ *   useFetch("pokeapi", "pokemonById", { method: "GET", urlOptions: { params: { id } }, signal }),
+ * )
+ * ```
  */
-export declare function useInitQueryClient(config: QueryClientConfig): QueryClient;
+export declare function useSafeQueryFn<T>(fn: (context: QueryFunctionContext) => Promise<FetchResult<T>>): (context: QueryFunctionContext) => Promise<T>;
 //# sourceMappingURL=query.service.d.ts.map

package/dist/core/services/query.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.service.d.ts","sourceRoot":"","sources":["../../../src/core/services/query.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"query.service.d.ts","sourceRoot":"","sources":["../../../src/core/services/query.service.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,WAAW,EACX,KAAK,iBAAiB,EACtB,KAAK,oBAAoB,EACzB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAExD;;;;;;;GAOG;AACH,cAAc,sBAAsB,CAAC;AAKrC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,GAAE,iBAAsB,GAAG,WAAW,CAEhF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,IAAI,WAAW,CAE5C;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,GAAE,iBAAsB,GAAG,WAAW,CAI9E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC/B,EAAE,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,GAC5D,CAAC,OAAO,EAAE,oBAAoB,KAAK,OAAO,CAAC,CAAC,CAAC,CAQ/C"}