Open History to see the last commit
1// Writes docs/errors.md, the page production error messages link to. Each
2// coded error class gets an `error-<code>` anchor and its development messages
3// for the sample inputs in packages/db/tests/error-sample-arguments.ts. Each
4// coded error site, a plain Error thrown elsewhere, gets an anchor, its source
5// file, and its message template.
6// With `--check`, it fails instead of writing when the page is out of date.
7// packages/db/tests/production-error-messages-oracle.test.ts checks the headings.
8import { readFile, writeFile } from 'node:fs/promises'
9import path from 'node:path'
10import { fileURLToPath } from 'node:url'
11
12const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
13const fixtures = path.join(root, 'packages/db/tests/fixtures')
14const read = async (name) =>
15 JSON.parse(await readFile(path.join(fixtures, name), 'utf8'))
16const codes = await read('error-codes.json')
17const messages = await read('error-messages.json')
18const sites = await read('error-site-messages.json')
19
20const sections = Object.entries(codes).map(
21 ([name, code]) => `<a id="error-${code}"></a>
22
23## Error ${code}: \`${name}\`
24
25Development builds show the full message. For example:
26
27${messages[name].map((message) => `\`\`\`text\n${message}\n\`\`\`\n`).join('\n')}`,
28)
29
30const siteSections = Object.entries(sites).map(
31 ([code, { file, template, kind = 'error' }]) => `<a id="${kind}-${code}"></a>
32
33## ${kind === 'warning' ? 'Warning' : 'Error'} ${code}: \`${file}\`
34
35Development builds show this message, with \`\${...}\` replaced by values:
36
37\`\`\`text
38${template}
39\`\`\`
40`,
41)
42
43const pagePath = path.join(root, 'docs/errors.md')
44const page = `---
45title: Error Codes
46id: errors
47---
48
49<!-- Generated by scripts/generate-error-docs.mjs. Do not edit by hand. -->
50
51Production builds of TanStack DB shorten error messages to a code, the inputs
52that the error can show, and a link to this page. For example:
53
54\`\`\`text
55TanStack DB error 17 (key=1, collectionId="todos"): https://tanstack.com/db/latest/docs/errors#error-17
56\`\`\`
57
58A console warning uses the same form with \`warning\` in place of \`error\`.
59Development builds keep the full messages below. The error classes, their
60\`name\` values, and their fields are the same in both builds. See
61[Error Handling](./guides/error-handling.md) for how to catch them.
62
63${sections.join('\n')}
64## Other errors and log messages
65
66These are plain \`Error\`, \`TypeError\`, \`RangeError\`, or
67\`AggregateError\` values, and \`console\` messages about runtime failures.
68Each heading names the source file under \`packages/db/src\` that writes it.
69
70${siteSections.join('\n')}`
71
72if (process.argv.includes('--check')) {
73 const current = await readFile(pagePath, 'utf8').catch(() => '')
74 if (current !== page) {
75 console.error(
76 'docs/errors.md is out of date; run node scripts/generate-error-docs.mjs',
77 )
78 process.exit(1)
79 }
80} else {
81 await writeFile(pagePath, page)
82}