@navios/react-query 0.7.1 → 1.0.0

package/lib/index.mjs

@@ -15,27 +15,28 @@ import { infiniteQueryOptions, queryOptions, useInfiniteQuery, useIsMutating, us
 */
 function createQueryKey(config, options, _isInfinite) {
 	const url = config.url;
-	const urlParts = url.split("/").filter(Boolean);
 	return {
-		template: urlParts,
+		template: url.split("/").filter(Boolean),
 		dataTag: (params) => {
 			const queryParams = params && "querySchema" in config && "params" in params ? config.querySchema?.parse(params.params) : [];
+			const boundUrlParts = bindUrlParams(url, params && "urlParams" in params ? params : {}, config.urlParamsSchema).split("/").filter(Boolean);
 			return [
 				...options.keyPrefix ?? [],
-				...urlParts.map((part) => part.startsWith("$") ? params.urlParams[part.slice(1)].toString() : part),
+				...boundUrlParts,
 				...options.keySuffix ?? [],
 				queryParams ?? []
 			];
 		},
 		filterKey: (params) => {
+			const boundUrlParts = bindUrlParams(url, params && "urlParams" in params ? params : {}, config.urlParamsSchema).split("/").filter(Boolean);
 			return [
 				...options.keyPrefix ?? [],
-				...urlParts.map((part) => part.startsWith("$") ? params.urlParams[part.slice(1)].toString() : part),
+				...boundUrlParts,
 				...options.keySuffix ?? []
 			];
 		},
 		bindToUrl: (params) => {
-			return bindUrlParams(url, params ?? {});
+			return bindUrlParams(url, params && "urlParams" in params ? params : {}, config.urlParamsSchema);
 		}
 	};
 }
@@ -50,12 +51,29 @@ const queryKeyCreator = createQueryKey;
 * Returns a function that generates TanStack Query options when called with params.
 * The returned function also has helper methods attached (use, useSuspense, invalidate, etc.)
 *
-* @param endpoint - The navios endpoint to create query options for
+* Uses const generics pattern to automatically infer types from the endpoint configuration.
+*
+* @param endpoint - The navios endpoint handler (from builder's declareEndpoint)
 * @param options - Query configuration including processResponse
 * @param baseQuery - Optional base query options to merge
 * @returns A function that generates query options with attached helpers
+*
+* @example
+* ```ts
+* const getUser = api.declareEndpoint({
+*   method: 'GET',
+*   url: '/users/$userId',
+*   responseSchema: userSchema,
+* })
+*
+* const queryOptions = makeQueryOptions(getUser, {
+*   processResponse: (data) => data,
+* })
+*
+* const { data } = queryOptions.useSuspense({ urlParams: { userId: '123' } })
+* ```
 */
-function makeQueryOptions(endpoint, options, baseQuery = {}) {
+function makeQueryOptions(endpoint, options, baseQuery) {
 	const config = endpoint.config;
 	const queryKey = createQueryKey(config, options, false);
 	const processResponse = options.processResponse;
@@ -78,18 +96,62 @@ function makeQueryOptions(endpoint, options, baseQuery = {}) {
 			...baseQuery
 		});
 	};
+	/** The query key creator for this endpoint */
 	result.queryKey = queryKey;
+	/**
+	* React hook that executes the query.
+	* Uses `useQuery` from TanStack Query internally.
+	*
+	* @param params - URL parameters, query parameters, and request body
+	* @returns Query result with data, isLoading, error, etc.
+	*/
 	result.use = (params) => {
 		return useQuery(result(params));
 	};
+	/**
+	* React hook that executes the query with Suspense support.
+	* Uses `useSuspenseQuery` from TanStack Query internally.
+	* The component will suspend while loading and throw on error.
+	*
+	* @param params - URL parameters, query parameters, and request body
+	* @returns Query result with data guaranteed to be defined
+	*/
 	result.useSuspense = (params) => {
 		return useSuspenseQuery(result(params));
 	};
+	/**
+	* Creates a function that invalidates a specific query in the cache.
+	* Call the returned function to trigger the invalidation.
+	*
+	* @param queryClient - The TanStack Query client instance
+	* @param params - The exact parameters used for this query
+	* @returns A function that when called invalidates the query
+	*
+	* @example
+	* ```ts
+	* const invalidate = getUser.invalidate(queryClient, { urlParams: { userId: '123' } })
+	* await invalidate() // Invalidates this specific query
+	* ```
+	*/
 	result.invalidate = (queryClient, params) => {
-		return queryClient.invalidateQueries({ queryKey: result.queryKey.dataTag(params) });
+		return () => queryClient.invalidateQueries({ queryKey: result.queryKey.dataTag(params) });
 	};
+	/**
+	* Creates a function that invalidates all queries matching the URL pattern.
+	* Useful for invalidating all queries for a resource regardless of query params.
+	*
+	* @param queryClient - The TanStack Query client instance
+	* @param params - URL parameters only (query params are ignored for matching)
+	* @returns A function that when called invalidates all matching queries
+	*
+	* @example
+	* ```ts
+	* const invalidateAll = getUserPosts.invalidateAll(queryClient, { urlParams: { userId: '123' } })
+	* await invalidateAll() // Invalidates all getUserPosts queries for user 123
+	* ```
+	*/
 	result.invalidateAll = (queryClient, params) => {
-		return queryClient.invalidateQueries({
+		return () => queryClient.invalidateQueries({
 			queryKey: result.queryKey.filterKey(params),
 			exact: false
 		});
@@ -136,22 +198,54 @@ function makeInfiniteQueryOptions(endpoint, options, baseQuery = {}) {
 			},
 			getNextPageParam: options.getNextPageParam,
 			getPreviousPageParam: options.getPreviousPageParam,
-			initialPageParam: options.initialPageParam ?? config.querySchema.parse("params" in params ? params.params : {}),
+			initialPageParam: options.initialPageParam ?? config.querySchema?.parse("params" in params ? params.params : {}) ?? ("params" in params ? params.params : {}),
 			...baseQuery
 		});
 	};
+	/** The query key creator for this infinite query endpoint */
 	res.queryKey = queryKey;
+	/**
+	* React hook that executes the infinite query.
+	* Uses `useInfiniteQuery` from TanStack Query internally.
+	*
+	* @param params - URL parameters and initial query parameters
+	* @returns Infinite query result with pages, fetchNextPage, etc.
+	*/
 	res.use = (params) => {
 		return useInfiniteQuery(res(params));
 	};
+	/**
+	* React hook that executes the infinite query with Suspense support.
+	* Uses `useSuspenseInfiniteQuery` from TanStack Query internally.
+	* The component will suspend while loading and throw on error.
+	*
+	* @param params - URL parameters and initial query parameters
+	* @returns Infinite query result with pages guaranteed to be defined
+	*/
 	res.useSuspense = (params) => {
 		return useSuspenseInfiniteQuery(res(params));
 	};
+	/**
+	* Creates a function that invalidates this specific infinite query in the cache.
+	* Call the returned function to trigger the invalidation.
+	*
+	* @param queryClient - The TanStack Query client instance
+	* @param params - The exact parameters used for this query
+	* @returns A function that when called invalidates the query
+	*/
 	res.invalidate = (queryClient, params) => {
-		return queryClient.invalidateQueries({ queryKey: res.queryKey.dataTag(params) });
+		return () => queryClient.invalidateQueries({ queryKey: res.queryKey.dataTag(params) });
 	};
+	/**
+	* Creates a function that invalidates all infinite queries matching the URL pattern.
+	* Useful for invalidating all queries for a resource regardless of query params.
+	*
+	* @param queryClient - The TanStack Query client instance
+	* @param params - URL parameters only (query params are ignored for matching)
+	* @returns A function that when called invalidates all matching queries
+	*/
 	res.invalidateAll = (queryClient, params) => {
-		return queryClient.invalidateQueries({
+		return () => queryClient.invalidateQueries({
 			queryKey: res.queryKey.filterKey(params),
 			exact: false
 		});
@@ -159,6 +253,179 @@ function makeInfiniteQueryOptions(endpoint, options, baseQuery = {}) {
 	return res;
 }
 
+//#endregion
+//#region src/query/prefetch.mts
+/**
+* Creates a type-safe prefetch helper for SSR/RSC.
+*
+* This utility wraps a query options creator to provide convenient
+* methods for server-side data fetching and hydration.
+*
+* @param queryOptionsCreator - A function that creates query options (from client.query())
+* @returns A prefetch helper object with prefetch, ensureData, and getQueryOptions methods
+*
+* @example
+* ```tsx
+* // 1. Create your query
+* const getUserQuery = client.query({
+*   method: 'GET',
+*   url: '/users/$userId',
+*   responseSchema: userSchema,
+* })
+*
+* // 2. Create prefetch helper
+* const userPrefetch = createPrefetchHelper(getUserQuery)
+*
+* // 3. Use in server component
+* async function UserPage({ userId }: { userId: string }) {
+*   const queryClient = new QueryClient()
+*
+*   await userPrefetch.prefetch(queryClient, {
+*     urlParams: { userId },
+*   })
+*
+*   return (
+*     <HydrationBoundary state={dehydrate(queryClient)}>
+*       <UserProfile userId={userId} />
+*     </HydrationBoundary>
+*   )
+* }
+* ```
+*
+* @example
+* ```tsx
+* // With Next.js App Router
+* import { dehydrate, HydrationBoundary, QueryClient } from '@tanstack/react-query'
+* import { createPrefetchHelper } from '@navios/react-query'
+*
+* // Define queries
+* const getPostsQuery = client.query({
+*   method: 'GET',
+*   url: '/posts',
+*   querySchema: z.object({ page: z.number() }),
+*   responseSchema: postsSchema,
+* })
+*
+* const postsPrefetch = createPrefetchHelper(getPostsQuery)
+*
+* // Server Component
+* export default async function PostsPage() {
+*   const queryClient = new QueryClient()
+*
+*   await postsPrefetch.prefetch(queryClient, {
+*     params: { page: 1 },
+*   })
+*
+*   return (
+*     <HydrationBoundary state={dehydrate(queryClient)}>
+*       <PostsList />
+*     </HydrationBoundary>
+*   )
+* }
+* ```
+*/
+function createPrefetchHelper(queryOptionsCreator) {
+	return {
+		prefetch: async (queryClient, params) => {
+			const options = queryOptionsCreator(params);
+			await queryClient.prefetchQuery(options);
+		},
+		ensureData: async (queryClient, params) => {
+			const options = queryOptionsCreator(params);
+			return queryClient.ensureQueryData(options);
+		},
+		getQueryOptions: (params) => {
+			return queryOptionsCreator(params);
+		},
+		prefetchMany: async (queryClient, paramsList) => {
+			await Promise.all(paramsList.map((params) => {
+				const options = queryOptionsCreator(params);
+				return queryClient.prefetchQuery(options);
+			}));
+		}
+	};
+}
+/**
+* Creates multiple prefetch helpers from a record of query options creators.
+*
+* Useful when you have multiple queries that need to be prefetched together.
+*
+* @param queries - Record of query options creator functions
+* @returns Record of prefetch helpers with the same keys
+*
+* @example
+* ```tsx
+* // Define all your queries
+* const queries = {
+*   user: client.query({
+*     method: 'GET',
+*     url: '/users/$userId',
+*     responseSchema: userSchema,
+*   }),
+*   posts: client.query({
+*     method: 'GET',
+*     url: '/users/$userId/posts',
+*     responseSchema: postsSchema,
+*   }),
+* }
+*
+* // Create all prefetch helpers at once
+* const prefetchers = createPrefetchHelpers(queries)
+*
+* // Use in server component
+* async function UserPage({ userId }: { userId: string }) {
+*   const queryClient = new QueryClient()
+*
+*   await Promise.all([
+*     prefetchers.user.prefetch(queryClient, { urlParams: { userId } }),
+*     prefetchers.posts.prefetch(queryClient, { urlParams: { userId } }),
+*   ])
+*
+*   return (
+*     <HydrationBoundary state={dehydrate(queryClient)}>
+*       <UserProfileWithPosts userId={userId} />
+*     </HydrationBoundary>
+*   )
+* }
+* ```
+*/
+function createPrefetchHelpers(queries) {
+	const result = {};
+	for (const key of Object.keys(queries)) result[key] = createPrefetchHelper(queries[key]);
+	return result;
+}
+/**
+* Prefetch multiple queries from different query creators in parallel.
+*
+* @param queryClient - The QueryClient instance
+* @param prefetches - Array of { helper, params } objects
+* @returns Promise that resolves when all prefetches complete
+*
+* @example
+* ```tsx
+* const userPrefetch = createPrefetchHelper(getUserQuery)
+* const postsPrefetch = createPrefetchHelper(getPostsQuery)
+*
+* async function DashboardPage({ userId }: { userId: string }) {
+*   const queryClient = new QueryClient()
+*
+*   await prefetchAll(queryClient, [
+*     { helper: userPrefetch, params: { urlParams: { userId } } },
+*     { helper: postsPrefetch, params: { urlParams: { userId }, params: { limit: 10 } } },
+*   ])
+*
+*   return (
+*     <HydrationBoundary state={dehydrate(queryClient)}>
+*       <Dashboard userId={userId} />
+*     </HydrationBoundary>
+*   )
+* }
+* ```
+*/
+async function prefetchAll(queryClient, prefetches) {
+	await Promise.all(prefetches.map(({ helper, params }) => helper.prefetch(queryClient, params)));
+}
+
 //#endregion
 //#region src/mutation/key-creator.mts
 /**
@@ -199,16 +466,6 @@ const mutationKeyCreator = createMutationKey;
 
 //#endregion
 //#region src/mutation/make-hook.mts
-/**
-* Creates a mutation hook for a given endpoint.
-*
-* Returns a function that when called returns a TanStack Query mutation result.
-* The returned function also has helper methods attached (mutationKey, useIsMutating).
-*
-* @param endpoint - The navios endpoint to create a mutation hook for
-* @param options - Mutation configuration including processResponse and callbacks
-* @returns A hook function that returns mutation result with attached helpers
-*/
 function makeMutation(endpoint, options) {
 	const config = endpoint.config;
 	const mutationKey = createMutationKey(config, {
@@ -257,23 +514,178 @@ function makeMutation(endpoint, options) {
 	};
 	result.useIsMutating = (keyParams) => {
 		if (!options.useKey) throw new Error("useIsMutating can only be used when useKey is set to true");
-		return useIsMutating({ mutationKey: mutationKey({ urlParams: keyParams }) }) > 0;
+		return useIsMutating({ mutationKey: mutationKey(keyParams) }) > 0;
 	};
 	result.mutationKey = mutationKey;
 	return result;
 }
 
+//#endregion
+//#region src/mutation/optimistic.mts
+/**
+* Creates type-safe optimistic update callbacks for mutations.
+*
+* This helper generates the onMutate, onError, and onSettled callbacks
+* that implement the standard optimistic update pattern:
+*
+* 1. onMutate: Cancel refetches, snapshot cache, apply optimistic update
+* 2. onError: Rollback cache to previous value on failure
+* 3. onSettled: Invalidate query to refetch fresh data
+*
+* @experimental This API is experimental and may change in future versions.
+* Use with caution in production code.
+*
+* @param config - Configuration for the optimistic update
+* @returns Object containing onMutate, onError, and onSettled callbacks
+*
+* @example
+* ```ts
+* // Create a mutation with optimistic updates
+* const updateUser = client.mutation({
+*   method: 'PATCH',
+*   url: '/users/$userId',
+*   requestSchema: updateUserSchema,
+*   responseSchema: userSchema,
+*   processResponse: (data) => data,
+*   ...createOptimisticUpdate({
+*     queryKey: ['users', userId],
+*     updateFn: (oldData, variables) => ({
+*       ...oldData,
+*       ...variables.data,
+*     }),
+*   }),
+* })
+* ```
+*
+* @example
+* ```ts
+* // Optimistic update for adding an item to a list
+* const addTodo = client.mutation({
+*   method: 'POST',
+*   url: '/todos',
+*   requestSchema: createTodoSchema,
+*   responseSchema: todoSchema,
+*   processResponse: (data) => data,
+*   ...createOptimisticUpdate({
+*     queryKey: ['todos'],
+*     updateFn: (oldData, variables) => [
+*       ...(oldData ?? []),
+*       { id: 'temp-id', ...variables.data, createdAt: new Date() },
+*     ],
+*   }),
+* })
+* ```
+*
+* @example
+* ```ts
+* // Optimistic delete
+* const deleteTodo = client.mutation({
+*   method: 'DELETE',
+*   url: '/todos/$todoId',
+*   responseSchema: z.object({ success: z.boolean() }),
+*   processResponse: (data) => data,
+*   ...createOptimisticUpdate({
+*     queryKey: ['todos'],
+*     updateFn: (oldData, variables) =>
+*       (oldData ?? []).filter((t) => t.id !== variables.urlParams.todoId),
+*   }),
+* })
+* ```
+*/
+function createOptimisticUpdate(config) {
+	const { queryKey, updateFn, rollbackOnError = true, invalidateOnSettled = true } = config;
+	return {
+		onMutate: async (variables, context) => {
+			await context.queryClient.cancelQueries({ queryKey });
+			const previousData = context.queryClient.getQueryData(queryKey);
+			context.queryClient.setQueryData(queryKey, (old) => updateFn(old, variables));
+			return { previousData };
+		},
+		onError: (_err, _variables, context) => {
+			if (rollbackOnError && context?.previousData !== void 0) context.queryClient.setQueryData(queryKey, context.previousData);
+		},
+		onSettled: (_data, _error, _variables, context) => {
+			if (invalidateOnSettled) context.queryClient.invalidateQueries({ queryKey });
+		}
+	};
+}
+/**
+* Creates optimistic update callbacks that work with multiple query keys.
+*
+* Useful when a mutation affects multiple cached queries.
+*
+* @experimental This API is experimental and may change in future versions.
+* Use with caution in production code.
+*
+* @param configs - Array of optimistic update configurations
+* @returns Combined callbacks that handle all specified queries
+*
+* @example
+* ```ts
+* // Updating a user affects both user detail and user list queries
+* const updateUser = client.mutation({
+*   method: 'PATCH',
+*   url: '/users/$userId',
+*   requestSchema: updateUserSchema,
+*   responseSchema: userSchema,
+*   processResponse: (data) => data,
+*   ...createMultiOptimisticUpdate([
+*     {
+*       queryKey: ['users', userId],
+*       updateFn: (oldData, variables) => ({ ...oldData, ...variables.data }),
+*     },
+*     {
+*       queryKey: ['users'],
+*       updateFn: (oldList, variables) =>
+*         (oldList ?? []).map((u) =>
+*           u.id === userId ? { ...u, ...variables.data } : u
+*         ),
+*     },
+*   ]),
+* })
+* ```
+*/
+function createMultiOptimisticUpdate(configs) {
+	return {
+		onMutate: async (variables, context) => {
+			const previousData = /* @__PURE__ */ new Map();
+			for (const config of configs) {
+				await context.queryClient.cancelQueries({ queryKey: config.queryKey });
+				const key = JSON.stringify(config.queryKey);
+				previousData.set(key, context.queryClient.getQueryData(config.queryKey));
+				context.queryClient.setQueryData(config.queryKey, (old) => config.updateFn(old, variables));
+			}
+			return { previousData };
+		},
+		onError: (_err, _variables, context) => {
+			if (context?.previousData) {
+				for (const config of configs) if (config.rollbackOnError !== false) {
+					const key = JSON.stringify(config.queryKey);
+					const previous = context.previousData.get(key);
+					if (previous !== void 0) context.queryClient.setQueryData(config.queryKey, previous);
+				}
+			}
+		},
+		onSettled: (_data, _error, _variables, context) => {
+			for (const config of configs) if (config.invalidateOnSettled !== false) context.queryClient.invalidateQueries({ queryKey: config.queryKey });
+		}
+	};
+}
+
 //#endregion
 //#region src/client/declare-client.mts
 /**
 * Creates a client instance for making type-safe queries and mutations.
 *
+* @template UseDiscriminator - When `true`, errors are returned as union types.
+*   When `false` (default), errors are thrown and not included in TData.
+*
 * @param options - Client configuration including the API builder and defaults
 * @returns A client instance with query, infiniteQuery, and mutation methods
 *
 * @example
 * ```typescript
-* const api = createBuilder({ baseUrl: '/api' });
+* const api = builder({});
 * const client = declareClient({ api });
 *
 * const getUser = client.query({
@@ -293,7 +705,8 @@ function declareClient({ api, defaults = {} }) {
 			url: config.url,
 			querySchema: config.querySchema,
 			requestSchema: config.requestSchema,
-			responseSchema: config.responseSchema
+			responseSchema: config.responseSchema,
+			errorSchema: config.errorSchema
 		});
 		const queryOptions$1 = makeQueryOptions(endpoint, {
 			...defaults,
@@ -314,7 +727,8 @@ function declareClient({ api, defaults = {} }) {
 			url: config.url,
 			querySchema: config.querySchema,
 			requestSchema: config.requestSchema,
-			responseSchema: config.responseSchema
+			responseSchema: config.responseSchema,
+			errorSchema: config.errorSchema
 		});
 		const infiniteQueryOptions$1 = makeInfiniteQueryOptions(endpoint, {
 			...defaults,
@@ -341,13 +755,16 @@ function declareClient({ api, defaults = {} }) {
 			url: config.url,
 			querySchema: config.querySchema,
 			requestSchema: config.requestSchema,
-			responseSchema: config.responseSchema
+			responseSchema: config.responseSchema,
+			errorSchema: config.errorSchema
 		});
 		const useMutation$1 = makeMutation(endpoint, {
 			processResponse: config.processResponse ?? ((data) => data),
 			useContext: config.useContext,
+			onMutate: config.onMutate,
 			onSuccess: config.onSuccess,
 			onError: config.onError,
+			onSettled: config.onSettled,
 			useKey: config.useKey,
 			meta: config.meta,
 			...defaults
@@ -374,7 +791,8 @@ function declareClient({ api, defaults = {} }) {
 			url: config.url,
 			querySchema: config.querySchema,
 			requestSchema: config.requestSchema,
-			responseSchema: config.responseSchema
+			responseSchema: config.responseSchema,
+			errorSchema: config.errorSchema
 		});
 		const useMutation$1 = makeMutation(endpoint, {
 			processResponse: config.processResponse ?? ((data) => data),
@@ -401,5 +819,5 @@ function declareClient({ api, defaults = {} }) {
 }
 
 //#endregion
-export { createMutationKey, createQueryKey, declareClient, makeInfiniteQueryOptions, makeMutation, makeQueryOptions, mutationKeyCreator, queryKeyCreator };
+export { createMultiOptimisticUpdate, createMutationKey, createOptimisticUpdate, createPrefetchHelper, createPrefetchHelpers, createQueryKey, declareClient, makeInfiniteQueryOptions, makeMutation, makeQueryOptions, mutationKeyCreator, prefetchAll, queryKeyCreator };
 //# sourceMappingURL=index.mjs.map