bun-types 1.3.2-canary.20251105T140650 → 1.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (370) hide show
  1. package/bun.d.ts +102 -6
  2. package/docs/README.md +28 -0
  3. package/docs/bundler/bytecode.mdx +465 -0
  4. package/docs/bundler/{css.md → css.mdx} +97 -101
  5. package/docs/bundler/esbuild.mdx +253 -0
  6. package/docs/bundler/{executables.md → executables.mdx} +130 -221
  7. package/docs/bundler/fullstack.mdx +1064 -0
  8. package/docs/bundler/{hmr.md → hot-reloading.mdx} +74 -79
  9. package/docs/bundler/{html.md → html-static.mdx} +148 -111
  10. package/docs/bundler/index.mdx +1499 -0
  11. package/docs/bundler/loaders.mdx +356 -0
  12. package/docs/bundler/{macros.md → macros.mdx} +83 -84
  13. package/docs/bundler/minifier.mdx +1306 -0
  14. package/docs/bundler/plugins.mdx +411 -0
  15. package/docs/feedback.mdx +85 -0
  16. package/docs/guides/binary/{arraybuffer-to-array.md → arraybuffer-to-array.mdx} +3 -1
  17. package/docs/guides/binary/{arraybuffer-to-blob.md → arraybuffer-to-blob.mdx} +3 -1
  18. package/docs/guides/binary/{arraybuffer-to-buffer.md → arraybuffer-to-buffer.mdx} +3 -1
  19. package/docs/guides/binary/{arraybuffer-to-string.md → arraybuffer-to-string.mdx} +3 -1
  20. package/docs/guides/binary/{arraybuffer-to-typedarray.md → arraybuffer-to-typedarray.mdx} +3 -1
  21. package/docs/guides/binary/{blob-to-arraybuffer.md → blob-to-arraybuffer.mdx} +3 -1
  22. package/docs/guides/binary/{blob-to-dataview.md → blob-to-dataview.mdx} +3 -1
  23. package/docs/guides/binary/{blob-to-stream.md → blob-to-stream.mdx} +3 -1
  24. package/docs/guides/binary/{blob-to-string.md → blob-to-string.mdx} +3 -1
  25. package/docs/guides/binary/{blob-to-typedarray.md → blob-to-typedarray.mdx} +3 -1
  26. package/docs/guides/binary/{buffer-to-arraybuffer.md → buffer-to-arraybuffer.mdx} +3 -1
  27. package/docs/guides/binary/{buffer-to-blob.md → buffer-to-blob.mdx} +3 -1
  28. package/docs/guides/binary/{buffer-to-readablestream.md → buffer-to-readablestream.mdx} +3 -1
  29. package/docs/guides/binary/{buffer-to-string.md → buffer-to-string.mdx} +3 -1
  30. package/docs/guides/binary/{buffer-to-typedarray.md → buffer-to-typedarray.mdx} +3 -1
  31. package/docs/guides/binary/{dataview-to-string.md → dataview-to-string.mdx} +3 -1
  32. package/docs/guides/binary/{typedarray-to-arraybuffer.md → typedarray-to-arraybuffer.mdx} +3 -1
  33. package/docs/guides/binary/{typedarray-to-blob.md → typedarray-to-blob.mdx} +3 -1
  34. package/docs/guides/binary/{typedarray-to-buffer.md → typedarray-to-buffer.mdx} +3 -1
  35. package/docs/guides/binary/{typedarray-to-dataview.md → typedarray-to-dataview.mdx} +3 -1
  36. package/docs/guides/binary/{typedarray-to-readablestream.md → typedarray-to-readablestream.mdx} +3 -1
  37. package/docs/guides/binary/{typedarray-to-string.md → typedarray-to-string.mdx} +3 -1
  38. package/docs/guides/deployment/aws-lambda.mdx +204 -0
  39. package/docs/guides/deployment/digital-ocean.mdx +161 -0
  40. package/docs/guides/deployment/google-cloud-run.mdx +197 -0
  41. package/docs/guides/deployment/{railway.md → railway.mdx} +42 -54
  42. package/docs/guides/deployment/render.mdx +82 -0
  43. package/docs/guides/deployment/vercel.mdx +99 -0
  44. package/docs/guides/ecosystem/{astro.md → astro.mdx} +16 -6
  45. package/docs/guides/ecosystem/{discordjs.md → discordjs.mdx} +21 -18
  46. package/docs/guides/ecosystem/{docker.md → docker.mdx} +25 -14
  47. package/docs/guides/ecosystem/{drizzle.md → drizzle.mdx} +32 -22
  48. package/docs/guides/ecosystem/{edgedb.md → edgedb.mdx} +63 -34
  49. package/docs/guides/ecosystem/{elysia.md → elysia.mdx} +11 -11
  50. package/docs/guides/ecosystem/{express.md → express.mdx} +12 -9
  51. package/docs/guides/ecosystem/{hono.md → hono.mdx} +16 -8
  52. package/docs/guides/ecosystem/{mongoose.md → mongoose.mdx} +26 -21
  53. package/docs/guides/ecosystem/{neon-drizzle.md → neon-drizzle.mdx} +49 -35
  54. package/docs/guides/ecosystem/{neon-serverless-postgres.md → neon-serverless-postgres.mdx} +16 -11
  55. package/docs/guides/ecosystem/{nextjs.md → nextjs.mdx} +18 -10
  56. package/docs/guides/ecosystem/{nuxt.md → nuxt.mdx} +45 -11
  57. package/docs/guides/ecosystem/{pm2.md → pm2.mdx} +7 -9
  58. package/docs/guides/ecosystem/prisma-postgres.mdx +169 -0
  59. package/docs/guides/ecosystem/prisma.mdx +164 -0
  60. package/docs/guides/ecosystem/{qwik.md → qwik.mdx} +18 -11
  61. package/docs/guides/ecosystem/{react.md → react.mdx} +9 -7
  62. package/docs/guides/ecosystem/{remix.md → remix.mdx} +45 -26
  63. package/docs/guides/ecosystem/{sentry.md → sentry.mdx} +7 -5
  64. package/docs/guides/ecosystem/{solidstart.md → solidstart.mdx} +21 -13
  65. package/docs/guides/ecosystem/{ssr-react.md → ssr-react.mdx} +9 -11
  66. package/docs/guides/ecosystem/{stric.md → stric.mdx} +16 -17
  67. package/docs/guides/ecosystem/{sveltekit.md → sveltekit.mdx} +42 -29
  68. package/docs/guides/ecosystem/{systemd.md → systemd.mdx} +27 -26
  69. package/docs/guides/ecosystem/upstash.mdx +87 -0
  70. package/docs/guides/ecosystem/{vite.md → vite.mdx} +20 -14
  71. package/docs/guides/html-rewriter/{extract-links.md → extract-links.mdx} +11 -7
  72. package/docs/guides/html-rewriter/{extract-social-meta.md → extract-social-meta.mdx} +6 -2
  73. package/docs/guides/http/{cluster.md → cluster.mdx} +10 -7
  74. package/docs/guides/http/{fetch-unix.md → fetch-unix.mdx} +5 -3
  75. package/docs/guides/http/{fetch.md → fetch.mdx} +5 -3
  76. package/docs/guides/http/{file-uploads.md → file-uploads.mdx} +18 -15
  77. package/docs/guides/http/{hot.md → hot.mdx} +9 -7
  78. package/docs/guides/http/{proxy.md → proxy.mdx} +7 -5
  79. package/docs/guides/http/{server.md → server.mdx} +4 -2
  80. package/docs/guides/http/{simple.md → simple.mdx} +4 -2
  81. package/docs/guides/http/{stream-file.md → stream-file.mdx} +6 -4
  82. package/docs/guides/http/{stream-iterator.md → stream-iterator.mdx} +5 -3
  83. package/docs/guides/http/{stream-node-streams-in-bun.md → stream-node-streams-in-bun.mdx} +4 -2
  84. package/docs/guides/http/{tls.md → tls.mdx} +5 -3
  85. package/docs/guides/index.mdx +10 -0
  86. package/docs/guides/install/{add-dev.md → add-dev.mdx} +8 -6
  87. package/docs/guides/install/add-git.mdx +38 -0
  88. package/docs/guides/install/{add-optional.md → add-optional.mdx} +7 -5
  89. package/docs/guides/install/{add-peer.md → add-peer.mdx} +13 -11
  90. package/docs/guides/install/{add-tarball.md → add-tarball.mdx} +7 -5
  91. package/docs/guides/install/{add.md → add.mdx} +12 -10
  92. package/docs/guides/install/{azure-artifacts.md → azure-artifacts.mdx} +15 -12
  93. package/docs/guides/{runtime/cicd.md → install/cicd.mdx} +13 -13
  94. package/docs/guides/install/{custom-registry.md → custom-registry.mdx} +6 -4
  95. package/docs/guides/install/{from-npm-install-to-bun-install.md → from-npm-install-to-bun-install.mdx} +50 -34
  96. package/docs/guides/install/{git-diff-bun-lockfile.md → git-diff-bun-lockfile.mdx} +14 -11
  97. package/docs/guides/install/{jfrog-artifactory.md → jfrog-artifactory.mdx} +4 -4
  98. package/docs/guides/install/{npm-alias.md → npm-alias.mdx} +6 -4
  99. package/docs/guides/install/{registry-scope.md → registry-scope.mdx} +6 -4
  100. package/docs/guides/install/{trusted.md → trusted.mdx} +22 -18
  101. package/docs/guides/install/{workspaces.md → workspaces.mdx} +13 -13
  102. package/docs/guides/install/{yarnlock.md → yarnlock.mdx} +15 -9
  103. package/docs/guides/process/{argv.md → argv.mdx} +17 -9
  104. package/docs/guides/process/{ctrl-c.md → ctrl-c.mdx} +4 -2
  105. package/docs/guides/process/{ipc.md → ipc.mdx} +13 -10
  106. package/docs/guides/process/{nanoseconds.md → nanoseconds.mdx} +3 -1
  107. package/docs/guides/process/{os-signals.md → os-signals.mdx} +3 -1
  108. package/docs/guides/process/{spawn-stderr.md → spawn-stderr.mdx} +4 -1
  109. package/docs/guides/process/{spawn-stdout.md → spawn-stdout.mdx} +3 -1
  110. package/docs/guides/process/{spawn.md → spawn.mdx} +3 -1
  111. package/docs/guides/process/{stdin.md → stdin.mdx} +15 -7
  112. package/docs/guides/read-file/{arraybuffer.md → arraybuffer.mdx} +5 -3
  113. package/docs/guides/read-file/{buffer.md → buffer.mdx} +4 -2
  114. package/docs/guides/read-file/{exists.md → exists.mdx} +4 -2
  115. package/docs/guides/read-file/{json.md → json.mdx} +4 -2
  116. package/docs/guides/read-file/{mime.md → mime.mdx} +3 -1
  117. package/docs/guides/read-file/{stream.md → stream.mdx} +3 -1
  118. package/docs/guides/read-file/{string.md → string.mdx} +3 -1
  119. package/docs/guides/read-file/{uint8array.md → uint8array.mdx} +3 -1
  120. package/docs/guides/read-file/{watch.md → watch.mdx} +6 -8
  121. package/docs/guides/runtime/{build-time-constants.md → build-time-constants.mdx} +24 -22
  122. package/docs/guides/{install/cicd.md → runtime/cicd.mdx} +11 -7
  123. package/docs/guides/runtime/{codesign-macos-executable.md → codesign-macos-executable.mdx} +14 -9
  124. package/docs/guides/runtime/{define-constant.md → define-constant.mdx} +20 -16
  125. package/docs/guides/runtime/{delete-directory.md → delete-directory.mdx} +5 -3
  126. package/docs/guides/runtime/{delete-file.md → delete-file.mdx} +4 -2
  127. package/docs/guides/runtime/{heap-snapshot.md → heap-snapshot.mdx} +5 -3
  128. package/docs/guides/runtime/{import-html.md → import-html.mdx} +4 -2
  129. package/docs/guides/runtime/{import-json.md → import-json.mdx} +6 -4
  130. package/docs/guides/runtime/{import-toml.md → import-toml.mdx} +5 -3
  131. package/docs/guides/runtime/{import-yaml.md → import-yaml.mdx} +9 -7
  132. package/docs/guides/runtime/{read-env.md → read-env.mdx} +10 -5
  133. package/docs/guides/runtime/{set-env.md → set-env.mdx} +14 -10
  134. package/docs/guides/runtime/{shell.md → shell.mdx} +6 -4
  135. package/docs/guides/runtime/{timezone.md → timezone.mdx} +10 -7
  136. package/docs/guides/runtime/{tsconfig-paths.md → tsconfig-paths.mdx} +5 -3
  137. package/docs/guides/runtime/{typescript.md → typescript.mdx} +8 -6
  138. package/docs/guides/runtime/{vscode-debugger.md → vscode-debugger.mdx} +12 -11
  139. package/docs/guides/runtime/{web-debugger.md → web-debugger.mdx} +39 -18
  140. package/docs/guides/streams/{node-readable-to-arraybuffer.md → node-readable-to-arraybuffer.mdx} +3 -1
  141. package/docs/guides/streams/{node-readable-to-blob.md → node-readable-to-blob.mdx} +3 -1
  142. package/docs/guides/streams/{node-readable-to-json.md → node-readable-to-json.mdx} +3 -1
  143. package/docs/guides/streams/{node-readable-to-string.md → node-readable-to-string.mdx} +3 -1
  144. package/docs/guides/streams/{node-readable-to-uint8array.md → node-readable-to-uint8array.mdx} +3 -1
  145. package/docs/guides/streams/{to-array.md → to-array.mdx} +3 -1
  146. package/docs/guides/streams/{to-arraybuffer.md → to-arraybuffer.mdx} +3 -1
  147. package/docs/guides/streams/{to-blob.md → to-blob.mdx} +3 -1
  148. package/docs/guides/streams/{to-buffer.md → to-buffer.mdx} +3 -1
  149. package/docs/guides/streams/{to-json.md → to-json.mdx} +4 -2
  150. package/docs/guides/streams/{to-string.md → to-string.mdx} +3 -1
  151. package/docs/guides/streams/{to-typedarray.md → to-typedarray.mdx} +3 -1
  152. package/docs/guides/test/{bail.md → bail.mdx} +7 -5
  153. package/docs/guides/test/{coverage-threshold.md → coverage-threshold.mdx} +14 -7
  154. package/docs/guides/test/{coverage.md → coverage.mdx} +9 -4
  155. package/docs/guides/test/{happy-dom.md → happy-dom.mdx} +13 -8
  156. package/docs/guides/test/{migrate-from-jest.md → migrate-from-jest.mdx} +19 -37
  157. package/docs/guides/test/{mock-clock.md → mock-clock.mdx} +3 -1
  158. package/docs/guides/test/{mock-functions.md → mock-functions.mdx} +7 -5
  159. package/docs/guides/test/{rerun-each.md → rerun-each.mdx} +5 -3
  160. package/docs/guides/test/{run-tests.md → run-tests.mdx} +16 -11
  161. package/docs/guides/test/{skip-tests.md → skip-tests.mdx} +8 -4
  162. package/docs/guides/test/{snapshot.md → snapshot.mdx} +20 -13
  163. package/docs/guides/test/spy-on.mdx +49 -0
  164. package/docs/guides/test/{svelte-test.md → svelte-test.mdx} +16 -23
  165. package/docs/guides/test/{testing-library.md → testing-library.mdx} +18 -17
  166. package/docs/guides/test/{timeout.md → timeout.mdx} +5 -3
  167. package/docs/guides/test/{todo-tests.md → todo-tests.mdx} +13 -6
  168. package/docs/guides/test/{update-snapshots.md → update-snapshots.mdx} +9 -6
  169. package/docs/guides/test/{watch-mode.md → watch-mode.mdx} +9 -4
  170. package/docs/guides/util/{base64.md → base64.mdx} +3 -1
  171. package/docs/guides/util/{deep-equals.md → deep-equals.mdx} +5 -3
  172. package/docs/guides/util/{deflate.md → deflate.mdx} +3 -1
  173. package/docs/guides/util/{detect-bun.md → detect-bun.mdx} +3 -1
  174. package/docs/guides/util/{entrypoint.md → entrypoint.mdx} +4 -2
  175. package/docs/guides/util/{escape-html.md → escape-html.mdx} +3 -1
  176. package/docs/guides/util/{file-url-to-path.md → file-url-to-path.mdx} +3 -1
  177. package/docs/guides/util/{gzip.md → gzip.mdx} +3 -1
  178. package/docs/guides/util/{hash-a-password.md → hash-a-password.mdx} +3 -1
  179. package/docs/guides/util/{import-meta-dir.md → import-meta-dir.mdx} +4 -2
  180. package/docs/guides/util/{import-meta-file.md → import-meta-file.mdx} +4 -2
  181. package/docs/guides/util/{import-meta-path.md → import-meta-path.mdx} +4 -2
  182. package/docs/guides/util/{javascript-uuid.md → javascript-uuid.mdx} +3 -1
  183. package/docs/guides/util/{main.md → main.mdx} +19 -8
  184. package/docs/guides/util/{path-to-file-url.md → path-to-file-url.mdx} +3 -1
  185. package/docs/guides/util/{sleep.md → sleep.mdx} +3 -1
  186. package/docs/guides/util/{version.md → version.mdx} +6 -4
  187. package/docs/guides/util/{which-path-to-executable-bin.md → which-path-to-executable-bin.mdx} +4 -2
  188. package/docs/guides/websocket/{compression.md → compression.mdx} +5 -3
  189. package/docs/guides/websocket/{context.md → context.mdx} +9 -12
  190. package/docs/guides/websocket/{pubsub.md → pubsub.mdx} +5 -6
  191. package/docs/guides/websocket/{simple.md → simple.mdx} +5 -3
  192. package/docs/guides/write-file/{append.md → append.mdx} +3 -1
  193. package/docs/guides/write-file/{basic.md → basic.mdx} +3 -1
  194. package/docs/guides/write-file/{blob.md → blob.mdx} +3 -1
  195. package/docs/guides/write-file/{cat.md → cat.mdx} +4 -2
  196. package/docs/guides/write-file/{file-cp.md → file-cp.mdx} +3 -1
  197. package/docs/guides/write-file/{filesink.md → filesink.mdx} +3 -1
  198. package/docs/guides/write-file/{response.md → response.mdx} +3 -1
  199. package/docs/guides/write-file/{stdout.md → stdout.mdx} +3 -1
  200. package/docs/guides/write-file/{stream.md → stream.mdx} +3 -1
  201. package/docs/guides/write-file/{unlink.md → unlink.mdx} +3 -1
  202. package/docs/{index.md → index.mdx} +97 -41
  203. package/docs/installation.mdx +365 -0
  204. package/docs/{cli/bunx.md → pm/bunx.mdx} +25 -31
  205. package/docs/{install/catalogs.md → pm/catalogs.mdx} +18 -24
  206. package/docs/{cli/add.md → pm/cli/add.mdx} +61 -55
  207. package/docs/{install/audit.md → pm/cli/audit.mdx} +11 -8
  208. package/docs/{cli/install.md → pm/cli/install.mdx} +208 -81
  209. package/docs/{cli/link.md → pm/cli/link.mdx} +27 -19
  210. package/docs/{cli/outdated.md → pm/cli/outdated.mdx} +119 -12
  211. package/docs/{install/patch.md → pm/cli/patch.mdx} +25 -15
  212. package/docs/{cli/pm.md → pm/cli/pm.mdx} +96 -62
  213. package/docs/{cli/publish.md → pm/cli/publish.mdx} +38 -35
  214. package/docs/pm/cli/remove.mdx +16 -0
  215. package/docs/{cli/update.md → pm/cli/update.mdx} +26 -15
  216. package/docs/{cli/why.md → pm/cli/why.mdx} +27 -10
  217. package/docs/{cli/filter.md → pm/filter.mdx} +26 -14
  218. package/docs/{install/cache.md → pm/global-cache.mdx} +25 -12
  219. package/docs/{install/isolated.md → pm/isolated-installs.mdx} +32 -24
  220. package/docs/{install/lifecycle.md → pm/lifecycle.mdx} +20 -9
  221. package/docs/{install/lockfile.md → pm/lockfile.mdx} +18 -12
  222. package/docs/{install/npmrc.md → pm/npmrc.mdx} +30 -24
  223. package/docs/{install/overrides.md → pm/overrides.mdx} +47 -37
  224. package/docs/{install/registries.md → pm/scopes-registries.mdx} +8 -3
  225. package/docs/{install/security-scanner-api.md → pm/security-scanner-api.mdx} +22 -8
  226. package/docs/{install/workspaces.md → pm/workspaces.mdx} +17 -22
  227. package/docs/project/{benchmarking.md → benchmarking.mdx} +26 -11
  228. package/docs/project/{bindgen.md → bindgen.mdx} +12 -14
  229. package/docs/project/{building-windows.md → building-windows.mdx} +18 -47
  230. package/docs/project/{contributing.md → contributing.mdx} +56 -60
  231. package/docs/project/feedback.mdx +20 -0
  232. package/docs/project/license.mdx +78 -0
  233. package/docs/project/roadmap.mdx +8 -0
  234. package/docs/quickstart.mdx +240 -0
  235. package/docs/runtime/{autoimport.md → auto-install.mdx} +34 -31
  236. package/docs/{api/binary-data.md → runtime/binary-data.mdx} +77 -269
  237. package/docs/runtime/bun-apis.mdx +59 -0
  238. package/docs/runtime/{bunfig.md → bunfig.mdx} +95 -225
  239. package/docs/{api/cc.md → runtime/c-compiler.mdx} +16 -9
  240. package/docs/{api/spawn.md → runtime/child-process.mdx} +69 -119
  241. package/docs/{api/color.md → runtime/color.mdx} +6 -1
  242. package/docs/{api/console.md → runtime/console.mdx} +17 -7
  243. package/docs/{api/cookie.md → runtime/cookies.mdx} +24 -19
  244. package/docs/runtime/{debugger.md → debugger.mdx} +61 -51
  245. package/docs/runtime/environment-variables.mdx +214 -0
  246. package/docs/{api/ffi.md → runtime/ffi.mdx} +53 -45
  247. package/docs/{api/file-io.md → runtime/file-io.mdx} +41 -101
  248. package/docs/{api/file-system-router.md → runtime/file-system-router.mdx} +8 -2
  249. package/docs/{bundler/loaders.md → runtime/file-types.mdx} +56 -112
  250. package/docs/{api/glob.md → runtime/glob.mdx} +4 -1
  251. package/docs/runtime/globals.mdx +72 -0
  252. package/docs/{api/hashing.md → runtime/hashing.mdx} +18 -22
  253. package/docs/{api/html-rewriter.md → runtime/html-rewriter.mdx} +36 -30
  254. package/docs/runtime/http/cookies.mdx +79 -0
  255. package/docs/runtime/http/error-handling.mdx +40 -0
  256. package/docs/runtime/http/metrics.mdx +36 -0
  257. package/docs/runtime/http/routing.mdx +289 -0
  258. package/docs/runtime/http/server.mdx +647 -0
  259. package/docs/runtime/http/tls.mdx +101 -0
  260. package/docs/{api/websockets.md → runtime/http/websockets.mdx} +62 -231
  261. package/docs/{cli/run.md → runtime/index.mdx} +70 -108
  262. package/docs/runtime/jsx.mdx +115 -0
  263. package/docs/runtime/{modules.md → module-resolution.mdx} +83 -61
  264. package/docs/{api/dns.md → runtime/networking/dns.mdx} +23 -22
  265. package/docs/{api/fetch.md → runtime/networking/fetch.mdx} +10 -5
  266. package/docs/{api/tcp.md → runtime/networking/tcp.mdx} +59 -41
  267. package/docs/{api/udp.md → runtime/networking/udp.mdx} +14 -8
  268. package/docs/{api/node-api.md → runtime/node-api.mdx} +5 -0
  269. package/docs/runtime/{nodejs-apis.md → nodejs-compat.mdx} +9 -4
  270. package/docs/{bundler/plugins.md → runtime/plugins.mdx} +17 -61
  271. package/docs/{api/redis.md → runtime/redis.mdx} +65 -80
  272. package/docs/{api/s3.md → runtime/s3.mdx} +79 -66
  273. package/docs/{api/secrets.md → runtime/secrets.mdx} +27 -10
  274. package/docs/{api/semver.md → runtime/semver.mdx} +9 -4
  275. package/docs/runtime/{shell.md → shell.mdx} +52 -20
  276. package/docs/{api/sql.md → runtime/sql.mdx} +129 -99
  277. package/docs/{api/sqlite.md → runtime/sqlite.mdx} +162 -157
  278. package/docs/{api/streams.md → runtime/streams.mdx} +33 -31
  279. package/docs/{cli/bun-create.md → runtime/templating/create.mdx} +74 -143
  280. package/docs/{cli/init.md → runtime/templating/init.mdx} +24 -51
  281. package/docs/{api/transpiler.md → runtime/transpiler.mdx} +50 -38
  282. package/docs/{typescript.md → runtime/typescript.mdx} +7 -2
  283. package/docs/{api/utils.md → runtime/utils.mdx} +81 -50
  284. package/docs/runtime/{hot.md → watch-mode.mdx} +53 -37
  285. package/docs/runtime/web-apis.mdx +29 -0
  286. package/docs/{api/workers.md → runtime/workers.mdx} +28 -22
  287. package/docs/{api/yaml.md → runtime/yaml.mdx} +33 -232
  288. package/docs/snippets/cli/add.mdx +166 -0
  289. package/docs/snippets/cli/build.mdx +196 -0
  290. package/docs/snippets/cli/feedback.mdx +17 -0
  291. package/docs/snippets/cli/init.mdx +84 -0
  292. package/docs/snippets/cli/install.mdx +173 -0
  293. package/docs/snippets/cli/link.mdx +163 -0
  294. package/docs/snippets/cli/outdated.mdx +140 -0
  295. package/docs/snippets/cli/patch.mdx +171 -0
  296. package/docs/snippets/cli/publish.mdx +198 -0
  297. package/docs/snippets/cli/remove.mdx +146 -0
  298. package/docs/snippets/cli/run.mdx +293 -0
  299. package/docs/snippets/cli/test.mdx +100 -0
  300. package/docs/snippets/cli/update.mdx +144 -0
  301. package/docs/snippets/product-card.mdx +32 -0
  302. package/docs/snippets/product-tiles.mdx +94 -0
  303. package/docs/test/code-coverage.mdx +409 -0
  304. package/docs/test/configuration.mdx +467 -0
  305. package/docs/test/{time.md → dates-times.mdx} +23 -20
  306. package/docs/test/{discovery.md → discovery.mdx} +15 -10
  307. package/docs/test/dom.mdx +226 -0
  308. package/docs/{cli/test.md → test/index.mdx} +77 -94
  309. package/docs/test/lifecycle.mdx +348 -0
  310. package/docs/test/mocks.mdx +637 -0
  311. package/docs/test/{reporters.md → reporters.mdx} +15 -15
  312. package/docs/test/runtime-behavior.mdx +342 -0
  313. package/docs/test/snapshots.mdx +434 -0
  314. package/docs/test/writing-tests.mdx +635 -0
  315. package/docs/typescript.mdx +54 -0
  316. package/package.json +8 -6
  317. package/test.d.ts +2 -2
  318. package/docs/api/file.md +0 -19
  319. package/docs/api/globals.md +0 -387
  320. package/docs/api/http.md +0 -1408
  321. package/docs/api/import-meta.md +0 -69
  322. package/docs/benchmarks.md +0 -120
  323. package/docs/bun-flavored-toml.md +0 -42
  324. package/docs/bundler/css_modules.md +0 -145
  325. package/docs/bundler/fullstack.md +0 -418
  326. package/docs/bundler/index.md +0 -1735
  327. package/docs/bundler/intro.md +0 -75
  328. package/docs/bundler/vs-esbuild.md +0 -1127
  329. package/docs/cli/bun-completions.md +0 -3
  330. package/docs/cli/bun-install.md +0 -349
  331. package/docs/cli/bun-upgrade.md +0 -39
  332. package/docs/cli/info.md +0 -65
  333. package/docs/cli/patch-commit.md +0 -11
  334. package/docs/cli/remove.md +0 -7
  335. package/docs/cli/unlink.md +0 -9
  336. package/docs/contributing/upgrading-webkit.md +0 -57
  337. package/docs/ecosystem/elysia.md +0 -24
  338. package/docs/ecosystem/express.md +0 -37
  339. package/docs/ecosystem/hono.md +0 -18
  340. package/docs/ecosystem/react.md +0 -65
  341. package/docs/ecosystem/stric.md +0 -38
  342. package/docs/guides/ecosystem/prisma.md +0 -141
  343. package/docs/guides/ecosystem/render.md +0 -79
  344. package/docs/guides/install/add-git.md +0 -36
  345. package/docs/guides/test/spy-on.md +0 -46
  346. package/docs/install/index.md +0 -248
  347. package/docs/installation.md +0 -327
  348. package/docs/project/asan.md +0 -124
  349. package/docs/project/internals/build-process-for-ci.md +0 -75
  350. package/docs/project/licensing.md +0 -73
  351. package/docs/project/roadmap.md +0 -87
  352. package/docs/quickstart.md +0 -157
  353. package/docs/runtime/bun-apis.md +0 -207
  354. package/docs/runtime/env.md +0 -253
  355. package/docs/runtime/index.md +0 -312
  356. package/docs/runtime/jsx.md +0 -385
  357. package/docs/runtime/loaders.md +0 -130
  358. package/docs/runtime/plugins.md +0 -561
  359. package/docs/runtime/typescript.md +0 -139
  360. package/docs/runtime/web-apis.md +0 -128
  361. package/docs/test/configuration.md +0 -154
  362. package/docs/test/coverage.md +0 -142
  363. package/docs/test/dom.md +0 -75
  364. package/docs/test/examples/concurrent-test-glob.md +0 -132
  365. package/docs/test/hot.md +0 -15
  366. package/docs/test/lifecycle.md +0 -81
  367. package/docs/test/mocks.md +0 -313
  368. package/docs/test/runtime-behavior.md +0 -95
  369. package/docs/test/snapshots.md +0 -68
  370. package/docs/test/writing.md +0 -825
@@ -1,8 +1,13 @@
1
+ ---
2
+ title: Shell
3
+ description: Use Bun's shell scripting API to run shell commands from JavaScript
4
+ ---
5
+
1
6
  Bun Shell makes shell scripting with JavaScript & TypeScript fun. It's a cross-platform bash-like shell with seamless JavaScript interop.
2
7
 
3
8
  Quickstart:
4
9
 
5
- ```js
10
+ ```ts index.ts icon="/icons/typescript.svg"
6
11
  import { $ } from "bun";
7
12
 
8
13
  const response = await fetch("https://example.com");
@@ -11,7 +16,9 @@ const response = await fetch("https://example.com");
11
16
  await $`cat < ${response} | wc -c`; // 1256
12
17
  ```
13
18
 
14
- ## Features:
19
+ ---
20
+
21
+ ## Features
15
22
 
16
23
  - **Cross-platform**: works on Windows, Linux & macOS. Instead of `rimraf` or `cross-env`', you can use Bun Shell without installing extra dependencies. Common shell commands like `ls`, `cd`, `rm` are implemented natively.
17
24
  - **Familiar**: Bun Shell is a bash-like shell, supporting redirection, pipes, environment variables and more.
@@ -22,6 +29,8 @@ await $`cat < ${response} | wc -c`; // 1256
22
29
  - **Shell scripting**: Bun Shell can be used to run shell scripts (`.bun.sh` files).
23
30
  - **Custom interpreter**: Bun Shell is written in Zig, along with its lexer, parser, and interpreter. Bun Shell is a small programming language.
24
31
 
32
+ ---
33
+
25
34
  ## Getting started
26
35
 
27
36
  The simplest shell command is `echo`. To run it, use the `$` template literal tag:
@@ -62,6 +71,8 @@ console.log(stdout); // Buffer(7) [ 72, 101, 108, 108, 111, 33, 10 ]
62
71
  console.log(stderr); // Buffer(0) []
63
72
  ```
64
73
 
74
+ ---
75
+
65
76
  ## Error handling
66
77
 
67
78
  By default, non-zero exit codes will throw an error. This `ShellError` contains information about the command run.
@@ -84,9 +95,7 @@ Throwing can be disabled with `.nothrow()`. The result's `exitCode` will need to
84
95
  ```js
85
96
  import { $ } from "bun";
86
97
 
87
- const { stdout, stderr, exitCode } = await $`something-that-may-fail`
88
- .nothrow()
89
- .quiet();
98
+ const { stdout, stderr, exitCode } = await $`something-that-may-fail`.nothrow().quiet();
90
99
 
91
100
  if (exitCode !== 0) {
92
101
  console.log(`Non-zero exit code ${exitCode}`);
@@ -113,6 +122,8 @@ $.throws(false);
113
122
  await $`something-that-may-fail`; // No exception thrown
114
123
  ```
115
124
 
125
+ ---
126
+
116
127
  ## Redirection
117
128
 
118
129
  A command's _input_ or _output_ may be _redirected_ using the typical Bash operators:
@@ -258,11 +269,11 @@ await $`
258
269
  `;
259
270
  ```
260
271
 
261
- {% callout %}
272
+ <Note>
262
273
 
263
- **NOTE**: Because Bun internally uses the special [`raw`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#raw_strings) property on the input template literal, using the backtick syntax for command substitution won't work:
274
+ Because Bun internally uses the special [`raw`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#raw_strings) property on the input template literal, using the backtick syntax for command substitution won't work:
264
275
 
265
- ```js
276
+ ```ts icon="file-code"
266
277
  import { $ } from "bun";
267
278
 
268
279
  await $`echo \`echo hi\``;
@@ -282,7 +293,9 @@ echo hi
282
293
 
283
294
  We instead recommend sticking to the `$(...)` syntax.
284
295
 
285
- {% /callout %}
296
+ </Note>
297
+
298
+ ---
286
299
 
287
300
  ## Environment variables
288
301
 
@@ -378,6 +391,8 @@ await $`pwd`; // /tmp
378
391
  await $`pwd`.cwd("/"); // /
379
392
  ```
380
393
 
394
+ ---
395
+
381
396
  ## Reading output
382
397
 
383
398
  To read the output of a command as a string, use `.text()`:
@@ -438,6 +453,8 @@ const result = await $`echo "Hello World!"`.blob();
438
453
  console.log(result); // Blob(13) { size: 13, type: "text/plain" }
439
454
  ```
440
455
 
456
+ ---
457
+
441
458
  ## Builtin Commands
442
459
 
443
460
  For cross-platform compatibility, Bun Shell implements a set of builtin commands, in addition to reading commands from the PATH environment variable.
@@ -469,6 +486,8 @@ For cross-platform compatibility, Bun Shell implements a set of builtin commands
469
486
 
470
487
  - See [Issue #9716](https://github.com/oven-sh/bun/issues/9716) for the full list.
471
488
 
489
+ ---
490
+
472
491
  ## Utilities
473
492
 
474
493
  Bun Shell also implements a set of utilities for working with shells.
@@ -506,32 +525,44 @@ await $`echo ${{ raw: '$(foo) `bar` "baz"' }}`;
506
525
  // => baz
507
526
  ```
508
527
 
509
- ## .sh file loader
528
+ ---
529
+
530
+ ## `.sh` file loader
510
531
 
511
532
  For simple shell scripts, instead of `/bin/sh`, you can use Bun Shell to run shell scripts.
512
533
 
513
534
  To do so, just run the script with `bun` on a file with the `.sh` extension.
514
535
 
515
- ```sh#script.sh
536
+ ```sh script.sh icon="file-code"
516
537
  echo "Hello World! pwd=$(pwd)"
517
538
  ```
518
539
 
519
- ```sh
520
- $ bun ./script.sh
540
+ ```sh terminal icon="terminal"
541
+ bun ./script.sh
542
+ ```
543
+
544
+ ```txt
521
545
  Hello World! pwd=/home/demo
522
546
  ```
523
547
 
524
548
  Scripts with Bun Shell are cross platform, which means they work on Windows:
525
549
 
526
- ```powershell
527
- > bun .\script.sh
550
+ ```powershell powershell icon="windows"
551
+ bun .\script.sh
552
+ ```
553
+
554
+ ```txt
528
555
  Hello World! pwd=C:\Users\Demo
529
556
  ```
530
557
 
558
+ ---
559
+
531
560
  ## Implementation notes
532
561
 
533
562
  Bun Shell is a small programming language in Bun that is implemented in Zig. It includes a handwritten lexer, parser, and interpreter. Unlike bash, zsh, and other shells, Bun Shell runs operations concurrently.
534
563
 
564
+ ---
565
+
535
566
  ## Security in the Bun shell
536
567
 
537
568
  By design, the Bun shell _does not invoke a system shell_ (like `/bin/sh`) and
@@ -594,11 +625,12 @@ const branch = "--upload-pack=echo pwned";
594
625
  await $`git ls-remote origin ${branch}`;
595
626
  ```
596
627
 
597
- {% callout %}
598
- **Recommendation** — As is best practice in every language, always sanitize
599
- user-provided input before passing it as an argument to an external command.
600
- The responsibility for validating arguments rests with your application code.
601
- {% /callout %}
628
+ <Note>
629
+ **Recommendation** — As is best practice in every language, always sanitize user-provided input before passing it as
630
+ an argument to an external command. The responsibility for validating arguments rests with your application code.
631
+ </Note>
632
+
633
+ ---
602
634
 
603
635
  ## Credits
604
636
 
@@ -1,6 +1,11 @@
1
- Bun provides native bindings for working with SQL databases through a unified Promise-based API that supports PostgreSQL, MySQL, and SQLite. The interface is designed to be simple and performant, using tagged template literals for queries and offering features like connection pooling, transactions, and prepared statements.
1
+ ---
2
+ title: SQL
3
+ description: Bun provides native bindings for working with SQL databases through a unified Promise-based API that supports PostgreSQL, MySQL, and SQLite.
4
+ ---
2
5
 
3
- ```ts
6
+ The interface is designed to be simple and performant, using tagged template literals for queries and offering features like connection pooling, transactions, and prepared statements.
7
+
8
+ ```ts title="db.ts" icon="/icons/typescript.svg"
4
9
  import { sql, SQL } from "bun";
5
10
 
6
11
  // PostgreSQL (default)
@@ -25,35 +30,25 @@ const sqliteResults = await sqlite`
25
30
  `;
26
31
  ```
27
32
 
28
- {% features title="Features" %}
29
-
30
- {% icon size=20 name="Shield" /%} Tagged template literals to protect against SQL injection
31
-
32
- {% icon size=20 name="GitMerge" /%} Transactions
33
-
34
- {% icon size=20 name="Variable" /%} Named & positional parameters
35
-
36
- {% icon size=20 name="Network" /%} Connection pooling
37
-
38
- {% icon size=20 name="Binary" /%} `BigInt` support
39
-
40
- {% icon size=20 name="Key" /%} SASL Auth support (SCRAM-SHA-256), MD5, and Clear Text
33
+ ### Features
41
34
 
42
- {% icon size=20 name="Timer" /%} Connection timeouts
35
+ - Tagged template literals to protect against SQL injection
36
+ - Transactions
37
+ - Named & positional parameters
38
+ - Connection pooling
39
+ - `BigInt` support
40
+ - SASL Auth support (SCRAM-SHA-256), MD5, and Clear Text
41
+ - Connection timeouts
42
+ - Returning rows as data objects, arrays of arrays, or Buffer
43
+ - Binary protocol support makes it faster
44
+ - TLS support (and auth mode)
45
+ - Automatic configuration with environment variable
43
46
 
44
- {% icon size=20 name="Database" /%} Returning rows as data objects, arrays of arrays, or `Buffer`
45
-
46
- {% icon size=20 name="Code" /%} Binary protocol support makes it faster
47
-
48
- {% icon size=20 name="Lock" /%} TLS support (and auth mode)
49
-
50
- {% icon size=20 name="Settings" /%} Automatic configuration with environment variable
51
-
52
- {% /features %}
47
+ ---
53
48
 
54
49
  ## Database Support
55
50
 
56
- Bun.SQL provides a unified API for multiple database systems:
51
+ `Bun.SQL` provides a unified API for multiple database systems:
57
52
 
58
53
  ### PostgreSQL
59
54
 
@@ -63,7 +58,7 @@ PostgreSQL is used when:
63
58
  - The connection string explicitly uses `postgres://` or `postgresql://` protocols
64
59
  - No connection string is provided and environment variables point to PostgreSQL
65
60
 
66
- ```ts
61
+ ```ts title="db.ts" icon="/icons/typescript.svg"
67
62
  import { sql } from "bun";
68
63
  // Uses PostgreSQL if DATABASE_URL is not set or is a PostgreSQL URL
69
64
  await sql`SELECT ...`;
@@ -77,7 +72,7 @@ await pg`SELECT ...`;
77
72
 
78
73
  MySQL support is built into Bun.SQL, providing the same tagged template literal interface with full compatibility for MySQL 5.7+ and MySQL 8.0+:
79
74
 
80
- ```ts
75
+ ```ts title="db.ts" icon="/icons/typescript.svg"
81
76
  import { SQL } from "bun";
82
77
 
83
78
  // MySQL connection
@@ -111,7 +106,7 @@ const newUsers = [
111
106
  await mysql`INSERT INTO users ${mysql(newUsers)}`;
112
107
  ```
113
108
 
114
- {% details summary="MySQL Connection String Formats" %}
109
+ <Accordion title="MySQL Connection String Formats">
115
110
 
116
111
  MySQL accepts various URL formats for connection strings:
117
112
 
@@ -130,9 +125,9 @@ new SQL("mysql://user:pass@localhost/db?ssl=true");
130
125
  new SQL("mysql://user:pass@/database?socket=/var/run/mysqld/mysqld.sock");
131
126
  ```
132
127
 
133
- {% /details %}
128
+ </Accordion>
134
129
 
135
- {% details summary="MySQL-Specific Features" %}
130
+ <Accordion title="MySQL-Specific Features">
136
131
 
137
132
  MySQL databases support:
138
133
 
@@ -144,7 +139,7 @@ MySQL databases support:
144
139
  - **Connection attributes**: Client information sent to server for monitoring
145
140
  - **Query pipelining**: Execute multiple prepared statements without waiting for responses
146
141
 
147
- {% /details %}
142
+ </Accordion>
148
143
 
149
144
  ### SQLite
150
145
 
@@ -170,7 +165,7 @@ const db2 = new SQL({
170
165
  const db3 = new SQL("myapp.db", { adapter: "sqlite" });
171
166
  ```
172
167
 
173
- {% details summary="SQLite Connection String Formats" %}
168
+ <Accordion title="SQLite Connection String Formats">
174
169
 
175
170
  SQLite accepts various URL formats for connection strings:
176
171
 
@@ -199,11 +194,13 @@ new SQL("sqlite://data.db?mode=rw"); // Read-write mode (no create)
199
194
  new SQL("sqlite://data.db?mode=rwc"); // Read-write-create mode (default)
200
195
  ```
201
196
 
202
- **Note:** Simple filenames without a protocol (like `"myapp.db"`) require explicitly specifying `{ adapter: "sqlite" }` to avoid ambiguity with PostgreSQL.
197
+ <Note>
198
+ Simple filenames without a protocol (like `"myapp.db"`) require explicitly specifying `{ adapter: "sqlite" }` to avoid ambiguity with PostgreSQL.
199
+ </Note>
203
200
 
204
- {% /details %}
201
+ </Accordion>
205
202
 
206
- {% details summary="SQLite-Specific Options" %}
203
+ <Accordion title="SQLite-Specific Options">
207
204
 
208
205
  SQLite databases support additional configuration options:
209
206
 
@@ -229,9 +226,9 @@ Query parameters in the URL are parsed to set these options:
229
226
  - `?mode=rw` → `readonly: false, create: false`
230
227
  - `?mode=rwc` → `readonly: false, create: true` (default)
231
228
 
232
- {% /details %}
229
+ </Accordion>
233
230
 
234
- ### Inserting data
231
+ ## Inserting data
235
232
 
236
233
  You can pass JavaScript values directly to the SQL template literal and escaping will be handled for you.
237
234
 
@@ -287,6 +284,8 @@ await sql`INSERT INTO users ${sql(user, "name", "email")}`;
287
284
  // Only inserts name and email columns, ignoring other fields
288
285
  ```
289
286
 
287
+ ---
288
+
290
289
  ## Query Results
291
290
 
292
291
  By default, Bun's SQL client returns query results as arrays of objects, where each object represents a row with column names as keys. However, there are cases where you might want the data in a different format. The client provides two additional methods for this purpose.
@@ -320,6 +319,8 @@ const rows = await sql`SELECT * FROM users`.raw();
320
319
  console.log(rows); // [[Buffer, Buffer], [Buffer, Buffer], [Buffer, Buffer]]
321
320
  ```
322
321
 
322
+ ---
323
+
323
324
  ## SQL Fragments
324
325
 
325
326
  A common need in database applications is the ability to construct queries dynamically based on runtime conditions. Bun provides safe ways to do this without risking SQL injection.
@@ -391,7 +392,9 @@ await sql`SELECT * FROM products WHERE ids = ANY(${sql.array([1, 2, 3])})`;
391
392
  // Generates: SELECT * FROM products WHERE ids = ANY(ARRAY[1, 2, 3])
392
393
  ```
393
394
 
394
- **Note**: `sql.array` is PostgreSQL-only. Multi-dimensional arrays and NULL elements may not be supported yet.
395
+ <Note>`sql.array` is PostgreSQL-only. Multi-dimensional arrays and NULL elements may not be supported yet.</Note>
396
+
397
+ ---
395
398
 
396
399
  ## `sql``.simple()`
397
400
 
@@ -431,16 +434,9 @@ const result = await sql.unsafe(`
431
434
  `);
432
435
 
433
436
  // Using parameters (only one command is allowed)
434
- const result = await sql.unsafe(
435
- "SELECT " + dangerous + " FROM users WHERE id = $1",
436
- [id],
437
- );
437
+ const result = await sql.unsafe("SELECT " + dangerous + " FROM users WHERE id = $1", [id]);
438
438
  ```
439
439
 
440
- #### What is SQL Injection?
441
-
442
- {% image href="https://xkcd.com/327/" src="https://imgs.xkcd.com/comics/exploits_of_a_mom.png" /%}
443
-
444
440
  ### Execute and Cancelling Queries
445
441
 
446
442
  Bun's SQL is lazy, which means it will only start executing when awaited or executed with `.execute()`.
@@ -452,6 +448,8 @@ setTimeout(() => query.cancel(), 100);
452
448
  await query;
453
449
  ```
454
450
 
451
+ ---
452
+
455
453
  ## Database Environment Variables
456
454
 
457
455
  `sql` connection parameters can be configured using environment variables. The client checks these variables in a specific order of precedence and automatically detects the database type based on the connection string format.
@@ -573,6 +571,8 @@ DATABASE_URL="file:///absolute/path/to/db.sqlite"
573
571
 
574
572
  **Note:** PostgreSQL-specific environment variables (`POSTGRES_URL`, `PGHOST`, etc.) are ignored when using SQLite.
575
573
 
574
+ ---
575
+
576
576
  ## Runtime Preconnection
577
577
 
578
578
  Bun can preconnect to PostgreSQL at startup to improve performance by establishing database connections before your application code runs. This is useful for reducing connection latency on the first database query.
@@ -590,6 +590,8 @@ bun --sql-preconnect --hot index.js
590
590
 
591
591
  The `--sql-preconnect` flag will automatically establish a PostgreSQL connection using your configured environment variables at startup. If the connection fails, it won't crash your application - the error will be handled gracefully.
592
592
 
593
+ ---
594
+
593
595
  ## Connection Options
594
596
 
595
597
  You can configure your database connection manually by passing options to the SQL constructor. Options vary depending on the database adapter:
@@ -620,12 +622,13 @@ const db = new SQL({
620
622
  connectionTimeout: 30, // Timeout when establishing new connections
621
623
 
622
624
  // SSL/TLS options
623
- tls: {
624
- rejectUnauthorized: true,
625
- ca: "path/to/ca.pem",
626
- key: "path/to/key.pem",
627
- cert: "path/to/cert.pem",
628
- },
625
+ ssl: "prefer", // or "disable", "require", "verify-ca", "verify-full"
626
+ // tls: {
627
+ // rejectUnauthorized: true,
628
+ // ca: "path/to/ca.pem",
629
+ // key: "path/to/key.pem",
630
+ // cert: "path/to/cert.pem",
631
+ // },
629
632
 
630
633
  // Callbacks
631
634
  onconnect: client => {
@@ -715,14 +718,16 @@ const db = new SQL({
715
718
  });
716
719
  ```
717
720
 
718
- {% details summary="SQLite Connection Notes" %}
721
+ <Accordion title="SQLite Connection Notes">
719
722
 
720
723
  - **Connection Pooling**: SQLite doesn't use connection pooling as it's a file-based database. Each `SQL` instance represents a single connection.
721
724
  - **Transactions**: SQLite supports nested transactions through savepoints, similar to PostgreSQL.
722
725
  - **Concurrent Access**: SQLite handles concurrent access through file locking. Use WAL mode for better concurrency.
723
726
  - **Memory Databases**: Using `:memory:` creates a temporary database that exists only for the connection lifetime.
724
727
 
725
- {% /details %}
728
+ </Accordion>
729
+
730
+ ---
726
731
 
727
732
  ## Dynamic passwords
728
733
 
@@ -739,6 +744,8 @@ const sql = new SQL(url, {
739
744
  });
740
745
  ```
741
746
 
747
+ ---
748
+
742
749
  ## SQLite-Specific Features
743
750
 
744
751
  ### Query Execution
@@ -794,6 +801,8 @@ await sqlite`
794
801
  await sqlite`INSERT INTO flexible VALUES (${1}, ${"text"}, ${123.45}, ${Buffer.from("binary")})`;
795
802
  ```
796
803
 
804
+ ---
805
+
797
806
  ## Transactions
798
807
 
799
808
  To start a new transaction, use `sql.begin`. This method works for both PostgreSQL and SQLite. For PostgreSQL, it reserves a dedicated connection from the pool. For SQLite, it begins a transaction on the single connection.
@@ -869,6 +878,8 @@ await sql.commitDistributed("tx1");
869
878
  await sql.rollbackDistributed("tx1");
870
879
  ```
871
880
 
881
+ ---
882
+
872
883
  ## Authentication
873
884
 
874
885
  Bun supports SCRAM-SHA-256 (SASL), MD5, and Clear Text authentication. SASL is recommended for better security. Check [Postgres SASL Authentication](https://www.postgresql.org/docs/current/sasl-authentication.html) for more information.
@@ -903,11 +914,11 @@ The SSL mode can also be specified in connection strings:
903
914
  const sql = new SQL("postgres://user:password@localhost/mydb?sslmode=prefer");
904
915
 
905
916
  // Using verify-full mode
906
- const sql = new SQL(
907
- "postgres://user:password@localhost/mydb?sslmode=verify-full",
908
- );
917
+ const sql = new SQL("postgres://user:password@localhost/mydb?sslmode=verify-full");
909
918
  ```
910
919
 
920
+ ---
921
+
911
922
  ## Connection Pooling
912
923
 
913
924
  Bun's SQL client automatically manages a connection pool, which is a pool of database connections that are reused for multiple queries. This helps to reduce the overhead of establishing and closing connections for each query, and it also helps to manage the number of concurrent connections to the database.
@@ -941,6 +952,8 @@ await sql.close({ timeout: 5 }); // wait 5 seconds and close all connections fro
941
952
  await sql.close({ timeout: 0 }); // close all connections from the pool immediately
942
953
  ```
943
954
 
955
+ ---
956
+
944
957
  ## Reserved Connections
945
958
 
946
959
  Bun enables you to reserve a connection from the pool, and returns a client that wraps the single connection. This can be used for running queries on an isolated connection.
@@ -963,6 +976,8 @@ try {
963
976
  } // Automatically released
964
977
  ```
965
978
 
979
+ ---
980
+
966
981
  ## Prepared Statements
967
982
 
968
983
  By default, Bun's SQL client automatically creates named prepared statements for queries where it can be inferred that the query is static. This provides better performance. However, you can change this behavior by setting `prepare: false` in the connection options:
@@ -991,6 +1006,8 @@ You might want to use `prepare: false` when:
991
1006
 
992
1007
  Note that disabling prepared statements may impact performance for queries that are executed frequently with different parameters, as the server needs to parse and plan each query from scratch.
993
1008
 
1009
+ ---
1010
+
994
1011
  ## Error Handling
995
1012
 
996
1013
  The client provides typed errors for different failure scenarios. Errors are database-specific and extend from base error classes:
@@ -1020,7 +1037,7 @@ try {
1020
1037
  }
1021
1038
  ```
1022
1039
 
1023
- {% details summary="PostgreSQL-Specific Error Codes" %}
1040
+ <Accordion title="PostgreSQL-Specific Error Codes">
1024
1041
 
1025
1042
  ### PostgreSQL Connection Errors
1026
1043
 
@@ -1087,13 +1104,13 @@ try {
1087
1104
  | `ERR_POSTGRES_UNSAFE_TRANSACTION` | Unsafe transaction operation detected |
1088
1105
  | `ERR_POSTGRES_INVALID_TRANSACTION_STATE` | Invalid transaction state |
1089
1106
 
1090
- {% /details %}
1107
+ </Accordion>
1091
1108
 
1092
1109
  ### SQLite-Specific Errors
1093
1110
 
1094
1111
  SQLite errors provide error codes and numbers that correspond to SQLite's standard error codes:
1095
1112
 
1096
- {% details summary="Common SQLite Error Codes" %}
1113
+ <Accordion title="Common SQLite Error Codes">
1097
1114
 
1098
1115
  | Error Code | errno | Description |
1099
1116
  | ------------------- | ----- | ---------------------------------------------------- |
@@ -1130,7 +1147,9 @@ try {
1130
1147
  }
1131
1148
  ```
1132
1149
 
1133
- {% /details %}
1150
+ </Accordion>
1151
+
1152
+ ---
1134
1153
 
1135
1154
  ## Numbers and BigInt
1136
1155
 
@@ -1145,6 +1164,8 @@ console.log(typeof x, x); // "string" "9223372036854777"
1145
1164
  console.log(typeof y, y); // "number" 12345
1146
1165
  ```
1147
1166
 
1167
+ ---
1168
+
1148
1169
  ## BigInt Instead of Strings
1149
1170
 
1150
1171
  If you need large numbers as BigInt instead of strings, you can enable this by setting the `bigint` option to `true` when initializing the SQL client:
@@ -1159,6 +1180,8 @@ const [{ x }] = await sql`SELECT 9223372036854777 as x`;
1159
1180
  console.log(typeof x, x); // "bigint" 9223372036854777n
1160
1181
  ```
1161
1182
 
1183
+ ---
1184
+
1162
1185
  ## Roadmap
1163
1186
 
1164
1187
  There's still some things we haven't finished yet.
@@ -1167,6 +1190,8 @@ There's still some things we haven't finished yet.
1167
1190
  - Column name transforms (e.g. `snake_case` to `camelCase`). This is mostly blocked on a unicode-aware implementation of changing the case in C++ using WebKit's `WTF::String`.
1168
1191
  - Column type transforms
1169
1192
 
1193
+ ---
1194
+
1170
1195
  ## Database-Specific Features
1171
1196
 
1172
1197
  #### Authentication Methods
@@ -1278,6 +1303,8 @@ We also haven't implemented some of the more uncommon features like:
1278
1303
  - Point & PostGIS types
1279
1304
  - All the multi-dimensional integer array types (only a couple of the types are supported)
1280
1305
 
1306
+ ---
1307
+
1281
1308
  ## Common Patterns & Best Practices
1282
1309
 
1283
1310
  ### Working with MySQL Result Sets
@@ -1288,8 +1315,7 @@ const result = await mysql`INSERT INTO users (name) VALUES (${"Alice"})`;
1288
1315
  console.log(result.lastInsertRowid); // MySQL's LAST_INSERT_ID()
1289
1316
 
1290
1317
  // Handling affected rows
1291
- const updated =
1292
- await mysql`UPDATE users SET active = ${false} WHERE age < ${18}`;
1318
+ const updated = await mysql`UPDATE users SET active = ${false} WHERE age < ${18}`;
1293
1319
  console.log(updated.affectedRows); // Number of rows updated
1294
1320
 
1295
1321
  // Using MySQL-specific functions
@@ -1322,43 +1348,47 @@ try {
1322
1348
  4. **Index properly**: MySQL relies heavily on indexes for query performance
1323
1349
  5. **Use `utf8mb4` charset**: It's set by default and handles all Unicode characters
1324
1350
 
1325
- ## Frequently Asked Questions
1326
-
1327
- > Why is this `Bun.sql` and not `Bun.postgres`?
1351
+ ---
1328
1352
 
1329
- The plan was to add more database drivers in the future. Now with MySQL support added, this unified API supports PostgreSQL, MySQL, and SQLite.
1330
-
1331
- > How do I know which database adapter is being used?
1332
-
1333
- The adapter is automatically detected from the connection string:
1334
-
1335
- - URLs starting with `mysql://` or `mysql2://` use MySQL
1336
- - URLs matching SQLite patterns (`:memory:`, `sqlite://`, `file://`) use SQLite
1337
- - Everything else defaults to PostgreSQL
1338
-
1339
- > Are MySQL stored procedures supported?
1340
-
1341
- Yes, stored procedures are fully supported including OUT parameters and multiple result sets:
1342
-
1343
- ```ts
1344
- // Call stored procedure
1345
- const results = await mysql`CALL GetUserStats(${userId}, @total_orders)`;
1346
-
1347
- // Get OUT parameter
1348
- const outParam = await mysql`SELECT @total_orders as total`;
1349
- ```
1350
-
1351
- > Can I use MySQL-specific SQL syntax?
1352
-
1353
- Yes, you can use any MySQL-specific syntax:
1353
+ ## Frequently Asked Questions
1354
1354
 
1355
- ```ts
1356
- // MySQL-specific syntax works fine
1357
- await mysql`SET @user_id = ${userId}`;
1358
- await mysql`SHOW TABLES`;
1359
- await mysql`DESCRIBE users`;
1360
- await mysql`EXPLAIN SELECT * FROM users WHERE id = ${id}`;
1361
- ```
1355
+ <AccordionGroup>
1356
+ <Accordion title="Why is this `Bun.sql` and not `Bun.postgres`?">
1357
+ The plan was to add more database drivers in the future. Now with MySQL support added, this unified API supports PostgreSQL, MySQL, and SQLite.
1358
+ </Accordion>
1359
+ <Accordion title="How do I know which database adapter is being used?">
1360
+ The adapter is automatically detected from the connection string:
1361
+
1362
+ - URLs starting with `mysql://` or `mysql2://` use MySQL
1363
+ - URLs matching SQLite patterns (`:memory:`, `sqlite://`, `file://`) use SQLite
1364
+ - Everything else defaults to PostgreSQL
1365
+ </Accordion>
1366
+ <Accordion title="Are MySQL stored procedures supported?">
1367
+ Yes, stored procedures are fully supported including OUT parameters and multiple result sets:
1368
+
1369
+ ```ts
1370
+ // Call stored procedure
1371
+ const results = await mysql`CALL GetUserStats(${userId}, @total_orders)`;
1372
+
1373
+ // Get OUT parameter
1374
+ const outParam = await mysql`SELECT @total_orders as total`;
1375
+ ```
1376
+ </Accordion>
1377
+ <Accordion title="Can I use MySQL-specific SQL syntax?">
1378
+ Yes, you can use any MySQL-specific syntax:
1379
+
1380
+ ```ts
1381
+ // MySQL-specific syntax works fine
1382
+ await mysql`SET @user_id = ${userId}`;
1383
+ await mysql`SHOW TABLES`;
1384
+ await mysql`DESCRIBE users`;
1385
+ await mysql`EXPLAIN SELECT * FROM users WHERE id = ${id}`;
1386
+ ```
1387
+ </Accordion>
1388
+
1389
+ </AccordionGroup>
1390
+
1391
+ ---
1362
1392
 
1363
1393
  ## Why not just use an existing library?
1364
1394