improve docs

Author: KurtGokhan

examples/vite/src/client.tsx

@@ -1,4 +1,8 @@
 import { QueryClient } from '@tanstack/react-query';
+import { getMockHandlers } from 'tanstack-query-builder-example-mocks';
+import { setupMSW } from 'tanstack-query-builder-example-mocks/setup-msw';
+
+await setupMSW(...getMockHandlers()).start({ onUnhandledRequest: 'bypass', quiet: true, waitUntilReady: true });
 
 export const queryClient = new QueryClient({
   defaultOptions: {

examples/vite/src/examples/main/example.tsx

@@ -1,10 +1,7 @@
 import { queryClient } from 'src/client';
-import { ArticleData, CommentData, baseUrl, getMockHandlers } from 'tanstack-query-builder-example-mocks';
-import { setupMSW } from 'tanstack-query-builder-example-mocks/setup-msw';
+import { ArticleData, CommentData, baseUrl } from 'tanstack-query-builder-example-mocks';
 import { HttpQueryBuilder } from 'tanstack-query-builder/http';
 
-await setupMSW(...getMockHandlers()).start({ onUnhandledRequest: 'bypass', quiet: true, waitUntilReady: true });
-
 export const builder = new HttpQueryBuilder().withClient(queryClient).withBaseUrl(baseUrl).withTagTypes<{
   article: ArticleData;
   articles: ArticleData[];

examples/vite/src/examples/main/list.tsx

@@ -1,11 +1,8 @@
-import { QueryClientProvider } from '@tanstack/react-query';
-import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
 import { useNavigate } from '@tanstack/react-router';
 import { useState } from 'react';
-import { queryClient } from '../../client';
 import { articleQuery, articlesQuery, builder, commentsQuery, deleteArticleMutation, resetMutation } from './example';
 
-function AppCore() {
+export function MainExample() {
   const [enablePrefetch, setEnablePrefetch] = useState(false);
   const nav = useNavigate();
 
@@ -82,12 +79,3 @@ function AppCore() {
     </>
   );
 }
-
-export function MainExample() {
-  return (
-    <QueryClientProvider client={queryClient}>
-      <AppCore />
-      <ReactQueryDevtools initialIsOpen={false} />
-    </QueryClientProvider>
-  );
-}

examples/vite/src/main.tsx

@@ -1,10 +1,21 @@
+import './index.css';
+
+import { QueryClientProvider } from '@tanstack/react-query';
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools';
 import { StrictMode } from 'react';
 import { createRoot } from 'react-dom/client';
-import './index.css';
+import { queryClient } from './client';
 import { AppRouter } from './router';
 
 const rootElement = document.getElementById('root')!;
 if (!rootElement.innerHTML) {
   const root = createRoot(rootElement);
-  root.render(<StrictMode children={<AppRouter />} />);
+  root.render(
+    <StrictMode>
+      <QueryClientProvider client={queryClient}>
+        <AppRouter />
+        <ReactQueryDevtools initialIsOpen={false} />
+      </QueryClientProvider>
+    </StrictMode>,
+  );
 }

examples/vite/tests/Render.test.tsx

@@ -1,3 +1,4 @@
+import { QueryClientProvider } from '@tanstack/react-query';
 import { createMemoryHistory } from '@tanstack/react-router';
 import { queryClient } from 'src/client';
 import { AppRouter } from 'src/router';
@@ -9,7 +10,11 @@ import '../src/index.css';
 import 'src/examples/main/example';
 
 const history = createMemoryHistory({ initialEntries: ['/main'] });
-const TestRenderer = () => <AppRouter history={history} />;
+const TestRenderer = () => (
+  <QueryClientProvider client={queryClient}>
+    <AppRouter history={history} />
+  </QueryClientProvider>
+);
 
 beforeEach(async () => {
   await fetch(`${baseUrl}/reset`, { method: 'POST' });

packages/tanstack-query-builder/src/builder/QueryBuilder.ts

@@ -19,6 +19,11 @@ export class QueryBuilder<
   TTags extends Record<string, unknown>,
   TFlags extends BuilderFlags = '',
 > extends QueryBuilderFrozen<TVars, TData, TError, TKey, TTags, TFlags> {
+  /**
+   * Declares the type of variables of the query.
+   * Optionally, you can pass the first argument to set the default variables,
+   * which will be merged with the variables passed to the query.
+   */
   withVars<TVars$ = TVars, const TReset extends boolean = false>(
     vars?: TVars$,
     resetVars = false as TReset,
@@ -30,21 +35,39 @@ export class QueryBuilder<
     }) as any;
   }
 
+  /**
+   * Declares the type of returned data of the query.
+   */
   withData<TData$>(): QueryBuilder<TVars, TData$, TError, TKey, TTags, TFlags> {
     return this as any;
   }
 
+  /**
+   * Declares the type of error of the query.
+   */
   withError<TError$>(): QueryBuilder<TVars, TData, TError$, TKey, TTags, TFlags> {
     return this as any;
   }
 
+  /**
+   * Creates a new query builder with additional config.
+   */
   withConfig(config: Partial<typeof this.config>): this {
     const ctor = this.constructor as typeof QueryBuilder;
     const newConfig = this.mergeConfigs(this.config, config);
     return new ctor(newConfig) as this;
   }
 
+  /**
+   * Adds a preprocessor function to the query.
+   * The preprocessor function is called before the query function is called.
+   */
   withPreprocessor(preprocessor: PreprocessorFn<TVars, TVars>): this;
+
+  /**
+   * Adds a preprocessor function to the query with a different type of input variables.
+   * The preprocessor function is called before the query function is called.
+   */
   withPreprocessor<TVars$ = TVars>(preprocessor: PreprocessorFn<TVars$, TVars>): QueryBuilder<TVars$, TData, TError, TKey, TTags, TFlags>;
 
   withPreprocessor<TVars$ = TVars>(preprocessor: PreprocessorFn<TVars$, TVars>): QueryBuilder<TVars$, TData, TError, TKey, TTags, TFlags> {
@@ -55,7 +78,18 @@ export class QueryBuilder<
     });
   }
 
+  /**
+   * Adds a middleware function to the query.
+   * The middleware function wraps the query function and
+   * can be used to modify the input variables, the output data, or the error.
+   */
   withMiddleware(middleware: MiddlewareFn<TVars, TData, TError, TKey>): this;
+
+  /**
+   * Adds a middleware function to the query with overloaded types.
+   * The middleware function wraps the query function and
+   * can be used to modify the input variables, the output data, or the error.
+   */
   withMiddleware<TVars$ = TVars, TData$ = TData, TError$ = TError>(
     middleware: MiddlewareFn<TVars$, TData$, TError$, TKey>,
   ): QueryBuilder<TVars$, TData$, TError$, TKey, TTags, TFlags>;
@@ -74,20 +108,39 @@ export class QueryBuilder<
 
   static tagCacheId = 0;
 
+  /**
+   * Adds a tag to the query.
+   * The tag is used to invalidate or update the query when the tag is updated.
+   */
   withTags(...tags: QueryTagOption<TVars, TData, TError, QueryTagObject<TTags>>[]): this {
     return this.withMiddleware(createTagMiddleware(tags.flat(), QueryBuilder.tagCacheId++)) as unknown as this;
   }
 
+  /**
+   * Adds a declarative update to the mutation.
+   * This is used to invalidate or update the queries that were marked with {@link withTags}.
+   */
   withUpdates(...tags: QueryTagOption<TVars, TData, TError, QueryUpdateTagObject<TVars, TData, TError, TTags>>[]): this {
     return this.withMiddleware(createUpdateMiddleware<TVars, TData, TError, TKey, TTags>(tags)) as unknown as this;
   }
 
   withTagTypes<TTag extends string, T = unknown>(): QueryBuilder<TVars, TData, TError, TKey, TTags & Record<TTag, T>, TFlags>;
   withTagTypes<TTags$ extends Record<string, unknown>>(): QueryBuilder<TVars, TData, TError, TKey, TTags$, TFlags>;
+
+  /**
+   * Declares the type of tags of the query.
+   * This is used to strongly type the tags which can be helpful when using {@link withUpdates}.
+   */
   withTagTypes(): this {
     return this as any;
   }
 
+  /**
+   * Sets the query client for this builder.
+   * This is required in order to enable {@link client} and {@link tags} interfaces.
+   * Imperative operations done through those interfaces will be done with the provided query client.
+   * This method also enables the ability to sync tag invalidation with other browser tabs.
+   */
   withClient(
     queryClient: QueryClient,
     { syncTagsWithOtherTabs = true }: { syncTagsWithOtherTabs?: boolean } = {},
@@ -105,16 +158,26 @@ export class QueryBuilder<
     return this.withConfig({ queryClient, syncChannel }) as any;
   }
 
+  /**
+   * Adds pagination to the query. This is required for methods like {@link useInfiniteQuery} to be available.
+   */
   withPagination(
     paginationOptions: BuilderPaginationOptions<TVars, TData, TError, TKey>,
   ): QueryBuilder<TVars, TData, TError, TKey, TTags, TFlags | 'withPagination'> {
     return this.withConfig({ paginationOptions } as TODO);
   }
 
+  /**
+   * Returns a frozen version of this builder.
+   * The frozen version cannot be modified using `with*` methods.
+   */
   asFrozen(): QueryBuilderFrozen<TVars, TData, TError, TKey, TTags, TFlags> {
     return this as any;
   }
 
+  /**
+   * Binds all query methods to this class instance, so that they can be called after object destructuring.
+   */
   asBound(): QueryBuilder<TVars, TData, TError, TKey, TTags, TFlags | 'bound'> {
     return this.withConfig({ bound: true });
   }

packages/tanstack-query-builder/src/http/HttpQueryBuilder.ts

@@ -8,6 +8,11 @@ import type { HttpBaseHeaders, HttpBaseParams, HttpBaseSearch, HttpBuilderVars }
 import { createHttpMergeVarsFn, createHttpQueryFn, createHttpQueryKeySanitizer } from './builder-utils';
 import type { ExtractPathParams, HttpMethod } from './request-types';
 
+/**
+ * A builder for creating HTTP queries.
+ * It allows you to define the path parameters, search parameters, body, headers, and metadata.
+ * It also provides methods for setting the base URL, HTTP method, and other options.
+ */
 export class HttpQueryBuilder<
   TParam = unknown,
   TSearch = unknown,
@@ -29,37 +34,64 @@ export class HttpQueryBuilder<
     super({ mergeVars, queryFn, queryKeySanitizer, ...config });
   }
 
+  /**
+   * Defines the type of body of the request.
+   * Optionally, you can pass the first argument to set the default body.
+   */
   withBody<TBody$>(body?: TBody$): HttpQueryBuilder<TParam, TSearch, TBody$, THeader, TMeta, TData, TError, TTags, TFlags> {
     if (!body) return this as any;
     return this.withVars({ body }) as any;
   }
 
+  /**
+   * Defines the type of headers of the request.
+   * Optionally, you can pass the first argument to set the default headers.
+   */
   withHeaders<THeaders$ extends HttpBaseHeaders>(
     headers?: THeaders$,
   ): HttpQueryBuilder<TParam, TSearch, TBody, THeaders$, TMeta, TData, TError, TTags, TFlags> {
     if (!headers) return this as any;
     return this.withVars({ headers }) as any;
   }
 
+  /**
+   * Defines the type of path parameters of the request.
+   * Optionally, you can pass the first argument to set the default parameters.
+   * Note that when {@link withPath} is used, the path parameters are automatically extracted.
+   * This method doesn't have to be used in that case.
+   */
   withParams<TParams$ extends HttpBaseParams>(
     params?: TParams$,
   ): HttpQueryBuilder<TParams$, TSearch, TBody, THeader, TMeta, TData, TError, TTags, TFlags> {
     if (!params) return this as any;
     return this.withVars({ params }) as any;
   }
 
+  /**
+   * Defines the type of search parameters of the request.
+   * Optionally, you can pass the first argument to set the default search parameters.
+   */
   withSearch<TSearch$ extends HttpBaseSearch>(
     search?: TSearch$,
   ): HttpQueryBuilder<TParam, TSearch$, TBody, THeader, TMeta, TData, TError, TTags, TFlags> {
     if (!search) return this as any;
     return this.withVars({ search }) as any;
   }
 
+  /**
+   * Defines the type of metadata of the request.
+   * Optionally, you can pass the first argument to set the default metadata.
+   */
   withMeta<TMeta$>(meta?: TMeta$): HttpQueryBuilder<TParam, TSearch, TBody, THeader, TMeta$, TData, TError, TTags, TFlags> {
     if (!meta) return this as any;
     return this.withVars({ meta }) as any;
   }
 
+  /**
+   * Sets the path for the HTTP request.
+   * The path can contain path parameters which are defined with the format `/path/:param1/:param2`.
+   * The path parameters are automatically extracted and typed strongly as if declared with {@link withParams}.
+   */
   withPath<const TPath$ extends string>(
     path: TPath$,
   ): ExtractPathParams<TPath$> extends void
@@ -68,10 +100,19 @@ export class HttpQueryBuilder<
     return this.withVars({ path }) as any;
   }
 
+  /**
+   * Sets the base URL for the HTTP request.
+   * The base URL will be prepended to relative URLs.
+   */
   withBaseUrl(baseUrl: string): this {
     return this.withVars({ baseUrl }) as any;
   }
 
+  /**
+   * SSets the HTTP method for the request.
+   * The method can be one of the following: `get`, `post`, `put`, `patch`, `delete`, `options`, `head`.
+   * The default method is `get`.
+   */
   withMethod(method: HttpMethod): this {
     return this.withVars({ method }) as any;
   }

website/docs/api/_category_.json

@@ -0,0 +1,6 @@
+{
+  "position": 100,
+  "label": "API Reference",
+  "collapsible": false,
+  "collapsed": false
+}