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.
- package/bun.d.ts +102 -6
- package/docs/README.md +28 -0
- package/docs/bundler/bytecode.mdx +465 -0
- package/docs/bundler/{css.md → css.mdx} +97 -101
- package/docs/bundler/esbuild.mdx +253 -0
- package/docs/bundler/{executables.md → executables.mdx} +130 -221
- package/docs/bundler/fullstack.mdx +1064 -0
- package/docs/bundler/{hmr.md → hot-reloading.mdx} +74 -79
- package/docs/bundler/{html.md → html-static.mdx} +148 -111
- package/docs/bundler/index.mdx +1499 -0
- package/docs/bundler/loaders.mdx +356 -0
- package/docs/bundler/{macros.md → macros.mdx} +83 -84
- package/docs/bundler/minifier.mdx +1306 -0
- package/docs/bundler/plugins.mdx +411 -0
- package/docs/feedback.mdx +85 -0
- package/docs/guides/binary/{arraybuffer-to-array.md → arraybuffer-to-array.mdx} +3 -1
- package/docs/guides/binary/{arraybuffer-to-blob.md → arraybuffer-to-blob.mdx} +3 -1
- package/docs/guides/binary/{arraybuffer-to-buffer.md → arraybuffer-to-buffer.mdx} +3 -1
- package/docs/guides/binary/{arraybuffer-to-string.md → arraybuffer-to-string.mdx} +3 -1
- package/docs/guides/binary/{arraybuffer-to-typedarray.md → arraybuffer-to-typedarray.mdx} +3 -1
- package/docs/guides/binary/{blob-to-arraybuffer.md → blob-to-arraybuffer.mdx} +3 -1
- package/docs/guides/binary/{blob-to-dataview.md → blob-to-dataview.mdx} +3 -1
- package/docs/guides/binary/{blob-to-stream.md → blob-to-stream.mdx} +3 -1
- package/docs/guides/binary/{blob-to-string.md → blob-to-string.mdx} +3 -1
- package/docs/guides/binary/{blob-to-typedarray.md → blob-to-typedarray.mdx} +3 -1
- package/docs/guides/binary/{buffer-to-arraybuffer.md → buffer-to-arraybuffer.mdx} +3 -1
- package/docs/guides/binary/{buffer-to-blob.md → buffer-to-blob.mdx} +3 -1
- package/docs/guides/binary/{buffer-to-readablestream.md → buffer-to-readablestream.mdx} +3 -1
- package/docs/guides/binary/{buffer-to-string.md → buffer-to-string.mdx} +3 -1
- package/docs/guides/binary/{buffer-to-typedarray.md → buffer-to-typedarray.mdx} +3 -1
- package/docs/guides/binary/{dataview-to-string.md → dataview-to-string.mdx} +3 -1
- package/docs/guides/binary/{typedarray-to-arraybuffer.md → typedarray-to-arraybuffer.mdx} +3 -1
- package/docs/guides/binary/{typedarray-to-blob.md → typedarray-to-blob.mdx} +3 -1
- package/docs/guides/binary/{typedarray-to-buffer.md → typedarray-to-buffer.mdx} +3 -1
- package/docs/guides/binary/{typedarray-to-dataview.md → typedarray-to-dataview.mdx} +3 -1
- package/docs/guides/binary/{typedarray-to-readablestream.md → typedarray-to-readablestream.mdx} +3 -1
- package/docs/guides/binary/{typedarray-to-string.md → typedarray-to-string.mdx} +3 -1
- package/docs/guides/deployment/aws-lambda.mdx +204 -0
- package/docs/guides/deployment/digital-ocean.mdx +161 -0
- package/docs/guides/deployment/google-cloud-run.mdx +197 -0
- package/docs/guides/deployment/{railway.md → railway.mdx} +42 -54
- package/docs/guides/deployment/render.mdx +82 -0
- package/docs/guides/deployment/vercel.mdx +99 -0
- package/docs/guides/ecosystem/{astro.md → astro.mdx} +16 -6
- package/docs/guides/ecosystem/{discordjs.md → discordjs.mdx} +21 -18
- package/docs/guides/ecosystem/{docker.md → docker.mdx} +25 -14
- package/docs/guides/ecosystem/{drizzle.md → drizzle.mdx} +32 -22
- package/docs/guides/ecosystem/{edgedb.md → edgedb.mdx} +63 -34
- package/docs/guides/ecosystem/{elysia.md → elysia.mdx} +11 -11
- package/docs/guides/ecosystem/{express.md → express.mdx} +12 -9
- package/docs/guides/ecosystem/{hono.md → hono.mdx} +16 -8
- package/docs/guides/ecosystem/{mongoose.md → mongoose.mdx} +26 -21
- package/docs/guides/ecosystem/{neon-drizzle.md → neon-drizzle.mdx} +49 -35
- package/docs/guides/ecosystem/{neon-serverless-postgres.md → neon-serverless-postgres.mdx} +16 -11
- package/docs/guides/ecosystem/{nextjs.md → nextjs.mdx} +18 -10
- package/docs/guides/ecosystem/{nuxt.md → nuxt.mdx} +45 -11
- package/docs/guides/ecosystem/{pm2.md → pm2.mdx} +7 -9
- package/docs/guides/ecosystem/prisma-postgres.mdx +169 -0
- package/docs/guides/ecosystem/prisma.mdx +164 -0
- package/docs/guides/ecosystem/{qwik.md → qwik.mdx} +18 -11
- package/docs/guides/ecosystem/{react.md → react.mdx} +9 -7
- package/docs/guides/ecosystem/{remix.md → remix.mdx} +45 -26
- package/docs/guides/ecosystem/{sentry.md → sentry.mdx} +7 -5
- package/docs/guides/ecosystem/{solidstart.md → solidstart.mdx} +21 -13
- package/docs/guides/ecosystem/{ssr-react.md → ssr-react.mdx} +9 -11
- package/docs/guides/ecosystem/{stric.md → stric.mdx} +16 -17
- package/docs/guides/ecosystem/{sveltekit.md → sveltekit.mdx} +42 -29
- package/docs/guides/ecosystem/{systemd.md → systemd.mdx} +27 -26
- package/docs/guides/ecosystem/upstash.mdx +87 -0
- package/docs/guides/ecosystem/{vite.md → vite.mdx} +20 -14
- package/docs/guides/html-rewriter/{extract-links.md → extract-links.mdx} +11 -7
- package/docs/guides/html-rewriter/{extract-social-meta.md → extract-social-meta.mdx} +6 -2
- package/docs/guides/http/{cluster.md → cluster.mdx} +10 -7
- package/docs/guides/http/{fetch-unix.md → fetch-unix.mdx} +5 -3
- package/docs/guides/http/{fetch.md → fetch.mdx} +5 -3
- package/docs/guides/http/{file-uploads.md → file-uploads.mdx} +18 -15
- package/docs/guides/http/{hot.md → hot.mdx} +9 -7
- package/docs/guides/http/{proxy.md → proxy.mdx} +7 -5
- package/docs/guides/http/{server.md → server.mdx} +4 -2
- package/docs/guides/http/{simple.md → simple.mdx} +4 -2
- package/docs/guides/http/{stream-file.md → stream-file.mdx} +6 -4
- package/docs/guides/http/{stream-iterator.md → stream-iterator.mdx} +5 -3
- package/docs/guides/http/{stream-node-streams-in-bun.md → stream-node-streams-in-bun.mdx} +4 -2
- package/docs/guides/http/{tls.md → tls.mdx} +5 -3
- package/docs/guides/index.mdx +10 -0
- package/docs/guides/install/{add-dev.md → add-dev.mdx} +8 -6
- package/docs/guides/install/add-git.mdx +38 -0
- package/docs/guides/install/{add-optional.md → add-optional.mdx} +7 -5
- package/docs/guides/install/{add-peer.md → add-peer.mdx} +13 -11
- package/docs/guides/install/{add-tarball.md → add-tarball.mdx} +7 -5
- package/docs/guides/install/{add.md → add.mdx} +12 -10
- package/docs/guides/install/{azure-artifacts.md → azure-artifacts.mdx} +15 -12
- package/docs/guides/{runtime/cicd.md → install/cicd.mdx} +13 -13
- package/docs/guides/install/{custom-registry.md → custom-registry.mdx} +6 -4
- package/docs/guides/install/{from-npm-install-to-bun-install.md → from-npm-install-to-bun-install.mdx} +50 -34
- package/docs/guides/install/{git-diff-bun-lockfile.md → git-diff-bun-lockfile.mdx} +14 -11
- package/docs/guides/install/{jfrog-artifactory.md → jfrog-artifactory.mdx} +4 -4
- package/docs/guides/install/{npm-alias.md → npm-alias.mdx} +6 -4
- package/docs/guides/install/{registry-scope.md → registry-scope.mdx} +6 -4
- package/docs/guides/install/{trusted.md → trusted.mdx} +22 -18
- package/docs/guides/install/{workspaces.md → workspaces.mdx} +13 -13
- package/docs/guides/install/{yarnlock.md → yarnlock.mdx} +15 -9
- package/docs/guides/process/{argv.md → argv.mdx} +17 -9
- package/docs/guides/process/{ctrl-c.md → ctrl-c.mdx} +4 -2
- package/docs/guides/process/{ipc.md → ipc.mdx} +13 -10
- package/docs/guides/process/{nanoseconds.md → nanoseconds.mdx} +3 -1
- package/docs/guides/process/{os-signals.md → os-signals.mdx} +3 -1
- package/docs/guides/process/{spawn-stderr.md → spawn-stderr.mdx} +4 -1
- package/docs/guides/process/{spawn-stdout.md → spawn-stdout.mdx} +3 -1
- package/docs/guides/process/{spawn.md → spawn.mdx} +3 -1
- package/docs/guides/process/{stdin.md → stdin.mdx} +15 -7
- package/docs/guides/read-file/{arraybuffer.md → arraybuffer.mdx} +5 -3
- package/docs/guides/read-file/{buffer.md → buffer.mdx} +4 -2
- package/docs/guides/read-file/{exists.md → exists.mdx} +4 -2
- package/docs/guides/read-file/{json.md → json.mdx} +4 -2
- package/docs/guides/read-file/{mime.md → mime.mdx} +3 -1
- package/docs/guides/read-file/{stream.md → stream.mdx} +3 -1
- package/docs/guides/read-file/{string.md → string.mdx} +3 -1
- package/docs/guides/read-file/{uint8array.md → uint8array.mdx} +3 -1
- package/docs/guides/read-file/{watch.md → watch.mdx} +6 -8
- package/docs/guides/runtime/{build-time-constants.md → build-time-constants.mdx} +24 -22
- package/docs/guides/{install/cicd.md → runtime/cicd.mdx} +11 -7
- package/docs/guides/runtime/{codesign-macos-executable.md → codesign-macos-executable.mdx} +14 -9
- package/docs/guides/runtime/{define-constant.md → define-constant.mdx} +20 -16
- package/docs/guides/runtime/{delete-directory.md → delete-directory.mdx} +5 -3
- package/docs/guides/runtime/{delete-file.md → delete-file.mdx} +4 -2
- package/docs/guides/runtime/{heap-snapshot.md → heap-snapshot.mdx} +5 -3
- package/docs/guides/runtime/{import-html.md → import-html.mdx} +4 -2
- package/docs/guides/runtime/{import-json.md → import-json.mdx} +6 -4
- package/docs/guides/runtime/{import-toml.md → import-toml.mdx} +5 -3
- package/docs/guides/runtime/{import-yaml.md → import-yaml.mdx} +9 -7
- package/docs/guides/runtime/{read-env.md → read-env.mdx} +10 -5
- package/docs/guides/runtime/{set-env.md → set-env.mdx} +14 -10
- package/docs/guides/runtime/{shell.md → shell.mdx} +6 -4
- package/docs/guides/runtime/{timezone.md → timezone.mdx} +10 -7
- package/docs/guides/runtime/{tsconfig-paths.md → tsconfig-paths.mdx} +5 -3
- package/docs/guides/runtime/{typescript.md → typescript.mdx} +8 -6
- package/docs/guides/runtime/{vscode-debugger.md → vscode-debugger.mdx} +12 -11
- package/docs/guides/runtime/{web-debugger.md → web-debugger.mdx} +39 -18
- package/docs/guides/streams/{node-readable-to-arraybuffer.md → node-readable-to-arraybuffer.mdx} +3 -1
- package/docs/guides/streams/{node-readable-to-blob.md → node-readable-to-blob.mdx} +3 -1
- package/docs/guides/streams/{node-readable-to-json.md → node-readable-to-json.mdx} +3 -1
- package/docs/guides/streams/{node-readable-to-string.md → node-readable-to-string.mdx} +3 -1
- package/docs/guides/streams/{node-readable-to-uint8array.md → node-readable-to-uint8array.mdx} +3 -1
- package/docs/guides/streams/{to-array.md → to-array.mdx} +3 -1
- package/docs/guides/streams/{to-arraybuffer.md → to-arraybuffer.mdx} +3 -1
- package/docs/guides/streams/{to-blob.md → to-blob.mdx} +3 -1
- package/docs/guides/streams/{to-buffer.md → to-buffer.mdx} +3 -1
- package/docs/guides/streams/{to-json.md → to-json.mdx} +4 -2
- package/docs/guides/streams/{to-string.md → to-string.mdx} +3 -1
- package/docs/guides/streams/{to-typedarray.md → to-typedarray.mdx} +3 -1
- package/docs/guides/test/{bail.md → bail.mdx} +7 -5
- package/docs/guides/test/{coverage-threshold.md → coverage-threshold.mdx} +14 -7
- package/docs/guides/test/{coverage.md → coverage.mdx} +9 -4
- package/docs/guides/test/{happy-dom.md → happy-dom.mdx} +13 -8
- package/docs/guides/test/{migrate-from-jest.md → migrate-from-jest.mdx} +19 -37
- package/docs/guides/test/{mock-clock.md → mock-clock.mdx} +3 -1
- package/docs/guides/test/{mock-functions.md → mock-functions.mdx} +7 -5
- package/docs/guides/test/{rerun-each.md → rerun-each.mdx} +5 -3
- package/docs/guides/test/{run-tests.md → run-tests.mdx} +16 -11
- package/docs/guides/test/{skip-tests.md → skip-tests.mdx} +8 -4
- package/docs/guides/test/{snapshot.md → snapshot.mdx} +20 -13
- package/docs/guides/test/spy-on.mdx +49 -0
- package/docs/guides/test/{svelte-test.md → svelte-test.mdx} +16 -23
- package/docs/guides/test/{testing-library.md → testing-library.mdx} +18 -17
- package/docs/guides/test/{timeout.md → timeout.mdx} +5 -3
- package/docs/guides/test/{todo-tests.md → todo-tests.mdx} +13 -6
- package/docs/guides/test/{update-snapshots.md → update-snapshots.mdx} +9 -6
- package/docs/guides/test/{watch-mode.md → watch-mode.mdx} +9 -4
- package/docs/guides/util/{base64.md → base64.mdx} +3 -1
- package/docs/guides/util/{deep-equals.md → deep-equals.mdx} +5 -3
- package/docs/guides/util/{deflate.md → deflate.mdx} +3 -1
- package/docs/guides/util/{detect-bun.md → detect-bun.mdx} +3 -1
- package/docs/guides/util/{entrypoint.md → entrypoint.mdx} +4 -2
- package/docs/guides/util/{escape-html.md → escape-html.mdx} +3 -1
- package/docs/guides/util/{file-url-to-path.md → file-url-to-path.mdx} +3 -1
- package/docs/guides/util/{gzip.md → gzip.mdx} +3 -1
- package/docs/guides/util/{hash-a-password.md → hash-a-password.mdx} +3 -1
- package/docs/guides/util/{import-meta-dir.md → import-meta-dir.mdx} +4 -2
- package/docs/guides/util/{import-meta-file.md → import-meta-file.mdx} +4 -2
- package/docs/guides/util/{import-meta-path.md → import-meta-path.mdx} +4 -2
- package/docs/guides/util/{javascript-uuid.md → javascript-uuid.mdx} +3 -1
- package/docs/guides/util/{main.md → main.mdx} +19 -8
- package/docs/guides/util/{path-to-file-url.md → path-to-file-url.mdx} +3 -1
- package/docs/guides/util/{sleep.md → sleep.mdx} +3 -1
- package/docs/guides/util/{version.md → version.mdx} +6 -4
- package/docs/guides/util/{which-path-to-executable-bin.md → which-path-to-executable-bin.mdx} +4 -2
- package/docs/guides/websocket/{compression.md → compression.mdx} +5 -3
- package/docs/guides/websocket/{context.md → context.mdx} +9 -12
- package/docs/guides/websocket/{pubsub.md → pubsub.mdx} +5 -6
- package/docs/guides/websocket/{simple.md → simple.mdx} +5 -3
- package/docs/guides/write-file/{append.md → append.mdx} +3 -1
- package/docs/guides/write-file/{basic.md → basic.mdx} +3 -1
- package/docs/guides/write-file/{blob.md → blob.mdx} +3 -1
- package/docs/guides/write-file/{cat.md → cat.mdx} +4 -2
- package/docs/guides/write-file/{file-cp.md → file-cp.mdx} +3 -1
- package/docs/guides/write-file/{filesink.md → filesink.mdx} +3 -1
- package/docs/guides/write-file/{response.md → response.mdx} +3 -1
- package/docs/guides/write-file/{stdout.md → stdout.mdx} +3 -1
- package/docs/guides/write-file/{stream.md → stream.mdx} +3 -1
- package/docs/guides/write-file/{unlink.md → unlink.mdx} +3 -1
- package/docs/{index.md → index.mdx} +97 -41
- package/docs/installation.mdx +365 -0
- package/docs/{cli/bunx.md → pm/bunx.mdx} +25 -31
- package/docs/{install/catalogs.md → pm/catalogs.mdx} +18 -24
- package/docs/{cli/add.md → pm/cli/add.mdx} +61 -55
- package/docs/{install/audit.md → pm/cli/audit.mdx} +11 -8
- package/docs/{cli/install.md → pm/cli/install.mdx} +208 -81
- package/docs/{cli/link.md → pm/cli/link.mdx} +27 -19
- package/docs/{cli/outdated.md → pm/cli/outdated.mdx} +119 -12
- package/docs/{install/patch.md → pm/cli/patch.mdx} +25 -15
- package/docs/{cli/pm.md → pm/cli/pm.mdx} +96 -62
- package/docs/{cli/publish.md → pm/cli/publish.mdx} +38 -35
- package/docs/pm/cli/remove.mdx +16 -0
- package/docs/{cli/update.md → pm/cli/update.mdx} +26 -15
- package/docs/{cli/why.md → pm/cli/why.mdx} +27 -10
- package/docs/{cli/filter.md → pm/filter.mdx} +26 -14
- package/docs/{install/cache.md → pm/global-cache.mdx} +25 -12
- package/docs/{install/isolated.md → pm/isolated-installs.mdx} +32 -24
- package/docs/{install/lifecycle.md → pm/lifecycle.mdx} +20 -9
- package/docs/{install/lockfile.md → pm/lockfile.mdx} +18 -12
- package/docs/{install/npmrc.md → pm/npmrc.mdx} +30 -24
- package/docs/{install/overrides.md → pm/overrides.mdx} +47 -37
- package/docs/{install/registries.md → pm/scopes-registries.mdx} +8 -3
- package/docs/{install/security-scanner-api.md → pm/security-scanner-api.mdx} +22 -8
- package/docs/{install/workspaces.md → pm/workspaces.mdx} +17 -22
- package/docs/project/{benchmarking.md → benchmarking.mdx} +26 -11
- package/docs/project/{bindgen.md → bindgen.mdx} +12 -14
- package/docs/project/{building-windows.md → building-windows.mdx} +18 -47
- package/docs/project/{contributing.md → contributing.mdx} +56 -60
- package/docs/project/feedback.mdx +20 -0
- package/docs/project/license.mdx +78 -0
- package/docs/project/roadmap.mdx +8 -0
- package/docs/quickstart.mdx +240 -0
- package/docs/runtime/{autoimport.md → auto-install.mdx} +34 -31
- package/docs/{api/binary-data.md → runtime/binary-data.mdx} +77 -269
- package/docs/runtime/bun-apis.mdx +59 -0
- package/docs/runtime/{bunfig.md → bunfig.mdx} +95 -225
- package/docs/{api/cc.md → runtime/c-compiler.mdx} +16 -9
- package/docs/{api/spawn.md → runtime/child-process.mdx} +69 -119
- package/docs/{api/color.md → runtime/color.mdx} +6 -1
- package/docs/{api/console.md → runtime/console.mdx} +17 -7
- package/docs/{api/cookie.md → runtime/cookies.mdx} +24 -19
- package/docs/runtime/{debugger.md → debugger.mdx} +61 -51
- package/docs/runtime/environment-variables.mdx +214 -0
- package/docs/{api/ffi.md → runtime/ffi.mdx} +53 -45
- package/docs/{api/file-io.md → runtime/file-io.mdx} +41 -101
- package/docs/{api/file-system-router.md → runtime/file-system-router.mdx} +8 -2
- package/docs/{bundler/loaders.md → runtime/file-types.mdx} +56 -112
- package/docs/{api/glob.md → runtime/glob.mdx} +4 -1
- package/docs/runtime/globals.mdx +72 -0
- package/docs/{api/hashing.md → runtime/hashing.mdx} +18 -22
- package/docs/{api/html-rewriter.md → runtime/html-rewriter.mdx} +36 -30
- package/docs/runtime/http/cookies.mdx +79 -0
- package/docs/runtime/http/error-handling.mdx +40 -0
- package/docs/runtime/http/metrics.mdx +36 -0
- package/docs/runtime/http/routing.mdx +289 -0
- package/docs/runtime/http/server.mdx +647 -0
- package/docs/runtime/http/tls.mdx +101 -0
- package/docs/{api/websockets.md → runtime/http/websockets.mdx} +62 -231
- package/docs/{cli/run.md → runtime/index.mdx} +70 -108
- package/docs/runtime/jsx.mdx +115 -0
- package/docs/runtime/{modules.md → module-resolution.mdx} +83 -61
- package/docs/{api/dns.md → runtime/networking/dns.mdx} +23 -22
- package/docs/{api/fetch.md → runtime/networking/fetch.mdx} +10 -5
- package/docs/{api/tcp.md → runtime/networking/tcp.mdx} +59 -41
- package/docs/{api/udp.md → runtime/networking/udp.mdx} +14 -8
- package/docs/{api/node-api.md → runtime/node-api.mdx} +5 -0
- package/docs/runtime/{nodejs-apis.md → nodejs-compat.mdx} +9 -4
- package/docs/{bundler/plugins.md → runtime/plugins.mdx} +17 -61
- package/docs/{api/redis.md → runtime/redis.mdx} +65 -80
- package/docs/{api/s3.md → runtime/s3.mdx} +79 -66
- package/docs/{api/secrets.md → runtime/secrets.mdx} +27 -10
- package/docs/{api/semver.md → runtime/semver.mdx} +9 -4
- package/docs/runtime/{shell.md → shell.mdx} +52 -20
- package/docs/{api/sql.md → runtime/sql.mdx} +129 -99
- package/docs/{api/sqlite.md → runtime/sqlite.mdx} +162 -157
- package/docs/{api/streams.md → runtime/streams.mdx} +33 -31
- package/docs/{cli/bun-create.md → runtime/templating/create.mdx} +74 -143
- package/docs/{cli/init.md → runtime/templating/init.mdx} +24 -51
- package/docs/{api/transpiler.md → runtime/transpiler.mdx} +50 -38
- package/docs/{typescript.md → runtime/typescript.mdx} +7 -2
- package/docs/{api/utils.md → runtime/utils.mdx} +81 -50
- package/docs/runtime/{hot.md → watch-mode.mdx} +53 -37
- package/docs/runtime/web-apis.mdx +29 -0
- package/docs/{api/workers.md → runtime/workers.mdx} +28 -22
- package/docs/{api/yaml.md → runtime/yaml.mdx} +33 -232
- package/docs/snippets/cli/add.mdx +166 -0
- package/docs/snippets/cli/build.mdx +196 -0
- package/docs/snippets/cli/feedback.mdx +17 -0
- package/docs/snippets/cli/init.mdx +84 -0
- package/docs/snippets/cli/install.mdx +173 -0
- package/docs/snippets/cli/link.mdx +163 -0
- package/docs/snippets/cli/outdated.mdx +140 -0
- package/docs/snippets/cli/patch.mdx +171 -0
- package/docs/snippets/cli/publish.mdx +198 -0
- package/docs/snippets/cli/remove.mdx +146 -0
- package/docs/snippets/cli/run.mdx +293 -0
- package/docs/snippets/cli/test.mdx +100 -0
- package/docs/snippets/cli/update.mdx +144 -0
- package/docs/snippets/product-card.mdx +32 -0
- package/docs/snippets/product-tiles.mdx +94 -0
- package/docs/test/code-coverage.mdx +409 -0
- package/docs/test/configuration.mdx +467 -0
- package/docs/test/{time.md → dates-times.mdx} +23 -20
- package/docs/test/{discovery.md → discovery.mdx} +15 -10
- package/docs/test/dom.mdx +226 -0
- package/docs/{cli/test.md → test/index.mdx} +77 -94
- package/docs/test/lifecycle.mdx +348 -0
- package/docs/test/mocks.mdx +637 -0
- package/docs/test/{reporters.md → reporters.mdx} +15 -15
- package/docs/test/runtime-behavior.mdx +342 -0
- package/docs/test/snapshots.mdx +434 -0
- package/docs/test/writing-tests.mdx +635 -0
- package/docs/typescript.mdx +54 -0
- package/package.json +8 -6
- package/test.d.ts +2 -2
- package/docs/api/file.md +0 -19
- package/docs/api/globals.md +0 -387
- package/docs/api/http.md +0 -1408
- package/docs/api/import-meta.md +0 -69
- package/docs/benchmarks.md +0 -120
- package/docs/bun-flavored-toml.md +0 -42
- package/docs/bundler/css_modules.md +0 -145
- package/docs/bundler/fullstack.md +0 -418
- package/docs/bundler/index.md +0 -1735
- package/docs/bundler/intro.md +0 -75
- package/docs/bundler/vs-esbuild.md +0 -1127
- package/docs/cli/bun-completions.md +0 -3
- package/docs/cli/bun-install.md +0 -349
- package/docs/cli/bun-upgrade.md +0 -39
- package/docs/cli/info.md +0 -65
- package/docs/cli/patch-commit.md +0 -11
- package/docs/cli/remove.md +0 -7
- package/docs/cli/unlink.md +0 -9
- package/docs/contributing/upgrading-webkit.md +0 -57
- package/docs/ecosystem/elysia.md +0 -24
- package/docs/ecosystem/express.md +0 -37
- package/docs/ecosystem/hono.md +0 -18
- package/docs/ecosystem/react.md +0 -65
- package/docs/ecosystem/stric.md +0 -38
- package/docs/guides/ecosystem/prisma.md +0 -141
- package/docs/guides/ecosystem/render.md +0 -79
- package/docs/guides/install/add-git.md +0 -36
- package/docs/guides/test/spy-on.md +0 -46
- package/docs/install/index.md +0 -248
- package/docs/installation.md +0 -327
- package/docs/project/asan.md +0 -124
- package/docs/project/internals/build-process-for-ci.md +0 -75
- package/docs/project/licensing.md +0 -73
- package/docs/project/roadmap.md +0 -87
- package/docs/quickstart.md +0 -157
- package/docs/runtime/bun-apis.md +0 -207
- package/docs/runtime/env.md +0 -253
- package/docs/runtime/index.md +0 -312
- package/docs/runtime/jsx.md +0 -385
- package/docs/runtime/loaders.md +0 -130
- package/docs/runtime/plugins.md +0 -561
- package/docs/runtime/typescript.md +0 -139
- package/docs/runtime/web-apis.md +0 -128
- package/docs/test/configuration.md +0 -154
- package/docs/test/coverage.md +0 -142
- package/docs/test/dom.md +0 -75
- package/docs/test/examples/concurrent-test-glob.md +0 -132
- package/docs/test/hot.md +0 -15
- package/docs/test/lifecycle.md +0 -81
- package/docs/test/mocks.md +0 -313
- package/docs/test/runtime-behavior.md +0 -95
- package/docs/test/snapshots.md +0 -68
- 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
|
-
```
|
|
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
|
-
|
|
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
|
-
|
|
272
|
+
<Note>
|
|
262
273
|
|
|
263
|
-
|
|
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
|
-
```
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
536
|
+
```sh script.sh icon="file-code"
|
|
516
537
|
echo "Hello World! pwd=$(pwd)"
|
|
517
538
|
```
|
|
518
539
|
|
|
519
|
-
```sh
|
|
520
|
-
|
|
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
|
-
|
|
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
|
-
|
|
598
|
-
**Recommendation** — As is best practice in every language, always sanitize
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
128
|
+
</Accordion>
|
|
134
129
|
|
|
135
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
201
|
+
</Accordion>
|
|
205
202
|
|
|
206
|
-
|
|
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
|
-
|
|
229
|
+
</Accordion>
|
|
233
230
|
|
|
234
|
-
|
|
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
|
-
|
|
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
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
1326
|
-
|
|
1327
|
-
> Why is this `Bun.sql` and not `Bun.postgres`?
|
|
1351
|
+
---
|
|
1328
1352
|
|
|
1329
|
-
|
|
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
|
-
|
|
1356
|
-
|
|
1357
|
-
|
|
1358
|
-
|
|
1359
|
-
|
|
1360
|
-
|
|
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
|
|