bun-types 1.1.37-canary.20241124T140524 → 1.1.37

package/docs/guides/ecosystem/astro.md

@@ -0,0 +1,72 @@
+---
+name: Build an app with Astro and Bun
+---
+
+Initialize a fresh Astro app with `bun create astro`. The `create-astro` package detects when you are using `bunx` and will automatically install dependencies using `bun`.
+
+```sh
+$ bun create astro
+╭─────╮  Houston:
+│ ◠ ◡ ◠  We're glad to have you on board.
+╰─────╯
+
+ astro   v3.1.4 Launch sequence initiated.
+
+   dir   Where should we create your new project?
+         ./fumbling-field
+
+  tmpl   How would you like to start your new project?
+         Use blog template
+      ✔  Template copied
+
+  deps   Install dependencies?
+         Yes
+      ✔  Dependencies installed
+
+    ts   Do you plan to write TypeScript?
+         Yes
+
+   use   How strict should TypeScript be?
+         Strict
+      ✔  TypeScript customized
+
+   git   Initialize a new git repository?
+         Yes
+      ✔  Git initialized
+
+  next   Liftoff confirmed. Explore your project!
+
+         Enter your project directory using cd ./fumbling-field
+         Run `bun run dev` to start the dev server. CTRL+C to stop.
+         Add frameworks like react or tailwind using astro add.
+
+         Stuck? Join us at https://astro.build/chat
+
+╭─────╮  Houston:
+│ ◠ ◡ ◠  Good luck out there, astronaut! 🚀
+╰─────╯
+```
+
+---
+
+Start the dev server with `bunx`.
+
+By default, Bun will run the dev server with Node.js. To use the Bun runtime instead, use the `--bun` flag.
+
+```sh
+$ bunx --bun astro dev
+  🚀  astro  v3.1.4 started in 200ms
+
+  ┃ Local    http://localhost:4321/
+  ┃ Network  use --host to expose
+```
+
+---
+
+Open [http://localhost:4321](http://localhost:4321) with your browser to see the result. Astro will hot-reload your app as you edit your source files.
+
+{% image src="https://i.imgur.com/Dswiu6w.png" caption="An Astro v3 starter app running on Bun" %}
+
+---
+
+Refer to the [Astro docs](https://docs.astro.build/en/getting-started/) for complete documentation.

package/docs/guides/ecosystem/discordjs.md

@@ -0,0 +1,77 @@
+---
+name: Create a Discord bot
+---
+
+Discord.js works out of the box with Bun. Let's write a simple bot. First create a directory and initialize it with `bun init`.
+
+```bash
+mkdir my-bot
+cd my-bot
+bun init
+```
+
+---
+
+Now install Discord.js.
+
+```bash
+bun add discord.js
+```
+
+---
+
+Before we go further, we need to go to the [Discord developer portal](https://discord.com/developers/applications), login/signup, create a new _Application_, then create a new _Bot_ within that application. Follow the [official guide](https://discordjs.guide/preparations/setting-up-a-bot-application.html#creating-your-bot) for step-by-step instructions.
+
+---
+
+Once complete, you'll be presented with your bot's _private key_. Let's add this to a file called `.env.local`. Bun automatically reads this file and loads it into `process.env`.
+
+{% callout %}
+This is an example token that has already been invalidated.
+{% /callout %}
+
+```txt#.env.local
+DISCORD_TOKEN=NzkyNzE1NDU0MTk2MDg4ODQy.X-hvzA.Ovy4MCQywSkoMRRclStW4xAYK7I
+```
+
+---
+
+Be sure to add `.env.local` to your `.gitignore`! It is dangerous to check your bot's private key into version control.
+
+```txt#.gitignore
+node_modules
+.env.local
+```
+
+---
+
+Now let's actually write our bot in a new file called `bot.ts`.
+
+```ts#bot.ts
+// import discord.js
+import {Client, Events, GatewayIntentBits} from 'discord.js';
+
+// create a new Client instance
+const client = new Client({intents: [GatewayIntentBits.Guilds]});
+
+// listen for the client to be ready
+client.once(Events.ClientReady, (c) => {
+  console.log(`Ready! Logged in as ${c.user.tag}`);
+});
+
+// login with the token from .env.local
+client.login(process.env.DISCORD_TOKEN);
+```
+
+---
+
+Now we can run our bot with `bun run`. It may take a several seconds for the client to initialize the first time you run the file.
+
+```bash
+$ bun run bot.ts
+Ready! Logged in as my-bot#1234
+```
+
+---
+
+You're up and running with a bare-bones Discord.js bot! This is a basic guide to setting up your bot with Bun; we recommend the [official discord.js docs](https://discordjs.guide/) for complete information on the `discord.js` API.

package/docs/guides/ecosystem/docker.md

@@ -0,0 +1,140 @@
+---
+name: Containerize a Bun application with Docker
+---
+
+{% callout %}
+This guide assumes you already have [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed.
+{% /callout %}
+
+[Docker](https://www.docker.com) is a platform for packaging and running an application as a lightweight, portable _container_ that encapsulates all the necessary dependencies.
+
+---
+
+To _containerize_ our application, we define a `Dockerfile`. This file contains a list of instructions to initialize the container, copy our local project files into it, install dependencies, and starts the application.
+
+```docker#Dockerfile
+# use the official Bun image
+# see all versions at https://hub.docker.com/r/oven/bun/tags
+FROM oven/bun:1 AS base
+WORKDIR /usr/src/app
+
+# install dependencies into temp directory
+# this will cache them and speed up future builds
+FROM base AS install
+RUN mkdir -p /temp/dev
+COPY package.json bun.lockb /temp/dev/
+RUN cd /temp/dev && bun install --frozen-lockfile
+
+# install with --production (exclude devDependencies)
+RUN mkdir -p /temp/prod
+COPY package.json bun.lockb /temp/prod/
+RUN cd /temp/prod && bun install --frozen-lockfile --production
+
+# copy node_modules from temp directory
+# then copy all (non-ignored) project files into the image
+FROM base AS prerelease
+COPY --from=install /temp/dev/node_modules node_modules
+COPY . .
+
+# [optional] tests & build
+ENV NODE_ENV=production
+RUN bun test
+RUN bun run build
+
+# copy production dependencies and source code into final image
+FROM base AS release
+COPY --from=install /temp/prod/node_modules node_modules
+COPY --from=prerelease /usr/src/app/index.ts .
+COPY --from=prerelease /usr/src/app/package.json .
+
+# run the app
+USER bun
+EXPOSE 3000/tcp
+ENTRYPOINT [ "bun", "run", "index.ts" ]
+```
+
+---
+
+Now that you have your docker image, let's look at `.dockerignore` which has the same syntax as `.gitignore`, here you need to specify the files/directories that must not go in any stage of the docker build. An example for a ignore file is
+
+```txt#.dockerignore
+node_modules
+Dockerfile*
+docker-compose*
+.dockerignore
+.git
+.gitignore
+README.md
+LICENSE
+.vscode
+Makefile
+helm-charts
+.env
+.editorconfig
+.idea
+coverage*
+```
+
+---
+
+We'll now use `docker build` to convert this `Dockerfile` into a _Docker image_, a self-contained template containing all the dependencies and configuration required to run the application.
+
+The `-t` flag lets us specify a name for the image, and `--pull` tells Docker to automatically download the latest version of the base image (`oven/bun`). The initial build will take longer, as Docker will download all the base images and dependencies.
+
+```bash
+$ docker build --pull -t bun-hello-world .
+[+] Building 0.9s (21/21) FINISHED
+ => [internal] load build definition from Dockerfile                                                                                     0.0s
+ => => transferring dockerfile: 37B                                                                                                      0.0s
+ => [internal] load .dockerignore                                                                                                        0.0s
+ => => transferring context: 35B                                                                                                         0.0s
+ => [internal] load metadata for docker.io/oven/bun:1                                                                                    0.8s
+ => [auth] oven/bun:pull token for registry-1.docker.io                                                                                  0.0s
+ => [base 1/2] FROM docker.io/oven/bun:1@sha256:373265748d3cd3624cb3f3ee6004f45b1fc3edbd07a622aeeec17566d2756997                         0.0s
+ => [internal] load build context                                                                                                        0.0s
+ => => transferring context: 155B                                                                                                        0.0s
+ # ...lots of commands...
+ => exporting to image                                                                                                                   0.0s
+ => => exporting layers                                                                                                                  0.0s
+ => => writing image sha256:360663f7fdcd6f11e8e94761d5592e2e4dfc8d167f034f15cd5a863d5dc093c4                                             0.0s
+ => => naming to docker.io/library/bun-hello-world                                                                                       0.0s
+```
+
+---
+
+We've built a new _Docker image_. Now let's use that image to spin up an actual, running _container_.
+
+We'll use `docker run` to start a new container using the `bun-hello-world` image. It will be run in _detached_ mode (`-d`) and we'll map the container's port 3000 to our local machine's port 3000 (`-p 3000:3000`).
+
+The `run` command prints a string representing the _container ID_.
+
+```sh
+$ docker run -d -p 3000:3000 bun-hello-world
+7f03e212a15ede8644379bce11a13589f563d3909a9640446c5bbefce993678d
+```
+
+---
+
+The container is now running in the background. Visit [localhost:3000](http://localhost:3000). You should see a `Hello, World!` message.
+
+---
+
+To stop the container, we'll use `docker stop <container-id>`.
+
+```sh
+$ docker stop 7f03e212a15ede8644379bce11a13589f563d3909a9640446c5bbefce993678d
+```
+
+---
+
+If you can't find the container ID, you can use `docker ps` to list all running containers.
+
+```sh
+$ docker ps
+CONTAINER ID        IMAGE               COMMAND                  CREATED             STATUS              PORTS                    NAMES
+7f03e212a15e        bun-hello-world     "bun run index.ts"       2 minutes ago       Up 2 minutes        0.0.0.0:3000->3000/tcp   flamboyant_cerf
+```
+
+---
+
+That's it! Refer to the [Docker documentation](https://docs.docker.com/) for more advanced usage.

package/docs/guides/ecosystem/drizzle.md

@@ -0,0 +1,185 @@
+---
+name: Use Drizzle ORM with Bun
+---
+
+Drizzle is an ORM that supports both a SQL-like "query builder" API and an ORM-like [Queries API](https://orm.drizzle.team/docs/rqb). It supports the `bun:sqlite` built-in module.
+
+---
+
+Let's get started by creating a fresh project with `bun init` and installing Drizzle.
+
+```sh
+$ bun init -y
+$ bun add drizzle-orm
+$ bun add -D drizzle-kit
+```
+
+---
+
+Then we'll connect to a SQLite database using the `bun:sqlite` module and create the Drizzle database instance.
+
+```ts#db.ts
+import { drizzle } from "drizzle-orm/bun-sqlite";
+import { Database } from "bun:sqlite";
+
+const sqlite = new Database("sqlite.db");
+export const db = drizzle(sqlite);
+```
+
+---
+
+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 = db.get<{ text: string }>(query);
+console.log(result);
+```
+
+---
+
+Then run `index.ts` with Bun. Bun will automatically create `sqlite.db` and execute the query.
+
+```sh
+$ bun run index.ts
+{
+  text: "hello world"
+}
+```
+
+---
+
+Lets give our database a proper schema. Create a `schema.ts` file and define a `movies` table.
+
+```ts#schema.ts
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+
+export const movies = sqliteTable("movies", {
+  id: integer("id").primaryKey(),
+  title: text("name"),
+  releaseYear: integer("release_year"),
+});
+```
+
+---
+
+We can use the `drizzle-kit` CLI to generate an initial SQL migration.
+
+```sh
+$ bunx drizzle-kit generate --dialect sqlite --schema ./schema.ts
+```
+
+---
+
+This creates a new `drizzle` directory containing a `.sql` migration file and `meta` directory.
+
+```txt
+drizzle
+├── 0000_ordinary_beyonder.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 a SQLite database that writes to `sqlite.db`, then executes all unexecuted migrations in the `drizzle` directory.
+
+```ts#migrate.ts
+import { migrate } from "drizzle-orm/bun-sqlite/migrator";
+
+import { drizzle } from "drizzle-orm/bun-sqlite";
+import { Database } from "bun:sqlite";
+
+const sqlite = new Database("sqlite.db");
+const db = drizzle(sqlite);
+await migrate(db, { migrationsFolder: "./drizzle" });
+```
+
+---
+
+We can run this script with `bun` to execute the migration.
+
+```sh
+$ bun run migrate.ts
+```
+
+---
+
+Now that we have a database, let's add some data to it. Create a `seed.ts` file with the following contents.
+
+```ts#seed.ts
+import { db } from "./db";
+import * as schema from "./schema";
+
+await db.insert(schema.movies).values([
+  {
+    title: "The Matrix",
+    releaseYear: 1999,
+  },
+  {
+    title: "The Matrix Reloaded",
+    releaseYear: 2003,
+  },
+  {
+    title: "The Matrix Revolutions",
+    releaseYear: 2003,
+  },
+]);
+
+console.log(`Seeding complete.`);
+```
+
+---
+
+Then run this file.
+
+```sh
+$ bun run seed.ts
+Seeding complete.
+```
+
+---
+
+We finally have a database with a schema and some sample data. Let's 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.movies);
+console.log(result);
+```
+
+---
+
+Then run the file. You should see the three movies we inserted.
+
+```sh
+$ bun run index.ts
+bun run index.ts
+[
+  {
+    id: 1,
+    title: "The Matrix",
+    releaseYear: 1999
+  }, {
+    id: 2,
+    title: "The Matrix Reloaded",
+    releaseYear: 2003
+  }, {
+    id: 3,
+    title: "The Matrix Revolutions",
+    releaseYear: 2003
+  }
+]
+```
+
+---
+
+Refer to the [Drizzle website](https://orm.drizzle.team/docs/overview) for complete documentation.

package/docs/guides/ecosystem/edgedb.md

@@ -0,0 +1,228 @@
+---
+name: Use EdgeDB with Bun
+---
+
+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.
+
+{% codetabs %}
+
+```sh#Linux/macOS
+$ curl --proto '=https' --tlsv1.2 -sSf https://sh.edgedb.com | sh
+```
+
+```sh#Windows
+$ iwr https://ps1.edgedb.com -useb | iex
+```
+
+{% /codetabs %}
+
+---
+
+Use `bun init` to create a fresh project.
+
+```sh
+$ 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
+$ edgedb project init
+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.
+
+Then run `\quit` to exit the REPL.
+
+```sh
+$ edgedb
+edgedb> select 1 + 1;
+2
+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
+dbschema
+├── default.esdl
+└── migrations
+```
+
+---
+
+Open that file and paste the following contents.
+
+```txt
+module default {
+  type Movie {
+    required title: str;
+    releaseYear: int64;
+  }
+};
+```
+
+---
+
+Then generate and apply an initial migration.
+
+```sh
+$ edgedb migration create
+Created /Users/colinmcd94/Documents/bun/fun/examples/my-edgedb-app/dbschema/migrations/00001.edgeql, id: m1uwekrn4ni4qs7ul7hfar4xemm5kkxlpswolcoyqj3xdhweomwjrq
+$ edgedb migrate
+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
+$ 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
+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
+$ bun run seed.ts
+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
+$ bunx @edgedb/generate edgeql-js
+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
+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
+$ bun run index.ts
+[
+  {
+    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).