Open History to see the last commit
1import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises'
2import { createRequire } from 'node:module'
3import { dirname, resolve } from 'node:path'
4import { fileURLToPath } from 'node:url'
5β
6const __dirname = fileURLToPath(new URL('.', import.meta.url))
7const require = createRequire(import.meta.url)
8const typedocConfigPackageJson =
9 require.resolve('@tanstack/typedoc-config/package.json')
10const typedocConfigDir = dirname(typedocConfigPackageJson)
11const typedocConfigRequire = createRequire(typedocConfigPackageJson)
12const TypeDoc = await import(typedocConfigRequire.resolve('typedoc'))
13β
14type PackageReferenceDocsConfig = {
15 entryPoints: Array<string>
16 tsconfig: string
17 outputDir: string
18 exclude?: Array<string>
19 excludeExternals?: boolean
20 simplifyLitQueriesControllerTypes?: boolean
21 trimGeneratedMarkdown?: boolean
22 // Maps a generated page's path (relative to outputDir, no extension) to the flat
23 // `docs/framework/<framework>/reference/<name>.md` URLs it replaced, so old links/bookmarks redirect
24 // instead of falling through to the framework docs index. See https://github.com/TanStack/query/issues/11371
25 redirectFrom?: Record<string, Array<string>>
26}
27β
28type TypeDocReflectionWithSignatures = {
29 name: string
30 children?: Array<TypeDocReflectionWithSignatures>
31 signatures?: Array<{
32 typeParameters?: Array<{
33 name: string
34 default?: unknown
35 }>
36 }>
37}
38β
39function simplifyLitQueriesControllerTypes(
40 project: TypeDocReflectionWithSignatures,
41) {
42 const stack: Array<TypeDocReflectionWithSignatures> = [project]
43β
44 for (const reflection of stack) {
45 stack.push(...(reflection.children ?? []))
46β
47 if (reflection.name !== 'createQueriesController') {
48 continue
49 }
50β
51 for (const signature of reflection.signatures ?? []) {
52 const combinedResult = signature.typeParameters?.find(
53 (typeParameter) => typeParameter.name === 'TCombinedResult',
54 )
55β
56 if (!combinedResult?.default) {
57 continue
58 }
59β
60 const queryOptionsType = TypeDoc.ReferenceType.createBrokenReference(
61 'TQueryOptions',
62 project,
63 undefined,
64 )
65 queryOptionsType.refersToTypeParameter = true
66β
67 // CreateQueriesResults is internal; render it as plain text, not a link.
68 const queriesResultsType = TypeDoc.ReferenceType.createBrokenReference(
69 'CreateQueriesResults',
70 project,
71 undefined,
72 )
73 queriesResultsType.typeArguments = [queryOptionsType]
74β
75 combinedResult.default = queriesResultsType
76 }
77 }
78}
79β
80async function trimTrailingWhitespaceInMarkdown(outputDir: string) {
81 const entries = await readdir(outputDir, { withFileTypes: true })
82β
83 await Promise.all(
84 entries.map(async (entry) => {
85 const path = resolve(outputDir, entry.name)
86β
87 if (entry.isDirectory()) {
88 await trimTrailingWhitespaceInMarkdown(path)
89 return
90 }
91β
92 if (!entry.isFile() || !path.endsWith('.md')) {
93 return
94 }
95β
96 const markdown = await readFile(path, 'utf8')
97 const trimmed = markdown.replace(/[ \t]+$/gm, '')
98β
99 if (trimmed !== markdown) {
100 await writeFile(path, trimmed)
101 }
102 }),
103 )
104}
105β
106async function addRedirectFromToFileFrontmatter(
107 filePath: string,
108 fromPaths: Array<string>,
109) {
110 const markdown = await readFile(filePath, 'utf8')
111β
112 const frontmatterMatch = markdown.match(/^---\n([\s\S]*?)\n---\n/)
113 if (!frontmatterMatch) {
114 throw new Error(`Expected frontmatter in ${filePath}`)
115 }
116β
117 const redirectLines = fromPaths
118 .map((fromPath) => ` - ${fromPath}`)
119 .join('\n')
120 const updatedFrontmatter = `---\n${frontmatterMatch[1]}\nredirect_from:\n${redirectLines}\n---\n`
121β
122 await writeFile(
123 filePath,
124 updatedFrontmatter + markdown.slice(frontmatterMatch[0].length),
125 )
126}
127β
128async function addRedirectFromToFrontmatter(
129 outputDir: string,
130 redirectFrom: Record<string, Array<string>>,
131) {
132 for (const [pagePath, fromPaths] of Object.entries(redirectFrom)) {
133 await addRedirectFromToFileFrontmatter(
134 resolve(outputDir, `${pagePath}.md`),
135 fromPaths,
136 )
137 }
138}
139β
140async function generatePackageReferenceDocs(pkg: PackageReferenceDocsConfig) {
141 const outputDir = pkg.outputDir
142 await rm(outputDir, { recursive: true, force: true })
143 await mkdir(outputDir, { recursive: true })
144β
145 const app = await TypeDoc.Application.bootstrapWithPlugins({
146 plugin: [
147 'typedoc-plugin-markdown',
148 'typedoc-plugin-frontmatter',
149 resolve(typedocConfigDir, './src/typedoc-custom-settings.js'),
150 ],
151 hideGenerator: true,
152 readme: 'none',
153 entryFileName: 'index',
154 hideBreadcrumbs: true,
155 hidePageHeader: true,
156 hidePageTitle: true,
157 useCodeBlocks: true,
158 // `parametersFormat` and `typeDeclarationFormat` are deliberately left as lists: the first
159 // inlines the huge conditional types of `useQueries` into a single cell and drops `@default`
160 // blocks, and the second collapses `@example` code blocks onto one line, which swallows the
161 // following statement into a `//` comment.
162 interfacePropertiesFormat: 'table',
163 typeAliasPropertiesFormat: 'table',
164 tableColumnSettings: {
165 hideInherited: true,
166 hideSources: true,
167 },
168 // Without this, a function property renders as `(data) => TData` β the table and list formats
169 // both omit the parameter types otherwise.
170 expandParameters: true,
171 excludePrivate: true,
172 excludeInternal: true,
173 excludeExternals: pkg.excludeExternals,
174 sourceLinkTemplate:
175 'https://github.com/TanStack/query/blob/{gitRevision}/{path}#L{line}',
176 gitRevision: 'main',
177 entryPoints: pkg.entryPoints,
178 tsconfig: pkg.tsconfig,
179 ...(pkg.exclude && { exclude: pkg.exclude }),
180 out: outputDir,
181 })
182β
183 const project = await app.convert()
184β
185 // `outputDir` was emptied above, so a failed conversion would otherwise leave it that way and
186 // look like every page was intentionally deleted. Fail loudly instead β TypeDoc reports the
187 // underlying diagnostics on stderr.
188 //
189 // The most likely cause is TS6305: `angular-query-experimental` reaches `@tanstack/query-devtools`
190 // through a TypeScript project reference, so it consumes that package's emitted `.d.ts` rather than
191 // its source (which is solid-js JSX and cannot be compiled under Angular's tsconfig). The
192 // `generate-docs` script builds it first, so this should only surface if that build was skipped.
193 if (!project) {
194 throw new Error(
195 `TypeDoc failed to convert ${pkg.entryPoints.join(', ')}. See the diagnostics above.`,
196 )
197 }
198β
199 if (pkg.simplifyLitQueriesControllerTypes) {
200 simplifyLitQueriesControllerTypes(project)
201 }
202β
203 await app.generateOutputs(project)
204β
205 if (pkg.trimGeneratedMarkdown) {
206 await trimTrailingWhitespaceInMarkdown(outputDir)
207 }
208β
209 if (pkg.redirectFrom) {
210 await addRedirectFromToFrontmatter(outputDir, pkg.redirectFrom)
211 }
212}
213β
214const packages: Array<PackageReferenceDocsConfig> = [
215 {
216 entryPoints: [
217 resolve(__dirname, '../packages/angular-query-experimental/src/index.ts'),
218 ],
219 tsconfig: resolve(
220 __dirname,
221 '../packages/angular-query-experimental/tsconfig.json',
222 ),
223 outputDir: resolve(__dirname, '../docs/framework/angular/reference'),
224 },
225 {
226 entryPoints: [resolve(__dirname, '../packages/svelte-query/src/index.ts')],
227 tsconfig: resolve(__dirname, '../packages/svelte-query/tsconfig.json'),
228 outputDir: resolve(__dirname, '../docs/framework/svelte/reference'),
229 },
230 {
231 entryPoints: [resolve(__dirname, '../packages/solid-query/src/index.ts')],
232 tsconfig: resolve(__dirname, '../packages/solid-query/tsconfig.json'),
233 outputDir: resolve(__dirname, '../docs/framework/solid/reference'),
234 redirectFrom: {
235 'functions/infiniteQueryOptions': [
236 'framework/solid/reference/infiniteQueryOptions',
237 ],
238 'functions/mutationOptions': [
239 'framework/solid/reference/mutationOptions',
240 ],
241 'functions/queryOptions': ['framework/solid/reference/queryOptions'],
242 'functions/useInfiniteQuery': [
243 'framework/solid/reference/useInfiniteQuery',
244 ],
245 'functions/useIsFetching': ['framework/solid/reference/useIsFetching'],
246 'functions/useIsMutating': ['framework/solid/reference/useIsMutating'],
247 'functions/useMutation': ['framework/solid/reference/useMutation'],
248 'functions/useMutationState': [
249 'framework/solid/reference/useMutationState',
250 ],
251 'functions/useQueries': ['framework/solid/reference/useQueries'],
252 'functions/useQuery': ['framework/solid/reference/useQuery'],
253 },
254 },
255 {
256 entryPoints: [resolve(__dirname, '../packages/vue-query/src/index.ts')],
257 tsconfig: resolve(__dirname, '../packages/vue-query/tsconfig.json'),
258 outputDir: resolve(__dirname, '../docs/framework/vue/reference'),
259 },
260 {
261 entryPoints: [resolve(__dirname, '../packages/react-query/src/index.ts')],
262 tsconfig: resolve(__dirname, '../packages/react-query/tsconfig.json'),
263 outputDir: resolve(__dirname, '../docs/framework/react/reference'),
264 redirectFrom: {
265 'functions/infiniteQueryOptions': [
266 'framework/react/reference/infiniteQueryOptions',
267 ],
268 'functions/mutationOptions': [
269 'framework/react/reference/mutationOptions',
270 ],
271 'functions/QueryClientProvider': [
272 'framework/react/reference/QueryClientProvider',
273 ],
274 'functions/QueryErrorResetBoundary': [
275 'framework/react/reference/QueryErrorResetBoundary',
276 ],
277 'functions/queryOptions': ['framework/react/reference/queryOptions'],
278 'functions/useInfiniteQuery': [
279 'framework/react/reference/useInfiniteQuery',
280 ],
281 'functions/useIsFetching': ['framework/react/reference/useIsFetching'],
282 'functions/useIsMutating': ['framework/react/reference/useIsMutating'],
283 'functions/useMutation': ['framework/react/reference/useMutation'],
284 'functions/useMutationState': [
285 'framework/react/reference/useMutationState',
286 ],
287 'functions/usePrefetchInfiniteQuery': [
288 'framework/react/reference/usePrefetchInfiniteQuery',
289 ],
290 'functions/usePrefetchQuery': [
291 'framework/react/reference/usePrefetchQuery',
292 ],
293 'functions/useQueries': ['framework/react/reference/useQueries'],
294 'functions/useQuery': ['framework/react/reference/useQuery'],
295 'functions/useQueryClient': ['framework/react/reference/useQueryClient'],
296 'functions/useQueryErrorResetBoundary': [
297 'framework/react/reference/useQueryErrorResetBoundary',
298 ],
299 'functions/useSuspenseInfiniteQuery': [
300 'framework/react/reference/useSuspenseInfiniteQuery',
301 ],
302 'functions/useSuspenseQueries': [
303 'framework/react/reference/useSuspenseQueries',
304 ],
305 'functions/useSuspenseQuery': [
306 'framework/react/reference/useSuspenseQuery',
307 ],
308 // Redirects from the legacy hand-written docs/reference/*.md pages, removed in favor of
309 // this generated reference.
310 'classes/QueryClient': [
311 'reference/QueryClient',
312 'framework/react/reference/QueryClient',
313 ],
314 'classes/QueryCache': [
315 'reference/QueryCache',
316 'framework/react/reference/QueryCache',
317 ],
318 'classes/MutationCache': [
319 'reference/MutationCache',
320 'framework/react/reference/MutationCache',
321 ],
322 'classes/QueryObserver': [
323 'reference/QueryObserver',
324 'framework/react/reference/QueryObserver',
325 ],
326 'classes/InfiniteQueryObserver': [
327 'reference/InfiniteQueryObserver',
328 'framework/react/reference/InfiniteQueryObserver',
329 ],
330 'classes/QueriesObserver': [
331 'reference/QueriesObserver',
332 'framework/react/reference/QueriesObserver',
333 ],
334 // focusManager/onlineManager/timeoutManager are class instances, not object literals, so
335 // TypeDoc can't inline their methods onto the `variables/*` instance page β the method docs
336 // that the legacy pages covered now live on the `interfaces/*` page for the class itself.
337 'interfaces/FocusManager': [
338 'reference/focusManager',
339 'framework/react/reference/focusManager',
340 ],
341 'interfaces/OnlineManager': [
342 'reference/onlineManager',
343 'framework/react/reference/onlineManager',
344 ],
345 'interfaces/TimeoutManager': ['reference/timeoutManager'],
346 'variables/notifyManager': [
347 'reference/notifyManager',
348 'framework/react/reference/notifyManager',
349 ],
350 'variables/environmentManager': ['reference/environmentManager'],
351 'functions/experimental_streamedQuery': ['reference/streamedQuery'],
352 },
353 },
354 {
355 entryPoints: [resolve(__dirname, '../packages/preact-query/src/index.ts')],
356 tsconfig: resolve(__dirname, '../packages/preact-query/tsconfig.json'),
357 outputDir: resolve(__dirname, '../docs/framework/preact/reference'),
358 },
359 {
360 entryPoints: [resolve(__dirname, '../packages/lit-query/src/index.ts')],
361 tsconfig: resolve(__dirname, '../packages/lit-query/tsconfig.json'),
362 outputDir: resolve(__dirname, '../docs/framework/lit/reference'),
363 excludeExternals: true,
364 simplifyLitQueriesControllerTypes: true,
365 trimGeneratedMarkdown: true,
366 },
367]
368β
369for (const pkg of packages) {
370 await generatePackageReferenceDocs(pkg)
371}
372β
373console.log('\nβ
All markdown files have been processed!')
374β
375process.exit(0)