bun-types 1.3.2-canary.20251106T140813 → 1.3.2

package/docs/guides/ecosystem/edgedb.mdx

@@ -0,0 +1,257 @@
+---
+title: Use EdgeDB with Bun
+sidebarTitle: EdgeDB with Bun
+mode: center
+---
+
+EdgeDB is a graph-relational database powered by Postgres under the hood. It provides a declarative schema language, migrations system, and object-oriented query language, in addition to supporting raw SQL queries. It solves the object-relational mapping problem at the database layer, eliminating the need for an ORM library in your application code.
+
+---
+
+First, [install EdgeDB](https://www.edgedb.com/install) if you haven't already.
+
+<CodeGroup>
+
+```sh Linux/macOS terminal icon="terminal"
+curl --proto '=https' --tlsv1.2 -sSf https://sh.edgedb.com | sh
+```
+
+```sh Windows terminal icon="windows"
+iwr https://ps1.edgedb.com -useb | iex
+```
+
+</CodeGroup>
+
+---
+
+Use `bun init` to create a fresh project.
+
+```sh terminal icon="terminal"
+mkdir my-edgedb-app
+cd my-edgedb-app
+bun init -y
+```
+
+---
+
+We'll use the EdgeDB CLI to initialize an EdgeDB instance for our project. This creates an `edgedb.toml` file in our project root.
+
+```sh terminal icon="terminal"
+edgedb project init
+```
+
+```txt
+No `edgedb.toml` found in `/Users/colinmcd94/Documents/bun/fun/examples/my-edgedb-app` or above
+Do you want to initialize a new project? [Y/n]
+> Y
+Specify the name of EdgeDB instance to use with this project [default: my_edgedb_app]:
+> my_edgedb_app
+Checking EdgeDB versions...
+Specify the version of EdgeDB to use with this project [default: x.y]:
+> x.y
+┌─────────────────────┬────────────────────────────────────────────────────────────────────────┐
+│ Project directory   │ /Users/colinmcd94/Documents/bun/fun/examples/my-edgedb-app             │
+│ Project config      │ /Users/colinmcd94/Documents/bun/fun/examples/my-edgedb-app/edgedb.toml │
+│ Schema dir (empty)  │ /Users/colinmcd94/Documents/bun/fun/examples/my-edgedb-app/dbschema    │
+│ Installation method │ portable package                                                       │
+│ Version             │ x.y+6d5921b                                                            │
+│ Instance name       │ my_edgedb_app                                                          │
+└─────────────────────┴────────────────────────────────────────────────────────────────────────┘
+Version x.y+6d5921b is already downloaded
+Initializing EdgeDB instance...
+Applying migrations...
+Everything is up to date. Revision initial
+Project initialized.
+To connect to my_edgedb_app, run `edgedb`
+```
+
+---
+
+To see if the database is running, let's open a REPL and run a simple query.
+
+```sh terminal icon="terminal"
+edgedb
+edgedb> select 1 + 1;
+```
+
+```txt
+2
+```
+
+Then run `\quit` to exit the REPL.
+
+```sh terminal icon="terminal"
+edgedb> \quit
+```
+
+---
+
+With the project initialized, we can define a schema. The `edgedb project init` command already created a `dbschema/default.esdl` file to contain our schema.
+
+```txt File Tree icon="folder-tree"
+dbschema
+├── default.esdl
+└── migrations
+```
+
+---
+
+Open that file and paste the following contents.
+
+```ts default.esdl icon="file-code"
+module default {
+  type Movie {
+    required title: str;
+    releaseYear: int64;
+  }
+};
+```
+
+---
+
+Then generate and apply an initial migration.
+
+```sh terminal icon="terminal"
+edgedb migration create
+```
+
+```txt
+Created /Users/colinmcd94/Documents/bun/fun/examples/my-edgedb-app/dbschema/migrations/00001.edgeql, id: m1uwekrn4ni4qs7ul7hfar4xemm5kkxlpswolcoyqj3xdhweomwjrq
+```
+
+```sh terminal icon="terminal"
+edgedb migrate
+```
+
+```txt
+Applied m1uwekrn4ni4qs7ul7hfar4xemm5kkxlpswolcoyqj3xdhweomwjrq (00001.edgeql)
+```
+
+---
+
+With our schema applied, let's execute some queries using EdgeDB's JavaScript client library. We'll install the client library and EdgeDB's codegen CLI, and create a `seed.ts`.file.
+
+```sh terminal icon="terminal"
+bun add edgedb
+bun add -D @edgedb/generate
+touch seed.ts
+```
+
+---
+
+Paste the following code into `seed.ts`.
+
+The client auto-connects to the database. We insert a couple movies using the `.execute()` method. We will use EdgeQL's `for` expression to turn this bulk insert into a single optimized query.
+
+```ts seed.ts icon="/icons/typescript.svg"
+import { createClient } from "edgedb";
+
+const client = createClient();
+
+const INSERT_MOVIE = `
+  with movies := <array<tuple<title: str, year: int64>>>$movies
+  for movie in array_unpack(movies) union (
+    insert Movie {
+      title := movie.title,
+      releaseYear := movie.year,
+    }
+  )
+`;
+
+const movies = [
+  { title: "The Matrix", year: 1999 },
+  { title: "The Matrix Reloaded", year: 2003 },
+  { title: "The Matrix Revolutions", year: 2003 },
+];
+
+await client.execute(INSERT_MOVIE, { movies });
+
+console.log(`Seeding complete.`);
+process.exit();
+```
+
+---
+
+Then run this file with Bun.
+
+```sh terminal icon="terminal"
+bun run seed.ts
+```
+
+```txt
+Seeding complete.
+```
+
+---
+
+EdgeDB implements a number of code generation tools for TypeScript. To query our newly seeded database in a typesafe way, we'll use `@edgedb/generate` to code-generate the EdgeQL query builder.
+
+```sh terminal icon="terminal"
+bunx @edgedb/generate edgeql-js
+```
+
+```txt
+Generating query builder...
+Detected tsconfig.json, generating TypeScript files.
+   To override this, use the --target flag.
+   Run `npx @edgedb/generate --help` for full options.
+Introspecting database schema...
+Writing files to ./dbschema/edgeql-js
+Generation complete! 🤘
+Checking the generated query builder into version control
+is not recommended. Would you like to update .gitignore to ignore
+the query builder directory? The following line will be added:
+
+   dbschema/edgeql-js
+
+[y/n] (leave blank for "y")
+> y
+```
+
+---
+
+In `index.ts`, we can import the generated query builder from `./dbschema/edgeql-js` and write a simple select query.
+
+```ts index.ts icon="/icons/typescript.svg"
+import { createClient } from "edgedb";
+import e from "./dbschema/edgeql-js";
+
+const client = createClient();
+
+const query = e.select(e.Movie, () => ({
+  title: true,
+  releaseYear: true,
+}));
+
+const results = await query.run(client);
+console.log(results);
+
+results; // { title: string, releaseYear: number | null }[]
+```
+
+---
+
+Running the file with Bun, we can see the list of movies we inserted.
+
+```sh terminal icon="terminal"
+bun run index.ts
+```
+
+```txt
+[
+  {
+    title: "The Matrix",
+    releaseYear: 1999
+  }, {
+    title: "The Matrix Reloaded",
+    releaseYear: 2003
+  }, {
+    title: "The Matrix Revolutions",
+    releaseYear: 2003
+  }
+]
+```
+
+---
+
+For complete documentation, refer to the [EdgeDB docs](https://www.edgedb.com/docs).

package/docs/guides/ecosystem/elysia.mdx

@@ -0,0 +1,31 @@
+---
+title: Build an HTTP server using Elysia and Bun
+sidebarTitle: Elysia with Bun
+mode: center
+---
+
+[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 terminal icon="terminal"
+bun create elysia myapp
+cd myapp
+bun run dev
+```
+
+---
+
+To define a simple HTTP route and start a server with Elysia:
+
+```ts server.ts icon="/icons/typescript.svg"
+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.mdx

@@ -0,0 +1,43 @@
+---
+title: Build an HTTP server using Express and Bun
+sidebarTitle: Express with Bun
+mode: center
+---
+
+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.
+
+<Note>
+  Refer to the [Runtime > Node.js APIs](https://bun.com/docs/runtime/nodejs-apis#node-http) page for more detailed
+  compatibility information.
+</Note>
+
+```sh terminal icon="terminal"
+bun add express
+```
+
+---
+
+To define a simple HTTP route and start a server with Express:
+
+```ts server.ts icon="/icons/typescript.svg"
+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 terminal icon="terminal"
+bun server.ts
+```

package/docs/guides/ecosystem/hono.mdx

@@ -0,0 +1,47 @@
+---
+title: Build an HTTP server using Hono and Bun
+sidebarTitle: Hono with Bun
+mode: center
+---
+
+[Hono](https://github.com/honojs/hono) is a lightweight ultrafast web framework designed for the edge.
+
+```ts server.ts icon="/icons/typescript.svg"
+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.
+
+```sh terminal icon="terminal"
+bun create hono myapp
+```
+
+```txt
+✔ Which template do you want to use? › bun
+cloned honojs/starter#main to /path/to/myapp
+✔ Copied project files
+```
+
+```sh terminal icon="terminal"
+cd myapp
+bun install
+```
+
+---
+
+Then start the dev server and visit [localhost:3000](http://localhost:3000).
+
+```sh terminal icon="terminal"
+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.mdx

@@ -0,0 +1,92 @@
+---
+title: Read and write data to MongoDB using Mongoose and Bun
+sidebarTitle: Mongoose with Bun
+mode: center
+---
+
+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`.
+
+```sh terminal icon="terminal"
+mkdir mongoose-app
+cd mongoose-app
+bun init
+```
+
+---
+
+Then add Mongoose as a dependency.
+
+```sh terminal icon="terminal"
+bun add mongoose
+```
+
+---
+
+In `schema.ts` we'll declare and export a simple `Animal` model.
+
+```ts schema.ts icon="/icons/typescript.svg"
+import * as mongoose from "mongoose";
+
+const animalSchema = new mongoose.Schema(
+  {
+    title: { 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 icon="/icons/typescript.svg"
+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({
+  title: "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 terminal icon="terminal"
+bun run index.ts
+```
+
+```txt
+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.mdx

@@ -0,0 +1,234 @@
+---
+title: Use Neon Postgres through Drizzle ORM
+sidebarTitle: Neon Drizzle with Bun
+mode: center
+---
+
+[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 terminal icon="terminal"
+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.
+
+```txt .env.local icon="settings"
+DATABASE_URL=postgresql://usertitle: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 icon="/icons/typescript.svg"
+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.com/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 icon="/icons/typescript.svg"
+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 terminal icon="terminal"
+bun run index.ts
+```
+
+```txt
+[
+  {
+    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 icon="/icons/typescript.svg"
+import { pgTable, integer, serial, text, timestamp } from "drizzle-orm/pg-core";
+
+export const authors = pgTable("authors", {
+  id: serial("id").primaryKey(),
+  title: 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 File Tree icon="folder-tree"
+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 terminal icon="terminal"
+bun run migrate.ts
+```
+
+```txt
+Migration completed
+```
+
+---
+
+We can now add some data to our database. Create a `seed.ts` file with the following contents.
+
+```ts seed.ts icon="/icons/typescript.svg"
+import { db } from "./db";
+import * as schema from "./schema";
+
+async function seed() {
+  await db.insert(schema.authors).values([
+    {
+      title: "J.R.R. Tolkien",
+      bio: "The creator of Middle-earth and author of The Lord of the Rings.",
+    },
+    {
+      title: "George R.R. Martin",
+      bio: "The author of the epic fantasy series A Song of Ice and Fire.",
+    },
+    {
+      title: "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 terminal icon="terminal"
+bun run seed.ts
+```
+
+```txt
+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 icon="/icons/typescript.svg"
+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 terminal icon="terminal"
+bun run index.ts
+```
+
+```txt
+[
+  {
+    id: 1,
+    title: "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,
+    title: "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,
+    title: "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.