bun-types 1.1.37-canary.20241124T140524 → 1.1.37

package/docs/guides/ecosystem/elysia.md

@@ -0,0 +1,31 @@
+---
+name: Build an HTTP server using Elysia and Bun
+---
+
+[Elysia](https://elysiajs.com) is a Bun-first performance focused web framework that takes full advantage of Bun's HTTP, file system, and hot reloading APIs. Get started with `bun create`.
+
+```bash
+$ bun create elysia myapp
+$ cd myapp
+$ bun run dev
+```
+
+---
+
+To define a simple HTTP route and start a server with Elysia:
+
+```ts#server.ts
+import { Elysia } from 'elysia'
+
+const app = new Elysia()
+	.get('/', () => 'Hello Elysia')
+	.listen(8080)
+
+console.log(`🦊 Elysia is running at on port ${app.server?.port}...`)
+```
+
+---
+
+Elysia is a full-featured server framework with Express-like syntax, type inference, middleware, file uploads, and plugins for JWT authentication, tRPC, and more. It's also is one of the [fastest Bun web frameworks](https://github.com/SaltyAom/bun-http-framework-benchmark).
+
+Refer to the Elysia [documentation](https://elysiajs.com/quick-start.html) for more information.

package/docs/guides/ecosystem/express.md

@@ -0,0 +1,40 @@
+---
+name: Build an HTTP server using Express and Bun
+---
+
+Express and other major Node.js HTTP libraries should work out of the box. Bun implements the [`node:http`](https://nodejs.org/api/http.html) and [`node:https`](https://nodejs.org/api/https.html) modules that these libraries rely on.
+
+{% callout %}
+Refer to the [Runtime > Node.js APIs](https://bun.sh/docs/runtime/nodejs-apis#node-http) page for more detailed compatibility information.
+{% /callout %}
+
+```sh
+$ bun add express
+```
+
+---
+
+To define a simple HTTP route and start a server with Express:
+
+```ts#server.ts
+import express from "express";
+
+const app = express();
+const port = 8080;
+
+app.get("/", (req, res) => {
+  res.send("Hello World!");
+});
+
+app.listen(port, () => {
+  console.log(`Listening on port ${port}...`);
+});
+```
+
+---
+
+To start the server on `localhost`:
+
+```sh
+$ bun server.ts
+```

package/docs/guides/ecosystem/hono.md

@@ -0,0 +1,39 @@
+---
+name: Build an HTTP server using Hono and Bun
+---
+
+[Hono](https://github.com/honojs/hono) is a lightweight ultrafast web framework designed for the edge.
+
+```ts
+import { Hono } from "hono";
+const app = new Hono();
+
+app.get("/", c => c.text("Hono!"));
+
+export default app;
+```
+
+---
+
+Use `create-hono` to get started with one of Hono's project templates. Select `bun` when prompted for a template.
+
+```bash
+$ bun create hono myapp
+✔ Which template do you want to use? › bun
+cloned honojs/starter#main to /path/to/myapp
+✔ Copied project files
+$ cd myapp
+$ bun install
+```
+
+---
+
+Then start the dev server and visit [localhost:3000](http://localhost:3000).
+
+```bash
+$ bun run dev
+```
+
+---
+
+Refer to Hono's guide on [getting started with Bun](https://hono.dev/getting-started/bun) for more information.

package/docs/guides/ecosystem/mongoose.md

@@ -0,0 +1,87 @@
+---
+name: Read and write data to MongoDB using Mongoose and Bun
+---
+
+MongoDB and Mongoose work out of the box with Bun. This guide assumes you've already installed MongoDB and are running it as background process/service on your development machine. Follow [this guide](https://www.mongodb.com/docs/manual/installation/) for details.
+
+---
+
+Once MongoDB is running, create a directory and initialize it with `bun init`.
+
+```bash
+mkdir mongoose-app
+cd mongoose-app
+bun init
+```
+
+---
+
+Then add Mongoose as a dependency.
+
+```bash
+bun add mongoose
+```
+
+---
+
+In `schema.ts` we'll declare and export a simple `Animal` model.
+
+```ts#schema.ts
+import * as mongoose from 'mongoose';
+
+const animalSchema = new mongoose.Schema(
+  {
+    name: {type: String, required: true},
+    sound: {type: String, required: true},
+  },
+  {
+    methods: {
+      speak() {
+        console.log(`${this.sound}!`);
+      },
+    },
+  }
+);
+
+export type Animal = mongoose.InferSchemaType<typeof animalSchema>;
+export const Animal = mongoose.model('Animal', animalSchema);
+```
+
+---
+
+Now from `index.ts` we can import `Animal`, connect to MongoDB, and add some data to our database.
+
+```ts#index.ts
+import * as mongoose from 'mongoose';
+import {Animal} from './schema';
+
+// connect to database
+await mongoose.connect('mongodb://127.0.0.1:27017/mongoose-app');
+
+// create new Animal
+const cow = new Animal({
+  name: 'Cow',
+  sound: 'Moo',
+});
+await cow.save(); // saves to the database
+
+// read all Animals
+const animals = await Animal.find();
+animals[0].speak(); // logs "Moo!"
+
+// disconnect
+await mongoose.disconnect();
+```
+
+---
+
+Let's run this with `bun run`.
+
+```bash
+$ bun run index.ts
+Moo!
+```
+
+---
+
+This is a simple introduction to using Mongoose with TypeScript and Bun. As you build your application, refer to the official [MongoDB](https://docs.mongodb.com/) and [Mongoose](https://mongoosejs.com/docs/) sites for complete documentation.

package/docs/guides/ecosystem/neon-drizzle.md

@@ -0,0 +1,220 @@
+---
+name: Use Neon Postgres through Drizzle ORM
+---
+
+[Neon](https://neon.tech/) is a fully managed serverless Postgres, separating compute and storage to offer features like autoscaling, branching and bottomless storage. Neon can be used from Bun directly using the `@neondatabase/serverless` driver or through an ORM like `Drizzle`. 
+
+Drizzle ORM supports both a SQL-like "query builder" API and an ORM-like [Queries API](https://orm.drizzle.team/docs/rqb). Get started by creating a project directory, initializing the directory using `bun init`, and installing Drizzle and the [Neon serverless driver](https://github.com/neondatabase/serverless/). 
+
+```sh
+$ mkdir bun-drizzle-neon
+$ cd bun-drizzle-neon
+$ bun init -y
+$ bun add drizzle-orm @neondatabase/serverless
+$ bun add -D drizzle-kit
+```
+
+---
+
+Create a `.env.local` file and add your [Neon Postgres connection string](https://neon.tech/docs/connect/connect-from-any-app) to it.
+
+```sh
+DATABASE_URL=postgresql://username:password@ep-adj-noun-guid.us-east-1.aws.neon.tech/neondb?sslmode=require
+```
+
+---
+
+We will connect to the Neon database using the Neon serverless driver, wrapped in a Drizzle database instance.
+
+```ts#db.ts
+import { neon } from '@neondatabase/serverless';
+import { drizzle } from 'drizzle-orm/neon-http';
+
+// Bun automatically loads the DATABASE_URL from .env.local
+// Refer to: https://bun.sh/docs/runtime/env for more information
+const sql = neon(process.env.DATABASE_URL!);
+
+export const db = drizzle(sql);
+```
+
+---
+
+To see the database in action, add these lines to `index.ts`.
+
+```ts#index.ts
+import { db } from "./db";
+import { sql } from "drizzle-orm";
+
+const query = sql`select 'hello world' as text`;
+const result = await db.execute(query);
+console.log(result.rows);
+```
+
+---
+
+Then run `index.ts` with Bun. 
+
+```sh
+$ bun run index.ts
+[
+  {
+    text: "hello world",
+  }
+]
+```
+
+---
+
+We can define a schema for our database using Drizzle ORM primitives. Create a `schema.ts` file and add this code. 
+
+```ts#schema.ts
+import { pgTable, integer, serial, text, timestamp } from "drizzle-orm/pg-core";
+
+export const authors = pgTable("authors", {
+  id: serial("id").primaryKey(),
+  name: text("name").notNull(),
+  bio: text("bio"),
+  createdAt: timestamp("created_at").notNull().defaultNow(),
+});
+```
+
+---
+
+We then use the `drizzle-kit` CLI to generate an initial SQL migration.
+
+```sh
+$ bunx drizzle-kit generate --dialect postgresql --schema ./schema.ts --out ./drizzle
+```
+
+---
+
+This creates a new `drizzle` directory containing a `.sql` migration file and `meta` directory.
+
+```txt
+drizzle
+├── 0000_aspiring_post.sql
+└── meta
+    ├── 0000_snapshot.json
+    └── _journal.json
+```
+
+---
+
+We can execute these migrations with a simple `migrate.ts` script. This script creates a new connection to the Neon database and executes all unexecuted migrations in the `drizzle` directory.
+
+```ts#migrate.ts
+import { db } from './db';
+import { migrate } from "drizzle-orm/neon-http/migrator";
+
+const main = async () => {
+  try {
+    await migrate(db, { migrationsFolder: "drizzle" });
+    console.log("Migration completed");
+  } catch (error) {
+    console.error("Error during migration:", error);
+    process.exit(1);
+  }
+};
+
+main();
+```
+
+---
+
+We can run this script with `bun` to execute the migration.
+
+```sh
+$ bun run migrate.ts
+Migration completed
+```
+
+---
+
+We can now add some data to our database. Create a `seed.ts` file with the following contents.
+
+```ts#seed.ts
+import { db } from "./db";
+import * as schema from "./schema";
+
+async function seed() {
+  await db.insert(schema.authors).values([
+    {
+      name: "J.R.R. Tolkien",
+      bio: "The creator of Middle-earth and author of The Lord of the Rings.",
+    },
+    {
+      name: "George R.R. Martin",
+      bio: "The author of the epic fantasy series A Song of Ice and Fire.",
+    },
+    {
+      name: "J.K. Rowling",
+      bio: "The creator of the Harry Potter series.",
+    },
+  ]);
+}
+
+async function main() {
+  try {
+    await seed();
+    console.log("Seeding completed");
+  } catch (error) {
+    console.error("Error during seeding:", error);
+    process.exit(1);
+  }
+}
+
+main();
+```
+
+---
+
+Then run this file.
+
+```sh
+$ bun run seed.ts
+Seeding completed
+```
+
+---
+
+We now have a database with a schema and sample data. We can use Drizzle to query it. Replace the contents of `index.ts` with the following.
+
+```ts#index.ts
+import * as schema from "./schema";
+import { db } from "./db";
+
+const result = await db.select().from(schema.authors);
+console.log(result);
+```
+
+---
+
+Then run the file. You should see the three authors we inserted.
+
+```sh
+$ bun run index.ts
+[
+  {
+    id: 1,
+    name: "J.R.R. Tolkien",
+    bio: "The creator of Middle-earth and author of The Lord of the Rings.",
+    createdAt: 2024-05-11T10:28:46.029Z,
+  }, {
+    id: 2,
+    name: "George R.R. Martin",
+    bio: "The author of the epic fantasy series A Song of Ice and Fire.",
+    createdAt: 2024-05-11T10:28:46.029Z,
+  }, {
+    id: 3,
+    name: "J.K. Rowling",
+    bio: "The creator of the Harry Potter series.",
+    createdAt: 2024-05-11T10:28:46.029Z,
+  }
+]
+```
+
+---
+
+This example used the Neon serverless driver's SQL-over-HTTP functionality. Neon's serverless driver also exposes `Client` and `Pool` constructors to enable sessions, interactive transactions, and node-postgres compatibility. Refer to [Neon's documentation](https://neon.tech/docs/serverless/serverless-driver) for a complete overview. 
+
+Refer to the [Drizzle website](https://orm.drizzle.team/docs/overview) for more documentation on using the Drizzle ORM.

package/docs/guides/ecosystem/neon-serverless-postgres.md

@@ -0,0 +1,55 @@
+---
+name: Use Neon's Serverless Postgres with Bun
+---
+
+[Neon](https://neon.tech/) is a fully managed serverless Postgres. Neon separates compute and storage to offer modern developer features such as autoscaling, branching, bottomless storage, and more.
+
+---
+
+Get started by creating a project directory, initializing the directory using `bun init`, and adding the [Neon serverless driver](https://github.com/neondatabase/serverless/) as a project dependency.
+
+```sh
+$ mkdir bun-neon-postgres
+$ cd bun-neon-postgres
+$ bun init -y
+$ bun add @neondatabase/serverless
+```
+
+---
+
+Create a `.env.local` file and add your [Neon Postgres connection string](https://neon.tech/docs/connect/connect-from-any-app) to it.
+
+```sh
+DATABASE_URL=postgresql://username:password@ep-adj-noun-guid.us-east-1.aws.neon.tech/neondb?sslmode=require
+```
+
+---
+
+Paste the following code into your project's `index.ts` file.
+
+```ts
+import { neon } from "@neondatabase/serverless";
+
+// Bun automatically loads the DATABASE_URL from .env.local
+// Refer to: https://bun.sh/docs/runtime/env for more information
+const sql = neon(process.env.DATABASE_URL);
+
+const rows = await sql`SELECT version()`;
+
+console.log(rows[0].version);
+```
+
+---
+
+Start the program using `bun ./index.ts`. The Postgres version should be printed to the console.
+
+```sh
+$ bun ./index.ts
+PostgreSQL 16.2 on x86_64-pc-linux-gnu, compiled by gcc (Debian 10.2.1-6) 10.2.1 20210110, 64-bit
+```
+
+---
+
+This example used the Neon serverless driver's SQL-over-HTTP functionality. Neon's serverless driver also exposes `Client` and `Pool` constructors to enable sessions, interactive transactions, and node-postgres compatibility.
+
+Refer to [Neon's documentation](https://neon.tech/docs/serverless/serverless-driver) for a complete overview of the serverless driver.

package/docs/guides/ecosystem/nextjs.md

@@ -0,0 +1,38 @@
+---
+name: Build an app with Next.js and Bun
+---
+
+Initialize a Next.js app with `create-next-app`. This will scaffold a new Next.js project and automatically install dependencies.
+
+```sh
+$ bun create next-app
+✔ What is your project named? … my-app
+✔ Would you like to use TypeScript with this project? … No / Yes
+✔ Would you like to use ESLint with this project? … No / Yes
+✔ Would you like to use `src/` directory with this project? … No / Yes
+✔ Would you like to use experimental `app/` directory with this project? … No / Yes
+✔ What import alias would you like configured? … @/*
+Creating a new Next.js app in /path/to/my-app.
+```
+
+---
+
+To start the dev server with Bun, run `bun --bun run dev` from the project root.
+
+```sh
+$ cd my-app
+$ bun --bun run dev
+```
+
+---
+
+To run the dev server with Node.js instead, omit `--bun`.
+
+```sh
+$ cd my-app
+$ bun run dev
+```
+
+---
+
+Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. Any changes you make to `(pages/app)/index.tsx` will be hot-reloaded in the browser.

package/docs/guides/ecosystem/nuxt.md

@@ -0,0 +1,56 @@
+---
+name: Build an app with Nuxt and Bun
+---
+
+Bun supports [Nuxt](https://nuxt.com) out of the box. Initialize a Nuxt app with official `nuxi` CLI.
+
+```sh
+$ bunx nuxi init my-nuxt-app
+✔ Which package manager would you like to use?
+bun
+◐ Installing dependencies...
+bun install v1.x (16b4bf34)
+ + @nuxt/devtools@0.8.2
+ + nuxt@3.7.0
+ 785 packages installed [2.67s]
+✔ Installation completed.
+✔ Types generated in .nuxt
+✨ Nuxt project has been created with the v3 template. Next steps:
+ › cd my-nuxt-app
+ › Start development server with bun run dev
+```
+
+---
+
+To start the dev server, run `bun --bun run dev` from the project root. This will execute the `nuxt dev` command (as defined in the `"dev"` script in `package.json`).
+
+{% callout %}
+The `nuxt` CLI uses Node.js by default; passing the `--bun` flag forces the dev server to use the Bun runtime instead.
+{% /callout %}
+
+```
+$ cd my-nuxt-app
+$ bun --bun run dev
+ $ nuxt dev
+Nuxi 3.6.5
+Nuxt 3.6.5 with Nitro 2.5.2
+  > Local:    http://localhost:3000/
+  > Network:  http://192.168.0.21:3000/
+  > Network:  http://[fd8a:d31d:481c:4883:1c64:3d90:9f83:d8a2]:3000/
+
+✔ Nuxt DevTools is enabled v0.8.0 (experimental)
+ℹ Vite client warmed up in 547ms
+✔ Nitro built in 244 ms
+```
+
+---
+
+Once the dev server spins up, open [http://localhost:3000](http://localhost:3000) to see the app. The app will render Nuxt's built-in `NuxtWelcome` template component.
+
+To start developing your app, replace `<NuxtWelcome />` in `app.vue` with your own UI.
+
+{% image src="https://github.com/oven-sh/bun/assets/3084745/2c683ecc-3298-4bb0-b8c0-cf4cfaea1daa" caption="Demo Nuxt app running on localhost" /%}
+
+---
+
+Refer to the [Nuxt website](https://nuxt.com/docs) for complete documentation.

package/docs/guides/ecosystem/pm2.md

@@ -0,0 +1,57 @@
+---
+name: Run Bun as a daemon with PM2
+---
+
+[PM2](https://pm2.keymetrics.io/) is a popular process manager that manages and runs your applications as daemons (background processes).
+
+It offers features like process monitoring, automatic restarts, and easy scaling. Using a process manager is common when deploying a Bun application on a cloud-hosted virtual private server (VPS), as it:
+
+- Keeps your Node.js application running continuously.
+- Ensure high availability and reliability of your application.
+- Monitor and manage multiple processes with ease.
+- Simplify the deployment process.
+
+---
+
+You can use PM2 with Bun in two ways: as a CLI option or in a configuration file.
+
+### With `--interpreter`
+
+---
+
+To start your application with PM2 and Bun as the interpreter, open your terminal and run the following command:
+
+```bash
+pm2 start --interpreter ~/.bun/bin/bun index.ts
+```
+
+---
+
+### With a configuration file
+
+---
+
+Alternatively, you can create a PM2 configuration file. Create a file named `pm2.config.js` in your project directory and add the following content.
+
+```javascript
+module.exports = {
+  name: "app", // Name of your application
+  script: "index.ts", // Entry point of your application
+  interpreter: "bun", // Bun interpreter
+  env: {
+    PATH: `${process.env.HOME}/.bun/bin:${process.env.PATH}`, // Add "~/.bun/bin/bun" to PATH
+  }
+};
+```
+
+---
+
+After saving the file, you can start your application with PM2
+
+```bash
+pm2 start pm2.config.js
+```
+
+---
+
+That’s it! Your JavaScript/TypeScript web server is now running as a daemon with PM2 using Bun as the interpreter.