diff --git a/README.md b/README.md index 5f02b6a91c..be08b49613 100644 --- a/README.md +++ b/README.md @@ -183,6 +183,193 @@ bun upgrade --canary - [Building Windows](https://bun.sh/docs/project/building-windows) - [License](https://bun.sh/docs/project/licensing) +## Guides + +- Binary + - [Convert an ArrayBuffer to an array of numbers](https://bun.sh/docs/guides/arraybuffer-to-array) + - [Convert an ArrayBuffer to a Blob](https://bun.sh/docs/guides/arraybuffer-to-blob) + - [Convert an ArrayBuffer to a Buffer](https://bun.sh/docs/guides/arraybuffer-to-buffer) + - [Convert an ArrayBuffer to a string](https://bun.sh/docs/guides/arraybuffer-to-string) + - [Convert an ArrayBuffer to a Uint8Array](https://bun.sh/docs/guides/arraybuffer-to-typedarray) + - [Convert a Blob to an ArrayBuffer](https://bun.sh/docs/guides/blob-to-arraybuffer) + - [Convert a Blob to a DataView](https://bun.sh/docs/guides/blob-to-dataview) + - [Convert a Blob to a ReadableStream](https://bun.sh/docs/guides/blob-to-stream) + - [Convert a Blob to a string](https://bun.sh/docs/guides/blob-to-string) + - [Convert a Blob to a Uint8Array](https://bun.sh/docs/guides/blob-to-typedarray) + - [Convert a Buffer to an ArrayBuffer](https://bun.sh/docs/guides/buffer-to-arraybuffer) + - [Convert a Buffer to a blob](https://bun.sh/docs/guides/buffer-to-blob) + - [Convert a Buffer to a ReadableStream](https://bun.sh/docs/guides/buffer-to-readablestream) + - [Convert a Buffer to a string](https://bun.sh/docs/guides/buffer-to-string) + - [Convert a Buffer to a Uint8Array](https://bun.sh/docs/guides/buffer-to-typedarray) + - [Convert a DataView to a string](https://bun.sh/docs/guides/dataview-to-string) + - [Convert a Uint8Array to an ArrayBuffer](https://bun.sh/docs/guides/typedarray-to-arraybuffer) + - [Convert a Uint8Array to a Blob](https://bun.sh/docs/guides/typedarray-to-blob) + - [Convert a Uint8Array to a Buffer](https://bun.sh/docs/guides/typedarray-to-buffer) + - [Convert a Uint8Array to a DataView](https://bun.sh/docs/guides/typedarray-to-dataview) + - [Convert a Uint8Array to a ReadableStream](https://bun.sh/docs/guides/typedarray-to-readablestream) + - [Convert a Uint8Array to a string](https://bun.sh/docs/guides/typedarray-to-string) + +- Ecosystem + - [Build an app with Astro and Bun](https://bun.sh/docs/guides/astro) + - [Create a Discord bot](https://bun.sh/docs/guides/discordjs) + - [Containerize a Bun application with Docker](https://bun.sh/docs/guides/docker) + - [Use Drizzle ORM with Bun](https://bun.sh/docs/guides/drizzle) + - [Use EdgeDB with Bun](https://bun.sh/docs/guides/edgedb) + - [Build an HTTP server using Elysia and Bun](https://bun.sh/docs/guides/elysia) + - [Build an HTTP server using Express and Bun](https://bun.sh/docs/guides/express) + - [Build an HTTP server using Hono and Bun](https://bun.sh/docs/guides/hono) + - [Read and write data to MongoDB using Mongoose and Bun](https://bun.sh/docs/guides/mongoose) + - [Use Neon's Serverless Postgres with Bun](https://bun.sh/docs/guides/neon-serverless-postgres) + - [Build an app with Next.js and Bun](https://bun.sh/docs/guides/nextjs) + - [Build an app with Nuxt and Bun](https://bun.sh/docs/guides/nuxt) + - [Run Bun as a daemon with PM2](https://bun.sh/docs/guides/pm2) + - [Use Prisma with Bun](https://bun.sh/docs/guides/prisma) + - [Build an app with Qwik and Bun](https://bun.sh/docs/guides/qwik) + - [Use React and JSX](https://bun.sh/docs/guides/react) + - [Build an app with Remix and Bun](https://bun.sh/docs/guides/remix) + - [Build an app with SolidStart and Bun](https://bun.sh/docs/guides/solidstart) + - [Server-side render (SSR) a React component](https://bun.sh/docs/guides/ssr-react) + - [Build an HTTP server using StricJS and Bun](https://bun.sh/docs/guides/stric) + - [Build an app with SvelteKit and Bun](https://bun.sh/docs/guides/sveltekit) + - [Run Bun as a daemon with systemd](https://bun.sh/docs/guides/systemd) + - [Build a frontend using Vite and Bun](https://bun.sh/docs/guides/vite) + +- HTTP + - [fetch with unix domain sockets in Bun](https://bun.sh/docs/guides/fetch-unix) + - [Send an HTTP request using fetch](https://bun.sh/docs/guides/fetch) + - [Upload files via HTTP using FormData](https://bun.sh/docs/guides/file-uploads) + - [Hot reload an HTTP server](https://bun.sh/docs/guides/hot) + - [Proxy HTTP requests using fetch()](https://bun.sh/docs/guides/proxy) + - [Common HTTP server usage](https://bun.sh/docs/guides/server) + - [Write a simple HTTP server](https://bun.sh/docs/guides/simple) + - [Stream a file as an HTTP Response](https://bun.sh/docs/guides/stream-file) + - [Streaming HTTP Server with Async Iterators](https://bun.sh/docs/guides/stream-iterator) + - [Streaming HTTP Server with Node.js Streams](https://bun.sh/docs/guides/stream-node-streams-in-bun) + - [Configure TLS on an HTTP server](https://bun.sh/docs/guides/tls) + +- Install + - [Add a development dependency](https://bun.sh/docs/guides/add-dev) + - [Add a Git dependency](https://bun.sh/docs/guides/add-git) + - [Add an optional dependency](https://bun.sh/docs/guides/add-optional) + - [Add a peer dependency](https://bun.sh/docs/guides/add-peer) + - [Add a tarball dependency](https://bun.sh/docs/guides/add-tarball) + - [Add a dependency](https://bun.sh/docs/guides/add) + - [Using bun install with an Azure Artifacts npm registry](https://bun.sh/docs/guides/azure-artifacts) + - [Install dependencies with Bun in GitHub Actions](https://bun.sh/docs/guides/cicd) + - [Override the default npm registry for bun install](https://bun.sh/docs/guides/custom-registry) + - [Configure git to diff Bun's lockb lockfile](https://bun.sh/docs/guides/git-diff-bun-lockfile) + - [Using bun install with Artifactory](https://bun.sh/docs/guides/jfrog-artifactory) + - [Install a package under a different name](https://bun.sh/docs/guides/npm-alias) + - [Configure a private registry for an organization scope with bun install](https://bun.sh/docs/guides/registry-scope) + - [Add a trusted dependency](https://bun.sh/docs/guides/trusted) + - [Configuring a monorepo using workspaces](https://bun.sh/docs/guides/workspaces) + - [Generate a human-readable lockfile](https://bun.sh/docs/guides/yarnlock) + +- Process + - [Parse command-line arguments](https://bun.sh/docs/guides/argv) + - [Listen for CTRL+C](https://bun.sh/docs/guides/ctrl-c) + - [Spawn a child process and communicate using IPC](https://bun.sh/docs/guides/ipc) + - [Get the process uptime in nanoseconds](https://bun.sh/docs/guides/nanoseconds) + - [Listen to OS signals](https://bun.sh/docs/guides/os-signals) + - [Read stderr from a child process](https://bun.sh/docs/guides/spawn-stderr) + - [Read stdout from a child process](https://bun.sh/docs/guides/spawn-stdout) + - [Spawn a child process](https://bun.sh/docs/guides/spawn) + - [Read from stdin](https://bun.sh/docs/guides/stdin) + +- Read file + - [Read a file to an ArrayBuffer](https://bun.sh/docs/guides/arraybuffer) + - [Read a file to a Buffer](https://bun.sh/docs/guides/buffer) + - [Check if a file exists](https://bun.sh/docs/guides/exists) + - [Read a JSON file](https://bun.sh/docs/guides/json) + - [Get the MIME type of a file](https://bun.sh/docs/guides/mime) + - [Read a file as a ReadableStream](https://bun.sh/docs/guides/stream) + - [Read a file as a string](https://bun.sh/docs/guides/string) + - [Read a file to a Uint8Array](https://bun.sh/docs/guides/uint8array) + - [Watch a directory for changes](https://bun.sh/docs/guides/watch) + +- Runtime + - [Install and run Bun in GitHub Actions](https://bun.sh/docs/guides/cicd) + - [Define and replace static globals & constants](https://bun.sh/docs/guides/define-constant) + - [Import HTML file as text](https://bun.sh/docs/guides/import-html) + - [Import a JSON file](https://bun.sh/docs/guides/import-json) + - [Import a TOML file](https://bun.sh/docs/guides/import-toml) + - [Read environment variables](https://bun.sh/docs/guides/read-env) + - [Set environment variables](https://bun.sh/docs/guides/set-env) + - [Run a Shell Command](https://bun.sh/docs/guides/shell) + - [Set a time zone in Bun](https://bun.sh/docs/guides/timezone) + - [Re-map import paths](https://bun.sh/docs/guides/tsconfig-paths) + - [Install TypeScript declarations for Bun](https://bun.sh/docs/guides/typescript) + - [Debugging Bun with the VS Code extension](https://bun.sh/docs/guides/vscode-debugger) + - [Debugging Bun with the web debugger](https://bun.sh/docs/guides/web-debugger) + +- Streams + - [Convert a Node.js Readable to an ArrayBuffer](https://bun.sh/docs/guides/node-readable-to-arraybuffer) + - [Convert a Node.js Readable to a Blob](https://bun.sh/docs/guides/node-readable-to-blob) + - [Convert a Node.js Readable to JSON](https://bun.sh/docs/guides/node-readable-to-json) + - [Convert a Node.js Readable to a string](https://bun.sh/docs/guides/node-readable-to-string) + - [Convert a ReadableStream to an array of chunks](https://bun.sh/docs/guides/to-array) + - [Convert a ReadableStream to an ArrayBuffer](https://bun.sh/docs/guides/to-arraybuffer) + - [Convert a ReadableStream to a Blob](https://bun.sh/docs/guides/to-blob) + - [Convert a ReadableStream to a Buffer](https://bun.sh/docs/guides/to-buffer) + - [Convert a ReadableStream to JSON](https://bun.sh/docs/guides/to-json) + - [Convert a ReadableStream to a string](https://bun.sh/docs/guides/to-string) + - [Convert a ReadableStream to a Uint8Array](https://bun.sh/docs/guides/to-typedarray) + +- Test + - [Bail early with the Bun test runner](https://bun.sh/docs/guides/bail) + - [Set a code coverage threshold with the Bun test runner](https://bun.sh/docs/guides/coverage-threshold) + - [Generate code coverage reports with the Bun test runner](https://bun.sh/docs/guides/coverage) + - [Write browser DOM tests with Bun and happy-dom](https://bun.sh/docs/guides/happy-dom) + - [Migrate from Jest to Bun's test runner](https://bun.sh/docs/guides/migrate-from-jest) + - [Set the system time in Bun's test runner](https://bun.sh/docs/guides/mock-clock) + - [Mock functions in `bun test`](https://bun.sh/docs/guides/mock-functions) + - [Re-run tests multiple times with the Bun test runner](https://bun.sh/docs/guides/rerun-each) + - [Run your tests with the Bun test runner](https://bun.sh/docs/guides/run-tests) + - [Skip tests with the Bun test runner](https://bun.sh/docs/guides/skip-tests) + - [Use snapshot testing in `bun test`](https://bun.sh/docs/guides/snapshot) + - [Spy on methods in `bun test`](https://bun.sh/docs/guides/spy-on) + - [Set a per-test timeout with the Bun test runner](https://bun.sh/docs/guides/timeout) + - [Mark a test as a "todo" with the Bun test runner](https://bun.sh/docs/guides/todo-tests) + - [Update snapshots in `bun test`](https://bun.sh/docs/guides/update-snapshots) + - [Run tests in watch mode with Bun](https://bun.sh/docs/guides/watch-mode) + +- Util + - [Encode and decode base64 strings](https://bun.sh/docs/guides/base64) + - [Check if two objects are deeply equal](https://bun.sh/docs/guides/deep-equals) + - [Compress and decompress data with DEFLATE](https://bun.sh/docs/guides/deflate) + - [Detect when code is executed with Bun](https://bun.sh/docs/guides/detect-bun) + - [Check if the current file is the entrypoint](https://bun.sh/docs/guides/entrypoint) + - [Escape an HTML string](https://bun.sh/docs/guides/escape-html) + - [Convert a file URL to an absolute path](https://bun.sh/docs/guides/file-url-to-path) + - [Compress and decompress data with gzip](https://bun.sh/docs/guides/gzip) + - [Hash a password](https://bun.sh/docs/guides/hash-a-password) + - [Get the directory of the current file](https://bun.sh/docs/guides/import-meta-dir) + - [Get the file name of the current file](https://bun.sh/docs/guides/import-meta-file) + - [Get the absolute path of the current file](https://bun.sh/docs/guides/import-meta-path) + - [Get the absolute path to the current entrypoint](https://bun.sh/docs/guides/main) + - [Convert an absolute path to a file URL](https://bun.sh/docs/guides/path-to-file-url) + - [Sleep for a fixed number of milliseconds](https://bun.sh/docs/guides/sleep) + - [Get the current Bun version](https://bun.sh/docs/guides/version) + - [Get the path to an executable bin file](https://bun.sh/docs/guides/which-path-to-executable-bin) + +- WebSocket + - [Enable compression for WebSocket messages](https://bun.sh/docs/guides/compression) + - [Set per-socket contextual data on a WebSocket](https://bun.sh/docs/guides/context) + - [Build a publish-subscribe WebSocket server](https://bun.sh/docs/guides/pubsub) + - [Build a simple WebSocket server](https://bun.sh/docs/guides/simple) + +- Write file + - [Append content to a file](https://bun.sh/docs/guides/append) + - [Write a string to a file](https://bun.sh/docs/guides/basic) + - [Write a Blob to a file](https://bun.sh/docs/guides/blob) + - [Write a file to stdout](https://bun.sh/docs/guides/cat) + - [Copy a file to another location](https://bun.sh/docs/guides/file-cp) + - [Write a file incrementally](https://bun.sh/docs/guides/filesink) + - [Write a Response to a file](https://bun.sh/docs/guides/response) + - [Write to stdout](https://bun.sh/docs/guides/stdout) + - [Write a ReadableStream to a file](https://bun.sh/docs/guides/stream) + - [Delete a file](https://bun.sh/docs/guides/unlink) + ## Contributing Refer to the [Project > Contributing](https://bun.sh/docs/project/contributing) guide to start contributing to Bun. diff --git a/scripts/nav2readme.ts b/scripts/nav2readme.ts index 6d19d42865..73873f521d 100644 --- a/scripts/nav2readme.ts +++ b/scripts/nav2readme.ts @@ -6,8 +6,9 @@ // // import nav from "../docs/nav"; - -function getMarkdown() { +import { readdirSync } from "fs"; +import path from "path"; +function getQuickLinks() { let md = ""; for (const item of nav.items) { @@ -21,6 +22,45 @@ function getMarkdown() { return md; } +async function getGuides() { + let md = ""; + const basePath = path.join(import.meta.dirname, "..", "docs/guides"); + const allGuides = readdirSync(basePath, { withFileTypes: true, recursive: true }); + const promises: Promise<{ name: string; file: string }>[] = []; + for (const guide of allGuides) { + if (guide.isFile() && guide.name.endsWith(".md")) { + const joined = path.join(basePath, guide.name); + promises.push( + Bun.file(joined) + .text() + .then(text => { + const nameI = text.indexOf("name: "); + const name = text.slice(nameI + "name: ".length, text.indexOf("\n", nameI)).trim(); + return { + name, + file: guide.name, + }; + }), + ); + } + } + + const files = await Promise.all(promises); + md += "## Guides " + "\n"; + files.sort((a, b) => a.file.localeCompare(b.file)); + let prevDirname = ""; + for (const { name, file } of files) { + const dirname = path.basename(path.dirname(file)); + if (dirname !== prevDirname) { + md += `\n- ${normalizeSectionName(dirname)} ` + "\n"; + prevDirname = dirname; + } + md += ` - [${name}](https://bun.sh/docs/guides/${path.basename(file, path.extname(file))})` + "\n"; + } + + return md; +} + const text = await Bun.file(Bun.fileURLToPath(import.meta.resolve("../README.md"))).text(); const startI = text.indexOf("## Quick links\n"); if (startI === -1) { @@ -34,7 +74,25 @@ if (contributing === -1) { throw new Error("Could not find ## Contributing in README"); } +const guides = await getGuides(); + const combined = - [text.slice(0, start), getMarkdown(), text.slice(contributing)].map(text => text.trim()).join("\n\n") + "\n"; + [text.slice(0, start), getQuickLinks(), guides, text.slice(contributing)].map(text => text.trim()).join("\n\n") + + "\n"; await Bun.write(Bun.fileURLToPath(import.meta.resolve("../README.md")), combined); + +function normalizeSectionName(name: string) { + if (name.includes("-")) { + return name + .split("-") + .map((s, i) => (i === 0 ? s.charAt(0).toUpperCase() + s.slice(1) : s)) + .join(" "); + } + + name = name.charAt(0).toUpperCase() + name.slice(1); + name = name.replaceAll("Https", "HTTPS"); + name = name.replaceAll("Http", "HTTP"); + name = name.replaceAll("Websocket", "WebSocket"); + return name; +}