DocsReferenceGuidesBlog
Discord logo
Discord
GitHub logo
Bun

module

bun

The 'bun' module is where most of Bun's APIs are located. You can import all of the values and types in this module with an import statement, or by referencing the Bun global namespace.

  • function $(
    strings: TemplateStringsArray,
    ...expressions: ShellExpression[]

    The Bun shell is a powerful tool for running shell commands.

    const result = await $`echo "Hello, world!"`.text();
console.log(result); // "Hello, world!"

    namespace $

    • class ShellError

      ShellError represents an error that occurred while executing a shell command with the Bun Shell.

      try {
  const result = await $`exit 1`;
} catch (error) {
  if (error instanceof ShellError) {
    console.log(error.exitCode); // 1
  }
}
      • cause?: unknown

        The cause of the error.

      • readonly exitCode: number
      • message: string
      • name: string
      • stack?: string
      • readonly stderr: Buffer
      • readonly stdout: Buffer
      • static prepareStackTrace?: (err: Error, stackTraces: CallSite[]) => any

        Optional override for formatting stack traces

      • static stackTraceLimit: number

        The maximum number of stack frames to capture.

      • Read from stdout as an ArrayBuffer

        @returns

        Stdout as an ArrayBuffer

        const output = await $`echo hello`;
console.log(output.arrayBuffer()); // ArrayBuffer { byteLength: 6 }

      • Read from stdout as a Blob

        @returns

        Stdout as a blob

        const output = await $`echo hello`;
console.log(output.blob()); // Blob { size: 6, type: "" }

      • Read from stdout as an Uint8Array

        @returns

        Stdout as an Uint8Array

        const output = await $`echo hello`;
console.log(output.bytes()); // Uint8Array { byteLength: 6 }
      • json(): any;

        Read from stdout as a JSON object

        @returns

        Stdout as a JSON object

        const output = await $`echo '{"hello": 123}'`;
console.log(output.json()); // { hello: 123 }
      • encoding?: BufferEncoding
        ): string;

        Read from stdout as a string

        @param encoding

        The encoding to use when decoding the output

        @returns

        Stdout as a string with the given encoding

        Read as UTF-8 string

        const output = await $`echo hello`;
console.log(output.text()); // "hello\n"

        Read as base64 string

        const output = await $`echo ${atob("hello")}`;
console.log(output.text("base64")); // "hello\n"
      • targetObject: object,
        constructorOpt?: Function
        ): void;

        Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

        const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

        The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

        The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

        The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

        function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
      • static isError(
        value: unknown
        ): value is Error;

        Check if a value is an instance of Error

        @param value

        The value to check

        @returns

        True if the value is an instance of Error, false otherwise

    • class ShellPromise

      The Bun.$.ShellPromise class represents a shell command that gets executed once awaited, or called with .text(), .json(), etc.

      const myShellPromise = $`echo "Hello, world!"`;
const result = await myShellPromise.text();
console.log(result); // "Hello, world!"
      • readonly [Symbol.toStringTag]: string

      • Read from stdout as an ArrayBuffer

        Automatically calls quiet

        @returns

        A promise that resolves with stdout as an ArrayBuffer

        const output = await $`echo hello`.arrayBuffer();
console.log(output); // ArrayBuffer { byteLength: 6 }
      • blob(): Promise<Blob>;

        Read from stdout as a Blob

        Automatically calls quiet

        @returns

        A promise that resolves with stdout as a Blob

        const output = await $`echo hello`.blob();
console.log(output); // Blob { size: 6, type: "" }
      • catch<TResult = never>(
        onrejected?: null | (reason: any) => TResult | PromiseLike<TResult>
        ): Promise<ShellOutput | TResult>;

        Attaches a callback for only the rejection of the Promise.

        @param onrejected

        The callback to execute when the Promise is rejected.

        @returns

        A Promise for the completion of the callback.

      • newCwd: string
        ): this;

        Change the current working directory of the shell.

        @param newCwd

        The new working directory

      • newEnv: undefined | Record<string, string>
        ): this;

        Set environment variables for the shell.

        @param newEnv

        The new environment variables

        await $`echo $FOO`.env({ ...process.env, FOO: "LOL!" })
expect(stdout.toString()).toBe("LOL!");
      • onfinally?: null | () => void
        ): Promise<ShellOutput>;

        Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected). The resolved value cannot be modified from the callback.

        @param onfinally

        The callback to execute when the Promise is settled (fulfilled or rejected).

        @returns

        A Promise for the completion of the callback.

      • json(): Promise<any>;

        Read from stdout as a JSON object

        Automatically calls quiet

        @returns

        A promise that resolves with stdout as a JSON object

        const output = await $`echo '{"hello": 123}'`.json();
console.log(output); // { hello: 123 }
      • lines(): AsyncIterable<string>;

        Read from stdout as a string, line by line

        Automatically calls quiet to disable echoing to stdout.

      • nothrow(): this;

        Configure the shell to not throw an exception on non-zero exit codes. Throwing can be re-enabled with .throws(true).

        By default, the shell with throw an exception on commands which return non-zero exit codes.

      • quiet(): this;

        By default, the shell will write to the current process's stdout and stderr, as well as buffering that output.

        This configures the shell to only buffer the output.

      • encoding?: BufferEncoding
        ): Promise<string>;

        Read from stdout as a string.

        Automatically calls quiet to disable echoing to stdout.

        @param encoding

        The encoding to use when decoding the output

        @returns

        A promise that resolves with stdout as a string

        Read as UTF-8 string

        const output = await $`echo hello`.text();
console.log(output); // "hello\n"

        Read as base64 string

        const output = await $`echo ${atob("hello")}`.text("base64");
console.log(output); // "hello\n"
      • then<TResult1 = ShellOutput, TResult2 = never>(
        onfulfilled?: null | (value: ShellOutput) => TResult1 | PromiseLike<TResult1>,
        onrejected?: null | (reason: any) => TResult2 | PromiseLike<TResult2>
        ): Promise<TResult1 | TResult2>;

        Attaches callbacks for the resolution and/or rejection of the Promise.

        @param onfulfilled

        The callback to execute when the Promise is resolved.

        @param onrejected

        The callback to execute when the Promise is rejected.

        @returns

        A Promise for the completion of which ever callback is executed.

      • shouldThrow: boolean
        ): this;

        Configure whether or not the shell should throw an exception on non-zero exit codes.

        By default, this is configured to true.

      • static all<T extends [] | readonly unknown[]>(
        values: T
        ): Promise<{ [K in string | number | symbol]: Awaited<T[P<P>]> }>;

        Creates a Promise that is resolved with an array of results when all of the provided Promises resolve, or rejected when any Promise is rejected.

        @param values

        An array of Promises.

        @returns

        A new Promise.

      • static allSettled<T>(
        values: Iterable<T | PromiseLike<T>>
        ): Promise<PromiseSettledResult<Awaited<T>>[]>;

        Creates a Promise that is resolved with an array of results when all of the provided Promises resolve or reject.

        @param values

        An array of Promises.

        @returns

        A new Promise.

      • static any<T extends [] | readonly unknown[]>(
        values: T
        ): Promise<Awaited<T[number]>>;

        The any function returns a promise that is fulfilled by the first given promise to be fulfilled, or rejected with an AggregateError containing an array of rejection reasons if all of the given promises are rejected. It resolves all elements of the passed iterable to promises as it runs this algorithm.

        @param values

        An array or iterable of Promises.

        @returns

        A new Promise.

      • static race<T extends [] | readonly unknown[]>(
        values: T
        ): Promise<Awaited<T[number]>>;

        Creates a Promise that is resolved or rejected when any of the provided Promises are resolved or rejected.

        @param values

        An array of Promises.

        @returns

        A new Promise.

      • static reject<T = never>(
        reason?: any
        ): Promise<T>;

        Creates a new rejected promise for the provided reason.

        @param reason

        The reason the promise was rejected.

        @returns

        A new rejected Promise.

      • static resolve<T>(
        value: T
        ): Promise<Awaited<T>>;

        Creates a new resolved promise for the provided value.

        @param value

        A promise.

        @returns

        A promise whose internal state matches the provided promise.

      • static try<T, A extends any[] = []>(
        fn: (...args: A) => T | PromiseLike<T>,
        ...args: A
        ): Promise<T>;

        Try to run a function and return the result. If the function throws, return the result of the catch function.

        @param fn

        The function to run

        @param args

        The arguments to pass to the function. This is similar to setTimeout and avoids the extra closure.

        @returns

        The result of the function or the result of the catch function

      • static withResolvers<T>(): { promise: Promise<T>; reject: (reason?: any) => void; resolve: (value?: T | PromiseLike<T>) => void };

        Create a deferred promise, with exposed resolve and reject methods which can be called separately.

        This is useful when you want to return a Promise and have code outside the Promise resolve or reject it.

        const { promise, resolve, reject } = Promise.withResolvers();

setTimeout(() => {
 resolve("Hello world!");
}, 1000);

await promise; // "Hello world!"

    • interface ShellOutput

      • readonly exitCode: number
      • readonly stderr: Buffer
      • readonly stdout: Buffer

      • Read from stdout as an ArrayBuffer

        @returns

        Stdout as an ArrayBuffer

        const output = await $`echo hello`;
console.log(output.arrayBuffer()); // ArrayBuffer { byteLength: 6 }

      • Read from stdout as a Blob

        @returns

        Stdout as a blob

        const output = await $`echo hello`;
console.log(output.blob()); // Blob { size: 6, type: "" }

      • Read from stdout as an Uint8Array

        @returns

        Stdout as an Uint8Array

        const output = await $`echo hello`;
console.log(output.bytes()); // Uint8Array { byteLength: 6 }
      • json(): any;

        Read from stdout as a JSON object

        @returns

        Stdout as a JSON object

        const output = await $`echo '{"hello": 123}'`;
console.log(output.json()); // { hello: 123 }
      • encoding?: BufferEncoding
        ): string;

        Read from stdout as a string

        @param encoding

        The encoding to use when decoding the output

        @returns

        Stdout as a string with the given encoding

        Read as UTF-8 string

        const output = await $`echo hello`;
console.log(output.text()); // "hello\n"

        Read as base64 string

        const output = await $`echo ${atob("hello")}`;
console.log(output.text("base64")); // "hello\n"
    • const Shell: new () => $
    • function braces(
      pattern: string
      ): string[];

      Perform bash-like brace expansion on the given pattern.

      @param pattern

      Brace pattern to expand

      const result = braces('index.{js,jsx,ts,tsx}');
console.log(result) // ['index.js', 'index.jsx', 'index.ts', 'index.tsx']
    • function cwd(
      newCwd?: string
      ): typeof $;
      @param newCwd

      Default working directory to use for shells created by this instance.

    • function env(
      newEnv?: Record<string, undefined | string>
      ): typeof $;

      Change the default environment variables for shells created by this instance.

      @param newEnv

      Default environment variables to use for shells created by this instance.

      import {$} from 'bun';
$.env({ BUN: "bun" });
await $`echo $BUN`;
// "bun"
    • function escape(
      input: string
      ): string;

      Escape strings for input into shell commands.

    • function nothrow(): typeof $;

      Configure the shell to not throw an exception on non-zero exit codes.

    • function throws(
      shouldThrow: boolean
      ): typeof $;

      Configure whether or not the shell should throw an exception on non-zero exit codes.

  • namespace CSRF

    Generate and verify CSRF tokens

    • function generate(
      secret?: string,
      options?: CSRFGenerateOptions
      ): string;

      Generate a CSRF token.

      @param secret

      The secret to use for the token. If not provided, a random default secret will be generated in memory and used.

      @param options

      The options for the token.

      @returns

      The generated token.

    • function verify(
      token: string,
      options?: CSRFVerifyOptions
      ): boolean;

      Verify a CSRF token.

      @param token

      The token to verify.

      @param options

      The options for the token.

      @returns

      True if the token is valid, false otherwise.

  • namespace dns

    DNS Related APIs

    • const ADDRCONFIG: number
    • const ALL: number
    • const V4MAPPED: number
    • function getCacheStats(): { cacheHitsCompleted: number; cacheHitsInflight: number; cacheMisses: number; errors: number; size: number; totalCount: number };

      Experimental API

    • function lookup(
      hostname: string,
      options?: { backend: 'system' | 'libc' | 'c-ares' | 'getaddrinfo'; family: 0 | 4 | 6 | 'IPv4' | 'IPv6' | 'any'; flags: number; port: number; socketType: 'udp' | 'tcp' }
      ): Promise<DNSLookup[]>;

      Lookup the IP address for a hostname

      Uses non-blocking APIs by default

      @param hostname

      The hostname to lookup

      @param options

      Options for the lookup

      Basic usage

      const [{ address }] = await Bun.dns.lookup('example.com');

      Filter results to IPv4

      import { dns } from 'bun';
const [{ address }] = await dns.lookup('example.com', {family: 4});
console.log(address); // "123.122.22.126"

      Filter results to IPv6

      import { dns } from 'bun';
const [{ address }] = await dns.lookup('example.com', {family: 6});
console.log(address); // "2001:db8::1"

      DNS resolver client

      Bun supports three DNS resolvers:

      • c-ares - Uses the c-ares library to perform DNS resolution. This is the default on Linux.
      • system - Uses the system's non-blocking DNS resolver API if available, falls back to getaddrinfo. This is the default on macOS and the same as getaddrinfo on Linux.
      • getaddrinfo - Uses the posix standard getaddrinfo function. Will cause performance issues under concurrent loads.

      To customize the DNS resolver, pass a backend option to dns.lookup:

      import { dns } from 'bun';
const [{ address }] = await dns.lookup('example.com', {backend: 'getaddrinfo'});
console.log(address); // "19.42.52.62"
    • function prefetch(
      hostname: string
      ): void;

      Experimental API

      Prefetch a hostname.

      This will be used by fetch() and Bun.connect() to avoid DNS lookups.

      @param hostname

      The hostname to prefetch

      import { dns } from 'bun';
dns.prefetch('example.com');
// ... something expensive
await fetch('https://example.com');
  • function inspect(
    arg: any,
    options?: BunInspectOptions
    ): string;

    Pretty-print an object the same as console.log to a string

    Supports JSX

    @param arg

    The value to inspect

    @param options

    Options for the inspection

    namespace inspect

    • That can be used to declare custom inspect functions.

    • function table(
      tabularData: object | unknown[],
      properties?: string[],
      options?: { colors: boolean }
      ): string;

      Pretty-print an object or array as a table

      Like console.table, except it returns a string

      function table(
      tabularData: object | unknown[],
      options?: { colors: boolean }
      ): string;

      Pretty-print an object or array as a table

      Like console.table, except it returns a string

  • function peek<T = undefined>(
    promise: T | Promise<T>
    ): T | Promise<T>;

    Extract the value from the Promise in the same tick of the event loop

    namespace peek

    • function status<T = undefined>(
      promise: T | Promise<T>
      ): 'pending' | 'fulfilled' | 'rejected';

  • namespace semver

    Bun.semver provides a fast way to parse and compare version numbers.

    • function order(
      v1: StringLike,
      v2: StringLike
      ): -1 | 0 | 1;

      Returns 0 if the versions are equal, 1 if v1 is greater, or -1 if v2 is greater. Throws an error if either version is invalid.

    • function satisfies(
      version: StringLike,
      range: StringLike
      ): boolean;

      Test if the version satisfies the range. Stringifies both arguments. Returns true or false.

  • namespace TOML

    TOML related APIs

    • function parse(
      input: string
      ): object;

      Parse a TOML string into a JavaScript object.

      @param input

      The TOML string to parse

      @returns

      A JavaScript object

  • namespace unsafe

    • buffer: ArrayBufferLike | Uint8Array<ArrayBufferLike>
      ): string;

      Cast bytes to a String without copying. This is the fastest way to get a String from a Uint8Array or ArrayBuffer.

      Only use this for ASCII strings. If there are non-ascii characters, your application may crash and/or very confusing bugs will happen such as "foo" !== "foo".

      The input buffer must not be garbage collected. That means you will need to hold on to it for the duration of the string's lifetime.

      buffer: Uint16Array
      ): string;

      Cast bytes to a String without copying. This is the fastest way to get a String from a Uint16Array

      The input must be a UTF-16 encoded string. This API does no validation whatsoever.

      The input buffer must not be garbage collected. That means you will need to hold on to it for the duration of the string's lifetime.

    • level?: 0 | 1 | 2
      ): 0 | 1 | 2;

      Force the garbage collector to run extremely often, especially inside bun:test.

      • 0: default, disable
      • 1: asynchronously call the garbage collector more often
      • 2: synchronously call the garbage collector more often.

      This is a global setting. It's useful for debugging seemingly random crashes.

      BUN_GARBAGE_COLLECTOR_LEVEL environment variable is also supported.

      @returns

      The previous level

    • function mimallocDump(): void;

      Dump the mimalloc heap to the console

  • class ArrayBufferSink

    Fast incremental writer that becomes an ArrayBuffer on end().

    • end(): ArrayBuffer | Uint8Array<ArrayBufferLike>;
    • flush(): number | ArrayBuffer | Uint8Array<ArrayBufferLike>;

      Flush the internal buffer

      If ArrayBufferSink.start was passed a stream option, this will return a ArrayBuffer If ArrayBufferSink.start was passed a stream option and asUint8Array, this will return a Uint8Array Otherwise, this will return the number of bytes written since the last flush

      This API might change later to separate Uint8ArraySink and ArrayBufferSink

    • options?: { asUint8Array: boolean; highWaterMark: number; stream: boolean }
      ): void;
    • chunk: string | ArrayBuffer | SharedArrayBuffer | ArrayBufferView<ArrayBufferLike>
      ): number;

  • class Cookie

    A class for working with a single cookie

    const cookie = new Bun.Cookie("name", "value");
console.log(cookie.toString()); // "name=value; Path=/; SameSite=Lax"
    • domain?: string

      The domain of the cookie

    • expires?: Date

      The expiration date of the cookie

    • httpOnly: boolean

      Whether the cookie is HTTP-only

    • maxAge?: number

      The maximum age of the cookie in seconds

    • readonly name: string

      The name of the cookie

    • partitioned: boolean

      Whether the cookie is partitioned

    • path: string

      The path of the cookie

    • sameSite: CookieSameSite

      The same-site attribute of the cookie

    • secure: boolean

      Whether the cookie is secure

    • value: string

      The value of the cookie

    • isExpired(): boolean;

      Whether the cookie is expired

    • serialize(): string;

      Serialize the cookie to a string

      const cookie = Bun.Cookie.from("session", "abc123", {
  domain: "example.com",
  path: "/",
  secure: true,
  httpOnly: true
}).serialize(); // "session=abc123; Domain=example.com; Path=/; Secure; HttpOnly; SameSite=Lax"

    • Serialize the cookie to a JSON object

    • toString(): string;

      Serialize the cookie to a string

      Alias of Cookie.serialize

    • static from(
      name: string,
      value: string,
      options?: CookieInit
      ): Cookie;

      Create a new cookie from a name and value and optional options

    • static parse(
      cookieString: string
      ): Cookie;

      Parse a cookie string into a Cookie object

      @param cookieString

      The cookie string

  • class CookieMap

    A Map-like interface for working with collections of cookies.

    Implements the Iterable interface, allowing use with for...of loops.

    • readonly size: number

      The number of cookies in the map.

    • [Symbol.iterator](): IterableIterator<[string, string]>;

      Returns the default iterator for the CookieMap. Used by for...of loops to iterate over all entries.

      @returns

      An iterator for the entries in the map

    • name: string
      ): void;

      Removes a cookie from the map.

      @param name

      The name of the cookie to delete

      options: CookieStoreDeleteOptions
      ): void;

      Removes a cookie from the map.

      @param options

      The options for the cookie to delete

      name: string,
      options: Omit<CookieStoreDeleteOptions, 'name'>
      ): void;

      Removes a cookie from the map.

      @param name

      The name of the cookie to delete

      @param options

      The options for the cookie to delete

    • entries(): IterableIterator<[string, string]>;

      Returns an iterator of [name, value] pairs for every cookie in the map.

      @returns

      An iterator for the entries in the map

    • callback: (value: string, key: string, map: CookieMap) => void
      ): void;

      Executes a provided function once for each cookie in the map.

      @param callback

      Function to execute for each entry

    • name: string
      ): null | string;

      Gets the value of a cookie with the specified name.

      @param name

      The name of the cookie to retrieve

      @returns

      The cookie value as a string, or null if the cookie doesn't exist

    • name: string
      ): boolean;

      Checks if a cookie with the given name exists.

      @param name

      The name of the cookie to check

      @returns

      true if the cookie exists, false otherwise

    • keys(): IterableIterator<string>;

      Returns an iterator of all cookie names in the map.

      @returns

      An iterator for the cookie names

    • name: string,
      value: string,
      options?: CookieInit
      ): void;

      Adds or updates a cookie in the map.

      @param name

      The name of the cookie

      @param value

      The value of the cookie

      @param options

      Optional cookie attributes

      options: CookieInit
      ): void;

      Adds or updates a cookie in the map using a cookie options object.

      @param options

      Cookie options including name and value

    • toJSON(): Record<string, string>;

      Converts the cookie map to a serializable format.

      @returns

      An array of name/value pairs

    • toSetCookieHeaders(): string[];

      Gets an array of values for Set-Cookie headers in order to apply all changes to cookies.

      @returns

      An array of values for Set-Cookie headers

    • values(): IterableIterator<string>;

      Returns an iterator of all cookie values in the map.

      @returns

      An iterator for the cookie values

  • class CryptoHasher

    Hardware-accelerated cryptographic hash functions

    Used for crypto.createHash()

  • class CryptoHashInterface<T>

    This class only exists in types

    • encoding: DigestEncoding
      ): string;

      Finalize the hash

      @param encoding

      DigestEncoding to return the hash in. If none is provided, it will return a Uint8Array.

      hashInto?: TypedArray<ArrayBufferLike>
      ): TypedArray;

      Finalize the hash

      @param hashInto

      TypedArray to write the hash into. Faster than creating a new one each time

    • data: BlobOrStringOrBuffer
      ): T;

      Update the hash with data

    • static hash(
      input: BlobOrStringOrBuffer,
      hashInto?: TypedArray<ArrayBufferLike>
      ): TypedArray;

      Run the hash over the given data

      @param input

      string, Uint8Array, or ArrayBuffer to hash. Uint8Array or ArrayBuffer is faster.

      @param hashInto

      TypedArray to write the hash into. Faster than creating a new one each time

      static hash(
      input: BlobOrStringOrBuffer,
      encoding: DigestEncoding
      ): string;

      Run the hash over the given data

      @param input

      string, Uint8Array, or ArrayBuffer to hash. Uint8Array or ArrayBuffer is faster.

      @param encoding

      DigestEncoding to return the hash in

  • class Glob

    Match files using glob patterns.

    The supported pattern syntax for is:

    • ? Matches any single character.
    • * Matches zero or more characters, except for path separators ('/' or '').
    • ** Matches zero or more characters, including path separators. Must match a complete path segment, i.e. followed by a path separator or at the end of the pattern.
    • [ab] Matches one of the characters contained in the brackets. Character ranges (e.g. "[a-z]") are also supported. Use "[!ab]" or "[^ab]" to match any character except those contained in the brackets.
    • {a,b} Match one of the patterns contained in the braces. Any of the wildcards listed above can be used in the sub patterns. Braces may be nested up to 10 levels deep.
    • ! Negates the result when at the start of the pattern. Multiple "!" characters negate the pattern multiple times.
    • `` Used to escape any of the special characters above.
    const glob = new Glob("*.{ts,tsx}");
const scannedFiles = await Array.fromAsync(glob.scan({ cwd: './src' }))
    • str: string
      ): boolean;

      Match the glob against a string

      const glob = new Glob("*.{ts,tsx}");
expect(glob.match('foo.ts')).toBeTrue();
    • optionsOrCwd?: string | GlobScanOptions
      ): AsyncIterableIterator<string>;

      Scan a root directory recursively for files that match this glob pattern. Returns an async iterator.

      const glob = new Glob("*.{ts,tsx}");
const scannedFiles = await Array.fromAsync(glob.scan({ cwd: './src' }))
    • optionsOrCwd?: string | GlobScanOptions
      ): IterableIterator<string>;

      Synchronously scan a root directory recursively for files that match this glob pattern. Returns an iterator.

      const glob = new Glob("*.{ts,tsx}");
const scannedFiles = Array.from(glob.scan({ cwd: './src' }))

  • class MD4

    This class only exists in types

    • readonly static byteLength: 16

      The number of bytes the hash will produce

    • encoding: DigestEncoding
      ): string;

      Finalize the hash

      @param encoding

      DigestEncoding to return the hash in. If none is provided, it will return a Uint8Array.

      hashInto?: TypedArray<ArrayBufferLike>
      ): TypedArray;

      Finalize the hash

      @param hashInto

      TypedArray to write the hash into. Faster than creating a new one each time

    • data: BlobOrStringOrBuffer
      ): MD4;

      Update the hash with data

    • static hash(
      input: BlobOrStringOrBuffer,
      hashInto?: TypedArray<ArrayBufferLike>
      ): TypedArray;

      Run the hash over the given data

      @param input

      string, Uint8Array, or ArrayBuffer to hash. Uint8Array or ArrayBuffer is faster.

      @param hashInto

      TypedArray to write the hash into. Faster than creating a new one each time

      static hash(
      input: BlobOrStringOrBuffer,
      encoding: DigestEncoding
      ): string;

      Run the hash over the given data

      @param input

      string, Uint8Array, or ArrayBuffer to hash. Uint8Array or ArrayBuffer is faster.

      @param encoding

      DigestEncoding to return the hash in

  • class MD5

    This class only exists in types

    • readonly static byteLength: 16

      The number of bytes the hash will produce

    • encoding: DigestEncoding
      ): string;

      Finalize the hash

      @param encoding

      DigestEncoding to return the hash in. If none is provided, it will return a Uint8Array.

      hashInto?: TypedArray<ArrayBufferLike>
      ): TypedArray;

      Finalize the hash

      @param hashInto

      TypedArray to write the hash into. Faster than creating a new one each time

    • data: BlobOrStringOrBuffer
      ): MD5;

      Update the hash with data

    • static hash(
      input: BlobOrStringOrBuffer,
      hashInto?: TypedArray<ArrayBufferLike>
      ): TypedArray;

      Run the hash over the given data

      @param input

      string, Uint8Array, or ArrayBuffer to hash. Uint8Array or ArrayBuffer is faster.

      @param hashInto

      TypedArray to write the hash into. Faster than creating a new one each time

      static hash(
      input: BlobOrStringOrBuffer,
      encoding: DigestEncoding
      ): string;

      Run the hash over the given data

      @param input

      string, Uint8Array, or ArrayBuffer to hash. Uint8Array or ArrayBuffer is faster.

      @param encoding

      DigestEncoding to return the hash in

    • readonly bufferedAmount: number

      Amount of data buffered in bytes

    • readonly connected: boolean

      Whether the client is connected to the Redis server

    • onclose: null | (this: RedisClient, error: Error) => void

      Callback fired when the client disconnects from the Redis server

    • onconnect: null | (this: RedisClient) => void

      Callback fired when the client connects to the Redis server

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      value: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<number>;

      Append a value to a key

      @param key

      The key to append to

      @param value

      The value to append

      @returns

      Promise that resolves with the length of the string after the append operation

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<number>;

      Count the number of set bits (population counting) in a string

      @param key

      The key to count bits in

      @returns

      Promise that resolves with the number of bits set to 1

    • close(): void;

      Disconnect from the Redis server

    • connect(): Promise<void>;

      Connect to the Redis server

      @returns

      A promise that resolves when connected

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<number>;

      Decrement the integer value of a key by one

      @param key

      The key to decrement

      @returns

      Promise that resolves with the new value

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<number>;

      Delete a key

      @param key

      The key to delete

      @returns

      Promise that resolves with the number of keys removed

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<null | string>;

      Return a serialized version of the value stored at the specified key

      @param key

      The key to dump

      @returns

      Promise that resolves with the serialized value, or null if the key doesn't exist

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<boolean>;

      Determine if a key exists

      @param key

      The key to check

      @returns

      Promise that resolves with true if the key exists, false otherwise

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      seconds: number
      ): Promise<number>;

      Set a key's time to live in seconds

      @param key

      The key to set the expiration for

      @param seconds

      The number of seconds until expiration

      @returns

      Promise that resolves with 1 if the timeout was set, 0 if not

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<number>;

      Get the expiration time of a key as a UNIX timestamp in seconds

      @param key

      The key to check

      @returns

      Promise that resolves with the timestamp, or -1 if the key has no expiration, or -2 if the key doesn't exist

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<null | string>;

      Get the value of a key

      @param key

      The key to get

      @returns

      Promise that resolves with the key's value, or null if the key doesn't exist

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<null | string>;

      Get the value of a key and delete the key

      @param key

      The key to get and delete

      @returns

      Promise that resolves with the value of the key, or null if the key doesn't exist

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<null | string>;

      Get the value of a key and optionally set its expiration

      @param key

      The key to get

      @returns

      Promise that resolves with the value of the key, or null if the key doesn't exist

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      value: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<null | string>;

      Set the value of a key and return its old value

      @param key

      The key to set

      @param value

      The value to set

      @returns

      Promise that resolves with the old value, or null if the key didn't exist

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<null | Record<string, string>>;

      Get all the fields and values in a hash

      @param key

      The hash key

      @returns

      Promise that resolves with an object containing all fields and values

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      field: string,
      increment: string | number
      ): Promise<number>;

      Increment the integer value of a hash field by the given number

      @param key

      The hash key

      @param field

      The field to increment

      @param increment

      The amount to increment by

      @returns

      Promise that resolves with the new value

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      field: string,
      increment: string | number
      ): Promise<string>;

      Increment the float value of a hash field by the given amount

      @param key

      The hash key

      @param field

      The field to increment

      @param increment

      The amount to increment by

      @returns

      Promise that resolves with the new value as a string

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<string[]>;

      Get all field names in a hash

      @param key

      The hash key

      @returns

      Promise that resolves with an array of field names

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<number>;

      Get the number of fields in a hash

      @param key

      The hash key

      @returns

      Promise that resolves with the number of fields

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      fields: string[]
      ): Promise<null | string[]>;

      Get the values of all the given hash fields

      @param key

      The hash key

      @param fields

      The fields to get

      @returns

      Promise that resolves with an array of values

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      fieldValues: string[]
      ): Promise<string>;

      Set multiple hash fields to multiple values

      @param key

      The hash key

      @param fieldValues

      An array of alternating field names and values

      @returns

      Promise that resolves with "OK" on success

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<string[]>;

      Get all values in a hash

      @param key

      The hash key

      @returns

      Promise that resolves with an array of values

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<number>;

      Increment the integer value of a key by one

      @param key

      The key to increment

      @returns

      Promise that resolves with the new value

    • pattern: string
      ): Promise<string[]>;

      Find all keys matching the given pattern

      @param pattern

      The pattern to match

      @returns

      Promise that resolves with an array of matching keys

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<number>;

      Get the length of a list

      @param key

      The list key

      @returns

      Promise that resolves with the length of the list

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<null | string>;

      Remove and get the first element in a list

      @param key

      The list key

      @returns

      Promise that resolves with the first element, or null if the list is empty

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      value: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<number>;

      Prepend one or multiple values to a list

      @param key

      The list key

      @param value

      The value to prepend

      @returns

      Promise that resolves with the length of the list after the push operation

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      value: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<number>;

      Prepend a value to a list, only if the list exists

      @param key

      The list key

      @param value

      The value to prepend

      @returns

      Promise that resolves with the length of the list after the push operation, or 0 if the list doesn't exist

    • ...keys: string | Blob | ArrayBufferView<ArrayBufferLike>[]
      ): Promise<null | string[]>;

      Get the values of all specified keys

      @param keys

      The keys to get

      @returns

      Promise that resolves with an array of values, with null for keys that don't exist

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<number>;

      Remove the expiration from a key

      @param key

      The key to persist

      @returns

      Promise that resolves with 1 if the timeout was removed, 0 if the key doesn't exist or has no timeout

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<number>;

      Get the expiration time of a key as a UNIX timestamp in milliseconds

      @param key

      The key to check

      @returns

      Promise that resolves with the timestamp, or -1 if the key has no expiration, or -2 if the key doesn't exist

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      element: string
      ): Promise<number>;

      Add one or more members to a HyperLogLog

      @param key

      The HyperLogLog key

      @param element

      The element to add

      @returns

      Promise that resolves with 1 if the HyperLogLog was altered, 0 otherwise

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<number>;

      Get the time to live for a key in milliseconds

      @param key

      The key to check

      @returns

      Promise that resolves with the TTL in milliseconds, or -1 if the key has no expiration, or -2 if the key doesn't exist

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<null | string>;

      Remove and get the last element in a list

      @param key

      The list key

      @returns

      Promise that resolves with the last element, or null if the list is empty

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      value: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<number>;

      Append one or multiple values to a list

      @param key

      The list key

      @param value

      The value to append

      @returns

      Promise that resolves with the length of the list after the push operation

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      value: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<number>;

      Append a value to a list, only if the list exists

      @param key

      The list key

      @param value

      The value to append

      @returns

      Promise that resolves with the length of the list after the push operation, or 0 if the list doesn't exist

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      member: string
      ): Promise<number>;

      Add a member to a set

      @param key

      The set key

      @param member

      The member to add

      @returns

      Promise that resolves with 1 if the member was added, 0 if it already existed

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<number>;

      Get the number of members in a set

      @param key

      The set key

      @returns

      Promise that resolves with the cardinality (number of elements) of the set

    • command: string,
      args: string[]
      ): Promise<any>;

      Send a raw command to the Redis server

      @param command

      The command to send

      @param args

      The arguments to the command

      @returns

      A promise that resolves with the command result

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      value: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<'OK'>;

      Set key to hold the string value

      @param key

      The key to set

      @param value

      The value to set

      @returns

      Promise that resolves with "OK" on success

      key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      value: string | Blob | ArrayBufferView<ArrayBufferLike>,
      ex: 'EX',
      seconds: number
      ): Promise<'OK'>;

      Set key to hold the string value with expiration

      @param key

      The key to set

      @param value

      The value to set

      @param ex

      Set the specified expire time, in seconds

      @returns

      Promise that resolves with "OK" on success

      key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      value: string | Blob | ArrayBufferView<ArrayBufferLike>,
      px: 'PX',
      milliseconds: number
      ): Promise<'OK'>;

      Set key to hold the string value with expiration

      @param key

      The key to set

      @param value

      The value to set

      @param px

      Set the specified expire time, in milliseconds

      @returns

      Promise that resolves with "OK" on success

      key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      value: string | Blob | ArrayBufferView<ArrayBufferLike>,
      exat: 'EXAT',
      timestampSeconds: number
      ): Promise<'OK'>;

      Set key to hold the string value with expiration at a specific Unix timestamp

      @param key

      The key to set

      @param value

      The value to set

      @param exat

      Set the specified Unix time at which the key will expire, in seconds

      @returns

      Promise that resolves with "OK" on success

      key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      value: string | Blob | ArrayBufferView<ArrayBufferLike>,
      pxat: 'PXAT',
      timestampMilliseconds: number
      ): Promise<'OK'>;

      Set key to hold the string value with expiration at a specific Unix timestamp

      @param key

      The key to set

      @param value

      The value to set

      @param pxat

      Set the specified Unix time at which the key will expire, in milliseconds

      @returns

      Promise that resolves with "OK" on success

      key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      value: string | Blob | ArrayBufferView<ArrayBufferLike>,
      nx: 'NX'
      ): Promise<null | 'OK'>;

      Set key to hold the string value only if key does not exist

      @param key

      The key to set

      @param value

      The value to set

      @param nx

      Only set the key if it does not already exist

      @returns

      Promise that resolves with "OK" on success, or null if the key already exists

      key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      value: string | Blob | ArrayBufferView<ArrayBufferLike>,
      xx: 'XX'
      ): Promise<null | 'OK'>;

      Set key to hold the string value only if key already exists

      @param key

      The key to set

      @param value

      The value to set

      @param xx

      Only set the key if it already exists

      @returns

      Promise that resolves with "OK" on success, or null if the key does not exist

      key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      value: string | Blob | ArrayBufferView<ArrayBufferLike>,
      get: 'GET'
      ): Promise<null | string>;

      Set key to hold the string value and return the old value

      @param key

      The key to set

      @param value

      The value to set

      @param get

      Return the old string stored at key, or null if key did not exist

      @returns

      Promise that resolves with the old value, or null if key did not exist

      key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      value: string | Blob | ArrayBufferView<ArrayBufferLike>,
      keepttl: 'KEEPTTL'
      ): Promise<'OK'>;

      Set key to hold the string value and retain the time to live

      @param key

      The key to set

      @param value

      The value to set

      @param keepttl

      Retain the time to live associated with the key

      @returns

      Promise that resolves with "OK" on success

      key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      value: string | Blob | ArrayBufferView<ArrayBufferLike>,
      ...options: string[]
      ): Promise<null | string>;

      Set key to hold the string value with various options

      @param key

      The key to set

      @param value

      The value to set

      @param options

      Array of options (EX, PX, EXAT, PXAT, NX, XX, KEEPTTL, GET)

      @returns

      Promise that resolves with "OK" on success, null if NX/XX condition not met, or the old value if GET is specified

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      value: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<number>;

      Set the value of a key, only if the key does not exist

      @param key

      The key to set

      @param value

      The value to set

      @returns

      Promise that resolves with 1 if the key was set, 0 if the key was not set

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      member: string
      ): Promise<boolean>;

      Check if a value is a member of a set

      @param key

      The set key

      @param member

      The member to check

      @returns

      Promise that resolves with true if the member exists, false otherwise

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<string[]>;

      Get all the members in a set

      @param key

      The set key

      @returns

      Promise that resolves with an array of all members

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<null | string>;

      Remove and return a random member from a set

      @param key

      The set key

      @returns

      Promise that resolves with the removed member, or null if the set is empty

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<null | string>;

      Get a random member from a set

      @param key

      The set key

      @returns

      Promise that resolves with a random member, or null if the set is empty

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      member: string
      ): Promise<number>;

      Remove a member from a set

      @param key

      The set key

      @param member

      The member to remove

      @returns

      Promise that resolves with 1 if the member was removed, 0 if it didn't exist

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<number>;

      Get the length of the value stored in a key

      @param key

      The key to check

      @returns

      Promise that resolves with the length of the string value, or 0 if the key doesn't exist

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<number>;

      Get the time to live for a key in seconds

      @param key

      The key to get the TTL for

      @returns

      Promise that resolves with the TTL, -1 if no expiry, or -2 if key doesn't exist

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<number>;

      Get the number of members in a sorted set

      @param key

      The sorted set key

      @returns

      Promise that resolves with the cardinality (number of elements) of the sorted set

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<null | string>;

      Remove and return members with the highest scores in a sorted set

      @param key

      The sorted set key

      @returns

      Promise that resolves with the removed member and its score, or null if the set is empty

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<null | string>;

      Remove and return members with the lowest scores in a sorted set

      @param key

      The sorted set key

      @returns

      Promise that resolves with the removed member and its score, or null if the set is empty

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>
      ): Promise<null | string>;

      Get one or multiple random members from a sorted set

      @param key

      The sorted set key

      @returns

      Promise that resolves with a random member, or null if the set is empty

    • key: string | Blob | ArrayBufferView<ArrayBufferLike>,
      member: string
      ): Promise<null | string>;

      Get the score associated with the given member in a sorted set

      @param key

      The sorted set key

      @param member

      The member to get the score for

      @returns

      Promise that resolves with the score of the member as a string, or null if the member or key doesn't exist

  • class S3Client

    A configured S3 bucket instance for managing files. The instance is callable to create S3File instances and provides methods for common operations.

    // Basic bucket setup
    const bucket = new S3Client({
      bucket: "my-bucket",
      accessKeyId: "key",
      secretAccessKey: "secret"
    });

    // Get file instance
    const file = bucket.file("image.jpg");

    // Common operations
    await bucket.write("data.json", JSON.stringify({hello: "world"}));
    const url = bucket.presign("file.pdf");
    await bucket.unlink("old.txt");
    • path: string,
      options?: S3Options
      ): Promise<void>;

      Delete a file from the bucket. Alias for S3Client.unlink.

      @param path

      The path to the file in the bucket

      @param options

      Additional S3 options to override defaults

      @returns

      A promise that resolves when deletion is complete

      // Simple delete
    await bucket.delete("old-file.txt");

    // With error handling
    try {
      await bucket.delete("file.dat");
      console.log("File deleted");
    } catch (err) {
      console.error("Delete failed:", err);
    }
    • path: string,
      options?: S3Options
      ): Promise<boolean>;

      Check if a file exists in the bucket. Uses HEAD request to check existence.

      @param path

      The path to the file in the bucket

      @param options

      Additional S3 options to override defaults

      @returns

      A promise that resolves to true if the file exists, false otherwise

      // Check existence
    if (await bucket.exists("config.json")) {
      const file = bucket.file("config.json");
      const config = await file.json();
    }

    // With error handling
    try {
      if (!await bucket.exists("required.txt")) {
        throw new Error("Required file missing");
      }
    } catch (err) {
      console.error("Check failed:", err);
    }
    • path: string,
      options?: S3Options
      ): S3File;

      Creates an S3File instance for the given path.

      @param path

      The path to the file in the bucket

      @param options

      Additional S3 options to override defaults

      @returns

      An S3File instance

      const file = bucket.file("image.jpg");
    await file.write(imageData);

    const configFile = bucket.file("config.json", {
      type: "application/json",
      acl: "private"
    });
    • input?: null | S3ListObjectsOptions,
      options?: Pick<S3Options, 'accessKeyId' | 'secretAccessKey' | 'sessionToken' | 'region' | 'bucket' | 'endpoint'>

      Returns some or all (up to 1,000) of the objects in a bucket with each request.

      You can use the request parameters as selection criteria to return a subset of the objects in a bucket.

      @param input

      Options for listing objects in the bucket

      @param options

      Additional S3 options to override defaults

      @returns

      A promise that resolves to the list response

      // List (up to) 1000 objects in the bucket
    const allObjects = await bucket.list();

    // List (up to) 500 objects under `uploads/` prefix, with owner field for each object
    const uploads = await bucket.list({
      prefix: 'uploads/',
      maxKeys: 500,
      fetchOwner: true,
    });

    // Check if more results are available
    if (uploads.isTruncated) {
      // List next batch of objects under `uploads/` prefix
      const moreUploads = await bucket.list({
        prefix: 'uploads/',
        maxKeys: 500,
        startAfter: uploads.contents!.at(-1).key
        fetchOwner: true,
      });
    }
    • path: string,
      options?: S3FilePresignOptions
      ): string;

      Generate a presigned URL for temporary access to a file. Useful for generating upload/download URLs without exposing credentials.

      @param path

      The path to the file in the bucket

      @param options

      Options for generating the presigned URL

      @returns

      A presigned URL string

      // Download URL
    const downloadUrl = bucket.presign("file.pdf", {
      expiresIn: 3600 // 1 hour
    });

    // Upload URL
    const uploadUrl = bucket.presign("uploads/image.jpg", {
      method: "PUT",
      expiresIn: 3600,
      type: "image/jpeg",
      acl: "public-read"
    });

    // Long-lived public URL
    const publicUrl = bucket.presign("public/doc.pdf", {
      expiresIn: 7 * 24 * 60 * 60, // 7 days
      acl: "public-read"
    });
    • path: string,
      options?: S3Options
      ): Promise<number>;

      Get the size of a file in bytes. Uses HEAD request to efficiently get size.

      @param path

      The path to the file in the bucket

      @param options

      Additional S3 options to override defaults

      @returns

      A promise that resolves to the file size in bytes

      // Get size
    const bytes = await bucket.size("video.mp4");
    console.log(`Size: ${bytes} bytes`);

    // Check if file is large
    if (await bucket.size("data.zip") > 100 * 1024 * 1024) {
      console.log("File is larger than 100MB");
    }
    • path: string,
      options?: S3Options
      ): Promise<S3Stats>;

      Get the stat of a file in an S3-compatible storage service.

      @param path

      The path to the file in the bucket

      @param options

      Additional S3 options to override defaults

      @returns

      A promise that resolves to the file stats

      const stat = await bucket.stat("my-file.txt");
    • path: string,
      data: string | ArrayBuffer | SharedArrayBuffer | Blob | BunFile | Request | Response | File | ArrayBufferView<ArrayBufferLike> | S3File,
      options?: S3Options
      ): Promise<number>;

      Writes data directly to a path in the bucket. Supports strings, buffers, streams, and web API types.

      @param path

      The path to the file in the bucket

      @param data

      The data to write to the file

      @param options

      Additional S3 options to override defaults

      @returns

      The number of bytes written

      // Write string
    await bucket.write("hello.txt", "Hello World");

    // Write JSON with type
    await bucket.write(
      "data.json",
      JSON.stringify({hello: "world"}),
      {type: "application/json"}
    );

    // Write from fetch
    const res = await fetch("https://example.com/data");
    await bucket.write("data.bin", res);

    // Write with ACL
    await bucket.write("public.html", html, {
      acl: "public-read",
      type: "text/html"
    });
    • static delete(
      path: string,
      options?: S3Options
      ): Promise<void>;

      Delete a file from the bucket. Alias for S3Client.unlink.

      @param path

      The path to the file in the bucket

      @param options

      S3 credentials and configuration options

      @returns

      A promise that resolves when deletion is complete

      // Simple delete
    await S3Client.delete("old-file.txt", credentials);

    // With error handling
    try {
      await S3Client.delete("file.dat", credentials);
      console.log("File deleted");
    } catch (err) {
      console.error("Delete failed:", err);
    }
    • static exists(
      path: string,
      options?: S3Options
      ): Promise<boolean>;

      Check if a file exists in the bucket. Uses HEAD request to check existence.

      @param path

      The path to the file in the bucket

      @param options

      S3 credentials and configuration options

      @returns

      A promise that resolves to true if the file exists, false otherwise

      // Check existence
    if (await S3Client.exists("config.json", credentials)) {
      const file = bucket.file("config.json");
      const config = await file.json();
    }

    // With error handling
    try {
      if (!await S3Client.exists("required.txt", credentials)) {
        throw new Error("Required file missing");
      }
    } catch (err) {
      console.error("Check failed:", err);
    }
    • static file(
      path: string,
      options?: S3Options
      ): S3File;

      Creates an S3File instance for the given path.

      @param path

      The path to the file in the bucket

      @param options

      S3 credentials and configuration options

      @returns

      An S3File instance

      const file = S3Client.file("image.jpg", credentials);
    await file.write(imageData);

    const configFile = S3Client.file("config.json", {
      ...credentials,
      type: "application/json",
      acl: "private"
    });
    • static list(
      input?: null | S3ListObjectsOptions,
      options?: Pick<S3Options, 'accessKeyId' | 'secretAccessKey' | 'sessionToken' | 'region' | 'bucket' | 'endpoint'>

      Returns some or all (up to 1,000) of the objects in a bucket with each request.

      You can use the request parameters as selection criteria to return a subset of the objects in a bucket.

      @param input

      Options for listing objects in the bucket

      @param options

      S3 credentials and configuration options

      @returns

      A promise that resolves to the list response

      // List (up to) 1000 objects in the bucket
    const allObjects = await S3Client.list(null, credentials);

    // List (up to) 500 objects under `uploads/` prefix, with owner field for each object
    const uploads = await S3Client.list({
      prefix: 'uploads/',
      maxKeys: 500,
      fetchOwner: true,
    }, credentials);

    // Check if more results are available
    if (uploads.isTruncated) {
      // List next batch of objects under `uploads/` prefix
      const moreUploads = await S3Client.list({
        prefix: 'uploads/',
        maxKeys: 500,
        startAfter: uploads.contents!.at(-1).key
        fetchOwner: true,
      }, credentials);
    }
    • static presign(
      path: string,
      options?: S3FilePresignOptions
      ): string;

      Generate a presigned URL for temporary access to a file. Useful for generating upload/download URLs without exposing credentials.

      @param path

      The path to the file in the bucket

      @param options

      S3 credentials and presigned URL configuration

      @returns

      A presigned URL string

      // Download URL
    const downloadUrl = S3Client.presign("file.pdf", {
      ...credentials,
      expiresIn: 3600 // 1 hour
    });

    // Upload URL
    const uploadUrl = S3Client.presign("uploads/image.jpg", {
      ...credentials,
      method: "PUT",
      expiresIn: 3600,
      type: "image/jpeg",
      acl: "public-read"
    });

    // Long-lived public URL
    const publicUrl = S3Client.presign("public/doc.pdf", {
      ...credentials,
      expiresIn: 7 * 24 * 60 * 60, // 7 days
      acl: "public-read"
    });
    • static size(
      path: string,
      options?: S3Options
      ): Promise<number>;

      Get the size of a file in bytes. Uses HEAD request to efficiently get size.

      @param path

      The path to the file in the bucket

      @param options

      S3 credentials and configuration options

      @returns

      A promise that resolves to the file size in bytes

      // Get size
    const bytes = await S3Client.size("video.mp4", credentials);
    console.log(`Size: ${bytes} bytes`);

    // Check if file is large
    if (await S3Client.size("data.zip", credentials) > 100 * 1024 * 1024) {
      console.log("File is larger than 100MB");
    }
    • static stat(
      path: string,
      options?: S3Options
      ): Promise<S3Stats>;

      Get the stat of a file in an S3-compatible storage service.

      @param path

      The path to the file in the bucket

      @param options

      S3 credentials and configuration options

      @returns

      A promise that resolves to the file stats

      const stat = await S3Client.stat("my-file.txt", credentials);
    • static write(
      path: string,
      data: string | ArrayBuffer | SharedArrayBuffer | Blob | BunFile | Request | Response | File | ArrayBufferView<ArrayBufferLike> | S3File,
      options?: S3Options
      ): Promise<number>;

      Writes data directly to a path in the bucket. Supports strings, buffers, streams, and web API types.

      @param path

      The path to the file in the bucket

      @param data

      The data to write to the file

      @param options

      S3 credentials and configuration options

      @returns

      The number of bytes written

      // Write string
    await S3Client.write("hello.txt", "Hello World", credentials);

    // Write JSON with type
    await S3Client.write(
      "data.json",
      JSON.stringify({hello: "world"}),
      {
        ...credentials,
        type: "application/json"
      }
    );

    // Write from fetch
    const res = await fetch("https://example.com/data");
    await S3Client.write("data.bin", res, credentials);

    // Write with ACL
    await S3Client.write("public.html", html, {
      ...credentials,
      acl: "public-read",
      type: "text/html"
    });

  • class SHA1

    This is not the default because it's not cryptographically secure and it's slower than SHA512

    Consider using the ugly-named SHA512_256 instead

    • readonly static byteLength: 20

      The number of bytes the hash will produce

    • encoding: DigestEncoding
      ): string;

      Finalize the hash

      @param encoding

      DigestEncoding to return the hash in. If none is provided, it will return a Uint8Array.

      hashInto?: TypedArray<ArrayBufferLike>
      ): TypedArray;

      Finalize the hash

      @param hashInto

      TypedArray to write the hash into. Faster than creating a new one each time

    • data: BlobOrStringOrBuffer
      ): SHA1;

      Update the hash with data

    • static hash(
      input: BlobOrStringOrBuffer,
      hashInto?: TypedArray<ArrayBufferLike>
      ): TypedArray;

      Run the hash over the given data

      @param input

      string, Uint8Array, or ArrayBuffer to hash. Uint8Array or ArrayBuffer is faster.

      @param hashInto

      TypedArray to write the hash into. Faster than creating a new one each time

      static hash(
      input: BlobOrStringOrBuffer,
      encoding: DigestEncoding
      ): string;

      Run the hash over the given data

      @param input

      string, Uint8Array, or ArrayBuffer to hash. Uint8Array or ArrayBuffer is faster.

      @param encoding

      DigestEncoding to return the hash in

  • class SHA224

    This class only exists in types

    • readonly static byteLength: 28

      The number of bytes the hash will produce

    • encoding: DigestEncoding
      ): string;

      Finalize the hash

      @param encoding

      DigestEncoding to return the hash in. If none is provided, it will return a Uint8Array.

      hashInto?: TypedArray<ArrayBufferLike>
      ): TypedArray;

      Finalize the hash

      @param hashInto

      TypedArray to write the hash into. Faster than creating a new one each time

    • data: BlobOrStringOrBuffer
      ): SHA224;

      Update the hash with data

    • static hash(
      input: BlobOrStringOrBuffer,
      hashInto?: TypedArray<ArrayBufferLike>
      ): TypedArray;

      Run the hash over the given data

      @param input

      string, Uint8Array, or ArrayBuffer to hash. Uint8Array or ArrayBuffer is faster.

      @param hashInto

      TypedArray to write the hash into. Faster than creating a new one each time

      static hash(
      input: BlobOrStringOrBuffer,
      encoding: DigestEncoding
      ): string;

      Run the hash over the given data

      @param input

      string, Uint8Array, or ArrayBuffer to hash. Uint8Array or ArrayBuffer is faster.

      @param encoding

      DigestEncoding to return the hash in

  • class SHA256

    This class only exists in types

    • readonly static byteLength: 32

      The number of bytes the hash will produce

    • encoding: DigestEncoding
      ): string;

      Finalize the hash

      @param encoding

      DigestEncoding to return the hash in. If none is provided, it will return a Uint8Array.

      hashInto?: TypedArray<ArrayBufferLike>
      ): TypedArray;

      Finalize the hash

      @param hashInto

      TypedArray to write the hash into. Faster than creating a new one each time

    • data: BlobOrStringOrBuffer
      ): SHA256;

      Update the hash with data

    • static hash(
      input: BlobOrStringOrBuffer,
      hashInto?: TypedArray<ArrayBufferLike>
      ): TypedArray;

      Run the hash over the given data

      @param input

      string, Uint8Array, or ArrayBuffer to hash. Uint8Array or ArrayBuffer is faster.

      @param hashInto

      TypedArray to write the hash into. Faster than creating a new one each time

      static hash(
      input: BlobOrStringOrBuffer,
      encoding: DigestEncoding
      ): string;

      Run the hash over the given data

      @param input

      string, Uint8Array, or ArrayBuffer to hash. Uint8Array or ArrayBuffer is faster.

      @param encoding

      DigestEncoding to return the hash in

  • class SHA384

    This class only exists in types

    • readonly static byteLength: 48

      The number of bytes the hash will produce

    • encoding: DigestEncoding
      ): string;

      Finalize the hash

      @param encoding

      DigestEncoding to return the hash in. If none is provided, it will return a Uint8Array.

      hashInto?: TypedArray<ArrayBufferLike>
      ): TypedArray;

      Finalize the hash

      @param hashInto

      TypedArray to write the hash into. Faster than creating a new one each time

    • data: BlobOrStringOrBuffer
      ): SHA384;

      Update the hash with data

    • static hash(
      input: BlobOrStringOrBuffer,
      hashInto?: TypedArray<ArrayBufferLike>
      ): TypedArray;

      Run the hash over the given data

      @param input

      string, Uint8Array, or ArrayBuffer to hash. Uint8Array or ArrayBuffer is faster.

      @param hashInto

      TypedArray to write the hash into. Faster than creating a new one each time

      static hash(
      input: BlobOrStringOrBuffer,
      encoding: DigestEncoding
      ): string;

      Run the hash over the given data

      @param input

      string, Uint8Array, or ArrayBuffer to hash. Uint8Array or ArrayBuffer is faster.

      @param encoding

      DigestEncoding to return the hash in

  • class SHA512

    This class only exists in types

    • readonly static byteLength: 64

      The number of bytes the hash will produce

    • encoding: DigestEncoding
      ): string;

      Finalize the hash

      @param encoding

      DigestEncoding to return the hash in. If none is provided, it will return a Uint8Array.

      hashInto?: TypedArray<ArrayBufferLike>
      ): TypedArray;

      Finalize the hash

      @param hashInto

      TypedArray to write the hash into. Faster than creating a new one each time

    • data: BlobOrStringOrBuffer
      ): SHA512;

      Update the hash with data

    • static hash(
      input: BlobOrStringOrBuffer,
      hashInto?: TypedArray<ArrayBufferLike>
      ): TypedArray;

      Run the hash over the given data

      @param input

      string, Uint8Array, or ArrayBuffer to hash. Uint8Array or ArrayBuffer is faster.

      @param hashInto

      TypedArray to write the hash into. Faster than creating a new one each time

      static hash(
      input: BlobOrStringOrBuffer,
      encoding: DigestEncoding
      ): string;

      Run the hash over the given data

      @param input

      string, Uint8Array, or ArrayBuffer to hash. Uint8Array or ArrayBuffer is faster.

      @param encoding

      DigestEncoding to return the hash in

  • class SHA512_256

    See also sha

    • readonly static byteLength: 32

      The number of bytes the hash will produce

    • encoding: DigestEncoding
      ): string;

      Finalize the hash

      @param encoding

      DigestEncoding to return the hash in. If none is provided, it will return a Uint8Array.

      hashInto?: TypedArray<ArrayBufferLike>
      ): TypedArray;

      Finalize the hash

      @param hashInto

      TypedArray to write the hash into. Faster than creating a new one each time

    • data: BlobOrStringOrBuffer

      Update the hash with data

    • static hash(
      input: BlobOrStringOrBuffer,
      hashInto?: TypedArray<ArrayBufferLike>
      ): TypedArray;

      Run the hash over the given data

      @param input

      string, Uint8Array, or ArrayBuffer to hash. Uint8Array or ArrayBuffer is faster.

      @param hashInto

      TypedArray to write the hash into. Faster than creating a new one each time

      static hash(
      input: BlobOrStringOrBuffer,
      encoding: DigestEncoding
      ): string;

      Run the hash over the given data

      @param input

      string, Uint8Array, or ArrayBuffer to hash. Uint8Array or ArrayBuffer is faster.

      @param encoding

      DigestEncoding to return the hash in

  • class Transpiler

    Quickly transpile TypeScript, JSX, or JS to modern JavaScript.

    const transpiler = new Bun.Transpiler();
transpiler.transformSync(`
  const App = () => <div>Hello World</div>;
export default App;
`);
// This outputs:
const output = `
const App = () => jsx("div", {
  children: "Hello World"
}, undefined, false, undefined, this);
export default App;
`
    • code: StringOrBuffer
      ): { exports: string[]; imports: Import[] };

      Get a list of import paths and paths from a TypeScript, JSX, TSX, or JavaScript file.

      @param code

      The code to scan

      const {imports, exports} = transpiler.scan(`
import {foo} from "baz";
export const hello = "hi!";
`);

console.log(imports); // ["baz"]
console.log(exports); // ["hello"]
    • code: StringOrBuffer
      ): Import[];

      Get a list of import paths from a TypeScript, JSX, TSX, or JavaScript file.

      @param code

      The code to scan

      const imports = transpiler.scanImports(`
import {foo} from "baz";
import type {FooType} from "bar";
import type {DogeType} from "wolf";
`);

console.log(imports); // ["baz"]

      This is a fast path which performs less work than scan.

    • code: StringOrBuffer,
      loader?: JavaScriptLoader
      ): Promise<string>;

      Transpile code from TypeScript or JSX into valid JavaScript. This function does not resolve imports.

      @param code

      The code to transpile

    • code: StringOrBuffer,
      loader: JavaScriptLoader,
      ctx: object
      ): string;

      Transpile code from TypeScript or JSX into valid JavaScript. This function does not resolve imports.

      @param code

      The code to transpile

      code: StringOrBuffer,
      ctx: object
      ): string;

      Transpile code from TypeScript or JSX into valid JavaScript. This function does not resolve imports.

      @param code

      The code to transpile

      @param ctx

      An object to pass to macros

      code: StringOrBuffer,
      loader?: JavaScriptLoader
      ): string;

      Transpile code from TypeScript or JSX into valid JavaScript. This function does not resolve imports.

      @param code

      The code to transpile

  • interface BunFile

    Blob powered by the fastest system calls available for operating on files.

    This Blob is lazy. That means it won't do any work until you read from it.

    • size will not be valid until the contents of the file are read at least once.
    • type is auto-set based on the file extension when possible
    const file = Bun.file("./hello.json");
console.log(file.type); // "application/json"
console.log(await file.text()); // '{"hello":"world"}'
    • lastModified: number

      A UNIX timestamp indicating when the file was last modified.

    • readonly name?: string

      The name or path of the file, as specified in the constructor.

    • readonly size: number
    • readonly type: string

    • Returns a promise that resolves to the contents of the blob as an ArrayBuffer

    • bytes(): Promise<Uint8Array<ArrayBufferLike>>;

      Returns a promise that resolves to the contents of the blob as a Uint8Array (array of bytes) its the same as new Uint8Array(await blob.arrayBuffer())

    • delete(): Promise<void>;

      Deletes the file (same as unlink)

    • exists(): Promise<boolean>;

      Does the file exist?

      This returns true for regular files and FIFOs. It returns false for directories. Note that a race condition can occur where the file is deleted or renamed after this is called but before you open it.

      This does a system call to check if the file exists, which can be slow.

      If using this in an HTTP server, it's faster to instead use return new Response(Bun.file(path)) and then an error handler to handle exceptions.

      Instead of checking for a file's existence and then performing the operation, it is faster to just perform the operation and handle the error.

      For empty Blob, this always returns true.

    • formData(): Promise<FormData>;

      Read the data from the blob as a FormData object.

      This first decodes the data from UTF-8, then parses it as a multipart/form-data body or a application/x-www-form-urlencoded body.

      The type property of the blob is used to determine the format of the body.

      This is a non-standard addition to the Blob API, to make it conform more closely to the BodyMixin API.

    • json(): Promise<any>;

      Read the data from the blob as a JSON object.

      This first decodes the data from UTF-8, then parses it as JSON.

    • begin?: number,
      end?: number,
      contentType?: string

      Offset any operation on the file starting at begin and ending at end. end is relative to 0

      Similar to TypedArray.subarray. Does not copy the file, open the file, or modify the file.

      If begin > 0, () will be slower on macOS

      @param begin

      start offset in bytes

      @param end

      absolute offset in bytes (relative to 0)

      @param contentType

      MIME type for the new BunFile

      begin?: number,
      contentType?: string

      Offset any operation on the file starting at begin

      Similar to TypedArray.subarray. Does not copy the file, open the file, or modify the file.

      If begin > 0, Bun.write() will be slower on macOS

      @param begin

      start offset in bytes

      @param contentType

      MIME type for the new BunFile

      contentType?: string

      Slice the file from the beginning to the end, optionally with a new MIME type.

      @param contentType

      MIME type for the new BunFile

    • stat(): Promise<Stats>;

      Provides useful information about the file.

    • stream(): ReadableStream<Uint8Array<ArrayBufferLike>>;

      Returns a readable stream of the blob's contents

    • text(): Promise<string>;

      Returns a promise that resolves to the contents of the blob as a string

    • data: string | ArrayBuffer | SharedArrayBuffer | BunFile | Request | Response | ArrayBufferView<ArrayBufferLike>,
      options?: { highWaterMark: number }
      ): Promise<number>;

      Write data to the file. This is equivalent to using Bun.write with a BunFile.

      @param data

      The data to write.

      @param options

      The options to use for the write.

    • options?: { highWaterMark: number }

      Incremental writer for files and pipes.

  • interface S3File

    Represents a file in an S3-compatible storage service. Extends the Blob interface for compatibility with web APIs.

    • readonly bucket?: string

      The bucket name containing the file.

      const file = s3.file("s3://my-bucket/file.txt");
   console.log(file.bucket); // "my-bucket"
    • readonly name?: string

      The name or path of the file in the bucket.

      const file = s3.file("folder/image.jpg");
console.log(file.name); // "folder/image.jpg"
    • readonly readable: ReadableStream

      Gets a readable stream of the file's content. Useful for processing large files without loading them entirely into memory.

      // Basic streaming read
    const stream = file.stream();
    for await (const chunk of stream) {
      console.log('Received chunk:', chunk);
    }
    • readonly size: number
    • readonly type: string

    • Returns a promise that resolves to the contents of the blob as an ArrayBuffer

    • bytes(): Promise<Uint8Array<ArrayBufferLike>>;

      Returns a promise that resolves to the contents of the blob as a Uint8Array (array of bytes) its the same as new Uint8Array(await blob.arrayBuffer())

    • delete(): Promise<void>;

      Deletes the file from S3.

      @returns

      Promise that resolves when deletion is complete

      // Basic deletion
    await file.delete();
    • exists(): Promise<boolean>;

      Checks if the file exists in S3. Uses HTTP HEAD request to efficiently check existence without downloading.

      @returns

      Promise resolving to true if file exists, false otherwise

      // Basic existence check
   if (await file.exists()) {
     console.log("File exists in S3");
   }
    • formData(): Promise<FormData>;

      Read the data from the blob as a FormData object.

      This first decodes the data from UTF-8, then parses it as a multipart/form-data body or a application/x-www-form-urlencoded body.

      The type property of the blob is used to determine the format of the body.

      This is a non-standard addition to the Blob API, to make it conform more closely to the BodyMixin API.

    • json(): Promise<any>;

      Read the data from the blob as a JSON object.

      This first decodes the data from UTF-8, then parses it as JSON.

    • options?: S3FilePresignOptions
      ): string;

      Generates a presigned URL for the file. Allows temporary access to the file without exposing credentials.

      @param options

      Configuration for the presigned URL

      @returns

      Presigned URL string

      // Basic download URL
    const url = file.presign({
      expiresIn: 3600 // 1 hour
    });
    • begin?: number,
      end?: number,
      contentType?: string
      ): S3File;

      Creates a new S3File representing a slice of the original file. Uses HTTP Range headers for efficient partial downloads.

      @param begin

      Starting byte offset

      @param end

      Ending byte offset (exclusive)

      @param contentType

      Optional MIME type for the slice

      @returns

      A new S3File representing the specified range

      // Reading file header
    const header = file.slice(0, 1024);
    const headerText = await header.text();
      begin?: number,
      contentType?: string
      ): S3File;
      contentType?: string
      ): S3File;
    • stat(): Promise<S3Stats>;

      Get the stat of a file in an S3-compatible storage service.

      @returns

      Promise resolving to S3Stat

    • text(): Promise<string>;

      Returns a promise that resolves to the contents of the blob as a string

    • data: string | ArrayBuffer | SharedArrayBuffer | Blob | BunFile | Request | Response | ArrayBufferView<ArrayBufferLike> | S3File,
      options?: S3Options
      ): Promise<number>;

      Uploads data to S3. Supports various input types and automatically handles large files.

      @param data

      The data to upload

      @param options

      Upload configuration options

      @returns

      Promise resolving to number of bytes written

      // Writing string data
    await file.write("Hello World", {
      type: "text/plain"
    });
    • options?: S3Options

      Creates a writable stream for uploading data. Suitable for large files as it uses multipart upload.

      @param options

      Configuration for the upload

      @returns

      A NetworkSink for writing data

      // Basic streaming write
    const writer = file.writer({
      type: "application/json"
    });
    writer.write('{"hello": ');
    writer.write('"world"}');
    await writer.end();

  • interface Server

    HTTP & HTTPS Server

    To start the server, see serve

    For performance, Bun pre-allocates most of the data for 2048 concurrent requests. That means starting a new server allocates about 500 KB of memory. Try to avoid starting and stopping the server often (unless it's a new instance of bun).

    Powered by a fork of uWebSockets. Thank you @alexhultman.

    • readonly development: boolean

      Is the server running in development mode?

      In development mode, Bun.serve() returns rendered error messages with stack traces instead of a generic 500 error. This makes debugging easier, but development mode shouldn't be used in production or you will risk leaking sensitive information.

    • readonly hostname: undefined | string

      The hostname the server is listening on. Does not include the port.

      This will be undefined when the server is listening on a unix socket.

      "localhost"
    • readonly id: string

      An identifier of the server instance

      When bun is started with the --hot flag, this ID is used to hot reload the server without interrupting pending requests or websockets.

      When bun is not started with the --hot flag, this ID is currently unused.

    • readonly pendingRequests: number

      How many requests are in-flight right now?

    • readonly pendingWebSockets: number

      How many ServerWebSockets are in-flight right now?

    • readonly port: undefined | number

      The port the server is listening on.

      This will be undefined when the server is listening on a unix socket.

      3000
    • readonly url: URL
    • request: string | Request
      ): Response | Promise<Response>;

      Mock the fetch handler for a running server.

      This feature is not fully implemented yet. It doesn't normalize URLs consistently in all cases and it doesn't yet call the error handler consistently. This needs to be fixed

    • topic: string,
      data: string | ArrayBuffer | SharedArrayBuffer | ArrayBufferView<ArrayBufferLike>,
      compress?: boolean
      ): number;

      Send a message to all connected ServerWebSocket subscribed to a topic

      @param topic

      The topic to publish to

      @param data

      The data to send

      @param compress

      Should the data be compressed? Ignored if the client does not support compression.

      @returns

      0 if the message was dropped, -1 if backpressure was applied, or the number of bytes sent.

      server.publish("chat", "Hello World");
    • ref(): void;

      Undo a call to Server.unref

      If the Server has already been stopped, this does nothing.

      If Server.ref is called multiple times, this does nothing. Think of it as a boolean toggle.

    • reload<T, R extends { [K in string | number | symbol]: RouteValue<K & string> }>(
      options: ServeFunctionOptions<T, R> & { static: R }
      ): Server;

      Update the fetch and error handlers without restarting the server.

      This is useful if you want to change the behavior of your server without restarting it or for hot reloading.

      // create the server
const server = Bun.serve({
 fetch(request) {
   return new Response("Hello World v1")
 }
});

// Update the server to return a different response
server.reload({
  fetch(request) {
    return new Response("Hello World v2")
  }
});

      Passing other options such as port or hostname won't do anything.

    • request: Request
      ): null | SocketAddress;

      Returns the client IP address and port of the given Request. If the request was closed or is a unix socket, returns null.

      export default {
 async fetch(request, server) {
   return new Response(server.requestIP(request));
 }
}
    • closeActiveConnections?: boolean
      ): Promise<void>;

      Stop listening to prevent new connections from being accepted.

      By default, it does not cancel in-flight requests or websockets. That means it may take some time before all network activity stops.

      @param closeActiveConnections

      Immediately terminate in-flight requests, websockets, and stop accepting new connections.

    • topic: string
      ): number;

      A count of connections subscribed to a given topic

      This operation will loop through each topic internally to get the count.

      @param topic

      the websocket topic to check how many subscribers are connected to

      @returns

      the number of subscribers

    • request: Request,
      seconds: number
      ): void;

      Reset the idleTimeout of the given Request to the number in seconds. 0 means no timeout.

      export default {
 async fetch(request, server) {
   server.timeout(request, 60);
   await Bun.sleep(30000);
   return new Response("30 seconds have passed");
 }
}
    • unref(): void;

      Don't keep the process alive if this server is the only thing left. Active connections may continue to keep the process alive.

      By default, the server is ref'd.

      To prevent new connections from being accepted, use Server.stop

    • upgrade<T = undefined>(
      request: Request,
      options?: { data: T; headers: HeadersInit }
      ): boolean;

      Upgrade a Request to a ServerWebSocket

      @param request

      The Request to upgrade

      @param options

      Pass headers or attach data to the ServerWebSocket

      @returns

      true if the upgrade was successful and false if it failed

      import { serve } from "bun";
 serve({
   websocket: {
     open: (ws) => {
       console.log("Client connected");
     },
     message: (ws, message) => {
       console.log("Client sent message", message);
     },
     close: (ws) => {
       console.log("Client disconnected");
     },
   },
   fetch(req, server) {
     const url = new URL(req.url);
     if (url.pathname === "/chat") {
       const upgraded = server.upgrade(req);
       if (!upgraded) {
         return new Response("Upgrade failed", { status: 400 });
       }
     }
     return new Response("Hello World");
   },
 });

      What you pass to data is available on the ServerWebSocket.data property

  • const argv: string[]

    The raw arguments passed to the process, including flags passed to Bun. If you want to easily read flags passed to your script, consider using process.argv instead.

  • const embeddedFiles: ReadonlyArray<Blob>

    A list of files embedded into the standalone executable. Lexigraphically sorted by name.

    If the process is not a standalone executable, this returns an empty array.

  • const enableANSIColors: boolean

    Are ANSI colors enabled for stdin and stdout?

    Used for console.log

  • const env: Env & NodeJS.ProcessEnv & ImportMetaEnv

    The environment variables of the process

    Defaults to process.env as it was when the current Bun process launched.

    Changes to process.env at runtime won't automatically be reflected in the default value. For that, you can pass process.env explicitly.

  • const fetch: typeof globalThis.fetch
  • const hash: (data: string | ArrayBufferView | ArrayBuffer | SharedArrayBuffer, seed?: number | bigint) => number | bigint & Hash

    Hash a string or array buffer using Wyhash

    This is not a cryptographic hash function.

  • const isMainThread: boolean

    Is the current global scope the main thread?

  • const main: string

    What script launched Bun?

    Absolute file path

    "/never-gonna-give-you-up.js"
  • const password: { hash(password: StringOrBuffer, algorithm?: Argon2Algorithm | 'argon2id' | 'argon2d' | 'argon2i' | BCryptAlgorithm | 'bcrypt'): Promise<string>; hashSync(password: StringOrBuffer, algorithm?: Argon2Algorithm | 'argon2id' | 'argon2d' | 'argon2i' | BCryptAlgorithm | 'bcrypt'): string; verify(password: StringOrBuffer, hash: StringOrBuffer, algorithm?: 'argon2id' | 'argon2d' | 'argon2i' | 'bcrypt'): Promise<boolean>; verifySync(password: StringOrBuffer, hash: StringOrBuffer, algorithm?: 'argon2id' | 'argon2d' | 'argon2i' | 'bcrypt'): boolean }

    Hash and verify passwords using argon2 or bcrypt. The default is argon2. Password hashing functions are necessarily slow, and this object will automatically run in a worker thread.

    Example with argon2

    import {password} from "bun";

const hash = await password.hash("hello world");
const verify = await password.verify("hello world", hash);
console.log(verify); // true

    Example with bcrypt

    import {password} from "bun";

const hash = await password.hash("hello world", "bcrypt");
// algorithm is optional, will be inferred from the hash if not specified
const verify = await password.verify("hello world", hash, "bcrypt");

console.log(verify); // true
  • const postgres: SQL

    SQL client for PostgreSQL

  • Default Redis client

    Connection information populated from one of, in order of preference:

    • process.env.VALKEY_URL
    • process.env.REDIS_URL
    • "valkey://localhost:6379"
  • const revision: string

    The git sha at the time the currently-running version of Bun was compiled

    "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
  • const s3: S3Client

    A default instance of S3Client

    Pulls credentials from environment variables. Use new Bun.S3Client() if you need to explicitly set credentials.

  • const sql: SQL

    SQL client

  • const SQL: SQL

    The SQL constructor

  • Write to stderr

  • const stdin: BunFile

    Read from stdin

    This is a read-only BunFile

  • Write to stdout

  • const version: string

    The current version of Bun

    "1.2.0"
  • const version_with_sha: string

    The current version of Bun with the shortened commit sha of the build

    "v1.2.0 (a1b2c3d4)"
  • function $(
    strings: TemplateStringsArray,
    ...expressions: ShellExpression[]

    The Bun shell is a powerful tool for running shell commands.

    const result = await $`echo "Hello, world!"`.text();
console.log(result); // "Hello, world!"

    class ShellError

    ShellError represents an error that occurred while executing a shell command with the Bun Shell.

    try {
  const result = await $`exit 1`;
} catch (error) {
  if (error instanceof ShellError) {
    console.log(error.exitCode); // 1
  }
}
    • cause?: unknown

      The cause of the error.

    • readonly exitCode: number
    • message: string
    • name: string
    • stack?: string
    • readonly stderr: Buffer
    • readonly stdout: Buffer
    • static prepareStackTrace?: (err: Error, stackTraces: CallSite[]) => any

      Optional override for formatting stack traces

    • static stackTraceLimit: number

      The maximum number of stack frames to capture.

    • Read from stdout as an ArrayBuffer

      @returns

      Stdout as an ArrayBuffer

      const output = await $`echo hello`;
console.log(output.arrayBuffer()); // ArrayBuffer { byteLength: 6 }

    • Read from stdout as a Blob

      @returns

      Stdout as a blob

      const output = await $`echo hello`;
console.log(output.blob()); // Blob { size: 6, type: "" }

    • Read from stdout as an Uint8Array

      @returns

      Stdout as an Uint8Array

      const output = await $`echo hello`;
console.log(output.bytes()); // Uint8Array { byteLength: 6 }
    • json(): any;

      Read from stdout as a JSON object

      @returns

      Stdout as a JSON object

      const output = await $`echo '{"hello": 123}'`;
console.log(output.json()); // { hello: 123 }
    • encoding?: BufferEncoding
      ): string;

      Read from stdout as a string

      @param encoding

      The encoding to use when decoding the output

      @returns

      Stdout as a string with the given encoding

      Read as UTF-8 string

      const output = await $`echo hello`;
console.log(output.text()); // "hello\n"

      Read as base64 string

      const output = await $`echo ${atob("hello")}`;
console.log(output.text("base64")); // "hello\n"
    • targetObject: object,
      constructorOpt?: Function
      ): void;

      Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

      const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

      The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

      The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

      The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

      function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();
    • static isError(
      value: unknown
      ): value is Error;

      Check if a value is an instance of Error

      @param value

      The value to check

      @returns

      True if the value is an instance of Error, false otherwise

    class ShellPromise

    The Bun.$.ShellPromise class represents a shell command that gets executed once awaited, or called with .text(), .json(), etc.

    const myShellPromise = $`echo "Hello, world!"`;
const result = await myShellPromise.text();
console.log(result); // "Hello, world!"
    • readonly [Symbol.toStringTag]: string

    • Read from stdout as an ArrayBuffer

      Automatically calls quiet

      @returns

      A promise that resolves with stdout as an ArrayBuffer

      const output = await $`echo hello`.arrayBuffer();
console.log(output); // ArrayBuffer { byteLength: 6 }
    • blob(): Promise<Blob>;

      Read from stdout as a Blob

      Automatically calls quiet

      @returns

      A promise that resolves with stdout as a Blob

      const output = await $`echo hello`.blob();
console.log(output); // Blob { size: 6, type: "" }
    • catch<TResult = never>(
      onrejected?: null | (reason: any) => TResult | PromiseLike<TResult>
      ): Promise<ShellOutput | TResult>;

      Attaches a callback for only the rejection of the Promise.

      @param onrejected

      The callback to execute when the Promise is rejected.

      @returns

      A Promise for the completion of the callback.

    • newCwd: string
      ): this;

      Change the current working directory of the shell.

      @param newCwd

      The new working directory

    • newEnv: undefined | Record<string, string>
      ): this;

      Set environment variables for the shell.

      @param newEnv

      The new environment variables

      await $`echo $FOO`.env({ ...process.env, FOO: "LOL!" })
expect(stdout.toString()).toBe("LOL!");
    • onfinally?: null | () => void
      ): Promise<ShellOutput>;

      Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected). The resolved value cannot be modified from the callback.

      @param onfinally

      The callback to execute when the Promise is settled (fulfilled or rejected).

      @returns

      A Promise for the completion of the callback.

    • json(): Promise<any>;

      Read from stdout as a JSON object

      Automatically calls quiet

      @returns

      A promise that resolves with stdout as a JSON object

      const output = await $`echo '{"hello": 123}'`.json();
console.log(output); // { hello: 123 }
    • lines(): AsyncIterable<string>;

      Read from stdout as a string, line by line

      Automatically calls quiet to disable echoing to stdout.

    • nothrow(): this;

      Configure the shell to not throw an exception on non-zero exit codes. Throwing can be re-enabled with .throws(true).

      By default, the shell with throw an exception on commands which return non-zero exit codes.

    • quiet(): this;

      By default, the shell will write to the current process's stdout and stderr, as well as buffering that output.

      This configures the shell to only buffer the output.

    • encoding?: BufferEncoding
      ): Promise<string>;

      Read from stdout as a string.

      Automatically calls quiet to disable echoing to stdout.

      @param encoding

      The encoding to use when decoding the output

      @returns

      A promise that resolves with stdout as a string

      Read as UTF-8 string

      const output = await $`echo hello`.text();
console.log(output); // "hello\n"

      Read as base64 string

      const output = await $`echo ${atob("hello")}`.text("base64");
console.log(output); // "hello\n"
    • then<TResult1 = ShellOutput, TResult2 = never>(
      onfulfilled?: null | (value: ShellOutput) => TResult1 | PromiseLike<TResult1>,
      onrejected?: null | (reason: any) => TResult2 | PromiseLike<TResult2>
      ): Promise<TResult1 | TResult2>;

      Attaches callbacks for the resolution and/or rejection of the Promise.

      @param onfulfilled

      The callback to execute when the Promise is resolved.

      @param onrejected

      The callback to execute when the Promise is rejected.

      @returns

      A Promise for the completion of which ever callback is executed.

    • shouldThrow: boolean
      ): this;

      Configure whether or not the shell should throw an exception on non-zero exit codes.

      By default, this is configured to true.

    • static all<T extends [] | readonly unknown[]>(
      values: T
      ): Promise<{ [K in string | number | symbol]: Awaited<T[P<P>]> }>;

      Creates a Promise that is resolved with an array of results when all of the provided Promises resolve, or rejected when any Promise is rejected.

      @param values

      An array of Promises.

      @returns

      A new Promise.

    • static allSettled<T>(
      values: Iterable<T | PromiseLike<T>>
      ): Promise<PromiseSettledResult<Awaited<T>>[]>;

      Creates a Promise that is resolved with an array of results when all of the provided Promises resolve or reject.

      @param values

      An array of Promises.

      @returns

      A new Promise.

    • static any<T extends [] | readonly unknown[]>(
      values: T
      ): Promise<Awaited<T[number]>>;

      The any function returns a promise that is fulfilled by the first given promise to be fulfilled, or rejected with an AggregateError containing an array of rejection reasons if all of the given promises are rejected. It resolves all elements of the passed iterable to promises as it runs this algorithm.

      @param values

      An array or iterable of Promises.

      @returns

      A new Promise.

    • static race<T extends [] | readonly unknown[]>(
      values: T
      ): Promise<Awaited<T[number]>>;

      Creates a Promise that is resolved or rejected when any of the provided Promises are resolved or rejected.

      @param values

      An array of Promises.

      @returns

      A new Promise.

    • static reject<T = never>(
      reason?: any
      ): Promise<T>;

      Creates a new rejected promise for the provided reason.

      @param reason

      The reason the promise was rejected.

      @returns

      A new rejected Promise.

    • static resolve<T>(
      value: T
      ): Promise<Awaited<T>>;

      Creates a new resolved promise for the provided value.

      @param value

      A promise.

      @returns

      A promise whose internal state matches the provided promise.

    • static try<T, A extends any[] = []>(
      fn: (...args: A) => T | PromiseLike<T>,
      ...args: A
      ): Promise<T>;

      Try to run a function and return the result. If the function throws, return the result of the catch function.

      @param fn

      The function to run

      @param args

      The arguments to pass to the function. This is similar to setTimeout and avoids the extra closure.

      @returns

      The result of the function or the result of the catch function

    • static withResolvers<T>(): { promise: Promise<T>; reject: (reason?: any) => void; resolve: (value?: T | PromiseLike<T>) => void };

      Create a deferred promise, with exposed resolve and reject methods which can be called separately.

      This is useful when you want to return a Promise and have code outside the Promise resolve or reject it.

      const { promise, resolve, reject } = Promise.withResolvers();

setTimeout(() => {
 resolve("Hello world!");
}, 1000);

await promise; // "Hello world!"

    interface ShellOutput

    • readonly exitCode: number
    • readonly stderr: Buffer
    • readonly stdout: Buffer

    • Read from stdout as an ArrayBuffer

      @returns

      Stdout as an ArrayBuffer

      const output = await $`echo hello`;
console.log(output.arrayBuffer()); // ArrayBuffer { byteLength: 6 }

    • Read from stdout as a Blob

      @returns

      Stdout as a blob

      const output = await $`echo hello`;
console.log(output.blob()); // Blob { size: 6, type: "" }

    • Read from stdout as an Uint8Array

      @returns

      Stdout as an Uint8Array

      const output = await $`echo hello`;
console.log(output.bytes()); // Uint8Array { byteLength: 6 }
    • json(): any;

      Read from stdout as a JSON object

      @returns

      Stdout as a JSON object

      const output = await $`echo '{"hello": 123}'`;
console.log(output.json()); // { hello: 123 }
    • encoding?: BufferEncoding
      ): string;

      Read from stdout as a string

      @param encoding

      The encoding to use when decoding the output

      @returns

      Stdout as a string with the given encoding

      Read as UTF-8 string

      const output = await $`echo hello`;
console.log(output.text()); // "hello\n"

      Read as base64 string

      const output = await $`echo ${atob("hello")}`;
console.log(output.text("base64")); // "hello\n"
    const Shell: new () => $
    function braces(
    pattern: string
    ): string[];

    Perform bash-like brace expansion on the given pattern.

    @param pattern

    Brace pattern to expand

    const result = braces('index.{js,jsx,ts,tsx}');
console.log(result) // ['index.js', 'index.jsx', 'index.ts', 'index.tsx']
    function cwd(
    newCwd?: string
    ): typeof $;
    @param newCwd

    Default working directory to use for shells created by this instance.

    function env(
    newEnv?: Record<string, undefined | string>
    ): typeof $;

    Change the default environment variables for shells created by this instance.

    @param newEnv

    Default environment variables to use for shells created by this instance.

    import {$} from 'bun';
$.env({ BUN: "bun" });
await $`echo $BUN`;
// "bun"
    function escape(
    input: string
    ): string;

    Escape strings for input into shell commands.

    function nothrow(): typeof $;

    Configure the shell to not throw an exception on non-zero exit codes.

    function throws(
    shouldThrow: boolean
    ): typeof $;

    Configure whether or not the shell should throw an exception on non-zero exit codes.

  • function allocUnsafe(
    size: number

    Allocate a new Uint8Array without zeroing the bytes.

    This can be 3.5x faster than new Uint8Array(size), but if you send uninitialized memory to your users (even unintentionally), it can potentially leak anything recently in memory.

  • function build(
    config: BuildConfig
    ): Promise<BuildOutput>;

    Bundles JavaScript, TypeScript, CSS, HTML and other supported files into optimized outputs.

    @param config

    Build configuration options

    @returns

    Promise that resolves to build output containing generated artifacts and build status

    Basic usage - Bundle a single entrypoint and check results

    const result = await Bun.build({
  entrypoints: ['./src/index.tsx'],
  outdir: './dist'
});

if (!result.success) {
  console.error('Build failed:', result.logs);
  process.exit(1);
}
  • function color(
    input: ColorInput,
    outputFormat?: 'number' | 'hex' | 'ansi' | 'ansi-16' | 'ansi-16m' | 'ansi-256' | 'css' | 'HEX' | 'hsl' | 'lab' | 'rgb' | 'rgba'
    ): null | string;

    Converts formats of colors

    @param input

    A value that could possibly be a color

    @param outputFormat

    An optional output format

    function color(
    input: ColorInput,
    outputFormat: '[rgb]'
    ): null | [number, number, number];

    Convert any color input to rgb

    @param input

    Any color input

    @param outputFormat

    Specify [rgb] to output as an array with r, g, and b properties

    function color(
    input: ColorInput,
    outputFormat: '[rgba]'
    ): null | [number, number, number, number];

    Convert any color input to rgba

    @param input

    Any color input

    @param outputFormat

    Specify [rgba] to output as an array with r, g, b, and a properties

    function color(
    input: ColorInput,
    outputFormat: '{rgb}'
    ): null | { b: number; g: number; r: number };

    Convert any color input to a number

    @param input

    Any color input

    @param outputFormat

    Specify {rgb} to output as an object with r, g, and b properties

    function color(
    input: ColorInput,
    outputFormat: '{rgba}'
    ): null | { a: number; b: number; g: number; r: number };

    Convert any color input to rgba

    @param input

    Any color input

    @param outputFormat

    Specify {rgba} to output as an object with r, g, b, and a properties

    function color(
    input: ColorInput,
    outputFormat: 'number'
    ): null | number;

    Convert any color input to a number

    @param input

    Any color input

    @param outputFormat

    Specify number to output as a number

  • buffers: ArrayBufferLike | ArrayBufferView<ArrayBufferLike>[],
    maxLength?: number

    Concatenate an array of typed arrays into a single ArrayBuffer. This is a fast path.

    You can do this manually if you'd like, but this function will generally be a little faster.

    If you want a Uint8Array instead, consider Buffer.concat.

    @param buffers

    An array of typed arrays to concatenate.

    @returns

    An ArrayBuffer with the data from all the buffers.

    Here is similar code to do it manually, except about 30% slower:

      var chunks = [...];
  var size = 0;
  for (const chunk of chunks) {
    size += chunk.byteLength;
  }
  var buffer = new ArrayBuffer(size);
  var view = new Uint8Array(buffer);
  var offset = 0;
  for (const chunk of chunks) {
    view.set(chunk, offset);
    offset += chunk.byteLength;
  }
  return buffer;

    This function is faster because it uses uninitialized memory when copying. Since the entire length of the buffer is known, it is safe to use uninitialized memory.

    buffers: ArrayBufferLike | ArrayBufferView<ArrayBufferLike>[],
    maxLength: number,
    asUint8Array: false

    Concatenate an array of typed arrays into a single ArrayBuffer. This is a fast path.

    You can do this manually if you'd like, but this function will generally be a little faster.

    If you want a Uint8Array instead, consider Buffer.concat.

    @param buffers

    An array of typed arrays to concatenate.

    @returns

    An ArrayBuffer with the data from all the buffers.

    Here is similar code to do it manually, except about 30% slower:

      var chunks = [...];
  var size = 0;
  for (const chunk of chunks) {
    size += chunk.byteLength;
  }
  var buffer = new ArrayBuffer(size);
  var view = new Uint8Array(buffer);
  var offset = 0;
  for (const chunk of chunks) {
    view.set(chunk, offset);
    offset += chunk.byteLength;
  }
  return buffer;

    This function is faster because it uses uninitialized memory when copying. Since the entire length of the buffer is known, it is safe to use uninitialized memory.

    buffers: ArrayBufferLike | ArrayBufferView<ArrayBufferLike>[],
    maxLength: number,
    asUint8Array: true

    Concatenate an array of typed arrays into a single ArrayBuffer. This is a fast path.

    You can do this manually if you'd like, but this function will generally be a little faster.

    If you want a Uint8Array instead, consider Buffer.concat.

    @param buffers

    An array of typed arrays to concatenate.

    @returns

    An ArrayBuffer with the data from all the buffers.

    Here is similar code to do it manually, except about 30% slower:

      var chunks = [...];
  var size = 0;
  for (const chunk of chunks) {
    size += chunk.byteLength;
  }
  var buffer = new ArrayBuffer(size);
  var view = new Uint8Array(buffer);
  var offset = 0;
  for (const chunk of chunks) {
    view.set(chunk, offset);
    offset += chunk.byteLength;
  }
  return buffer;

    This function is faster because it uses uninitialized memory when copying. Since the entire length of the buffer is known, it is safe to use uninitialized memory.

  • function connect<Data = undefined>(
    options: TCPSocketConnectOptions<Data>
    ): Promise<Socket<Data>>;

    Create a TCP client that connects to a server via a TCP socket

    function connect<Data = undefined>(
    options: UnixSocketOptions<Data>
    ): Promise<Socket<Data>>;

    Create a TCP client that connects to a server via a unix socket

  • function deepEquals(
    a: any,
    b: any,
    strict?: boolean
    ): boolean;

    Fast deep-equality check two objects.

    This also powers expect().toEqual in bun:test

    @param strict
  • function deepMatch(
    subset: unknown,
    a: unknown
    ): boolean;

    Returns true if all properties in the subset exist in the other and have equal values.

    This also powers expect().toMatchObject in bun:test

  • function deflateSync(
    data: string | ArrayBuffer | Uint8Array<ArrayBufferLike>,
    options?: ZlibCompressionOptions | LibdeflateCompressionOptions

    Compresses a chunk of data with zlib DEFLATE algorithm.

    @param data

    The buffer of data to compress

    @param options

    Compression options to use

    @returns

    The output buffer with the compressed data

  • function escapeHTML(
    input: string | number | boolean | object
    ): string;

    Escape the following characters in a string:

  • function file(
    path: string | URL,
    options?: BlobPropertyBag

    Blob powered by the fastest system calls available for operating on files.

    This Blob is lazy. That means it won't do any work until you read from it.

    • size will not be valid until the contents of the file are read at least once.
    • type is auto-set based on the file extension when possible
    @param path

    The path to the file (lazily loaded) if the path starts with s3:// it will behave like S3File

    const file = Bun.file("./hello.json");
console.log(file.type); // "application/json"
console.log(await file.json()); // { hello: "world" }
    function file(
    path: ArrayBufferLike | Uint8Array<ArrayBufferLike>,
    options?: BlobPropertyBag

    Blob that leverages the fastest system calls available to operate on files.

    This Blob is lazy. It won't do any work until you read from it. Errors propagate as promise rejections.

    Blob.size will not be valid until the contents of the file are read at least once. Blob.type will have a default set based on the file extension

    @param path

    The path to the file as a byte buffer (the buffer is copied) if the path starts with s3:// it will behave like S3File

    const file = Bun.file(new TextEncoder.encode("./hello.json"));
console.log(file.type); // "application/json"
    function file(
    fileDescriptor: number,
    options?: BlobPropertyBag

    Blob powered by the fastest system calls available for operating on files.

    This Blob is lazy. That means it won't do any work until you read from it.

    • size will not be valid until the contents of the file are read at least once.
    @param fileDescriptor

    The file descriptor of the file

    const file = Bun.file(fd);
  • function fileURLToPath(
    url: string | URL
    ): string;

    Convert a URL to a filesystem path.

    @param url

    The URL to convert.

    @returns

    A filesystem path.

    const path = Bun.fileURLToPath(new URL("file:///foo/bar.txt"));
console.log(path); // "/foo/bar.txt"
  • function gc(
    force: boolean
    ): void;

    Manually trigger the garbage collector

    This does two things:

    1. It tells JavaScriptCore to run the garbage collector
    2. It tells mimalloc to clean up fragmented memory. Mimalloc manages the heap not used in JavaScriptCore.
    @param force

    Synchronously run the garbage collector

  • format?: 'jsc'

    Show precise statistics about memory usage of your application

    Generate a heap snapshot in JavaScriptCore's format that can be viewed with bun --inspect or Safari's Web Inspector

    format: 'v8'
    ): string;

    Show precise statistics about memory usage of your application

    Generate a V8 Heap Snapshot that can be used with Chrome DevTools & Visual Studio Code

    This is a JSON string that can be saved to a file.

    const snapshot = Bun.generateHeapSnapshot("v8");
await Bun.write("heap.heapsnapshot", snapshot);
  • function gunzipSync(
    data: string | ArrayBuffer | Uint8Array<ArrayBufferLike>,
    options?: ZlibCompressionOptions | LibdeflateCompressionOptions

    Decompresses a chunk of data with zlib GUNZIP algorithm.

    @param data

    The buffer of data to decompress

    @returns

    The output buffer with the decompressed data

  • function gzipSync(
    data: string | ArrayBuffer | Uint8Array<ArrayBufferLike>,
    options?: ZlibCompressionOptions | LibdeflateCompressionOptions

    Compresses a chunk of data with zlib GZIP algorithm.

    @param data

    The buffer of data to compress

    @param options

    Compression options to use

    @returns

    The output buffer with the compressed data

  • function indexOfLine(
    buffer: ArrayBufferLike | ArrayBufferView<ArrayBufferLike>,
    offset?: number
    ): number;

    Find the index of a newline character in potentially ill-formed UTF-8 text.

    This is sort of like readline() except without the IO.

  • function inflateSync(
    data: string | ArrayBuffer | Uint8Array<ArrayBufferLike>,
    options?: ZlibCompressionOptions | LibdeflateCompressionOptions

    Decompresses a chunk of data with zlib INFLATE algorithm.

    @param data

    The buffer of data to decompress

    @returns

    The output buffer with the decompressed data

  • function inspect(
    arg: any,
    options?: BunInspectOptions
    ): string;

    Pretty-print an object the same as console.log to a string

    Supports JSX

    @param arg

    The value to inspect

    @param options

    Options for the inspection

    That can be used to declare custom inspect functions.

    function table(
    tabularData: object | unknown[],
    properties?: string[],
    options?: { colors: boolean }
    ): string;

    Pretty-print an object or array as a table

    Like console.table, except it returns a string

    function table(
    tabularData: object | unknown[],
    options?: { colors: boolean }
    ): string;

    Pretty-print an object or array as a table

    Like console.table, except it returns a string

  • function listen<Data = undefined>(
    options: TCPSocketListenOptions<Data>

    Create a TCP server that listens on a port

    function listen<Data = undefined>(
    options: UnixSocketOptions<Data>

    Create a TCP server that listens on a unix socket

  • function mmap(
    path: PathLike,
    opts?: MMapOptions

    Open a file as a live-updating Uint8Array without copying memory

    • Writing to the array writes to the file.
    • Reading from the array reads from the file.

    This uses the mmap() syscall under the hood.

    This API inherently has some rough edges:

    • It does not support empty files. It will throw a SystemError with EINVAL
    • Usage on shared/networked filesystems is discouraged. It will be very slow.
    • If you delete or truncate the file, that will crash bun. This is called a segmentation fault.

    To close the file, set the array to null and it will be garbage collected eventually.

  • function nanoseconds(): number;

    Returns the number of nanoseconds since the process was started.

    This function uses a high-resolution monotonic system timer to provide precise time measurements. In JavaScript, numbers are represented as double-precision floating-point values (IEEE 754), which can safely represent integers up to 2^53 - 1 (Number.MAX_SAFE_INTEGER).

    Due to this limitation, while the internal counter may continue beyond this point, the precision of the returned value will degrade after 14.8 weeks of uptime (when the nanosecond count exceeds Number.MAX_SAFE_INTEGER). Beyond this point, the function will continue to count but with reduced precision, which might affect time calculations and comparisons in long-running applications.

    @returns

    The number of nanoseconds since the process was started, with precise values up to Number.MAX_SAFE_INTEGER.

  • function openInEditor(
    path: string,
    options?: EditorOptions
    ): void;

    Open a file in your local editor. Auto-detects via $VISUAL || $EDITOR

    @param path

    path to open

  • function pathToFileURL(
    path: string
    ): URL;

    Convert a filesystem path to a file:// URL.

    @param path

    The path to convert.

    @returns

    A URL with the file:// scheme.

    const url = Bun.pathToFileURL("/foo/bar.txt");
console.log(url.href); // "file:///foo/bar.txt"

    Internally, this function uses WebKit's URL API to convert the path to a file:// URL.

  • function peek<T = undefined>(
    promise: T | Promise<T>
    ): T | Promise<T>;

    Extract the value from the Promise in the same tick of the event loop

    function status<T = undefined>(
    promise: T | Promise<T>
    ): 'pending' | 'fulfilled' | 'rejected';
  • function randomUUIDv7(
    encoding?: 'base64' | 'base64url' | 'hex',
    timestamp?: number | Date
    ): string;

    Generate a UUIDv7, which is a sequential ID based on the current timestamp with a random component.

    When the same timestamp is used multiple times, a monotonically increasing counter is appended to allow sorting. The final 8 bytes are cryptographically random. When the timestamp changes, the counter resets to a psuedo-random integer.

    @param encoding

    "hex" | "base64" | "base64url"

    @param timestamp

    Unix timestamp in milliseconds, defaults to Date.now()

    import { randomUUIDv7 } from "bun";
const array = [
  randomUUIDv7(),
  randomUUIDv7(),
  randomUUIDv7(),
]
[
  "0192ce07-8c4f-7d66-afec-2482b5c9b03c",
  "0192ce07-8c4f-7d67-805f-0f71581b5622",
  "0192ce07-8c4f-7d68-8170-6816e4451a58"
]
    function randomUUIDv7(
    encoding: 'buffer',
    timestamp?: number | Date
    ): Buffer;

    Generate a UUIDv7 as a Buffer

    @param encoding

    "buffer"

    @param timestamp

    Unix timestamp in milliseconds, defaults to Date.now()

  • stream: ReadableStream<T>
    ): T[] | Promise<T[]>;

    Consume all data from a ReadableStream until it closes or errors.

    @param stream

    The stream to consume

    @returns

    A promise that resolves with the chunks as an array

  • stream: ReadableStream<ArrayBufferLike | ArrayBufferView<ArrayBufferLike>>
    ): ArrayBuffer | Promise<ArrayBuffer>;

    Consume all data from a ReadableStream until it closes or errors.

    Concatenate the chunks into a single ArrayBuffer.

    Each chunk must be a TypedArray or an ArrayBuffer. If you need to support chunks of different types, consider readableStreamToBlob

    @param stream

    The stream to consume.

    @returns

    A promise that resolves with the concatenated chunks or the concatenated chunks as an ArrayBuffer.

  • stream: ReadableStream
    ): Promise<Blob>;

    Consume all data from a ReadableStream until it closes or errors.

    Concatenate the chunks into a single Blob.

    @param stream

    The stream to consume.

    @returns

    A promise that resolves with the concatenated chunks as a Blob.

  • stream: ReadableStream<ArrayBufferLike | ArrayBufferView<ArrayBufferLike>>
    ): Uint8Array<ArrayBufferLike> | Promise<Uint8Array<ArrayBufferLike>>;

    Consume all data from a ReadableStream until it closes or errors.

    Concatenate the chunks into a single ArrayBuffer.

    Each chunk must be a TypedArray or an ArrayBuffer. If you need to support chunks of different types, consider readableStreamToBlob

    @param stream

    The stream to consume.

    @returns

    A promise that resolves with the concatenated chunks or the concatenated chunks as a Uint8Array.

  • stream: ReadableStream<string | Uint8Array<ArrayBufferLike> | Uint8ClampedArray<ArrayBufferLike> | Uint16Array<ArrayBufferLike> | Uint32Array<ArrayBufferLike> | Int8Array<ArrayBufferLike> | Int16Array<ArrayBufferLike> | Int32Array<ArrayBufferLike> | BigUint64Array<ArrayBufferLike> | BigInt64Array<ArrayBufferLike> | Float32Array<ArrayBufferLike> | Float64Array<ArrayBufferLike> | DataView<ArrayBufferLike>>,
    multipartBoundaryExcludingDashes?: string | Uint8Array<ArrayBufferLike> | Uint8ClampedArray<ArrayBufferLike> | Uint16Array<ArrayBufferLike> | Uint32Array<ArrayBufferLike> | Int8Array<ArrayBufferLike> | Int16Array<ArrayBufferLike> | Int32Array<ArrayBufferLike> | BigUint64Array<ArrayBufferLike> | BigInt64Array<ArrayBufferLike> | Float32Array<ArrayBufferLike> | Float64Array<ArrayBufferLike> | DataView<ArrayBufferLike>
    ): Promise<FormData>;

    Consume all data from a ReadableStream until it closes or errors.

    Reads the multi-part or URL-encoded form data into a FormData object

    @param stream

    The stream to consume.

    @param multipartBoundaryExcludingDashes

    Optional boundary to use for multipart form data. If none is provided, assumes it is a URLEncoded form.

    @returns

    A promise that resolves with the data encoded into a FormData object.

    Multipart form data example

    // without dashes
const boundary = "WebKitFormBoundary" + Math.random().toString(16).slice(2);

const myStream = getStreamFromSomewhere() // ...
const formData = await Bun.readableStreamToFormData(stream, boundary);
formData.get("foo"); // "bar"

    URL-encoded form data example

    const stream = new Response("hello=123").body;
const formData = await Bun.readableStreamToFormData(stream);
formData.get("hello"); // "123"
  • stream: ReadableStream
    ): Promise<any>;

    Consume all data from a ReadableStream until it closes or errors.

    Concatenate the chunks into a single string and parse as JSON. Chunks must be a TypedArray or an ArrayBuffer. If you need to support chunks of different types, consider readableStreamToBlob.

    @param stream

    The stream to consume.

    @returns

    A promise that resolves with the concatenated chunks as a String.

  • stream: ReadableStream
    ): Promise<string>;

    Consume all data from a ReadableStream until it closes or errors.

    Concatenate the chunks into a single string. Chunks must be a TypedArray or an ArrayBuffer. If you need to support chunks of different types, consider readableStreamToBlob.

    @param stream

    The stream to consume.

    @returns

    A promise that resolves with the concatenated chunks as a String.

  • function resolve(
    moduleId: string,
    parent: string
    ): Promise<string>;

    Resolve a moduleId as though it were imported from parent

    On failure, throws a ResolveMessage

    For now, use the sync version. There is zero performance benefit to using this async version. It exists for future-proofing.

  • function resolveSync(
    moduleId: string,
    parent: string
    ): string;

    Synchronously resolve a moduleId as though it were imported from parent

    On failure, throws a ResolveMessage

  • function serve<T, R extends { [K in string | number | symbol]: RouteValue<K & string> }>(
    options: ServeFunctionOptions<T, R> & { static: R }
    ): Server;

    Bun.serve provides a high-performance HTTP server with built-in routing support. It enables both function-based and object-based route handlers with type-safe parameters and method-specific handling.

    @param options

    Server configuration options

    Bun.serve({
  port: 3000,
  fetch(req) {
    return new Response("Hello World");
  }
});
  • function sha(
    input: StringOrBuffer,
    hashInto?: TypedArray<ArrayBufferLike>
    ): TypedArray;
    @param input

    string, Uint8Array, or ArrayBuffer to hash. Uint8Array or ArrayBuffer will be faster

    @param hashInto

    optional Uint8Array to write the hash to. 32 bytes minimum.

    This hashing function balances speed with cryptographic strength. This does not encrypt or decrypt data.

    The implementation uses BoringSSL (used in Chromium & Go)

    The equivalent openssl command is:

    # You will need OpenSSL 3 or later
openssl sha512-256 /path/to/file
    function sha(
    input: StringOrBuffer,
    encoding: DigestEncoding
    ): string;
    @param input

    string, Uint8Array, or ArrayBuffer to hash. Uint8Array or ArrayBuffer will be faster

    @param encoding

    DigestEncoding to return the hash in

    This hashing function balances speed with cryptographic strength. This does not encrypt or decrypt data.

    The implementation uses BoringSSL (used in Chromium & Go)

    The equivalent openssl command is:

    # You will need OpenSSL 3 or later
openssl sha512-256 /path/to/file
  • function sleep(
    ms: number | Date
    ): Promise<void>;

    Resolve a Promise after milliseconds. This is like setTimeout except it returns a Promise.

    @param ms

    milliseconds to delay resolving the promise. This is a minimum number. It may take longer. If a Date is passed, it will sleep until the Date is reached.

    Sleep for 1 second

    import { sleep } from "bun";

await sleep(1000);

    Sleep for 10 milliseconds

    await Bun.sleep(10);

    Sleep until Date

    const target = new Date();
target.setSeconds(target.getSeconds() + 1);
await Bun.sleep(target);

    Internally, Bun.sleep is the equivalent of

    await new Promise((resolve) => setTimeout(resolve, ms));

    As always, you can use Bun.sleep or the imported sleep function interchangeably.

  • function sleepSync(
    ms: number
    ): void;

    Sleep the thread for a given number of milliseconds

    This is a blocking function.

    Internally, it calls nanosleep(2)

  • function spawn<In extends Writable = 'ignore', Out extends Readable = 'pipe', Err extends Readable = 'inherit'>(
    options: OptionsObject<In, Out, Err> & { cmd: string[] }
    ): Subprocess<In, Out, Err>;

    Spawn a new process

    function spawn<In extends Writable = 'ignore', Out extends Readable = 'pipe', Err extends Readable = 'inherit'>(
    cmds: string[],
    options?: OptionsObject<In, Out, Err>
    ): Subprocess<In, Out, Err>;

    Spawn a new process

    const {stdout} = Bun.spawn(["echo", "hello"]);
const text = await readableStreamToText(stdout);
console.log(text); // "hello\n"

    Internally, this uses posix_spawn(2)

    @param cmds

    The command to run

    The first argument will be resolved to an absolute executable path. It must be a file, not a directory.

    If you explicitly set PATH in env, that PATH will be used to resolve the executable instead of the default PATH.

    To check if the command exists before running it, use Bun.which(bin).

  • function spawnSync<Out extends Readable = 'pipe', Err extends Readable = 'inherit'>(
    options: OptionsObject<'ignore', Out, Err> & { cmd: string[]; onExit: undefined }
    ): SyncSubprocess<Out, Err>;

    Spawn a new process

    function spawnSync<Out extends Readable = 'pipe', Err extends Readable = 'inherit'>(
    cmds: string[],
    options?: OptionsObject<'ignore', Out, Err>
    ): SyncSubprocess<Out, Err>;

    Synchronously spawn a new process

    const {stdout} = Bun.spawnSync(["echo", "hello"]);
console.log(stdout.toString()); // "hello\n"

    Internally, this uses posix_spawn(2)

    @param cmds

    The command to run

    The first argument will be resolved to an absolute executable path. It must be a file, not a directory.

    If you explicitly set PATH in env, that PATH will be used to resolve the executable instead of the default PATH.

    To check if the command exists before running it, use Bun.which(bin).

  • function stringWidth(
    input: string,
    options?: StringWidthOptions
    ): number;

    Get the column count of a string as it would be displayed in a terminal. Supports ANSI escape codes, emoji, and wide characters.

    This is useful for:

    • Aligning text in a terminal
    • Quickly checking if a string contains ANSI escape codes
    • Measuring the width of a string in a terminal

    This API is designed to match the popular "string-width" package, so that existing code can be easily ported to Bun and vice versa.

    @param input

    The string to measure

    @returns

    The width of the string in columns

    import { stringWidth } from "bun";

console.log(stringWidth("abc")); // 3
console.log(stringWidth("👩‍👩‍👧‍👦")); // 1
console.log(stringWidth("\u001b[31mhello\u001b[39m")); // 5
console.log(stringWidth("\u001b[31mhello\u001b[39m", { countAnsiEscapeCodes: false })); // 5
console.log(stringWidth("\u001b[31mhello\u001b[39m", { countAnsiEscapeCodes: true })); // 13
  • function udpSocket<DataBinaryType extends keyof BinaryTypeList = 'buffer'>(
    options: SocketOptions<DataBinaryType>
    ): Promise<Socket<DataBinaryType>>;

    Create a UDP socket

    @param options

    The options to use when creating the server

    function udpSocket<DataBinaryType extends keyof BinaryTypeList = 'buffer'>(
    options: ConnectSocketOptions<DataBinaryType>
    ): Promise<ConnectedSocket<DataBinaryType>>;

    Create a UDP socket

    @param options

    The options to use when creating the server

  • function which(
    command: string,
    options?: WhichOptions
    ): null | string;

    Find the path to an executable, similar to typing which in your terminal. Reads the PATH environment variable unless overridden with options.PATH.

    @param command

    The name of the executable or script to find

    @param options

    Options for the search

  • function write(
    destination: BunFile | PathLike | S3File,
    input: string | ArrayBufferLike | TypedArray<ArrayBufferLike> | Blob | BlobPart[],
    options?: { createPath: boolean; mode: number }
    ): Promise<number>;

    Use the fastest syscalls available to copy from input into destination.

    If destination exists, it must be a regular file or symlink to a file. If destination's directory does not exist, it will be created by default.

    @param destination

    The file or file path to write to

    @param input

    The data to copy into destination.

    @param options

    Options for the write

    @returns

    A promise that resolves with the number of bytes written.

    function write(
    destination: BunFile,
    input: Response,
    options?: { createPath: boolean }
    ): Promise<number>;

    Persist a Response body to disk.

    @param destination

    The file to write to. If the file doesn't exist, it will be created and if the file does exist, it will be overwritten. If input's size is less than destination's size, destination will be truncated.

    @param input

    Response object

    @param options

    Options for the write

    @returns

    A promise that resolves with the number of bytes written.

    function write(
    destinationPath: PathLike,
    input: Response,
    options?: { createPath: boolean }
    ): Promise<number>;

    Persist a Response body to disk.

    @param destinationPath

    The file path to write to. If the file doesn't exist, it will be created and if the file does exist, it will be overwritten. If input's size is less than destination's size, destination will be truncated.

    @param input

    Response object

    @returns

    A promise that resolves with the number of bytes written.

    function write(
    destination: BunFile,
    input: BunFile,
    options?: { createPath: boolean }
    ): Promise<number>;

    Use the fastest syscalls available to copy from input into destination.

    If destination exists, it must be a regular file or symlink to a file.

    On Linux, this uses copy_file_range.

    On macOS, when the destination doesn't already exist, this uses clonefile() and falls back to fcopyfile()

    @param destination

    The file to write to. If the file doesn't exist, it will be created and if the file does exist, it will be overwritten. If input's size is less than destination's size, destination will be truncated.

    @param input

    The file to copy from.

    @returns

    A promise that resolves with the number of bytes written.

    function write(
    destinationPath: PathLike,
    input: BunFile,
    options?: { createPath: boolean }
    ): Promise<number>;

    Use the fastest syscalls available to copy from input into destination.

    If destination exists, it must be a regular file or symlink to a file.

    On Linux, this uses copy_file_range.

    On macOS, when the destination doesn't already exist, this uses clonefile() and falls back to fcopyfile()

    @param destinationPath

    The file path to write to. If the file doesn't exist, it will be created and if the file does exist, it will be overwritten. If input's size is less than destination's size, destination will be truncated.

    @param input

    The file to copy from.

    @returns

    A promise that resolves with the number of bytes written.

  • class EventSource

    EventTarget is a DOM interface implemented by objects that can receive events and may have listeners for them.

    MDN Reference

    • readonly CLOSED: 2
    • readonly CONNECTING: 0
    • onerror: null | (this: EventSource, ev: Event) => any
    • onmessage: null | (this: EventSource, ev: new (type: string, eventInitDict?: MessageEventInit<T>) => MessageEvent<T>) => any
    • onopen: null | (this: EventSource, ev: Event) => any
    • readonly OPEN: 1
    • readonly readyState: number

      Returns the state of this EventSource object's connection. It can have the values described below.

    • readonly url: string

      Returns the URL providing the event stream.

    • readonly withCredentials: boolean

      Returns true if the credentials mode for connection requests to the URL providing the event stream is set to "include", and false otherwise.

      Not supported in Bun

    • readonly static CLOSED: 2
    • readonly static CONNECTING: 0
    • readonly static OPEN: 1
    • type: K,
      listener: (this: EventSource, ev: EventSourceEventMap[K]) => any,
      options?: boolean | AddEventListenerOptions
      ): void;

      Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.

      The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options's capture.

      When set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET.

      When set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners.

      When set to true, options's once indicates that the callback will only be invoked once after which the event listener will be removed.

      If an AbortSignal is passed for options's signal, then the event listener will be removed when signal is aborted.

      The event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture.

      MDN Reference

      type: string,
      listener: (this: EventSource, event: new (type: string, eventInitDict?: MessageEventInit<T>) => MessageEvent<T>) => any,
      options?: boolean | AddEventListenerOptions
      ): void;

      Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.

      The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options's capture.

      When set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET.

      When set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners.

      When set to true, options's once indicates that the callback will only be invoked once after which the event listener will be removed.

      If an AbortSignal is passed for options's signal, then the event listener will be removed when signal is aborted.

      The event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture.

      MDN Reference

      type: string,
      listener: EventListenerOrEventListenerObject,
      options?: boolean | AddEventListenerOptions
      ): void;

      Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.

      The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options's capture.

      When set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET.

      When set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners.

      When set to true, options's once indicates that the callback will only be invoked once after which the event listener will be removed.

      If an AbortSignal is passed for options's signal, then the event listener will be removed when signal is aborted.

      The event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture.

      MDN Reference

    • close(): void;

      Aborts any instances of the fetch algorithm started for this EventSource object, and sets the readyState attribute to CLOSED.

    • event: Event
      ): boolean;

      Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise.

    • ref(): void;

      Keep the event loop alive while connection is open or reconnecting

      Not available in browsers

    • type: K,
      listener: (this: EventSource, ev: EventSourceEventMap[K]) => any,
      options?: boolean | EventListenerOptions
      ): void;

      Removes the event listener in target's event listener list with the same type, callback, and options.

      MDN Reference

      type: string,
      listener: (this: EventSource, event: new (type: string, eventInitDict?: MessageEventInit<T>) => MessageEvent<T>) => any,
      options?: boolean | EventListenerOptions
      ): void;

      Removes the event listener in target's event listener list with the same type, callback, and options.

      MDN Reference

      type: string,
      listener: EventListenerOrEventListenerObject,
      options?: boolean | EventListenerOptions
      ): void;

      Removes the event listener in target's event listener list with the same type, callback, and options.

      MDN Reference

    • unref(): void;

      Do not keep the event loop alive while connection is open or reconnecting

      Not available in browsers

  • class WebSocket

    A WebSocket client implementation

    const ws = new WebSocket("ws://localhost:8080", {
 headers: {
   "x-custom-header": "hello",
 },
});

ws.addEventListener("open", () => {
  console.log("Connected to server");
});

ws.addEventListener("message", (event) => {
  console.log("Received message:", event.data);
});

ws.send("Hello, server!");
ws.terminate();
    • binaryType: 'arraybuffer' | 'nodebuffer'

      The type of binary data being received.

    • readonly bufferedAmount: number

      The number of bytes of data that have been queued using send() but not yet transmitted to the network

    • readonly extensions: string

      The extensions selected by the server

    • onclose: null | (this: WebSocket, ev: CloseEvent) => any

      Event handler for close event

    • onerror: null | (this: WebSocket, ev: Event) => any

      Event handler for error event

    • onmessage: null | (this: WebSocket, ev: new (type: string, eventInitDict?: MessageEventInit<T>) => MessageEvent<T>) => any

      Event handler for message event

    • onopen: null | (this: WebSocket, ev: Event) => any

      Event handler for open event

    • readonly protocol: string

      The protocol selected by the server

    • readonly readyState: 0 | 1 | 2 | 3

      The current state of the connection

    • readonly url: string

      The URL of the WebSocket connection

    • readonly static CLOSED: 3
    • readonly static CLOSING: 2
    • readonly static CONNECTING: 0
    • readonly static OPEN: 1
    • type: K,
      listener: (this: WebSocket, ev: WebSocketEventMap[K]) => any,
      options?: boolean | AddEventListenerOptions
      ): void;

      Registers an event handler of a specific event type on the WebSocket.

      @param type

      A case-sensitive string representing the event type to listen for

      @param listener

      The function to be called when the event occurs

      @param options

      An options object that specifies characteristics about the event listener

      type: string,
      listener: EventListenerOrEventListenerObject,
      options?: boolean | AddEventListenerOptions
      ): void;

      Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.

      The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options's capture.

      When set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET.

      When set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners.

      When set to true, options's once indicates that the callback will only be invoked once after which the event listener will be removed.

      If an AbortSignal is passed for options's signal, then the event listener will be removed when signal is aborted.

      The event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture.

      MDN Reference

    • code?: number,
      reason?: string
      ): void;

      Closes the WebSocket connection

      @param code

      A numeric value indicating the status code

      @param reason

      A human-readable string explaining why the connection is closing

    • event: Event
      ): boolean;

      Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise.

    • data?: string | ArrayBufferLike | ArrayBufferView<ArrayBufferLike>
      ): void;

      Sends a ping frame to the server

      @param data

      Optional data to include in the ping frame

    • data?: string | ArrayBufferLike | ArrayBufferView<ArrayBufferLike>
      ): void;

      Sends a pong frame to the server

      @param data

      Optional data to include in the pong frame

    • type: K,
      listener: (this: WebSocket, ev: WebSocketEventMap[K]) => any,
      options?: boolean | EventListenerOptions
      ): void;

      Removes an event listener previously registered with addEventListener()

      @param type

      A case-sensitive string representing the event type to remove

      @param listener

      The function to remove from the event target

      @param options

      An options object that specifies characteristics about the event listener

      type: string,
      listener: EventListenerOrEventListenerObject,
      options?: boolean | EventListenerOptions
      ): void;

      Removes the event listener in target's event listener list with the same type, callback, and options.

      MDN Reference

    • data: string | ArrayBufferLike | ArrayBufferView<ArrayBufferLike>
      ): void;

      Transmits data to the server

      @param data

      The data to send to the server

    • terminate(): void;

      Immediately terminates the connection

  • class Worker

    EventTarget is a DOM interface implemented by objects that can receive events and may have listeners for them.

    MDN Reference

    • onerror: null | (this: AbstractWorker, ev: ErrorEvent) => any
    • onmessage: null | (this: Worker, ev: new (type: string, eventInitDict?: MessageEventInit<T>) => MessageEvent<T>) => any
    • onmessageerror: null | (this: Worker, ev: new (type: string, eventInitDict?: MessageEventInit<T>) => MessageEvent<T>) => any
    • threadId: number

      An integer identifier for the referenced thread. Inside the worker thread, it is available as require('node:worker_threads').threadId. This value is unique for each Worker instance inside a single process.

    • type: K,
      listener: (this: Worker, ev: WorkerEventMap[K]) => any,
      options?: boolean | AddEventListenerOptions
      ): void;

      Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.

      The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options's capture.

      When set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET.

      When set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners.

      When set to true, options's once indicates that the callback will only be invoked once after which the event listener will be removed.

      If an AbortSignal is passed for options's signal, then the event listener will be removed when signal is aborted.

      The event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture.

      MDN Reference

      type: string,
      listener: EventListenerOrEventListenerObject,
      options?: boolean | AddEventListenerOptions
      ): void;

      Appends an event listener for events whose type attribute value is type. The callback argument sets the callback that will be invoked when the event is dispatched.

      The options argument sets listener-specific options. For compatibility this can be a boolean, in which case the method behaves exactly as if the value was specified as options's capture.

      When set to true, options's capture prevents callback from being invoked when the event's eventPhase attribute value is BUBBLING_PHASE. When false (or not present), callback will not be invoked when event's eventPhase attribute value is CAPTURING_PHASE. Either way, callback will be invoked if event's eventPhase attribute value is AT_TARGET.

      When set to true, options's passive indicates that the callback will not cancel the event by invoking preventDefault(). This is used to enable performance optimizations described in § 2.8 Observing event listeners.

      When set to true, options's once indicates that the callback will only be invoked once after which the event listener will be removed.

      If an AbortSignal is passed for options's signal, then the event listener will be removed when signal is aborted.

      The event listener is appended to target's event listener list and is not appended if it has the same type, callback, and capture.

      MDN Reference

    • event: Event
      ): boolean;

      Dispatches a synthetic event event to target and returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise.

    • message: any,
      transfer: Transferable[]
      ): void;

      Clones message and transmits it to worker's global environment. transfer can be passed as a list of objects that are to be transferred rather than cloned.

      MDN Reference

      message: any,
      options?: StructuredSerializeOptions
      ): void;
    • ref(): void;

      Opposite of unref(), calling ref() on a previously unref()ed worker does not let the program exit if it's the only active handle left (the default behavior). If the worker is ref()ed, calling ref() again has no effect.

    • type: K,
      listener: (this: Worker, ev: WorkerEventMap[K]) => any,
      options?: boolean | EventListenerOptions
      ): void;

      Removes the event listener in target's event listener list with the same type, callback, and options.

      MDN Reference

      type: string,
      listener: EventListenerOrEventListenerObject,
      options?: boolean | EventListenerOptions
      ): void;

      Removes the event listener in target's event listener list with the same type, callback, and options.

      MDN Reference

    • terminate(): void;
    • unref(): void;

      Calling unref() on a worker allows the thread to exit if this is the only active handle in the event system. If the worker is already unref()ed callingunref() again has no effect.

Type definitions

  • namespace __internal

  • namespace Password

    Hash and verify passwords using argon2 or bcrypt

    These are fast APIs that can run in a worker thread if used asynchronously.

  • namespace RouterTypes

  • namespace SpawnOptions

    • interface OptionsObject<In extends Writable, Out extends Readable, Err extends Readable>

      • argv0?: string

        Path to the executable to run in the subprocess. This defaults to cmds[0].

        One use-case for this is for applications which wrap other applications or to simulate a symlink.

      • cwd?: string

        The current working directory of the process

        Defaults to process.cwd()

      • env?: Record<string, undefined | string>

        The environment variables of the process

        Defaults to process.env as it was when the current Bun process launched.

        Changes to process.env at runtime won't automatically be reflected in the default value. For that, you can pass process.env explicitly.

      • killSignal?: string | number

        The signal to use when killing the process after a timeout, when the AbortSignal is aborted, or when the process goes over the maxBuffer limit.

        // Kill the process with SIGKILL after 5 seconds
const subprocess = Bun.spawn({
  cmd: ["sleep", "10"],
  timeout: 5000,
  killSignal: "SIGKILL",
});
      • maxBuffer?: number

        The maximum number of bytes the process may output. If the process goes over this limit, it is killed with signal killSignal (defaults to SIGTERM).

      • serialization?: 'json' | 'advanced'

        The serialization format to use for IPC messages. Defaults to "advanced".

        To communicate with Node.js processes, use "json".

        When ipc is not specified, this is ignored.

      • signal?: AbortSignal

        An AbortSignal that can be used to abort the subprocess.

        This is useful for aborting a subprocess when some other part of the program is aborted, such as a fetch response.

        If the signal is aborted, the process will be killed with the signal specified by killSignal (defaults to SIGTERM).

        const controller = new AbortController();
const { signal } = controller;
const start = performance.now();
const subprocess = Bun.spawn({
 cmd: ["sleep", "100"],
 signal,
});
await Bun.sleep(1);
controller.abort();
await subprocess.exited;
const end = performance.now();
console.log(end - start); // 1ms instead of 101ms
      • stderr?: Err

        The file descriptor for the standard error. It may be:

        • "pipe", undefined: The process will have a ReadableStream for standard output/error
        • "ignore", null: The process will have no standard output/error
        • "inherit": The process will inherit the standard output/error of the current process
        • ArrayBufferView: The process write to the preallocated buffer. Not implemented.
        • number: The process will write to the file descriptor
      • stdin?: In

        The file descriptor for the standard input. It may be:

        • "ignore", null, undefined: The process will have no standard input
        • "pipe": The process will have a new FileSink for standard input
        • "inherit": The process will inherit the standard input of the current process
        • ArrayBufferView, Blob: The process will read from the buffer
        • number: The process will read from the file descriptor
      • stdio?: [In, Out, Err, ...Readable[]]

        The standard file descriptors of the process, in the form [stdin, stdout, stderr]. This overrides the stdin, stdout, and stderr properties.

        For stdin you may pass:

        • "ignore", null, undefined: The process will have no standard input (default)
        • "pipe": The process will have a new FileSink for standard input
        • "inherit": The process will inherit the standard input of the current process
        • ArrayBufferView, Blob, Bun.file(), Response, Request: The process will read from buffer/stream.
        • number: The process will read from the file descriptor

        For stdout and stdin you may pass:

        • "pipe", undefined: The process will have a ReadableStream for standard output/error
        • "ignore", null: The process will have no standard output/error
        • "inherit": The process will inherit the standard output/error of the current process
        • ArrayBufferView: The process write to the preallocated buffer. Not implemented.
        • number: The process will write to the file descriptor
      • stdout?: Out

        The file descriptor for the standard output. It may be:

        • "pipe", undefined: The process will have a ReadableStream for standard output/error
        • "ignore", null: The process will have no standard output/error
        • "inherit": The process will inherit the standard output/error of the current process
        • ArrayBufferView: The process write to the preallocated buffer. Not implemented.
        • number: The process will write to the file descriptor
      • timeout?: number

        The maximum amount of time the process is allowed to run in milliseconds.

        If the timeout is reached, the process will be killed with the signal specified by killSignal (defaults to SIGTERM).

        // Kill the process after 5 seconds
const subprocess = Bun.spawn({
  cmd: ["sleep", "10"],
  timeout: 5000,
});
await subprocess.exited; // Will resolve after 5 seconds
      • windowsHide?: boolean

        If true, the subprocess will have a hidden window.

      • windowsVerbatimArguments?: boolean

        If true, no quoting or escaping of arguments is done on Windows.

      • message: any,
        subprocess: Subprocess<In, Out, Err>
        ): void;

        When specified, Bun will open an IPC channel to the subprocess. The passed callback is called for incoming messages, and subprocess.send can send messages to the subprocess. Messages are serialized using the JSC serialize API, which allows for the same types that postMessage/structuredClone supports.

        The subprocess can send and recieve messages by using process.send and process.on("message"), respectively. This is the same API as what Node.js exposes when child_process.fork() is used.

        Currently, this is only compatible with processes that are other bun instances.

        @param subprocess

        The Subprocess that sent the message

      • subprocess: Subprocess<In, Out, Err>,
        exitCode: null | number,
        signalCode: null | number,
        error?: ErrorLike
        ): void | Promise<void>;

        Callback that runs when the Subprocess exits

        This is called even if the process exits with a non-zero exit code.

        Warning: this may run before the Bun.spawn function returns.

        A simple alternative is await subprocess.exited.

        @param error

        If an error occurred in the call to waitpid2, this will be the error.

        const subprocess = spawn({
 cmd: ["echo", "hello"],
 onExit: (subprocess, code) => {
   console.log(`Process exited with code ${code}`);
  },
});
    • type Readable = 'pipe' | 'inherit' | 'ignore' | null | undefined | BunFile | ArrayBufferView | number

      Option for stdout/stderr

    • type ReadableIO = ReadableStream<Uint8Array> | number | undefined
    • type ReadableToIO<X extends Readable> = X extends 'pipe' | undefined ? ReadableStream<Uint8Array> : X extends BunFile | ArrayBufferView | number ? number : undefined
    • type ReadableToSyncIO<X extends Readable> = X extends 'pipe' | undefined ? Buffer : undefined
    • type Writable = 'pipe' | 'inherit' | 'ignore' | null | undefined | BunFile | ArrayBufferView | number | ReadableStream | Blob | Response | Request

      Option for stdin

    • type WritableIO = FileSink | number | undefined
    • type WritableToIO<X extends Writable> = X extends 'pipe' ? FileSink : X extends BunFile | ArrayBufferView | Blob | Request | Response | number ? number : undefined

  • namespace udp

  • namespace WebAssembly

  • interface AbstractWorker

  • interface AddEventListenerOptions

    • capture?: boolean
    • once?: boolean

      When true, the listener is automatically removed when it is first invoked. Default: false.

    • passive?: boolean

      When true, serves as a hint that the listener will not call the Event object's preventDefault() method. Default: false.

  • interface BuildArtifact

    A build artifact represents a file that was generated by the bundler

    • hash: null | string
    • kind: 'entry-point' | 'chunk' | 'asset' | 'sourcemap' | 'bytecode'
    • path: string
    • readonly size: number
    • readonly type: string

    • Returns a promise that resolves to the contents of the blob as an ArrayBuffer

    • bytes(): Promise<Uint8Array<ArrayBufferLike>>;

      Returns a promise that resolves to the contents of the blob as a Uint8Array (array of bytes) its the same as new Uint8Array(await blob.arrayBuffer())

    • formData(): Promise<FormData>;

      Read the data from the blob as a FormData object.

      This first decodes the data from UTF-8, then parses it as a multipart/form-data body or a application/x-www-form-urlencoded body.

      The type property of the blob is used to determine the format of the body.

      This is a non-standard addition to the Blob API, to make it conform more closely to the BodyMixin API.

    • json(): Promise<any>;

      Read the data from the blob as a JSON object.

      This first decodes the data from UTF-8, then parses it as JSON.

    • start?: number,
      end?: number,
      contentType?: string
      ): Blob;
    • stream(): ReadableStream<Uint8Array<ArrayBufferLike>>;

      Returns a readable stream of the blob's contents

    • text(): Promise<string>;

      Returns a promise that resolves to the contents of the blob as a string

  • interface BuildConfig

    • banner?: string

      Add a banner to the bundled code such as "use client";

    • bytecode?: boolean

      Generate bytecode for the output. This can dramatically improve cold start times, but will make the final output larger and slightly increase memory usage.

      Bytecode is currently only supported for CommonJS (format: "cjs").

      Must be target: "bun"

    • conditions?: string | string[]

      package.json exports conditions used when resolving imports

      Equivalent to --conditions in bun build or bun run.

      https://nodejs.org/api/packages.html#exports

    • define?: Record<string, string>
    • drop?: string[]

      Drop function calls to matching property accesses.

    • emitDCEAnnotations?: boolean

      Force emitting @PURE annotations even if minify.whitespace is true.

    • entrypoints: string[]
    • env?: 'inline' | 'disable' | `${string}*`

      Controls how environment variables are handled during bundling.

      Can be one of:

      • "inline": Injects environment variables into the bundled output by converting process.env.FOO references to string literals containing the actual environment variable values
      • "disable": Disables environment variable injection entirely
      • A string ending in *: Inlines environment variables that match the given prefix. For example, "MY_PUBLIC_*" will only include env vars starting with "MY_PUBLIC_"
      Bun.build({
  env: "MY_PUBLIC_*",
  entrypoints: ["src/index.ts"],
})
    • external?: string[]
    • footer?: string

      Add a footer to the bundled code such as a comment block like

      // made with bun!

    • format?: 'esm' | 'cjs' | 'iife'

      Output module format. Top-level await is only supported for "esm".

      Can be:

      • "esm"
      • "cjs" (experimental)
      • "iife" (experimental)
    • ignoreDCEAnnotations?: boolean

      Ignore dead code elimination/tree-shaking annotations such as @PURE and package.json "sideEffects" fields. This should only be used as a temporary workaround for incorrect annotations in libraries.

    • loader?: {
      __index[
      key: string
      ]: Loader;
       }
    • minify?: boolean | { identifiers: boolean; syntax: boolean; whitespace: boolean }

      Whether to enable minification.

      Use true/false to enable/disable all minification options. Alternatively, you can pass an object for granular control over certain minifications.

    • naming?: string | { asset: string; chunk: string; entry: string }
    • outdir?: string
    • packages?: 'external' | 'bundle'
    • publicPath?: string
    • root?: string
    • sourcemap?: boolean | 'linked' | 'external' | 'none' | 'inline'

      Specifies if and how to generate source maps.

      • "none" - No source maps are generated
      • "linked" - A separate *.ext.map file is generated alongside each *.ext file. A //# sourceMappingURL comment is added to the output file to link the two. Requires outdir to be set.
      • "inline" - an inline source map is appended to the output file.
      • "external" - Generate a separate source map file for each input file. No //# sourceMappingURL comment is added to the output file.

      true and false are aliases for "inline" and "none", respectively.

    • splitting?: boolean
    • throw?: boolean

      When set to true, the returned promise rejects with an AggregateError when a build failure happens. When set to false, the success property of the returned object will be false when a build failure happens. This defaults to true.

  • interface BuildOutput

    The output of a build

  • interface BunInspectOptions

    Options for Bun.inspect

    • colors?: boolean

      Whether to colorize the output

    • compact?: boolean

      Whether to compact the output

    • depth?: number

      The depth of the inspection

    • sorted?: boolean

      Whether to sort the properties of the object

  • interface BunMessageEvent<T = any>

    A message received by a target object.

    • readonly AT_TARGET: 2
    • readonly bubbles: boolean

      Returns true or false depending on how event was initialized. True if event goes through its target's ancestors in reverse tree order, and false otherwise.

      MDN Reference

    • readonly BUBBLING_PHASE: 3
    • readonly cancelable: boolean

      Returns true or false depending on how event was initialized. Its return value does not always carry meaning, but true can indicate that part of the operation during which event was dispatched, can be canceled by invoking the preventDefault() method.

      MDN Reference

    • readonly CAPTURING_PHASE: 1
    • readonly composed: boolean

      Returns true or false depending on how event was initialized. True if event invokes listeners past a ShadowRoot node that is the root of its target, and false otherwise.

      MDN Reference

    • readonly currentTarget: null | EventTarget

      Returns the object whose event listener's callback is currently being invoked.

      MDN Reference

    • readonly data: T

      Returns the data of the message.

    • readonly defaultPrevented: boolean

      Returns true if preventDefault() was invoked successfully to indicate cancelation, and false otherwise.

      MDN Reference

    • readonly eventPhase: number

      Returns the event's phase, which is one of NONE, CAPTURING_PHASE, AT_TARGET, and BUBBLING_PHASE.

      MDN Reference

    • readonly isTrusted: boolean

      Returns true if event was dispatched by the user agent, and false otherwise.

      MDN Reference

    • readonly lastEventId: string

      Returns the last event ID string, for server-sent events.

    • readonly NONE: 0
    • readonly origin: string

      Returns the origin of the message, for server-sent events and cross-document messaging.

    • readonly ports: readonly MessagePort[]

      Returns the MessagePort array sent with the message, for cross-document messaging and channel messaging.

    • readonly source: undefined | null
    • readonly target: null | EventTarget

      Returns the object to which event is dispatched (its target).

      MDN Reference

    • readonly timeStamp: number

      Returns the event's timestamp as the number of milliseconds measured relative to the time origin.

      MDN Reference

    • readonly type: string

      Returns the type of event, e.g. "click", "hashchange", or "submit".

      MDN Reference

    • Returns the invocation target objects of event's path (objects on which listeners will be invoked), except for any nodes in shadow trees of which the shadow root's mode is "closed" that are not reachable from event's currentTarget.

      MDN Reference

      Returns an array containing the current EventTarget as the only entry or empty if the event is not being dispatched. This is not used in Node.js and is provided purely for completeness.

    • Sets the defaultPrevented property to true if cancelable is true.

    • Stops the invocation of event listeners after the current one completes.

    • This is not used in Node.js and is provided purely for completeness.

  • interface BunPlugin

    A Bun plugin. Used for extending Bun's behavior at runtime, or with Bun.build

    • name: string

      Human-readable name of the plugin

      In a future version of Bun, this will be used in error messages.

    • target?: Target

      The target JavaScript environment the plugin should be applied to.

      • bun: The default environment when using bun run or bun to load a script
      • browser: The plugin will be applied to browser builds
      • node: The plugin will be applied to Node.js builds

      If unspecified, it is assumed that the plugin is compatible with all targets.

      This field is not read by Bun.plugin, only Bun.build and bun build

    • build: PluginBuilder
      ): void | Promise<void>;

      A function that will be called when the plugin is loaded.

      This function may be called in the same tick that it is registered, or it may be called later. It could potentially be called multiple times for different targets.

      @param build

      A builder object that can be used to register plugin hooks

  • interface BunRegisterPlugin

    Extend Bun's module resolution and loading behavior

    Plugins are applied in the order they are defined.

    Today, there are two kinds of hooks:

    • onLoad lets you return source code or an object that will become the module's exports
    • onResolve lets you redirect a module specifier to another module specifier. It does not chain.

    Plugin hooks must define a filter RegExp and will only be matched if the import specifier contains a "." or a ":".

    ES Module resolution semantics mean that plugins may be initialized after a module is resolved. You might need to load plugins at the very beginning of the application and then use a dynamic import to load the rest of the application. A future version of Bun may also support specifying plugins via bunfig.toml.

    A YAML loader plugin

    Bun.plugin({
 setup(builder) {
  builder.onLoad({ filter: /\.yaml$/ }, ({path}) => ({
    loader: "object",
    exports: require("js-yaml").load(fs.readFileSync(path, "utf8"))
  }));
});

// You can use require()
const {foo} = require("./file.yaml");

// Or import
await import("./file.yaml");
    • clearAll(): void;

      Deactivate all plugins

      This prevents registered plugins from being applied to future builds.

  • interface BunRequest<T extends string = string>

    This Fetch API interface represents a resource request.

    MDN Reference

    • readonly body: null | ReadableStream<Uint8Array<ArrayBufferLike>>
    • readonly bodyUsed: boolean
    • readonly cache: RequestCache

      Returns the cache mode associated with request, which is a string indicating how the request will interact with the browser's cache when fetching.

      MDN Reference

    • readonly cookies: CookieMap
    • readonly credentials: RequestCredentials

      Returns the credentials mode associated with request, which is a string indicating whether credentials will be sent with the request always, never, or only when sent to a same-origin URL.

      MDN Reference

    • readonly destination: RequestDestination

      Returns the kind of resource requested by request, e.g., "document" or "script".

      MDN Reference

    • readonly headers: Headers

      Returns a Headers object consisting of the headers associated with request. Note that headers added in the network layer by the user agent will not be accounted for in this object, e.g., the "Host" header.

      MDN Reference

    • readonly integrity: string

      Returns request's subresource integrity metadata, which is a cryptographic hash of the resource being fetched. Its value consists of multiple hashes separated by whitespace. [SRI]

      MDN Reference

    • readonly keepalive: boolean

      Returns a boolean indicating whether or not request can outlive the global in which it was created.

      MDN Reference

    • readonly method: string

      Returns request's HTTP method, which is "GET" by default.

      MDN Reference

    • readonly mode: RequestMode

      Returns the mode associated with request, which is a string indicating whether the request will use CORS, or will be restricted to same-origin URLs.

      MDN Reference

    • readonly redirect: RequestRedirect

      Returns the redirect mode associated with request, which is a string indicating how redirects for the request will be handled during fetching. A request will follow redirects by default.

      MDN Reference

    • readonly referrer: string

      Returns the referrer of request. Its value can be a same-origin URL if explicitly set in init, the empty string to indicate no referrer, and "about:client" when defaulting to the global's default. This is used during fetching to determine the value of the Referer header of the request being made.

      MDN Reference

    • readonly referrerPolicy: ReferrerPolicy

      Returns the referrer policy associated with request. This is used during fetching to compute the value of the request's referrer.

      MDN Reference

    • readonly signal: AbortSignal

      Returns the signal associated with request, which is an AbortSignal object indicating whether or not request has been aborted, and its abort event handler.

      MDN Reference

    • readonly url: string
    • blob(): Promise<Blob>;
    • bytes(): Promise<Uint8Array<ArrayBufferLike>>;
    • json(): Promise<any>;
    • text(): Promise<string>;

  • interface CloseEventInit

  • interface CookieInit

  • interface CookieStoreDeleteOptions

  • interface CookieStoreGetOptions

  • interface CSRFGenerateOptions

    • algorithm?: CSRFAlgorithm

      The algorithm to use for the token.

    • encoding?: 'base64' | 'base64url' | 'hex'

      The encoding of the token.

    • expiresIn?: number

      The number of milliseconds until the token expires. 0 means the token never expires.

  • interface CSRFVerifyOptions

    • algorithm?: CSRFAlgorithm

      The algorithm to use for the token.

    • encoding?: 'base64' | 'base64url' | 'hex'

      The encoding of the token.

    • maxAge?: number

      The number of milliseconds until the token expires. 0 means the token never expires.

    • secret?: string

      The secret to use for the token. If not provided, a random default secret will be generated in memory and used.

  • interface CustomEventInit<T = any>

  • interface DirectUnderlyingSource<R = any>

  • interface DNSLookup

    • address: string

      The IP address of the host as a string in IPv4 or IPv6 format.

      "127.0.0.1"
    • family: 4 | 6
    • ttl: number

      Time to live in seconds

      Only supported when using the c-ares DNS resolver via "backend" option to dns.lookup. Otherwise, it's 0.

  • interface EditorOptions

  • interface Env

    • NODE_ENV?: string
    • TZ?: string

      Can be used to change the default timezone at runtime

  • interface ErrorEventInit

  • interface ErrorLike

  • interface EventInit

  • interface EventListener

  • interface EventListenerObject

  • interface EventListenerOptions

  • interface EventMap

  • interface EventSourceEventMap

  • interface FdSocketOptions<Data = undefined>

    • data?: Data

      The per-instance data context

    • fd: number

      The file descriptor to connect to

    • socket: SocketHandler<Data>

      Handlers for socket events

    • tls?: TLSOptions

      TLS Configuration with which to create the socket

  • interface FetchEvent

    • readonly AT_TARGET: 2
    • readonly bubbles: boolean

      Returns true or false depending on how event was initialized. True if event goes through its target's ancestors in reverse tree order, and false otherwise.

      MDN Reference

    • readonly BUBBLING_PHASE: 3
    • readonly cancelable: boolean

      Returns true or false depending on how event was initialized. Its return value does not always carry meaning, but true can indicate that part of the operation during which event was dispatched, can be canceled by invoking the preventDefault() method.

      MDN Reference

    • readonly CAPTURING_PHASE: 1
    • readonly composed: boolean

      Returns true or false depending on how event was initialized. True if event invokes listeners past a ShadowRoot node that is the root of its target, and false otherwise.

      MDN Reference

    • readonly currentTarget: null | EventTarget

      Returns the object whose event listener's callback is currently being invoked.

      MDN Reference

    • readonly defaultPrevented: boolean

      Returns true if preventDefault() was invoked successfully to indicate cancelation, and false otherwise.

      MDN Reference

    • readonly eventPhase: number

      Returns the event's phase, which is one of NONE, CAPTURING_PHASE, AT_TARGET, and BUBBLING_PHASE.

      MDN Reference

    • readonly isTrusted: boolean

      Returns true if event was dispatched by the user agent, and false otherwise.

      MDN Reference

    • readonly NONE: 0
    • readonly request: Request
    • readonly target: null | EventTarget

      Returns the object to which event is dispatched (its target).

      MDN Reference

    • readonly timeStamp: number

      Returns the event's timestamp as the number of milliseconds measured relative to the time origin.

      MDN Reference

    • readonly type: string

      Returns the type of event, e.g. "click", "hashchange", or "submit".

      MDN Reference

    • readonly url: string

    • Returns the invocation target objects of event's path (objects on which listeners will be invoked), except for any nodes in shadow trees of which the shadow root's mode is "closed" that are not reachable from event's currentTarget.

      MDN Reference

      Returns an array containing the current EventTarget as the only entry or empty if the event is not being dispatched. This is not used in Node.js and is provided purely for completeness.

    • Sets the defaultPrevented property to true if cancelable is true.

    • response: Response | Promise<Response>
      ): void;

    • Stops the invocation of event listeners after the current one completes.

    • This is not used in Node.js and is provided purely for completeness.

    • promise: Promise<any>
      ): void;

  • interface FileBlob

    Blob powered by the fastest system calls available for operating on files.

    This Blob is lazy. That means it won't do any work until you read from it.

    • size will not be valid until the contents of the file are read at least once.
    • type is auto-set based on the file extension when possible
    const file = Bun.file("./hello.json");
console.log(file.type); // "application/json"
console.log(await file.text()); // '{"hello":"world"}'
    • lastModified: number

      A UNIX timestamp indicating when the file was last modified.

    • readonly name?: string

      The name or path of the file, as specified in the constructor.

    • readonly size: number
    • readonly type: string

    • Returns a promise that resolves to the contents of the blob as an ArrayBuffer

    • bytes(): Promise<Uint8Array<ArrayBufferLike>>;

      Returns a promise that resolves to the contents of the blob as a Uint8Array (array of bytes) its the same as new Uint8Array(await blob.arrayBuffer())

    • delete(): Promise<void>;

      Deletes the file (same as unlink)

    • exists(): Promise<boolean>;

      Does the file exist?

      This returns true for regular files and FIFOs. It returns false for directories. Note that a race condition can occur where the file is deleted or renamed after this is called but before you open it.

      This does a system call to check if the file exists, which can be slow.

      If using this in an HTTP server, it's faster to instead use return new Response(Bun.file(path)) and then an error handler to handle exceptions.

      Instead of checking for a file's existence and then performing the operation, it is faster to just perform the operation and handle the error.

      For empty Blob, this always returns true.

    • formData(): Promise<FormData>;

      Read the data from the blob as a FormData object.

      This first decodes the data from UTF-8, then parses it as a multipart/form-data body or a application/x-www-form-urlencoded body.

      The type property of the blob is used to determine the format of the body.

      This is a non-standard addition to the Blob API, to make it conform more closely to the BodyMixin API.

    • json(): Promise<any>;

      Read the data from the blob as a JSON object.

      This first decodes the data from UTF-8, then parses it as JSON.

    • begin?: number,
      end?: number,
      contentType?: string

      Offset any operation on the file starting at begin and ending at end. end is relative to 0

      Similar to TypedArray.subarray. Does not copy the file, open the file, or modify the file.

      If begin > 0, () will be slower on macOS

      @param begin

      start offset in bytes

      @param end

      absolute offset in bytes (relative to 0)

      @param contentType

      MIME type for the new BunFile

      begin?: number,
      contentType?: string

      Offset any operation on the file starting at begin

      Similar to TypedArray.subarray. Does not copy the file, open the file, or modify the file.

      If begin > 0, Bun.write() will be slower on macOS

      @param begin

      start offset in bytes

      @param contentType

      MIME type for the new BunFile

      contentType?: string

      Slice the file from the beginning to the end, optionally with a new MIME type.

      @param contentType

      MIME type for the new BunFile

    • stat(): Promise<Stats>;

      Provides useful information about the file.

    • stream(): ReadableStream<Uint8Array<ArrayBufferLike>>;

      Returns a readable stream of the blob's contents

    • text(): Promise<string>;

      Returns a promise that resolves to the contents of the blob as a string

    • data: string | ArrayBuffer | SharedArrayBuffer | BunFile | Request | Response | ArrayBufferView<ArrayBufferLike>,
      options?: { highWaterMark: number }
      ): Promise<number>;

      Write data to the file. This is equivalent to using Bun.write with a BunFile.

      @param data

      The data to write.

      @param options

      The options to use for the write.

    • options?: { highWaterMark: number }

      Incremental writer for files and pipes.

  • interface FileSink

    Fast incremental writer for files and pipes.

    This uses the same interface as ArrayBufferSink, but writes to a file or pipe.

    • error?: Error
      ): number | Promise<number>;

      Close the file descriptor. This also flushes the internal buffer.

      @param error

      Optional error to associate with the close operation

      @returns

      Number of bytes written or a Promise resolving to the number of bytes

    • flush(): number | Promise<number>;

      Flush the internal buffer, committing the data to disk or the pipe.

      @returns

      Number of bytes flushed or a Promise resolving to the number of bytes

    • ref(): void;

      For FIFOs & pipes, this lets you decide whether Bun's process should remain alive until the pipe is closed.

      By default, it is automatically managed. While the stream is open, the process remains alive and once the other end hangs up or the stream closes, the process exits.

      If you previously called unref, you can call this again to re-enable automatic management.

      Internally, it will reference count the number of times this is called. By default, that number is 1

      If the file is not a FIFO or pipe, ref and unref do nothing. If the pipe is already closed, this does nothing.

    • options?: { highWaterMark: number }
      ): void;

      Start the file sink with provided options.

      @param options

      Configuration options for the file sink

    • unref(): void;

      For FIFOs & pipes, this lets you decide whether Bun's process should remain alive until the pipe is closed.

      If you want to allow Bun's process to terminate while the stream is open, call this.

      If the file is not a FIFO or pipe, ref and unref do nothing. If the pipe is already closed, this does nothing.

    • chunk: string | ArrayBuffer | SharedArrayBuffer | ArrayBufferView<ArrayBufferLike>
      ): number;

      Write a chunk of data to the file.

      If the file descriptor is not writable yet, the data is buffered.

      @param chunk

      The data to write

      @returns

      Number of bytes written

  • interface GenericServeOptions

    • development?: boolean | { console: boolean; hmr: boolean }

      Render contextual errors? This enables bun's error page

    • error?: (this: Server, error: ErrorLike) => void | Promise<void> | Response | Promise<Response>
    • id?: null | string

      Uniquely identify a server instance with an ID

      When bun is started with the --hot flag:

      This string will be used to hot reload the server without interrupting pending requests or websockets. If not provided, a value will be generated. To disable hot reloading, set this value to null.

      When bun is not started with the --hot flag:

      This string will currently do nothing. But in the future it could be useful for logs or metrics.

    • maxRequestBodySize?: number

      What is the maximum size of a request body? (in bytes)

  • interface GlobScanOptions

    • absolute?: boolean

      Return the absolute path for entries.

    • cwd?: string

      The root directory to start matching from. Defaults to process.cwd()

    • dot?: boolean

      Allow patterns to match entries that begin with a period (.).

    • onlyFiles?: boolean

      Return only files.

  • interface Hash

  • interface HeapSnapshot

    JavaScriptCore engine's internal heap snapshot

    I don't know how to make this something Chrome or Safari can read.

    If you have any ideas, please file an issue https://github.com/oven-sh/bun

  • interface HTMLBundle

    Used when importing an HTML file at runtime.

    import app from "./index.html";

    Bun.build support for this isn't imlpemented yet.

  • interface Import

  • interface LibdeflateCompressionOptions

    • level?: 0 | 1 | 5 | 3 | 4 | 6 | 2 | 7 | 8 | 9 | 10 | 11 | 12
    • library?: 'libdeflate'

  • interface MatchedRoute

    • readonly filePath: string
    • readonly kind: 'exact' | 'catch-all' | 'optional-catch-all' | 'dynamic'
    • readonly name: string
    • readonly params: Record<string, string>

      A map of the parameters from the route

      const router = new FileSystemRouter({
  dir: "/path/to/files",
  style: "nextjs",
});
const {params} = router.match("/blog/2020/01/01/hello-world");
console.log(params.year); // "2020"
console.log(params.month); // "01"
console.log(params.day); // "01"
console.log(params.slug); // "hello-world"
    • readonly pathname: string
    • readonly query: Record<string, string>
    • readonly src: string

  • interface MessageEventInit<T = any>

  • interface MMapOptions

    • shared?: boolean

      Allow other processes to see results instantly? This enables MAP_SHARED. If false, it enables MAP_PRIVATE.

    • sync?: boolean

      Sets MAP_SYNC flag on Linux. Ignored on macOS due to lack of support.

  • interface NetworkSink

    Fast incremental writer for files and pipes.

    This uses the same interface as ArrayBufferSink, but writes to a file or pipe.

    • error?: Error
      ): number | Promise<number>;

      Finish the upload. This also flushes the internal buffer.

      @param error

      Optional error to associate with the end operation

      @returns

      Number of bytes written or a Promise resolving to the number of bytes

    • flush(): number | Promise<number>;

      Flush the internal buffer, committing the data to the network.

      @returns

      Number of bytes flushed or a Promise resolving to the number of bytes

    • ref(): void;

      For FIFOs & pipes, this lets you decide whether Bun's process should remain alive until the pipe is closed.

      By default, it is automatically managed. While the stream is open, the process remains alive and once the other end hangs up or the stream closes, the process exits.

      If you previously called unref, you can call this again to re-enable automatic management.

      Internally, it will reference count the number of times this is called. By default, that number is 1

      If the file is not a FIFO or pipe, ref and unref do nothing. If the pipe is already closed, this does nothing.

    • options?: { highWaterMark: number }
      ): void;

      Start the file sink with provided options.

      @param options

      Configuration options for the file sink

    • stat(): Promise<Stats>;

      Get the stat of the file.

      @returns

      Promise resolving to the file stats

    • unref(): void;

      For FIFOs & pipes, this lets you decide whether Bun's process should remain alive until the pipe is closed.

      If you want to allow Bun's process to terminate while the stream is open, call this.

      If the file is not a FIFO or pipe, ref and unref do nothing. If the pipe is already closed, this does nothing.

    • chunk: string | ArrayBuffer | SharedArrayBuffer | ArrayBufferView<ArrayBufferLike>
      ): number;

      Write a chunk of data to the network.

      If the network is not writable yet, the data is buffered.

      @param chunk

      The data to write

      @returns

      Number of bytes written

  • interface OnLoadArgs

    • defer: () => Promise<void>

      Defer the execution of this callback until all other modules have been parsed.

    • loader: Loader

      The default loader for this file extension

    • namespace: string

      The namespace of the module being loaded

    • path: string

      The resolved import specifier of the module being loaded

      builder.onLoad({ filter: /^hello:world$/ }, (args) => {
  console.log(args.path); // "hello:world"
  return { exports: { foo: "bar" }, loader: "object" };
});

  • interface OnLoadResultObject

    • exports: Record<string, unknown>

      The object to use as the module

      // In your loader
builder.onLoad({ filter: /^hello:world$/ }, (args) => {
   return { exports: { foo: "bar" }, loader: "object" };
});

// In your script
import {foo} from "hello:world";
console.log(foo); // "bar"
    • loader: 'object'

      The loader to use for this file

  • interface OnLoadResultSourceCode

  • interface OnResolveArgs

    • importer: string

      The module that imported the module being resolved

    • kind: ImportKind

      The kind of import this resolve is for.

    • namespace: string

      The namespace of the importer.

    • path: string

      The import specifier of the module being loaded

    • resolveDir: string

      The directory to perform file-based resolutions in.

  • interface OnResolveResult

    • external?: boolean
    • namespace?: string

      The namespace of the destination It will be concatenated with path to form the final import specifier

      "foo" // "foo:bar"
    • path: string

      The destination of the import

  • interface PluginBuilder

    The builder object passed to Bun.plugin

    • config: BuildConfig & { plugins: BunPlugin[] }

      The config object passed to Bun.build as is. Can be mutated.

    • specifier: string,
      callback: () => OnLoadResult | Promise<OnLoadResult>
      ): this;

      Create a lazy-loaded virtual module that can be imported or required from other modules

      @param specifier

      The module specifier to register the callback for

      @param callback

      The function to run when the module is imported or required

      @returns

      this for method chaining

      Bun.plugin({
  setup(builder) {
    builder.module("hello:world", () => {
      return { exports: { foo: "bar" }, loader: "object" };
    });
  },
});

// sometime later
const { foo } = await import("hello:world");
console.log(foo); // "bar"

// or
const { foo } = require("hello:world");
console.log(foo); // "bar"
    • constraints: PluginConstraints,
      callback: { external: unknown; napiModule: unknown; symbol: string }
      ): this;
    • constraints: PluginConstraints,
      callback: OnLoadCallback
      ): this;

      Register a callback to load imports with a specific import specifier

      @param constraints

      The constraints to apply the plugin to

      @param callback

      The callback to handle the import

      @returns

      this for method chaining

      Bun.plugin({
  setup(builder) {
    builder.onLoad({ filter: /^hello:world$/ }, (args) => {
      return { exports: { foo: "bar" }, loader: "object" };
    });
  },
});
    • constraints: PluginConstraints,
      callback: OnResolveCallback
      ): this;

      Register a callback to resolve imports matching a filter and/or namespace

      @param constraints

      The constraints to apply the plugin to

      @param callback

      The callback to handle the import

      @returns

      this for method chaining

      Bun.plugin({
  setup(builder) {
    builder.onResolve({ filter: /^wat$/ }, (args) => {
      return { path: "/tmp/woah.js" };
    });
  },
});
    • callback: OnStartCallback
      ): this;

      Register a callback which will be invoked when bundling starts. When using hot module reloading, this is called at the start of each incremental rebuild.

      @returns

      this for method chaining

      Bun.plugin({
  setup(builder) {
    builder.onStart(() => {
      console.log("bundle just started!!")
    });
  },
});

  • interface PluginConstraints

    • filter: RegExp

      Only apply the plugin when the import specifier matches this regular expression

      // Only apply the plugin when the import specifier matches the regex
Bun.plugin({
 setup(builder) {
    builder.onLoad({ filter: /node_modules/underscore/ }, (args) => {
     return { contents: "throw new Error('Please use lodash instead of underscore.')" };
    });
 }
})
    • namespace?: string

      Only apply the plugin when the import specifier has a namespace matching this string

      Namespaces are prefixes in import specifiers. For example, "bun:ffi" has the namespace "bun".

      The default namespace is "file" and it can be omitted from import specifiers.

  • interface ReadableStreamDefaultReadManyResult<T>

  • interface RedisOptions

    • autoReconnect?: boolean

      Whether to automatically reconnect

    • connectionTimeout?: number

      Connection timeout in milliseconds

    • enableAutoPipelining?: boolean

      Whether to enable auto-pipelining

    • enableOfflineQueue?: boolean

      Whether to queue commands when disconnected

    • idleTimeout?: number

      Idle timeout in milliseconds

    • maxRetries?: number

      Maximum number of reconnection attempts

    • tls?: boolean | { ca: string | Buffer<ArrayBufferLike> | string | Buffer<ArrayBufferLike>[]; cert: string | Buffer<ArrayBufferLike>; key: string | Buffer<ArrayBufferLike>; rejectUnauthorized: boolean }

      TLS options Can be a boolean or an object with TLS options

  • interface ReservedSQL

    Represents a reserved connection from the connection pool Extends SQL with additional release functionality

    • constructor ReservedSQL(
      connectionString: string | URL
      ): SQL;

      Creates a new SQL client instance

      const sql = new SQL("postgres://localhost:5432/mydb");
const sql = new SQL(new URL("postgres://localhost:5432/mydb"));
      constructor ReservedSQL(
      connectionString: string | URL,
      options: SQLOptions
      ): SQL;

      Creates a new SQL client instance with options

      const sql = new SQL("postgres://localhost:5432/mydb", { idleTimeout: 1000 });
      constructor ReservedSQL(
      options?: SQLOptions
      ): SQL;

      Creates a new SQL client instance with options

      const sql = new SQL({ url: "postgres://localhost:5432/mydb", idleTimeout: 1000 });
    • options: SQLOptions

      Current client options

    • [Symbol.asyncDispose](): Promise<any>;
    • fn: SQLTransactionContextCallback
      ): Promise<any>;

      Begins a new transaction Will reserve a connection for the transaction and supply a scoped sql instance for all transaction uses in the callback function. sql.begin will resolve with the returned value from the callback function. BEGIN is automatically sent with the optional options, and if anything fails ROLLBACK will be called so the connection can be released and execution can continue.

      const [user, account] = await sql.begin(async sql => {
  const [user] = await sql`
    insert into users (
      name
    ) values (
      'Murray'
    )
    returning *
  `
  const [account] = await sql`
    insert into accounts (
      user_id
    ) values (
      ${ user.user_id }
    )
    returning *
  `
  return [user, account]
})
      options: string,
      fn: SQLTransactionContextCallback
      ): Promise<any>;

      Begins a new transaction with options Will reserve a connection for the transaction and supply a scoped sql instance for all transaction uses in the callback function. sql.begin will resolve with the returned value from the callback function. BEGIN is automatically sent with the optional options, and if anything fails ROLLBACK will be called so the connection can be released and execution can continue.

      const [user, account] = await sql.begin("read write", async sql => {
  const [user] = await sql`
    insert into users (
      name
    ) values (
      'Murray'
    )
    returning *
  `
  const [account] = await sql`
    insert into accounts (
      user_id
    ) values (
      ${ user.user_id }
    )
    returning *
  `
  return [user, account]
})
    • name: string,
      fn: SQLTransactionContextCallback
      ): Promise<any>;

      Begins a distributed transaction Also know as Two-Phase Commit, in a distributed transaction, Phase 1 involves the coordinator preparing nodes by ensuring data is written and ready to commit, while Phase 2 finalizes with nodes committing or rolling back based on the coordinator's decision, ensuring durability and releasing locks. In PostgreSQL and MySQL distributed transactions persist beyond the original session, allowing privileged users or coordinators to commit/rollback them, ensuring support for distributed transactions, recovery, and administrative tasks. beginDistributed will automatic rollback if any exception are not caught, and you can commit and rollback later if everything goes well. PostgreSQL natively supports distributed transactions using PREPARE TRANSACTION, while MySQL uses XA Transactions, and MSSQL also supports distributed/XA transactions. However, in MSSQL, distributed transactions are tied to the original session, the DTC coordinator, and the specific connection. These transactions are automatically committed or rolled back following the same rules as regular transactions, with no option for manual intervention from other sessions, in MSSQL distributed transactions are used to coordinate transactions using Linked Servers.

      await sql.beginDistributed("numbers", async sql => {
  await sql`create table if not exists numbers (a int)`;
  await sql`insert into numbers values(1)`;
});
// later you can call
await sql.commitDistributed("numbers");
// or await sql.rollbackDistributed("numbers");
    • options?: { timeout: number }
      ): Promise<void>;

      Closes the database connection with optional timeout in seconds. If timeout is 0, it will close immediately, if is not provided it will wait for all queries to finish before closing.

      await sql.close({ timeout: 1 });
    • name: string
      ): Promise<void>;

      Commits a distributed transaction also know as prepared transaction in postgres or XA transaction in MySQL

      await sql.commitDistributed("my_distributed_transaction");
    • connect(): Promise<SQL>;

      Waits for the database connection to be established

      await sql.connect();
    • name: string,
      fn: SQLTransactionContextCallback
      ): Promise<any>;

      Alternative method to begin a distributed transaction

    • options?: { timeout: number }
      ): Promise<void>;

      Closes the database connection with optional timeout in seconds. If timeout is 0, it will close immediately, if is not provided it will wait for all queries to finish before closing.

      await sql.end({ timeout: 1 });
    • filename: string,
      values?: any[]

      Reads a file and uses the contents as a query. Optional parameters can be used if the file includes $1, $2, etc

      const result = await sql.file("query.sql", [1, 2, 3]);
    • flush(): void;

      Flushes any pending operations

    • release(): void;

      Releases the client back to the connection pool

    • reserve(): Promise<ReservedSQL>;

      The reserve method pulls out 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. Calling reserve in a reserved Sql will return a new reserved connection, not the same connection (behavior matches postgres package).

      const reserved = await sql.reserve();
await reserved`select * from users`;
await reserved.release();
// with in a production scenario would be something more like
const reserved = await sql.reserve();
try {
  // ... queries
} finally {
  await reserved.release();
}
//To make it simpler bun supportsSymbol.dispose and Symbol.asyncDispose
{
// always release after context (safer)
using reserved = await sql.reserve()
await reserved`select * from users`
}
    • name: string
      ): Promise<void>;

      Rolls back a distributed transaction also know as prepared transaction in postgres or XA transaction in MySQL

      await sql.rollbackDistributed("my_distributed_transaction");
    • fn: SQLTransactionContextCallback
      ): Promise<any>;

      Alternative method to begin a transaction Will reserve a connection for the transaction and supply a scoped sql instance for all transaction uses in the callback function. sql.transaction will resolve with the returned value from the callback function. BEGIN is automatically sent with the optional options, and if anything fails ROLLBACK will be called so the connection can be released and execution can continue.

      const [user, account] = await sql.transaction(async sql => {
  const [user] = await sql`
    insert into users (
      name
    ) values (
      'Murray'
    )
    returning *
  `
  const [account] = await sql`
    insert into accounts (
      user_id
    ) values (
      ${ user.user_id }
    )
    returning *
  `
  return [user, account]
})
      options: string,
      fn: SQLTransactionContextCallback
      ): Promise<any>;

      Alternative method to begin a transaction with options Will reserve a connection for the transaction and supply a scoped sql instance for all transaction uses in the callback function. sql.transaction will resolve with the returned value from the callback function. BEGIN is automatically sent with the optional options, and if anything fails ROLLBACK will be called so the connection can be released and execution can continue.

      const [user, account] = await sql.transaction("read write", async sql => {
  const [user] = await sql`
    insert into users (
      name
    ) values (
      'Murray'
    )
    returning *
  `
  const [account] = await sql`
    insert into accounts (
      user_id
    ) values (
      ${ user.user_id }
    )
    returning *
  `
  return [user, account]
})
    • string: string,
      values?: any[]

      If you know what you're doing, you can use unsafe to pass any string you'd like. Please note that this can lead to SQL injection if you're not careful. You can also nest sql.unsafe within a safe sql expression. This is useful if only part of your fraction has unsafe elements.

      const result = await sql.unsafe(`select ${danger} from users where id = ${dragons}`)

  • interface ResourceUsage

    • contextSwitches: { involuntary: number; voluntary: number }

      The number of voluntary and involuntary context switches that the process made.

    • cpuTime: { system: number; total: number; user: number }

      The amount of CPU time used by the process, in microseconds.

    • maxRSS: number

      The maximum amount of resident set size (in bytes) used by the process during its lifetime.

    • messages: { received: number; sent: number }

      IPC messages sent and received by the process.

    • ops: { in: number; out: number }

      The number of IO operations done by the process.

    • shmSize: number

      The amount of shared memory that the process used.

    • signalCount: number

      The number of signals delivered to the process.

    • swapCount: number

      The number of times the process was swapped out of main memory.

  • interface S3FilePresignOptions

    Options for generating presigned URLs

    • accessKeyId?: string

      The access key ID for authentication. Defaults to S3_ACCESS_KEY_ID or AWS_ACCESS_KEY_ID environment variables.

    • acl?: 'private' | 'public-read' | 'public-read-write' | 'aws-exec-read' | 'authenticated-read' | 'bucket-owner-read' | 'bucket-owner-full-control' | 'log-delivery-write'

      The Access Control List (ACL) policy for the file. Controls who can access the file and what permissions they have.

      // Setting public read access
    const file = s3.file("public-file.txt", {
      acl: "public-read",
      bucket: "my-bucket"
    });
    • bucket?: string

      The S3 bucket name. Defaults to S3_BUCKET or AWS_BUCKET environment variables.

      // Using explicit bucket
    const file = s3.file("my-file.txt", { bucket: "my-bucket" });
    • endings?: EndingType
    • endpoint?: string

      The S3-compatible service endpoint URL. Defaults to S3_ENDPOINT or AWS_ENDPOINT environment variables.

      // AWS S3
    const file = s3.file("my-file.txt", {
      endpoint: "https://s3.us-east-1.amazonaws.com"
    });
    • expiresIn?: number

      Number of seconds until the presigned URL expires.

      • Default: 86400 (1 day)
      // Short-lived URL
    const url = file.presign({
      expiresIn: 3600 // 1 hour
    });
    • method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD'

      The HTTP method allowed for the presigned URL.

      // GET URL for downloads
    const downloadUrl = file.presign({
      method: "GET",
      expiresIn: 3600
    });
    • partSize?: number

      The size of each part in multipart uploads (in bytes).

      • Minimum: 5 MiB
      • Maximum: 5120 MiB
      • Default: 5 MiB
      // Configuring multipart uploads
    const file = s3.file("large-file.dat", {
      partSize: 10 * 1024 * 1024, // 10 MiB parts
      queueSize: 4  // Upload 4 parts in parallel
    });

    const writer = file.writer();
    // ... write large file in chunks
    • queueSize?: number

      Number of parts to upload in parallel for multipart uploads.

      • Default: 5
      • Maximum: 255

      Increasing this value can improve upload speeds for large files but will use more memory.

    • region?: string

      The AWS region. Defaults to S3_REGION or AWS_REGION environment variables.

      const file = s3.file("my-file.txt", {
      bucket: "my-bucket",
      region: "us-west-2"
    });
    • retry?: number

      Number of retry attempts for failed uploads.

      • Default: 3
      • Maximum: 255
      // Setting retry attempts
    const file = s3.file("my-file.txt", {
      retry: 5 // Retry failed uploads up to 5 times
    });
    • secretAccessKey?: string

      The secret access key for authentication. Defaults to S3_SECRET_ACCESS_KEY or AWS_SECRET_ACCESS_KEY environment variables.

    • sessionToken?: string

      Optional session token for temporary credentials. Defaults to S3_SESSION_TOKEN or AWS_SESSION_TOKEN environment variables.

      // Using temporary credentials
    const file = s3.file("my-file.txt", {
      accessKeyId: tempAccessKey,
      secretAccessKey: tempSecretKey,
      sessionToken: tempSessionToken
    });
    • storageClass?: 'STANDARD' | 'DEEP_ARCHIVE' | 'EXPRESS_ONEZONE' | 'GLACIER' | 'GLACIER_IR' | 'INTELLIGENT_TIERING' | 'ONEZONE_IA' | 'OUTPOSTS' | 'REDUCED_REDUNDANCY' | 'SNOW' | 'STANDARD_IA'

      By default, Amazon S3 uses the STANDARD Storage Class to store newly created objects.

      // Setting explicit Storage class
    const file = s3.file("my-file.json", {
      storageClass: "STANDARD_IA"
    });
    • type?: string

      The Content-Type of the file. Automatically set based on file extension when possible.

      // Setting explicit content type
    const file = s3.file("data.bin", {
      type: "application/octet-stream"
    });
    • virtualHostedStyle?: boolean

      Use virtual hosted style endpoint. default to false, when true if endpoint is informed it will ignore the bucket

      // Using virtual hosted style
    const file = s3.file("my-file.txt", {
      virtualHostedStyle: true,
      endpoint: "https://my-bucket.s3.us-east-1.amazonaws.com"
    });

  • interface S3ListObjectsOptions

    • continuationToken?: string

      ContinuationToken indicates to S3 that the list is being continued on this bucket with a token. ContinuationToken is obfuscated and is not a real key. You can use this ContinuationToken for pagination of the list results.

    • delimiter?: string

      A delimiter is a character that you use to group keys.

    • encodingType?: 'url'

      Encoding type used by S3 to encode the object keys in the response. Responses are encoded only in UTF-8. An object key can contain any Unicode character. However, the XML 1.0 parser can't parse certain characters, such as characters with an ASCII value from 0 to 10. For characters that aren't supported in XML 1.0, you can add this parameter to request that S3 encode the keys in the response.

    • fetchOwner?: boolean

      If you want to return the owner field with each key in the result, then set the FetchOwner field to true.

    • maxKeys?: number

      Sets the maximum number of keys returned in the response. By default, the action returns up to 1,000 key names. The response might contain fewer keys but will never contain more.

    • prefix?: string

      Limits the response to keys that begin with the specified prefix.

    • startAfter?: string

      StartAfter is where you want S3 to start listing from. S3 starts listing after this specified key. StartAfter can be any key in the bucket.

  • interface S3ListObjectsResponse

    • commonPrefixes?: { prefix: string }[]

      All of the keys (up to 1,000) that share the same prefix are grouped together. When counting the total numbers of returns by this API operation, this group of keys is considered as one item.

      A response can contain CommonPrefixes only if you specify a delimiter.

      CommonPrefixes contains all (if there are any) keys between Prefix and the next occurrence of the string specified by a delimiter.

      CommonPrefixes lists keys that act like subdirectories in the directory specified by Prefix.

      For example, if the prefix is notes/ and the delimiter is a slash (/) as in notes/summer/july, the common prefix is notes/summer/. All of the keys that roll up into a common prefix count as a single return when calculating the number of returns.

    • contents?: { checksumAlgorithm: 'CRC32' | 'CRC32C' | 'SHA1' | 'SHA256' | 'CRC64NVME'; checksumType: 'COMPOSITE' | 'FULL_OBJECT'; eTag: string; key: string; lastModified: string; owner: { displayName: string; id: string }; restoreStatus: { isRestoreInProgress: boolean; restoreExpiryDate: string }; size: number; storageClass: 'STANDARD' | 'DEEP_ARCHIVE' | 'EXPRESS_ONEZONE' | 'GLACIER' | 'GLACIER_IR' | 'INTELLIGENT_TIERING' | 'ONEZONE_IA' | 'OUTPOSTS' | 'REDUCED_REDUNDANCY' | 'SNOW' | 'STANDARD_IA' }[]

      Metadata about each object returned.

    • continuationToken?: string

      If ContinuationToken was sent with the request, it is included in the response. You can use the returned ContinuationToken for pagination of the list response.

    • delimiter?: string

      Causes keys that contain the same string between the prefix and the first occurrence of the delimiter to be rolled up into a single result element in the CommonPrefixes collection. These rolled-up keys are not returned elsewhere in the response. Each rolled-up result counts as only one return against the MaxKeys value.

    • encodingType?: 'url'

      Encoding type used by S3 to encode object key names in the XML response.

    • isTruncated?: boolean

      Set to false if all of the results were returned. Set to true if more keys are available to return. If the number of results exceeds that specified by MaxKeys, all of the results might not be returned.

    • keyCount?: number

      KeyCount is the number of keys returned with this request. KeyCount will always be less than or equal to the MaxKeys field. For example, if you ask for 50 keys, your result will include 50 keys or fewer.

    • maxKeys?: number

      Sets the maximum number of keys returned in the response. By default, the action returns up to 1,000 key names. The response might contain fewer keys but will never contain more.

    • name?: string

      The bucket name.

    • nextContinuationToken?: string

      NextContinuationToken is sent when isTruncated is true, which means there are more keys in the bucket that can be listed. The next list requests to S3 can be continued with this NextContinuationToken. NextContinuationToken is obfuscated and is not a real key.

    • prefix?: string

      Keys that begin with the indicated prefix.

    • startAfter?: string

      If StartAfter was sent with the request, it is included in the response.

  • interface S3Options

    Configuration options for S3 operations

    • accessKeyId?: string

      The access key ID for authentication. Defaults to S3_ACCESS_KEY_ID or AWS_ACCESS_KEY_ID environment variables.

    • acl?: 'private' | 'public-read' | 'public-read-write' | 'aws-exec-read' | 'authenticated-read' | 'bucket-owner-read' | 'bucket-owner-full-control' | 'log-delivery-write'

      The Access Control List (ACL) policy for the file. Controls who can access the file and what permissions they have.

      // Setting public read access
    const file = s3.file("public-file.txt", {
      acl: "public-read",
      bucket: "my-bucket"
    });
    • bucket?: string

      The S3 bucket name. Defaults to S3_BUCKET or AWS_BUCKET environment variables.

      // Using explicit bucket
    const file = s3.file("my-file.txt", { bucket: "my-bucket" });
    • endings?: EndingType
    • endpoint?: string

      The S3-compatible service endpoint URL. Defaults to S3_ENDPOINT or AWS_ENDPOINT environment variables.

      // AWS S3
    const file = s3.file("my-file.txt", {
      endpoint: "https://s3.us-east-1.amazonaws.com"
    });
    • partSize?: number

      The size of each part in multipart uploads (in bytes).

      • Minimum: 5 MiB
      • Maximum: 5120 MiB
      • Default: 5 MiB
      // Configuring multipart uploads
    const file = s3.file("large-file.dat", {
      partSize: 10 * 1024 * 1024, // 10 MiB parts
      queueSize: 4  // Upload 4 parts in parallel
    });

    const writer = file.writer();
    // ... write large file in chunks
    • queueSize?: number

      Number of parts to upload in parallel for multipart uploads.

      • Default: 5
      • Maximum: 255

      Increasing this value can improve upload speeds for large files but will use more memory.

    • region?: string

      The AWS region. Defaults to S3_REGION or AWS_REGION environment variables.

      const file = s3.file("my-file.txt", {
      bucket: "my-bucket",
      region: "us-west-2"
    });
    • retry?: number

      Number of retry attempts for failed uploads.

      • Default: 3
      • Maximum: 255
      // Setting retry attempts
    const file = s3.file("my-file.txt", {
      retry: 5 // Retry failed uploads up to 5 times
    });
    • secretAccessKey?: string

      The secret access key for authentication. Defaults to S3_SECRET_ACCESS_KEY or AWS_SECRET_ACCESS_KEY environment variables.

    • sessionToken?: string

      Optional session token for temporary credentials. Defaults to S3_SESSION_TOKEN or AWS_SESSION_TOKEN environment variables.

      // Using temporary credentials
    const file = s3.file("my-file.txt", {
      accessKeyId: tempAccessKey,
      secretAccessKey: tempSecretKey,
      sessionToken: tempSessionToken
    });
    • storageClass?: 'STANDARD' | 'DEEP_ARCHIVE' | 'EXPRESS_ONEZONE' | 'GLACIER' | 'GLACIER_IR' | 'INTELLIGENT_TIERING' | 'ONEZONE_IA' | 'OUTPOSTS' | 'REDUCED_REDUNDANCY' | 'SNOW' | 'STANDARD_IA'

      By default, Amazon S3 uses the STANDARD Storage Class to store newly created objects.

      // Setting explicit Storage class
    const file = s3.file("my-file.json", {
      storageClass: "STANDARD_IA"
    });
    • type?: string

      The Content-Type of the file. Automatically set based on file extension when possible.

      // Setting explicit content type
    const file = s3.file("data.bin", {
      type: "application/octet-stream"
    });
    • virtualHostedStyle?: boolean

      Use virtual hosted style endpoint. default to false, when true if endpoint is informed it will ignore the bucket

      // Using virtual hosted style
    const file = s3.file("my-file.txt", {
      virtualHostedStyle: true,
      endpoint: "https://my-bucket.s3.us-east-1.amazonaws.com"
    });

  • interface S3Stats

  • interface SavepointSQL

    Represents a savepoint within a transaction

    • constructor SavepointSQL(
      connectionString: string | URL
      ): SQL;

      Creates a new SQL client instance

      const sql = new SQL("postgres://localhost:5432/mydb");
const sql = new SQL(new URL("postgres://localhost:5432/mydb"));
      constructor SavepointSQL(
      connectionString: string | URL,
      options: SQLOptions
      ): SQL;

      Creates a new SQL client instance with options

      const sql = new SQL("postgres://localhost:5432/mydb", { idleTimeout: 1000 });
      constructor SavepointSQL(
      options?: SQLOptions
      ): SQL;

      Creates a new SQL client instance with options

      const sql = new SQL({ url: "postgres://localhost:5432/mydb", idleTimeout: 1000 });
    • options: SQLOptions

      Current client options

    • [Symbol.asyncDispose](): Promise<any>;
    • fn: SQLTransactionContextCallback
      ): Promise<any>;

      Begins a new transaction Will reserve a connection for the transaction and supply a scoped sql instance for all transaction uses in the callback function. sql.begin will resolve with the returned value from the callback function. BEGIN is automatically sent with the optional options, and if anything fails ROLLBACK will be called so the connection can be released and execution can continue.

      const [user, account] = await sql.begin(async sql => {
  const [user] = await sql`
    insert into users (
      name
    ) values (
      'Murray'
    )
    returning *
  `
  const [account] = await sql`
    insert into accounts (
      user_id
    ) values (
      ${ user.user_id }
    )
    returning *
  `
  return [user, account]
})
      options: string,
      fn: SQLTransactionContextCallback
      ): Promise<any>;

      Begins a new transaction with options Will reserve a connection for the transaction and supply a scoped sql instance for all transaction uses in the callback function. sql.begin will resolve with the returned value from the callback function. BEGIN is automatically sent with the optional options, and if anything fails ROLLBACK will be called so the connection can be released and execution can continue.

      const [user, account] = await sql.begin("read write", async sql => {
  const [user] = await sql`
    insert into users (
      name
    ) values (
      'Murray'
    )
    returning *
  `
  const [account] = await sql`
    insert into accounts (
      user_id
    ) values (
      ${ user.user_id }
    )
    returning *
  `
  return [user, account]
})
    • name: string,
      fn: SQLTransactionContextCallback
      ): Promise<any>;

      Begins a distributed transaction Also know as Two-Phase Commit, in a distributed transaction, Phase 1 involves the coordinator preparing nodes by ensuring data is written and ready to commit, while Phase 2 finalizes with nodes committing or rolling back based on the coordinator's decision, ensuring durability and releasing locks. In PostgreSQL and MySQL distributed transactions persist beyond the original session, allowing privileged users or coordinators to commit/rollback them, ensuring support for distributed transactions, recovery, and administrative tasks. beginDistributed will automatic rollback if any exception are not caught, and you can commit and rollback later if everything goes well. PostgreSQL natively supports distributed transactions using PREPARE TRANSACTION, while MySQL uses XA Transactions, and MSSQL also supports distributed/XA transactions. However, in MSSQL, distributed transactions are tied to the original session, the DTC coordinator, and the specific connection. These transactions are automatically committed or rolled back following the same rules as regular transactions, with no option for manual intervention from other sessions, in MSSQL distributed transactions are used to coordinate transactions using Linked Servers.

      await sql.beginDistributed("numbers", async sql => {
  await sql`create table if not exists numbers (a int)`;
  await sql`insert into numbers values(1)`;
});
// later you can call
await sql.commitDistributed("numbers");
// or await sql.rollbackDistributed("numbers");
    • options?: { timeout: number }
      ): Promise<void>;

      Closes the database connection with optional timeout in seconds. If timeout is 0, it will close immediately, if is not provided it will wait for all queries to finish before closing.

      await sql.close({ timeout: 1 });
    • name: string
      ): Promise<void>;

      Commits a distributed transaction also know as prepared transaction in postgres or XA transaction in MySQL

      await sql.commitDistributed("my_distributed_transaction");
    • connect(): Promise<SQL>;

      Waits for the database connection to be established

      await sql.connect();
    • name: string,
      fn: SQLTransactionContextCallback
      ): Promise<any>;

      Alternative method to begin a distributed transaction

    • options?: { timeout: number }
      ): Promise<void>;

      Closes the database connection with optional timeout in seconds. If timeout is 0, it will close immediately, if is not provided it will wait for all queries to finish before closing.

      await sql.end({ timeout: 1 });
    • filename: string,
      values?: any[]

      Reads a file and uses the contents as a query. Optional parameters can be used if the file includes $1, $2, etc

      const result = await sql.file("query.sql", [1, 2, 3]);
    • flush(): void;

      Flushes any pending operations

    • reserve(): Promise<ReservedSQL>;

      The reserve method pulls out 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. Calling reserve in a reserved Sql will return a new reserved connection, not the same connection (behavior matches postgres package).

      const reserved = await sql.reserve();
await reserved`select * from users`;
await reserved.release();
// with in a production scenario would be something more like
const reserved = await sql.reserve();
try {
  // ... queries
} finally {
  await reserved.release();
}
//To make it simpler bun supportsSymbol.dispose and Symbol.asyncDispose
{
// always release after context (safer)
using reserved = await sql.reserve()
await reserved`select * from users`
}
    • name: string
      ): Promise<void>;

      Rolls back a distributed transaction also know as prepared transaction in postgres or XA transaction in MySQL

      await sql.rollbackDistributed("my_distributed_transaction");
    • fn: SQLTransactionContextCallback
      ): Promise<any>;

      Alternative method to begin a transaction Will reserve a connection for the transaction and supply a scoped sql instance for all transaction uses in the callback function. sql.transaction will resolve with the returned value from the callback function. BEGIN is automatically sent with the optional options, and if anything fails ROLLBACK will be called so the connection can be released and execution can continue.

      const [user, account] = await sql.transaction(async sql => {
  const [user] = await sql`
    insert into users (
      name
    ) values (
      'Murray'
    )
    returning *
  `
  const [account] = await sql`
    insert into accounts (
      user_id
    ) values (
      ${ user.user_id }
    )
    returning *
  `
  return [user, account]
})
      options: string,
      fn: SQLTransactionContextCallback
      ): Promise<any>;

      Alternative method to begin a transaction with options Will reserve a connection for the transaction and supply a scoped sql instance for all transaction uses in the callback function. sql.transaction will resolve with the returned value from the callback function. BEGIN is automatically sent with the optional options, and if anything fails ROLLBACK will be called so the connection can be released and execution can continue.

      const [user, account] = await sql.transaction("read write", async sql => {
  const [user] = await sql`
    insert into users (
      name
    ) values (
      'Murray'
    )
    returning *
  `
  const [account] = await sql`
    insert into accounts (
      user_id
    ) values (
      ${ user.user_id }
    )
    returning *
  `
  return [user, account]
})
    • string: string,
      values?: any[]

      If you know what you're doing, you can use unsafe to pass any string you'd like. Please note that this can lead to SQL injection if you're not careful. You can also nest sql.unsafe within a safe sql expression. This is useful if only part of your fraction has unsafe elements.

      const result = await sql.unsafe(`select ${danger} from users where id = ${dragons}`)

  • interface ServeOptions

    • development?: boolean | { console: boolean; hmr: boolean }

      Render contextual errors? This enables bun's error page

    • error?: (this: Server, error: ErrorLike) => void | Promise<void> | Response | Promise<Response>
    • hostname?: string

      What hostname should the server listen on?

      "127.0.0.1" // Only listen locally
    • id?: null | string

      Uniquely identify a server instance with an ID

      When bun is started with the --hot flag:

      This string will be used to hot reload the server without interrupting pending requests or websockets. If not provided, a value will be generated. To disable hot reloading, set this value to null.

      When bun is not started with the --hot flag:

      This string will currently do nothing. But in the future it could be useful for logs or metrics.

    • idleTimeout?: number

      Sets the the number of seconds to wait before timing out a connection due to inactivity.

      Default is 10 seconds.

    • ipv6Only?: boolean

      Whether the IPV6_V6ONLY flag should be set.

    • maxRequestBodySize?: number

      What is the maximum size of a request body? (in bytes)

    • port?: string | number

      What port should the server listen on?

    • reusePort?: boolean

      Whether the SO_REUSEPORT flag should be set.

      This allows multiple processes to bind to the same port, which is useful for load balancing.

    • unix?: undefined

      If set, the HTTP server will listen on a unix socket instead of a port. (Cannot be used with hostname+port)

    • this: Server,
      request: Request,
      server: Server
      ): Response | Promise<Response>;

      Handle HTTP requests

      Respond to Request objects with a Response object.

  • interface ServerWebSocket<T = undefined>

    A fast WebSocket designed for servers.

    Features:

    • Message compression - Messages can be compressed
    • Backpressure - If the client is not ready to receive data, the server will tell you.
    • Dropped messages - If the client cannot receive data, the server will tell you.
    • Topics - Messages can be ServerWebSocket.published to a specific topic and the client can ServerWebSocket.subscribe to topics

    This is slightly different than the browser WebSocket which Bun supports for clients.

    Powered by uWebSockets.

    Bun.serve({
  websocket: {
    open(ws) {
      console.log("Connected", ws.remoteAddress);
    },
    message(ws, data) {
      console.log("Received", data);
      ws.send(data);
    },
    close(ws, code, reason) {
      console.log("Disconnected", code, reason);
    },
  }
});
    • binaryType?: 'arraybuffer' | 'uint8array' | 'nodebuffer'

      Sets how binary data is returned in events.

      • if nodebuffer, binary data is returned as Buffer objects. (default)
      • if arraybuffer, binary data is returned as ArrayBuffer objects.
      • if uint8array, binary data is returned as Uint8Array objects.
      let ws: WebSocket;
ws.binaryType = "uint8array";
ws.addEventListener("message", ({ data }) => {
  console.log(data instanceof Uint8Array); // true
});
    • data: T

      Custom data that you can assign to a client, can be read and written at any time.

      import { serve } from "bun";

serve({
  fetch(request, server) {
    const data = {
      accessToken: request.headers.get("Authorization"),
    };
    if (server.upgrade(request, { data })) {
      return;
    }
    return new Response();
  },
  websocket: {
    open(ws) {
      console.log(ws.data.accessToken);
    }
  }
});
    • readonly readyState: WebSocketReadyState

      The ready state of the client.

      • if 0, the client is connecting.
      • if 1, the client is connected.
      • if 2, the client is closing.
      • if 3, the client is closed.
      console.log(socket.readyState); // 1
    • readonly remoteAddress: string

      The IP address of the client.

      console.log(socket.remoteAddress); // "127.0.0.1"
    • code?: number,
      reason?: string
      ): void;

      Closes the connection.

      Here is a list of close codes:

      • 1000 means "normal closure" (default)
      • 1009 means a message was too big and was rejected
      • 1011 means the server encountered an error
      • 1012 means the server is restarting
      • 1013 means the server is too busy or the client is rate-limited
      • 4000 through 4999 are reserved for applications (you can use it!)

      To close the connection abruptly, use terminate().

      @param code

      The close code to send

      @param reason

      The close reason to send

    • cork<T = unknown>(
      callback: (ws: ServerWebSocket<T>) => T
      ): T;

      Batches send() and publish() operations, which makes it faster to send data.

      The message, open, and drain callbacks are automatically corked, so you only need to call this if you are sending messages outside of those callbacks or in async functions.

      @param callback

      The callback to run.

      ws.cork((ctx) => {
  ctx.send("These messages");
  ctx.sendText("are sent");
  ctx.sendBinary(new TextEncoder().encode("together!"));
});
    • topic: string
      ): boolean;

      Is the client subscribed to a topic?

      @param topic

      The topic name.

      ws.subscribe("chat");
console.log(ws.isSubscribed("chat")); // true
    • data?: string | BufferSource
      ): number;

      Sends a ping.

      @param data

      The data to send

    • data?: string | BufferSource
      ): number;

      Sends a pong.

      @param data

      The data to send

    • topic: string,
      data: string | BufferSource,
      compress?: boolean
      ): number;

      Sends a message to subscribers of the topic.

      @param topic

      The topic name.

      @param data

      The data to send.

      @param compress

      Should the data be compressed? If the client does not support compression, this is ignored.

      ws.publish("chat", "Hello!");
ws.publish("chat", "Compress this.", true);
ws.publish("chat", new Uint8Array([1, 2, 3, 4]));
    • topic: string,
      data: BufferSource,
      compress?: boolean
      ): number;

      Sends a binary message to subscribers of the topic.

      @param topic

      The topic name.

      @param data

      The data to send.

      @param compress

      Should the data be compressed? If the client does not support compression, this is ignored.

      ws.publish("chat", new TextEncoder().encode("Hello!"));
ws.publish("chat", new Uint8Array([1, 2, 3, 4]), true);
    • topic: string,
      data: string,
      compress?: boolean
      ): number;

      Sends a text message to subscribers of the topic.

      @param topic

      The topic name.

      @param data

      The data to send.

      @param compress

      Should the data be compressed? If the client does not support compression, this is ignored.

      ws.publish("chat", "Hello!");
ws.publish("chat", "Compress this.", true);
    • data: string | BufferSource,
      compress?: boolean
      ): number;

      Sends a message to the client.

      @param data

      The data to send.

      @param compress

      Should the data be compressed? If the client does not support compression, this is ignored.

      ws.send("Hello!");
ws.send("Compress this.", true);
ws.send(new Uint8Array([1, 2, 3, 4]));
    • data: BufferSource,
      compress?: boolean
      ): number;

      Sends a binary message to the client.

      @param data

      The data to send.

      @param compress

      Should the data be compressed? If the client does not support compression, this is ignored.

      ws.send(new TextEncoder().encode("Hello!"));
ws.send(new Uint8Array([1, 2, 3, 4]), true);
    • data: string,
      compress?: boolean
      ): number;

      Sends a text message to the client.

      @param data

      The data to send.

      @param compress

      Should the data be compressed? If the client does not support compression, this is ignored.

      ws.send("Hello!");
ws.send("Compress this.", true);
    • topic: string
      ): void;

      Subscribes a client to the topic.

      @param topic

      The topic name.

      ws.subscribe("chat");
    • terminate(): void;

      Abruptly close the connection.

      To gracefully close the connection, use close().

    • topic: string
      ): void;

      Unsubscribes a client to the topic.

      @param topic

      The topic name.

      ws.unsubscribe("chat");

  • interface Socket<Data = undefined>

    • readonly alpnProtocol: null | string | false

      String containing the selected ALPN protocol. Before a handshake has completed, this value is always null. When a handshake is completed but not ALPN protocol was selected, socket.alpnProtocol equals false.

    • readonly authorized: boolean

      This property is true if the peer certificate was signed by one of the CAs specified when creating the Socket instance, otherwise false.

    • readonly bytesWritten: number

      The number of bytes written to the socket.

    • data: Data

      The data context for the socket.

    • readonly listener?: SocketListener<undefined>

      Get the server that created this socket

      This will return undefined if the socket was created by Bun.connect or if the listener has already closed.

    • readonly localAddress: string
    • readonly localFamily: 'IPv4' | 'IPv6'
    • readonly localPort: number

      local port connected to the socket

    • readonly readyState: -2 | -1 | 0 | 1 | 2

      The ready state of the socket.

      You can assume that a positive value means the socket is open and usable

      • -2 = Shutdown
      • -1 = Detached
      • 0 = Closed
      • 1 = Established
      • 2 = Else
    • readonly remoteAddress: string

      Remote IP address connected to the socket

    • readonly remoteFamily: 'IPv4' | 'IPv6'
    • readonly remotePort: number

    • Disables TLS renegotiation for this Socket instance. Once called, attempts to renegotiate will trigger an error handler on the Socket.

      There is no support for renegotiation as a server. (Attempts by clients will result in a fatal alert so that ClientHello messages cannot be used to flood a server and escape higher-level limits.)

    • data?: string | BufferSource,
      byteOffset?: number,
      byteLength?: number
      ): number;

      Like Socket.write except it includes a TCP FIN packet

      Use it to send your last message and close the connection.

      end(): void;

      Close the socket immediately

    • length: number,
      label: string,
      context: Buffer
      ): Buffer;

      Keying material is used for validations to prevent different kind of attacks in network protocols, for example in the specifications of IEEE 802.1X.

      Example

      const keyingMaterial = socket.exportKeyingMaterial(
  128,
  'client finished');

/*
 Example return value of keyingMaterial:
 <Buffer 76 26 af 99 c5 56 8e 42 09 91 ef 9f 93 cb ad 6c 7b 65 f8 53 f1 d8 d9
    12 5a 33 b8 b5 25 df 7b 37 9f e0 e2 4f b8 67 83 a3 2f cd 5d 41 42 4c 91
    74 ef 2c ... 78 more bytes>
      @param length

      number of bytes to retrieve from keying material

      @param label
      @param context

      Optionally provide a context.

      @returns

      requested bytes of the keying material

    • flush(): void;

      Flush any buffered data to the socket

    • Returns the reason why the peer's certificate was not been verified. This property is set only when socket.authorized === false.

    • getCertificate(): null | object | PeerCertificate;

      Returns an object representing the local certificate. The returned object has some properties corresponding to the fields of the certificate.

      If there is no local certificate, an empty object will be returned. If the socket has been destroyed, null will be returned.

    • Returns an object containing information on the negotiated cipher suite.

      For example, a TLSv1.2 protocol with AES256-SHA cipher:

      {
    "name": "AES256-SHA",
    "standardName": "TLS_RSA_WITH_AES_256_CBC_SHA",
    "version": "SSLv3"
}

    • Returns an object representing the type, name, and size of parameter of an ephemeral key exchange in perfect forward secrecy on a client connection. It returns an empty object when the key exchange is not ephemeral. As this is only supported on a client socket; null is returned if called on a server socket. The supported types are 'DH' and 'ECDH'. Thename property is available only when type is 'ECDH'.

      For example: { type: 'ECDH', name: 'prime256v1', size: 256 }.

    • Returns an object representing the peer's certificate. If the peer does not provide a certificate, an empty object will be returned. If the socket has been destroyed, null will be returned.

      If the full certificate chain was requested, each certificate will include anissuerCertificate property containing an object representing its issuer's certificate.

      @returns

      A certificate object.

    • getSharedSigalgs(): string[];
      @returns

      List of signature algorithms shared between the server and the client in the order of decreasing preference.

    • getTLSFinishedMessage(): undefined | Buffer<ArrayBufferLike>;

      As the Finished messages are message digests of the complete handshake (with a total of 192 bits for TLS 1.0 and more for SSL 3.0), they can be used for external authentication procedures when the authentication provided by SSL/TLS is not desired or is not enough.

      @returns

      The latest Finished message that has been sent to the socket as part of a SSL/TLS handshake, or undefined if no Finished message has been sent yet.

    • getTLSPeerFinishedMessage(): undefined | Buffer<ArrayBufferLike>;

      As the Finished messages are message digests of the complete handshake (with a total of 192 bits for TLS 1.0 and more for SSL 3.0), they can be used for external authentication procedures when the authentication provided by SSL/TLS is not desired or is not enough.

      @returns

      The latest Finished message that is expected or has actually been received from the socket as part of a SSL/TLS handshake, or undefined if there is no Finished message so far.

    • getTLSTicket(): undefined | Buffer<ArrayBufferLike>;

      For a client, returns the TLS session ticket if one is available, orundefined. For a server, always returns undefined.

      It may be useful for debugging.

      See Session Resumption for more information.

    • getTLSVersion(): string;

      Returns a string containing the negotiated SSL/TLS protocol version of the current connection. The value 'unknown' will be returned for connected sockets that have not completed the handshaking process. The value null will be returned for server sockets or disconnected client sockets.

      Protocol versions are:

      • 'SSLv3'
      • 'TLSv1'
      • 'TLSv1.1'
      • 'TLSv1.2'
      • 'TLSv1.3'
    • isSessionReused(): boolean;

      See Session Resumption for more information.

      @returns

      true if the session was reused, false otherwise.

    • ref(): void;

      Keep Bun's process alive at least until this socket is closed

      After the socket has closed, the socket is unref'd, the process may exit, and this becomes a no-op

    • handler: SocketHandler
      ): void;

      Reset the socket's callbacks. This is useful with bun --hot to facilitate hot reloading.

      This will apply to all sockets from the same Listener. it is per socket only for Bun.connect.

    • enable?: boolean,
      initialDelay?: number
      ): boolean;

      Enable/disable keep-alive functionality, and optionally set the initial delay before the first keepalive probe is sent on an idle socket. Set initialDelay (in milliseconds) to set the delay between the last data packet received and the first keepalive probe. Only available for already connected sockets, will return false otherwise.

      Enabling the keep-alive functionality will set the following socket options: SO_KEEPALIVE=1 TCP_KEEPIDLE=initialDelay TCP_KEEPCNT=10 TCP_KEEPINTVL=1

      @param enable

      Default: false

      @param initialDelay

      Default: 0

      @returns

      true if is able to setNoDelay and false if it fails.

    • size?: number
      ): boolean;

      The socket.setMaxSendFragment() method sets the maximum TLS fragment size. Returns true if setting the limit succeeded; false otherwise.

      Smaller fragment sizes decrease the buffering latency on the client: larger fragments are buffered by the TLS layer until the entire fragment is received and its integrity is verified; large fragments can span multiple roundtrips and their processing can be delayed due to packet loss or reordering. However, smaller fragments add extra TLS framing bytes and CPU overhead, which may decrease overall server throughput.

      @param size

      The maximum TLS fragment size. The maximum value is 16384.

    • noDelay?: boolean
      ): boolean;

      Enable/disable the use of Nagle's algorithm. Only available for already connected sockets, will return false otherwise

      @param noDelay

      Default: true

      @returns

      true if is able to setNoDelay and false if it fails.

    • halfClose?: boolean
      ): void;

      Shutdown writes to a socket

      This makes the socket a half-closed socket. It can still receive data.

      This calls shutdown(2) internally

    • terminate(): void;

      Forcefully close the socket. The other end may not receive all data, and the socket will be closed immediately.

      This passes SO_LINGER with l_onoff set to 1 and l_linger set to 0 and then calls close(2).

    • seconds: number
      ): void;

      Set a timeout until the socket automatically closes.

      To reset the timeout, call this function again.

      When a timeout happens, the timeout callback is called and the socket is closed.

    • unref(): void;

      Allow Bun's process to exit even if this socket is still open

      After the socket has closed, this function does nothing.

    • data: string | BufferSource,
      byteOffset?: number,
      byteLength?: number
      ): number;

      Write data to the socket

      @param data

      The data to write to the socket

      @param byteOffset

      The offset in the buffer to start writing from (defaults to 0)

      @param byteLength

      The number of bytes to write (defaults to the length of the buffer)

      When passed a string, byteOffset and byteLength refer to the UTF-8 offset, not the string character offset.

      This is unbuffered as of Bun v0.2.2. That means individual write() calls will be slow. In the future, Bun will buffer writes and flush them at the end of the tick, when the event loop is idle, or sooner if the buffer is full.

  • interface SocketAddress

    • address: string

      The IP address of the client.

    • family: 'IPv4' | 'IPv6'

      The IP family ("IPv4" or "IPv6").

    • port: number

      The port of the client.

  • interface SocketHandler<Data = unknown, DataBinaryType extends BinaryType = 'buffer'>

    • binaryType?: unknown

      Choose what ArrayBufferView is returned in the SocketHandler.data callback.

    • socket: Socket<Data>,
      error?: Error
      ): void | Promise<void>;
    • socket: Socket<Data>,
      error: Error
      ): void | Promise<void>;

      When the socket fails to be created, this function is called.

      The promise returned by Bun.connect rejects after this function is called.

      When connectError is specified, the rejected promise will not be added to the promise rejection queue (so it won't be reported as an unhandled promise rejection, since connectError handles it).

      When connectError is not specified, the rejected promise will be added to the promise rejection queue.

    • socket: Socket<Data>,
      data: BinaryTypeList[DataBinaryType]
      ): void | Promise<void>;
    • socket: Socket<Data>
      ): void | Promise<void>;
    • socket: Socket<Data>
      ): void | Promise<void>;

      When the socket has been shutdown from the other end, this function is called. This is a TCP FIN packet.

    • socket: Socket<Data>,
      error: Error
      ): void | Promise<void>;
    • socket: Socket<Data>,
      success: boolean,
      authorizationError: null | Error
      ): void;

      When handshake is completed, this functions is called.

      @param success

      Indicates if the server authorized despite the authorizationError.

      @param authorizationError

      Certificate Authorization Error or null.

    • socket: Socket<Data>
      ): void | Promise<void>;

      Is called when the socket connects, or in case of TLS if no handshake is provided this will be called only after handshake

    • socket: Socket<Data>
      ): void | Promise<void>;

      Called when a message times out.

  • interface SocketListener<Data = undefined>

  • interface SocketOptions<Data = unknown>

  • interface SQL

    Main SQL client interface providing connection and transaction management

    • constructor SQL(
      connectionString: string | URL
      ): SQL;

      Creates a new SQL client instance

      const sql = new SQL("postgres://localhost:5432/mydb");
const sql = new SQL(new URL("postgres://localhost:5432/mydb"));
      constructor SQL(
      connectionString: string | URL,
      options: SQLOptions
      ): SQL;

      Creates a new SQL client instance with options

      const sql = new SQL("postgres://localhost:5432/mydb", { idleTimeout: 1000 });
      constructor SQL(
      options?: SQLOptions
      ): SQL;

      Creates a new SQL client instance with options

      const sql = new SQL({ url: "postgres://localhost:5432/mydb", idleTimeout: 1000 });
    • options: SQLOptions

      Current client options

    • [Symbol.asyncDispose](): Promise<any>;
    • fn: SQLTransactionContextCallback
      ): Promise<any>;

      Begins a new transaction Will reserve a connection for the transaction and supply a scoped sql instance for all transaction uses in the callback function. sql.begin will resolve with the returned value from the callback function. BEGIN is automatically sent with the optional options, and if anything fails ROLLBACK will be called so the connection can be released and execution can continue.

      const [user, account] = await sql.begin(async sql => {
  const [user] = await sql`
    insert into users (
      name
    ) values (
      'Murray'
    )
    returning *
  `
  const [account] = await sql`
    insert into accounts (
      user_id
    ) values (
      ${ user.user_id }
    )
    returning *
  `
  return [user, account]
})
      options: string,
      fn: SQLTransactionContextCallback
      ): Promise<any>;

      Begins a new transaction with options Will reserve a connection for the transaction and supply a scoped sql instance for all transaction uses in the callback function. sql.begin will resolve with the returned value from the callback function. BEGIN is automatically sent with the optional options, and if anything fails ROLLBACK will be called so the connection can be released and execution can continue.

      const [user, account] = await sql.begin("read write", async sql => {
  const [user] = await sql`
    insert into users (
      name
    ) values (
      'Murray'
    )
    returning *
  `
  const [account] = await sql`
    insert into accounts (
      user_id
    ) values (
      ${ user.user_id }
    )
    returning *
  `
  return [user, account]
})
    • name: string,
      fn: SQLTransactionContextCallback
      ): Promise<any>;

      Begins a distributed transaction Also know as Two-Phase Commit, in a distributed transaction, Phase 1 involves the coordinator preparing nodes by ensuring data is written and ready to commit, while Phase 2 finalizes with nodes committing or rolling back based on the coordinator's decision, ensuring durability and releasing locks. In PostgreSQL and MySQL distributed transactions persist beyond the original session, allowing privileged users or coordinators to commit/rollback them, ensuring support for distributed transactions, recovery, and administrative tasks. beginDistributed will automatic rollback if any exception are not caught, and you can commit and rollback later if everything goes well. PostgreSQL natively supports distributed transactions using PREPARE TRANSACTION, while MySQL uses XA Transactions, and MSSQL also supports distributed/XA transactions. However, in MSSQL, distributed transactions are tied to the original session, the DTC coordinator, and the specific connection. These transactions are automatically committed or rolled back following the same rules as regular transactions, with no option for manual intervention from other sessions, in MSSQL distributed transactions are used to coordinate transactions using Linked Servers.

      await sql.beginDistributed("numbers", async sql => {
  await sql`create table if not exists numbers (a int)`;
  await sql`insert into numbers values(1)`;
});
// later you can call
await sql.commitDistributed("numbers");
// or await sql.rollbackDistributed("numbers");
    • options?: { timeout: number }
      ): Promise<void>;

      Closes the database connection with optional timeout in seconds. If timeout is 0, it will close immediately, if is not provided it will wait for all queries to finish before closing.

      await sql.close({ timeout: 1 });
    • name: string
      ): Promise<void>;

      Commits a distributed transaction also know as prepared transaction in postgres or XA transaction in MySQL

      await sql.commitDistributed("my_distributed_transaction");
    • connect(): Promise<SQL>;

      Waits for the database connection to be established

      await sql.connect();
    • name: string,
      fn: SQLTransactionContextCallback
      ): Promise<any>;

      Alternative method to begin a distributed transaction

    • options?: { timeout: number }
      ): Promise<void>;

      Closes the database connection with optional timeout in seconds. If timeout is 0, it will close immediately, if is not provided it will wait for all queries to finish before closing.

      await sql.end({ timeout: 1 });
    • filename: string,
      values?: any[]

      Reads a file and uses the contents as a query. Optional parameters can be used if the file includes $1, $2, etc

      const result = await sql.file("query.sql", [1, 2, 3]);
    • flush(): void;

      Flushes any pending operations

    • reserve(): Promise<ReservedSQL>;

      The reserve method pulls out 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. Calling reserve in a reserved Sql will return a new reserved connection, not the same connection (behavior matches postgres package).

      const reserved = await sql.reserve();
await reserved`select * from users`;
await reserved.release();
// with in a production scenario would be something more like
const reserved = await sql.reserve();
try {
  // ... queries
} finally {
  await reserved.release();
}
//To make it simpler bun supportsSymbol.dispose and Symbol.asyncDispose
{
// always release after context (safer)
using reserved = await sql.reserve()
await reserved`select * from users`
}
    • name: string
      ): Promise<void>;

      Rolls back a distributed transaction also know as prepared transaction in postgres or XA transaction in MySQL

      await sql.rollbackDistributed("my_distributed_transaction");
    • fn: SQLTransactionContextCallback
      ): Promise<any>;

      Alternative method to begin a transaction Will reserve a connection for the transaction and supply a scoped sql instance for all transaction uses in the callback function. sql.transaction will resolve with the returned value from the callback function. BEGIN is automatically sent with the optional options, and if anything fails ROLLBACK will be called so the connection can be released and execution can continue.

      const [user, account] = await sql.transaction(async sql => {
  const [user] = await sql`
    insert into users (
      name
    ) values (
      'Murray'
    )
    returning *
  `
  const [account] = await sql`
    insert into accounts (
      user_id
    ) values (
      ${ user.user_id }
    )
    returning *
  `
  return [user, account]
})
      options: string,
      fn: SQLTransactionContextCallback
      ): Promise<any>;

      Alternative method to begin a transaction with options Will reserve a connection for the transaction and supply a scoped sql instance for all transaction uses in the callback function. sql.transaction will resolve with the returned value from the callback function. BEGIN is automatically sent with the optional options, and if anything fails ROLLBACK will be called so the connection can be released and execution can continue.

      const [user, account] = await sql.transaction("read write", async sql => {
  const [user] = await sql`
    insert into users (
      name
    ) values (
      'Murray'
    )
    returning *
  `
  const [account] = await sql`
    insert into accounts (
      user_id
    ) values (
      ${ user.user_id }
    )
    returning *
  `
  return [user, account]
})
    • string: string,
      values?: any[]

      If you know what you're doing, you can use unsafe to pass any string you'd like. Please note that this can lead to SQL injection if you're not careful. You can also nest sql.unsafe within a safe sql expression. This is useful if only part of your fraction has unsafe elements.

      const result = await sql.unsafe(`select ${danger} from users where id = ${dragons}`)

  • interface SQLQuery

    Represents a SQL query that can be executed, with additional control methods Extends Promise to allow for async/await usage

    • readonly [Symbol.toStringTag]: string
    • active: boolean

      Indicates if the query is currently executing

    • cancelled: boolean

      Indicates if the query has been cancelled

    • Cancels the executing query

    • catch<TResult = never>(
      onrejected?: null | (reason: any) => TResult | PromiseLike<TResult>
      ): Promise<any>;

      Attaches a callback for only the rejection of the Promise.

      @param onrejected

      The callback to execute when the Promise is rejected.

      @returns

      A Promise for the completion of the callback.

    • Executes the query

    • onfinally?: null | () => void
      ): Promise<any>;

      Attaches a callback that is invoked when the Promise is settled (fulfilled or rejected). The resolved value cannot be modified from the callback.

      @param onfinally

      The callback to execute when the Promise is settled (fulfilled or rejected).

      @returns

      A Promise for the completion of the callback.

    • Returns the raw query result

    • Execute as a simple query, no parameters are allowed but can execute multiple commands separated by semicolons

    • then<TResult1 = any, TResult2 = never>(
      onfulfilled?: null | (value: any) => TResult1 | PromiseLike<TResult1>,
      onrejected?: null | (reason: any) => TResult2 | PromiseLike<TResult2>
      ): Promise<TResult1 | TResult2>;

      Attaches callbacks for the resolution and/or rejection of the Promise.

      @param onfulfilled

      The callback to execute when the Promise is resolved.

      @param onrejected

      The callback to execute when the Promise is rejected.

      @returns

      A Promise for the completion of which ever callback is executed.

    • Returns only the values from the query result

  • interface StringWidthOptions

    • ambiguousIsNarrow?: boolean

      When it's ambiugous and true, count emoji as 1 characters wide. If false, emoji are counted as 2 character wide.

    • countAnsiEscapeCodes?: boolean

      If true, count ANSI escape codes as part of the string width. If false, ANSI escape codes are ignored when calculating the string width.

  • interface Subprocess<In extends SpawnOptions.Writable = SpawnOptions.Writable, Out extends SpawnOptions.Readable = SpawnOptions.Readable, Err extends SpawnOptions.Readable = SpawnOptions.Readable>

    A process created by Bun.spawn.

    This type accepts 3 optional type parameters which correspond to the stdio array from the options object. Instead of specifying these, you should use one of the following utility types instead:

    • ReadableSubprocess (any, pipe, pipe)
    • WritableSubprocess (pipe, any, any)
    • PipedSubprocess (pipe, pipe, pipe)
    • NullSubprocess (ignore, ignore, ignore)
    • readonly exitCode: null | number

      Synchronously get the exit code of the process

      If the process hasn't exited yet, this will return null

    • readonly exited: Promise<number>

      The exit code of the process

      The promise will resolve when the process exits

    • readonly killed: boolean

      Has the process exited?

    • readonly pid: number

      The process ID of the child process

      const { pid } = Bun.spawn({ cmd: ["echo", "hello"] });
console.log(pid); // 1234
    • readonly readable: ReadableToIO<Out>

      This returns the same value as Subprocess.stdout

      It exists for compatibility with ReadableStream.pipeThrough

    • readonly signalCode: null | Signals

      Synchronously get the signal code of the process

      If the process never sent a signal code, this will return null

      To receive signal code changes, use the onExit callback.

      If the signal code is unknown, it will return the original signal code number, but that case should essentially never happen.

    • readonly stderr: ReadableToIO<Err>
    • readonly stdin: WritableToIO<In>
    • readonly stdio: [null, null, null, ...number[]]

      Access extra file descriptors passed to the stdio option in the options object.

    • readonly stdout: ReadableToIO<Out>
    • [Symbol.asyncDispose](): PromiseLike<void>;
    • disconnect(): void;

      Disconnect the IPC channel to the subprocess. This is only supported if the subprocess was created with the ipc option.

    • exitCode?: number | Signals
      ): void;

      Kill the process

      @param exitCode

      The exitCode to send to the process

    • ref(): void;

      This method will tell Bun to wait for this process to exit after you already called unref().

      Before shutting down, Bun will wait for all subprocesses to exit by default

    • Get the resource usage information of the process (max RSS, CPU time, etc)

      Only available after the process has exited

      If the process hasn't exited yet, this will return undefined

    • message: any
      ): void;

      Send a message to the subprocess. This is only supported if the subprocess was created with the ipc option, and is another instance of bun.

      Messages are serialized using the JSC serialize API, which allows for the same types that postMessage/structuredClone supports.

    • unref(): void;

      Before shutting down, Bun will wait for all subprocesses to exit by default

      This method will tell Bun to not wait for this process to exit before shutting down.

  • interface SyncSubprocess<Out extends SpawnOptions.Readable = SpawnOptions.Readable, Err extends SpawnOptions.Readable = SpawnOptions.Readable>

    A process created by Bun.spawnSync.

    This type accepts 2 optional type parameters which correspond to the stdout and stderr options. Instead of specifying these, you should use one of the following utility types instead:

    • ReadableSyncSubprocess (pipe, pipe)
    • NullSyncSubprocess (ignore, ignore)

  • interface SystemError

  • interface TCPSocket

    • readonly alpnProtocol: null | string | false

      String containing the selected ALPN protocol. Before a handshake has completed, this value is always null. When a handshake is completed but not ALPN protocol was selected, socket.alpnProtocol equals false.

    • readonly authorized: boolean

      This property is true if the peer certificate was signed by one of the CAs specified when creating the Socket instance, otherwise false.

    • readonly bytesWritten: number

      The number of bytes written to the socket.

    • data: undefined

      The data context for the socket.

    • readonly listener?: SocketListener<undefined>

      Get the server that created this socket

      This will return undefined if the socket was created by Bun.connect or if the listener has already closed.

    • readonly localAddress: string
    • readonly localFamily: 'IPv4' | 'IPv6'
    • readonly localPort: number

      local port connected to the socket

    • readonly readyState: -2 | -1 | 0 | 1 | 2

      The ready state of the socket.

      You can assume that a positive value means the socket is open and usable

      • -2 = Shutdown
      • -1 = Detached
      • 0 = Closed
      • 1 = Established
      • 2 = Else
    • readonly remoteAddress: string

      Remote IP address connected to the socket

    • readonly remoteFamily: 'IPv4' | 'IPv6'
    • readonly remotePort: number

    • Disables TLS renegotiation for this Socket instance. Once called, attempts to renegotiate will trigger an error handler on the Socket.

      There is no support for renegotiation as a server. (Attempts by clients will result in a fatal alert so that ClientHello messages cannot be used to flood a server and escape higher-level limits.)

    • data?: string | BufferSource,
      byteOffset?: number,
      byteLength?: number
      ): number;

      Like Socket.write except it includes a TCP FIN packet

      Use it to send your last message and close the connection.

      end(): void;

      Close the socket immediately

    • length: number,
      label: string,
      context: Buffer
      ): Buffer;

      Keying material is used for validations to prevent different kind of attacks in network protocols, for example in the specifications of IEEE 802.1X.

      Example

      const keyingMaterial = socket.exportKeyingMaterial(
  128,
  'client finished');

/*
 Example return value of keyingMaterial:
 <Buffer 76 26 af 99 c5 56 8e 42 09 91 ef 9f 93 cb ad 6c 7b 65 f8 53 f1 d8 d9
    12 5a 33 b8 b5 25 df 7b 37 9f e0 e2 4f b8 67 83 a3 2f cd 5d 41 42 4c 91
    74 ef 2c ... 78 more bytes>
      @param length

      number of bytes to retrieve from keying material

      @param label
      @param context

      Optionally provide a context.

      @returns

      requested bytes of the keying material

    • flush(): void;

      Flush any buffered data to the socket

    • Returns the reason why the peer's certificate was not been verified. This property is set only when socket.authorized === false.

    • getCertificate(): null | object | PeerCertificate;

      Returns an object representing the local certificate. The returned object has some properties corresponding to the fields of the certificate.

      If there is no local certificate, an empty object will be returned. If the socket has been destroyed, null will be returned.

    • Returns an object containing information on the negotiated cipher suite.

      For example, a TLSv1.2 protocol with AES256-SHA cipher:

      {
    "name": "AES256-SHA",
    "standardName": "TLS_RSA_WITH_AES_256_CBC_SHA",
    "version": "SSLv3"
}

    • Returns an object representing the type, name, and size of parameter of an ephemeral key exchange in perfect forward secrecy on a client connection. It returns an empty object when the key exchange is not ephemeral. As this is only supported on a client socket; null is returned if called on a server socket. The supported types are 'DH' and 'ECDH'. Thename property is available only when type is 'ECDH'.

      For example: { type: 'ECDH', name: 'prime256v1', size: 256 }.

    • Returns an object representing the peer's certificate. If the peer does not provide a certificate, an empty object will be returned. If the socket has been destroyed, null will be returned.

      If the full certificate chain was requested, each certificate will include anissuerCertificate property containing an object representing its issuer's certificate.

      @returns

      A certificate object.

    • getSharedSigalgs(): string[];
      @returns

      List of signature algorithms shared between the server and the client in the order of decreasing preference.

    • getTLSFinishedMessage(): undefined | Buffer<ArrayBufferLike>;

      As the Finished messages are message digests of the complete handshake (with a total of 192 bits for TLS 1.0 and more for SSL 3.0), they can be used for external authentication procedures when the authentication provided by SSL/TLS is not desired or is not enough.

      @returns

      The latest Finished message that has been sent to the socket as part of a SSL/TLS handshake, or undefined if no Finished message has been sent yet.

    • getTLSPeerFinishedMessage(): undefined | Buffer<ArrayBufferLike>;

      As the Finished messages are message digests of the complete handshake (with a total of 192 bits for TLS 1.0 and more for SSL 3.0), they can be used for external authentication procedures when the authentication provided by SSL/TLS is not desired or is not enough.

      @returns

      The latest Finished message that is expected or has actually been received from the socket as part of a SSL/TLS handshake, or undefined if there is no Finished message so far.

    • getTLSTicket(): undefined | Buffer<ArrayBufferLike>;

      For a client, returns the TLS session ticket if one is available, orundefined. For a server, always returns undefined.

      It may be useful for debugging.

      See Session Resumption for more information.

    • getTLSVersion(): string;

      Returns a string containing the negotiated SSL/TLS protocol version of the current connection. The value 'unknown' will be returned for connected sockets that have not completed the handshaking process. The value null will be returned for server sockets or disconnected client sockets.

      Protocol versions are:

      • 'SSLv3'
      • 'TLSv1'
      • 'TLSv1.1'
      • 'TLSv1.2'
      • 'TLSv1.3'
    • isSessionReused(): boolean;

      See Session Resumption for more information.

      @returns

      true if the session was reused, false otherwise.

    • ref(): void;

      Keep Bun's process alive at least until this socket is closed

      After the socket has closed, the socket is unref'd, the process may exit, and this becomes a no-op

    • handler: SocketHandler
      ): void;

      Reset the socket's callbacks. This is useful with bun --hot to facilitate hot reloading.

      This will apply to all sockets from the same Listener. it is per socket only for Bun.connect.

    • enable?: boolean,
      initialDelay?: number
      ): boolean;

      Enable/disable keep-alive functionality, and optionally set the initial delay before the first keepalive probe is sent on an idle socket. Set initialDelay (in milliseconds) to set the delay between the last data packet received and the first keepalive probe. Only available for already connected sockets, will return false otherwise.

      Enabling the keep-alive functionality will set the following socket options: SO_KEEPALIVE=1 TCP_KEEPIDLE=initialDelay TCP_KEEPCNT=10 TCP_KEEPINTVL=1

      @param enable

      Default: false

      @param initialDelay

      Default: 0

      @returns

      true if is able to setNoDelay and false if it fails.

    • size?: number
      ): boolean;

      The socket.setMaxSendFragment() method sets the maximum TLS fragment size. Returns true if setting the limit succeeded; false otherwise.

      Smaller fragment sizes decrease the buffering latency on the client: larger fragments are buffered by the TLS layer until the entire fragment is received and its integrity is verified; large fragments can span multiple roundtrips and their processing can be delayed due to packet loss or reordering. However, smaller fragments add extra TLS framing bytes and CPU overhead, which may decrease overall server throughput.

      @param size

      The maximum TLS fragment size. The maximum value is 16384.

    • noDelay?: boolean
      ): boolean;

      Enable/disable the use of Nagle's algorithm. Only available for already connected sockets, will return false otherwise

      @param noDelay

      Default: true

      @returns

      true if is able to setNoDelay and false if it fails.

    • halfClose?: boolean
      ): void;

      Shutdown writes to a socket

      This makes the socket a half-closed socket. It can still receive data.

      This calls shutdown(2) internally

    • terminate(): void;

      Forcefully close the socket. The other end may not receive all data, and the socket will be closed immediately.

      This passes SO_LINGER with l_onoff set to 1 and l_linger set to 0 and then calls close(2).

    • seconds: number
      ): void;

      Set a timeout until the socket automatically closes.

      To reset the timeout, call this function again.

      When a timeout happens, the timeout callback is called and the socket is closed.

    • unref(): void;

      Allow Bun's process to exit even if this socket is still open

      After the socket has closed, this function does nothing.

    • data: string | BufferSource,
      byteOffset?: number,
      byteLength?: number
      ): number;

      Write data to the socket

      @param data

      The data to write to the socket

      @param byteOffset

      The offset in the buffer to start writing from (defaults to 0)

      @param byteLength

      The number of bytes to write (defaults to the length of the buffer)

      When passed a string, byteOffset and byteLength refer to the UTF-8 offset, not the string character offset.

      This is unbuffered as of Bun v0.2.2. That means individual write() calls will be slow. In the future, Bun will buffer writes and flush them at the end of the tick, when the event loop is idle, or sooner if the buffer is full.

  • interface TCPSocketConnectOptions<Data = undefined>

    • allowHalfOpen?: boolean

      Whether to allow half-open connections.

      A half-open connection occurs when one end of the connection has called close() or sent a FIN packet, while the other end remains open. When set to true:

      • The socket won't automatically send FIN when the remote side closes its end
      • The local side can continue sending data even after the remote side has closed
      • The application must explicitly call end() to fully close the connection

      When false (default), the socket automatically closes both ends of the connection when either side closes.

    • data?: Data

      The per-instance data context

    • exclusive?: boolean

      Whether to use exclusive mode.

      When set to true, the socket binds exclusively to the specified address:port combination, preventing other processes from binding to the same port.

      When false (default), other sockets may be able to bind to the same port depending on the operating system's socket sharing capabilities and settings.

      Exclusive mode is useful in scenarios where you want to ensure only one instance of your server can bind to a specific port at a time.

    • hostname: string

      The hostname to connect to

    • port: number

      The port to connect to

    • socket: SocketHandler<Data>

      Handlers for socket events

    • tls?: boolean

      TLS Configuration with which to create the socket

  • interface TCPSocketListener<Data = unknown>

  • interface TCPSocketListenOptions<Data = undefined>

    • allowHalfOpen?: boolean

      Whether to allow half-open connections.

      A half-open connection occurs when one end of the connection has called close() or sent a FIN packet, while the other end remains open. When set to true:

      • The socket won't automatically send FIN when the remote side closes its end
      • The local side can continue sending data even after the remote side has closed
      • The application must explicitly call end() to fully close the connection

      When false (default), the socket automatically closes both ends of the connection when either side closes.

    • data?: Data

      The per-instance data context

    • exclusive?: boolean

      Whether to use exclusive mode.

      When set to true, the socket binds exclusively to the specified address:port combination, preventing other processes from binding to the same port.

      When false (default), other sockets may be able to bind to the same port depending on the operating system's socket sharing capabilities and settings.

      Exclusive mode is useful in scenarios where you want to ensure only one instance of your server can bind to a specific port at a time.

    • hostname: string

      The hostname to listen on

    • port: number

      The port to listen on

    • socket: SocketHandler<Data>

      Handlers for socket events

    • tls?: TLSOptions

      The TLS configuration object with which to create the server

  • interface TLSOptions

    Options for TLS connections

    • ca?: string | Buffer<ArrayBufferLike> | BunFile | string | Buffer<ArrayBufferLike> | BunFile[]

      Optionally override the trusted CA certificates. Default is to trust the well-known CAs curated by Mozilla. Mozilla's CAs are completely replaced when CAs are explicitly specified using this option.

    • cert?: string | Buffer<ArrayBufferLike> | BunFile | string | Buffer<ArrayBufferLike> | BunFile[]

      Cert chains in PEM format. One cert chain should be provided per private key. Each cert chain should consist of the PEM formatted certificate for a provided private key, followed by the PEM formatted intermediate certificates (if any), in order, and not including the root CA (the root CA must be pre-known to the peer, see ca). When providing multiple cert chains, they do not have to be in the same order as their private keys in key. If the intermediate certificates are not provided, the peer will not be able to validate the certificate, and the handshake will fail.

    • dhParamsFile?: string

      File path to a .pem file custom Diffie Helman parameters

    • key?: string | Buffer<ArrayBufferLike> | BunFile | string | Buffer<ArrayBufferLike> | BunFile[]

      Private keys in PEM format. PEM allows the option of private keys being encrypted. Encrypted keys will be decrypted with options.passphrase. Multiple keys using different algorithms can be provided either as an array of unencrypted key strings or buffers, or an array of objects in the form {pem: <string|buffer>[, passphrase: <string>]}. The object form can only occur in an array. object.passphrase is optional. Encrypted keys will be decrypted with object.passphrase if provided, or options.passphrase if it is not.

    • lowMemoryMode?: boolean

      This sets OPENSSL_RELEASE_BUFFERS to 1. It reduces overall performance but saves some memory.

    • passphrase?: string

      Passphrase for the TLS key

    • rejectUnauthorized?: boolean

      If set to false, any certificate is accepted. Default is $NODE_TLS_REJECT_UNAUTHORIZED environment variable, or true if it is not set.

    • requestCert?: boolean

      If set to true, the server will request a client certificate.

      Default is false.

    • secureOptions?: number

      Optionally affect the OpenSSL protocol behavior, which is not usually necessary. This should be used carefully if at all! Value is a numeric bitmask of the SSL_OP_* options from OpenSSL Options

    • serverName?: string

      Explicitly set a server name

  • interface TLSSocket

    • readonly alpnProtocol: null | string | false

      String containing the selected ALPN protocol. Before a handshake has completed, this value is always null. When a handshake is completed but not ALPN protocol was selected, socket.alpnProtocol equals false.

    • readonly authorized: boolean

      This property is true if the peer certificate was signed by one of the CAs specified when creating the Socket instance, otherwise false.

    • readonly bytesWritten: number

      The number of bytes written to the socket.

    • data: undefined

      The data context for the socket.

    • readonly listener?: SocketListener<undefined>

      Get the server that created this socket

      This will return undefined if the socket was created by Bun.connect or if the listener has already closed.

    • readonly localAddress: string
    • readonly localFamily: 'IPv4' | 'IPv6'
    • readonly localPort: number

      local port connected to the socket

    • readonly readyState: -2 | -1 | 0 | 1 | 2

      The ready state of the socket.

      You can assume that a positive value means the socket is open and usable

      • -2 = Shutdown
      • -1 = Detached
      • 0 = Closed
      • 1 = Established
      • 2 = Else
    • readonly remoteAddress: string

      Remote IP address connected to the socket

    • readonly remoteFamily: 'IPv4' | 'IPv6'
    • readonly remotePort: number

    • Disables TLS renegotiation for this Socket instance. Once called, attempts to renegotiate will trigger an error handler on the Socket.

      There is no support for renegotiation as a server. (Attempts by clients will result in a fatal alert so that ClientHello messages cannot be used to flood a server and escape higher-level limits.)

    • data?: string | BufferSource,
      byteOffset?: number,
      byteLength?: number
      ): number;

      Like Socket.write except it includes a TCP FIN packet

      Use it to send your last message and close the connection.

      end(): void;

      Close the socket immediately

    • length: number,
      label: string,
      context: Buffer
      ): Buffer;

      Keying material is used for validations to prevent different kind of attacks in network protocols, for example in the specifications of IEEE 802.1X.

      Example

      const keyingMaterial = socket.exportKeyingMaterial(
  128,
  'client finished');

/*
 Example return value of keyingMaterial:
 <Buffer 76 26 af 99 c5 56 8e 42 09 91 ef 9f 93 cb ad 6c 7b 65 f8 53 f1 d8 d9
    12 5a 33 b8 b5 25 df 7b 37 9f e0 e2 4f b8 67 83 a3 2f cd 5d 41 42 4c 91
    74 ef 2c ... 78 more bytes>
      @param length

      number of bytes to retrieve from keying material

      @param label
      @param context

      Optionally provide a context.

      @returns

      requested bytes of the keying material

    • flush(): void;

      Flush any buffered data to the socket

    • Returns the reason why the peer's certificate was not been verified. This property is set only when socket.authorized === false.

    • getCertificate(): null | object | PeerCertificate;

      Returns an object representing the local certificate. The returned object has some properties corresponding to the fields of the certificate.

      If there is no local certificate, an empty object will be returned. If the socket has been destroyed, null will be returned.

    • Returns an object containing information on the negotiated cipher suite.

      For example, a TLSv1.2 protocol with AES256-SHA cipher:

      {
    "name": "AES256-SHA",
    "standardName": "TLS_RSA_WITH_AES_256_CBC_SHA",
    "version": "SSLv3"
}

    • Returns an object representing the type, name, and size of parameter of an ephemeral key exchange in perfect forward secrecy on a client connection. It returns an empty object when the key exchange is not ephemeral. As this is only supported on a client socket; null is returned if called on a server socket. The supported types are 'DH' and 'ECDH'. Thename property is available only when type is 'ECDH'.

      For example: { type: 'ECDH', name: 'prime256v1', size: 256 }.

    • Returns an object representing the peer's certificate. If the peer does not provide a certificate, an empty object will be returned. If the socket has been destroyed, null will be returned.

      If the full certificate chain was requested, each certificate will include anissuerCertificate property containing an object representing its issuer's certificate.

      @returns

      A certificate object.

    • getSharedSigalgs(): string[];
      @returns

      List of signature algorithms shared between the server and the client in the order of decreasing preference.

    • getTLSFinishedMessage(): undefined | Buffer<ArrayBufferLike>;

      As the Finished messages are message digests of the complete handshake (with a total of 192 bits for TLS 1.0 and more for SSL 3.0), they can be used for external authentication procedures when the authentication provided by SSL/TLS is not desired or is not enough.

      @returns

      The latest Finished message that has been sent to the socket as part of a SSL/TLS handshake, or undefined if no Finished message has been sent yet.

    • getTLSPeerFinishedMessage(): undefined | Buffer<ArrayBufferLike>;

      As the Finished messages are message digests of the complete handshake (with a total of 192 bits for TLS 1.0 and more for SSL 3.0), they can be used for external authentication procedures when the authentication provided by SSL/TLS is not desired or is not enough.

      @returns

      The latest Finished message that is expected or has actually been received from the socket as part of a SSL/TLS handshake, or undefined if there is no Finished message so far.

    • getTLSTicket(): undefined | Buffer<ArrayBufferLike>;

      For a client, returns the TLS session ticket if one is available, orundefined. For a server, always returns undefined.

      It may be useful for debugging.

      See Session Resumption for more information.

    • getTLSVersion(): string;

      Returns a string containing the negotiated SSL/TLS protocol version of the current connection. The value 'unknown' will be returned for connected sockets that have not completed the handshaking process. The value null will be returned for server sockets or disconnected client sockets.

      Protocol versions are:

      • 'SSLv3'
      • 'TLSv1'
      • 'TLSv1.1'
      • 'TLSv1.2'
      • 'TLSv1.3'
    • isSessionReused(): boolean;

      See Session Resumption for more information.

      @returns

      true if the session was reused, false otherwise.

    • ref(): void;

      Keep Bun's process alive at least until this socket is closed

      After the socket has closed, the socket is unref'd, the process may exit, and this becomes a no-op

    • handler: SocketHandler
      ): void;

      Reset the socket's callbacks. This is useful with bun --hot to facilitate hot reloading.

      This will apply to all sockets from the same Listener. it is per socket only for Bun.connect.

    • enable?: boolean,
      initialDelay?: number
      ): boolean;

      Enable/disable keep-alive functionality, and optionally set the initial delay before the first keepalive probe is sent on an idle socket. Set initialDelay (in milliseconds) to set the delay between the last data packet received and the first keepalive probe. Only available for already connected sockets, will return false otherwise.

      Enabling the keep-alive functionality will set the following socket options: SO_KEEPALIVE=1 TCP_KEEPIDLE=initialDelay TCP_KEEPCNT=10 TCP_KEEPINTVL=1

      @param enable

      Default: false

      @param initialDelay

      Default: 0

      @returns

      true if is able to setNoDelay and false if it fails.

    • size?: number
      ): boolean;

      The socket.setMaxSendFragment() method sets the maximum TLS fragment size. Returns true if setting the limit succeeded; false otherwise.

      Smaller fragment sizes decrease the buffering latency on the client: larger fragments are buffered by the TLS layer until the entire fragment is received and its integrity is verified; large fragments can span multiple roundtrips and their processing can be delayed due to packet loss or reordering. However, smaller fragments add extra TLS framing bytes and CPU overhead, which may decrease overall server throughput.

      @param size

      The maximum TLS fragment size. The maximum value is 16384.

    • noDelay?: boolean
      ): boolean;

      Enable/disable the use of Nagle's algorithm. Only available for already connected sockets, will return false otherwise

      @param noDelay

      Default: true

      @returns

      true if is able to setNoDelay and false if it fails.

    • halfClose?: boolean
      ): void;

      Shutdown writes to a socket

      This makes the socket a half-closed socket. It can still receive data.

      This calls shutdown(2) internally

    • terminate(): void;

      Forcefully close the socket. The other end may not receive all data, and the socket will be closed immediately.

      This passes SO_LINGER with l_onoff set to 1 and l_linger set to 0 and then calls close(2).

    • seconds: number
      ): void;

      Set a timeout until the socket automatically closes.

      To reset the timeout, call this function again.

      When a timeout happens, the timeout callback is called and the socket is closed.

    • unref(): void;

      Allow Bun's process to exit even if this socket is still open

      After the socket has closed, this function does nothing.

    • data: string | BufferSource,
      byteOffset?: number,
      byteLength?: number
      ): number;

      Write data to the socket

      @param data

      The data to write to the socket

      @param byteOffset

      The offset in the buffer to start writing from (defaults to 0)

      @param byteLength

      The number of bytes to write (defaults to the length of the buffer)

      When passed a string, byteOffset and byteLength refer to the UTF-8 offset, not the string character offset.

      This is unbuffered as of Bun v0.2.2. That means individual write() calls will be slow. In the future, Bun will buffer writes and flush them at the end of the tick, when the event loop is idle, or sooner if the buffer is full.

  • interface TransactionSQL

    Represents a client within a transaction context Extends SQL with savepoint functionality

    • constructor TransactionSQL(
      connectionString: string | URL
      ): SQL;

      Creates a new SQL client instance

      const sql = new SQL("postgres://localhost:5432/mydb");
const sql = new SQL(new URL("postgres://localhost:5432/mydb"));
      constructor TransactionSQL(
      connectionString: string | URL,
      options: SQLOptions
      ): SQL;

      Creates a new SQL client instance with options

      const sql = new SQL("postgres://localhost:5432/mydb", { idleTimeout: 1000 });
      constructor TransactionSQL(
      options?: SQLOptions
      ): SQL;

      Creates a new SQL client instance with options

      const sql = new SQL({ url: "postgres://localhost:5432/mydb", idleTimeout: 1000 });
    • options: SQLOptions

      Current client options

    • [Symbol.asyncDispose](): Promise<any>;
    • fn: SQLTransactionContextCallback
      ): Promise<any>;

      Begins a new transaction Will reserve a connection for the transaction and supply a scoped sql instance for all transaction uses in the callback function. sql.begin will resolve with the returned value from the callback function. BEGIN is automatically sent with the optional options, and if anything fails ROLLBACK will be called so the connection can be released and execution can continue.

      const [user, account] = await sql.begin(async sql => {
  const [user] = await sql`
    insert into users (
      name
    ) values (
      'Murray'
    )
    returning *
  `
  const [account] = await sql`
    insert into accounts (
      user_id
    ) values (
      ${ user.user_id }
    )
    returning *
  `
  return [user, account]
})
      options: string,
      fn: SQLTransactionContextCallback
      ): Promise<any>;

      Begins a new transaction with options Will reserve a connection for the transaction and supply a scoped sql instance for all transaction uses in the callback function. sql.begin will resolve with the returned value from the callback function. BEGIN is automatically sent with the optional options, and if anything fails ROLLBACK will be called so the connection can be released and execution can continue.

      const [user, account] = await sql.begin("read write", async sql => {
  const [user] = await sql`
    insert into users (
      name
    ) values (
      'Murray'
    )
    returning *
  `
  const [account] = await sql`
    insert into accounts (
      user_id
    ) values (
      ${ user.user_id }
    )
    returning *
  `
  return [user, account]
})
    • name: string,
      fn: SQLTransactionContextCallback
      ): Promise<any>;

      Begins a distributed transaction Also know as Two-Phase Commit, in a distributed transaction, Phase 1 involves the coordinator preparing nodes by ensuring data is written and ready to commit, while Phase 2 finalizes with nodes committing or rolling back based on the coordinator's decision, ensuring durability and releasing locks. In PostgreSQL and MySQL distributed transactions persist beyond the original session, allowing privileged users or coordinators to commit/rollback them, ensuring support for distributed transactions, recovery, and administrative tasks. beginDistributed will automatic rollback if any exception are not caught, and you can commit and rollback later if everything goes well. PostgreSQL natively supports distributed transactions using PREPARE TRANSACTION, while MySQL uses XA Transactions, and MSSQL also supports distributed/XA transactions. However, in MSSQL, distributed transactions are tied to the original session, the DTC coordinator, and the specific connection. These transactions are automatically committed or rolled back following the same rules as regular transactions, with no option for manual intervention from other sessions, in MSSQL distributed transactions are used to coordinate transactions using Linked Servers.

      await sql.beginDistributed("numbers", async sql => {
  await sql`create table if not exists numbers (a int)`;
  await sql`insert into numbers values(1)`;
});
// later you can call
await sql.commitDistributed("numbers");
// or await sql.rollbackDistributed("numbers");
    • options?: { timeout: number }
      ): Promise<void>;

      Closes the database connection with optional timeout in seconds. If timeout is 0, it will close immediately, if is not provided it will wait for all queries to finish before closing.

      await sql.close({ timeout: 1 });
    • name: string
      ): Promise<void>;

      Commits a distributed transaction also know as prepared transaction in postgres or XA transaction in MySQL

      await sql.commitDistributed("my_distributed_transaction");
    • connect(): Promise<SQL>;

      Waits for the database connection to be established

      await sql.connect();
    • name: string,
      fn: SQLTransactionContextCallback
      ): Promise<any>;

      Alternative method to begin a distributed transaction

    • options?: { timeout: number }
      ): Promise<void>;

      Closes the database connection with optional timeout in seconds. If timeout is 0, it will close immediately, if is not provided it will wait for all queries to finish before closing.

      await sql.end({ timeout: 1 });
    • filename: string,
      values?: any[]

      Reads a file and uses the contents as a query. Optional parameters can be used if the file includes $1, $2, etc

      const result = await sql.file("query.sql", [1, 2, 3]);
    • flush(): void;

      Flushes any pending operations

    • reserve(): Promise<ReservedSQL>;

      The reserve method pulls out 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. Calling reserve in a reserved Sql will return a new reserved connection, not the same connection (behavior matches postgres package).

      const reserved = await sql.reserve();
await reserved`select * from users`;
await reserved.release();
// with in a production scenario would be something more like
const reserved = await sql.reserve();
try {
  // ... queries
} finally {
  await reserved.release();
}
//To make it simpler bun supportsSymbol.dispose and Symbol.asyncDispose
{
// always release after context (safer)
using reserved = await sql.reserve()
await reserved`select * from users`
}
    • name: string
      ): Promise<void>;

      Rolls back a distributed transaction also know as prepared transaction in postgres or XA transaction in MySQL

      await sql.rollbackDistributed("my_distributed_transaction");
    • name: string,
      fn: SQLSavepointContextCallback
      ): Promise<any>;

      Creates a savepoint within the current transaction

    • fn: SQLTransactionContextCallback
      ): Promise<any>;

      Alternative method to begin a transaction Will reserve a connection for the transaction and supply a scoped sql instance for all transaction uses in the callback function. sql.transaction will resolve with the returned value from the callback function. BEGIN is automatically sent with the optional options, and if anything fails ROLLBACK will be called so the connection can be released and execution can continue.

      const [user, account] = await sql.transaction(async sql => {
  const [user] = await sql`
    insert into users (
      name
    ) values (
      'Murray'
    )
    returning *
  `
  const [account] = await sql`
    insert into accounts (
      user_id
    ) values (
      ${ user.user_id }
    )
    returning *
  `
  return [user, account]
})
      options: string,
      fn: SQLTransactionContextCallback
      ): Promise<any>;

      Alternative method to begin a transaction with options Will reserve a connection for the transaction and supply a scoped sql instance for all transaction uses in the callback function. sql.transaction will resolve with the returned value from the callback function. BEGIN is automatically sent with the optional options, and if anything fails ROLLBACK will be called so the connection can be released and execution can continue.

      const [user, account] = await sql.transaction("read write", async sql => {
  const [user] = await sql`
    insert into users (
      name
    ) values (
      'Murray'
    )
    returning *
  `
  const [account] = await sql`
    insert into accounts (
      user_id
    ) values (
      ${ user.user_id }
    )
    returning *
  `
  return [user, account]
})
    • string: string,
      values?: any[]

      If you know what you're doing, you can use unsafe to pass any string you'd like. Please note that this can lead to SQL injection if you're not careful. You can also nest sql.unsafe within a safe sql expression. This is useful if only part of your fraction has unsafe elements.

      const result = await sql.unsafe(`select ${danger} from users where id = ${dragons}`)

  • interface TranspilerOptions

    • allowBunRuntime?: boolean
    • autoImportJSX?: boolean
    • deadCodeElimination?: boolean

      Experimental

      Enabled by default, use this to disable dead code elimination.

      Some other transpiler options may still do some specific dead code elimination.

    • define?: Record<string, string>

      Replace key with value. Value must be a JSON string.

       { "process.env.NODE_ENV": "\"production\"" }
    • exports?: { eliminate: string[]; replace: Record<string, string> }
    • inline?: boolean

      This does two things (and possibly more in the future):

      1. const declarations to primitive types (excluding Object/Array) at the top of a scope before any let or var declarations will be inlined into their usages.
      2. let and const declarations only used once are inlined into their usages.

      JavaScript engines typically do these optimizations internally, however it might only happen much later in the compilation pipeline, after code has been executed many many times.

      This will typically shrink the output size of code, but it might increase it in some cases. Do your own benchmarks!

    • loader?: JavaScriptLoader

      What is the default loader used for this transpiler?

    • logLevel?: 'error' | 'verbose' | 'debug' | 'info' | 'warn'
    • macro?: MacroMap

      Replace an import statement with a macro.

      This will remove the import statement from the final output and replace any function calls or template strings with the result returned by the macro

         {
       "react-relay": {
           "graphql": "bun-macro-relay"
       }
   }

      Code that calls graphql will be replaced with the result of the macro.

      import {graphql} from "react-relay";

// Input:
const query = graphql`
    query {
        ... on User {
            id
        }
    }
}`;

      Will be replaced with:

      import UserQuery from "./UserQuery.graphql";
const query = UserQuery;
    • minifyWhitespace?: boolean

      Experimental

      Minify whitespace and comments from the output.

    • target?: Target
      "browser"
    • treeShaking?: boolean
    • tsconfig?: string | TSConfig

      TSConfig.json file as stringified JSON or an object Use this to set a custom JSX factory, fragment, or import source For example, if you want to use Preact instead of React. Or if you want to use Emotion.

  • interface TSConfig

    tsconfig.json options supported by Bun

    • compilerOptions?: { baseUrl: string; importsNotUsedAsValues: 'error' | 'preserve' | 'remove'; jsx: 'preserve' | 'react' | 'react-jsx' | 'react-jsxdev'; jsxFactory: string; jsxFragmentFactory: string; jsxImportSource: string; moduleSuffixes: any; paths: Record<string, string[]>; useDefineForClassFields: boolean }
    • extends?: string

  • interface UnderlyingSource<R = any>

  • interface UnixServeOptions

    • development?: boolean | { console: boolean; hmr: boolean }

      Render contextual errors? This enables bun's error page

    • error?: (this: Server, error: ErrorLike) => void | Promise<void> | Response | Promise<Response>
    • id?: null | string

      Uniquely identify a server instance with an ID

      When bun is started with the --hot flag:

      This string will be used to hot reload the server without interrupting pending requests or websockets. If not provided, a value will be generated. To disable hot reloading, set this value to null.

      When bun is not started with the --hot flag:

      This string will currently do nothing. But in the future it could be useful for logs or metrics.

    • maxRequestBodySize?: number

      What is the maximum size of a request body? (in bytes)

    • unix: string

      If set, the HTTP server will listen on a unix socket instead of a port. (Cannot be used with hostname+port)

    • this: Server,
      request: Request,
      server: Server
      ): Response | Promise<Response>;

      Handle HTTP requests

      Respond to Request objects with a Response object.

  • interface UnixSocketListener<Data>

  • interface UnixSocketOptions<Data = undefined>

    • data?: Data

      The per-instance data context

    • socket: SocketHandler<Data>

      Handlers for socket events

    • tls?: TLSOptions

      TLS Configuration with which to create the socket

    • unix: string

      The unix socket to listen on or connect to

  • interface UnixWebSocketServeOptions<WebSocketDataType = undefined>

    • development?: boolean | { console: boolean; hmr: boolean }

      Render contextual errors? This enables bun's error page

    • error?: (this: Server, error: ErrorLike) => void | Promise<void> | Response | Promise<Response>
    • id?: null | string

      Uniquely identify a server instance with an ID

      When bun is started with the --hot flag:

      This string will be used to hot reload the server without interrupting pending requests or websockets. If not provided, a value will be generated. To disable hot reloading, set this value to null.

      When bun is not started with the --hot flag:

      This string will currently do nothing. But in the future it could be useful for logs or metrics.

    • maxRequestBodySize?: number

      What is the maximum size of a request body? (in bytes)

    • unix: string

      If set, the HTTP server will listen on a unix socket instead of a port. (Cannot be used with hostname+port)

    • websocket: WebSocketHandler<WebSocketDataType>

      Enable websockets with Bun.serve

      For simpler type safety, see Bun.websocket

      import { serve } from "bun";
serve({
 websocket: {
   open: (ws) => {
     console.log("Client connected");
   },
   message: (ws, message) => {
     console.log("Client sent message", message);
   },
   close: (ws) => {
     console.log("Client disconnected");
   },
 },
 fetch(req, server) {
   const url = new URL(req.url);
   if (url.pathname === "/chat") {
     const upgraded = server.upgrade(req);
     if (!upgraded) {
       return new Response("Upgrade failed", { status: 400 });
     }
   }
   return new Response("Hello World");
 },
});

      Upgrade a Request to a ServerWebSocket via Server.upgrade

      Pass data in @{link Server.upgrade} to attach data to the ServerWebSocket.data property

    • this: Server,
      request: Request,
      server: Server
      ): undefined | Response | Promise<undefined | Response>;

      Handle HTTP requests or upgrade them to a ServerWebSocket

      Respond to Request objects with a Response object.

  • interface WebSocketEventMap

  • interface WebSocketHandler<T = undefined>

    Create a server-side ServerWebSocket handler for use with Bun.serve

    import { websocket, serve } from "bun";

serve<{name: string}>({
  port: 3000,
  websocket: {
    open: (ws) => {
      console.log("Client connected");
   },
    message: (ws, message) => {
      console.log(`${ws.data.name}: ${message}`);
   },
    close: (ws) => {
      console.log("Client disconnected");
   },
 },

  fetch(req, server) {
    const url = new URL(req.url);
    if (url.pathname === "/chat") {
      const upgraded = server.upgrade(req, {
        data: {
          name: new URL(req.url).searchParams.get("name"),
       },
     });
      if (!upgraded) {
        return new Response("Upgrade failed", { status: 400 });
     }
     return;
   }
    return new Response("Hello World");
 },
});
    • backpressureLimit?: number

      Sets the maximum number of bytes that can be buffered on a single connection.

      Default is 16 MB, or 1024 * 1024 * 16 in bytes.

    • closeOnBackpressureLimit?: boolean

      Sets if the connection should be closed if backpressureLimit is reached.

      Default is false.

    • idleTimeout?: number

      Sets the the number of seconds to wait before timing out a connection due to no messages or pings.

      Default is 2 minutes, or 120 in seconds.

    • maxPayloadLength?: number

      Sets the maximum size of messages in bytes.

      Default is 16 MB, or 1024 * 1024 * 16 in bytes.

    • perMessageDeflate?: boolean | { compress: boolean | WebSocketCompressor; decompress: boolean | WebSocketCompressor }

      Sets the compression level for messages, for clients that supports it. By default, compression is disabled.

      Default is false.

    • publishToSelf?: boolean

      Should ws.publish() also send a message to ws (itself), if it is subscribed?

      Default is false.

    • sendPings?: boolean

      Should the server automatically send and respond to pings to clients?

      Default is true.

    • ws: ServerWebSocket<T>,
      code: number,
      reason: string
      ): void | Promise<void>;

      Called when a connection is closed.

      @param ws

      The websocket that was closed

      @param code

      The close code

      @param reason

      The close reason

    • ws: ServerWebSocket<T>
      ): void | Promise<void>;

      Called when a connection was previously under backpressure, meaning it had too many queued messages, but is now ready to receive more data.

      @param ws

      The websocket that is ready for more data

    • ws: ServerWebSocket<T>,
      message: string | Buffer<ArrayBufferLike>
      ): void | Promise<void>;

      Called when the server receives an incoming message.

      If the message is not a string, its type is based on the value of binaryType.

      • if nodebuffer, then the message is a Buffer.
      • if arraybuffer, then the message is an ArrayBuffer.
      • if uint8array, then the message is a Uint8Array.
      @param ws

      The websocket that sent the message

      @param message

      The message received

    • ws: ServerWebSocket<T>
      ): void | Promise<void>;

      Called when a connection is opened.

      @param ws

      The websocket that was opened

    • ws: ServerWebSocket<T>,
      data: Buffer
      ): void | Promise<void>;

      Called when a ping is sent.

      @param ws

      The websocket that received the ping

      @param data

      The data sent with the ping

    • ws: ServerWebSocket<T>,
      data: Buffer
      ): void | Promise<void>;

      Called when a pong is received.

      @param ws

      The websocket that received the ping

      @param data

      The data sent with the ping

  • interface WebSocketServeOptions<WebSocketDataType = undefined>

    • development?: boolean | { console: boolean; hmr: boolean }

      Render contextual errors? This enables bun's error page

    • error?: (this: Server, error: ErrorLike) => void | Promise<void> | Response | Promise<Response>
    • hostname?: string

      What hostname should the server listen on?

      "127.0.0.1" // Only listen locally
    • id?: null | string

      Uniquely identify a server instance with an ID

      When bun is started with the --hot flag:

      This string will be used to hot reload the server without interrupting pending requests or websockets. If not provided, a value will be generated. To disable hot reloading, set this value to null.

      When bun is not started with the --hot flag:

      This string will currently do nothing. But in the future it could be useful for logs or metrics.

    • maxRequestBodySize?: number

      What is the maximum size of a request body? (in bytes)

    • port?: string | number

      What port should the server listen on?

    • websocket: WebSocketHandler<WebSocketDataType>

      Enable websockets with Bun.serve

      For simpler type safety, see Bun.websocket

      Bun.serve({
 websocket: {
   open: (ws) => {
     console.log("Client connected");
   },
   message: (ws, message) => {
     console.log("Client sent message", message);
   },
   close: (ws) => {
     console.log("Client disconnected");
   },
 },
 fetch(req, server) {
   const url = new URL(req.url);
   if (url.pathname === "/chat") {
     const upgraded = server.upgrade(req);
     if (!upgraded) {
       return new Response("Upgrade failed", { status: 400 });
     }
   }
   return new Response("Hello World");
 },
});

      Upgrade a Request to a ServerWebSocket via Server.upgrade

      Pass data in @{link Server.upgrade} to attach data to the ServerWebSocket.data property

    • this: Server,
      request: Request,
      server: Server
      ): undefined | void | Response | Promise<undefined | void | Response>;

      Handle HTTP requests or upgrade them to a ServerWebSocket

      Respond to Request objects with a Response object.

  • interface WhichOptions

    • cwd?: string

      When given a relative path, use this path to join it.

    • PATH?: string

      Overrides the PATH environment variable

  • interface WorkerEventMap

  • interface WorkerOptions

    Bun's Web Worker constructor supports some extra options on top of the API browsers have.

    • argv?: any[]

      List of arguments which would be stringified and appended to Bun.argv / process.argv in the worker. This is mostly similar to the data but the values will be available on the global Bun.argv as if they were passed as CLI options to the script.

    • credentials?: RequestCredentials

      In Bun, this does nothing.

    • env?: typeof SHARE_ENV | Record<string, string>

      If set, specifies the initial value of process.env inside the Worker thread. As a special value, worker.SHARE_ENV may be used to specify that the parent thread and the child thread should share their environment variables; in that case, changes to one thread's process.env object affect the other thread as well. Default: process.env.

    • name?: string

      A string specifying an identifying name for the DedicatedWorkerGlobalScope representing the scope of the worker, which is mainly useful for debugging purposes.

    • preload?: string | string[]

      An array of module specifiers to preload in the worker.

      These modules load before the worker's entry point is executed.

      Equivalent to passing the --preload CLI argument, but only for this Worker.

    • ref?: boolean

      When true, the worker will keep the parent thread alive until the worker is terminated or unref'd. When false, the worker will not keep the parent thread alive.

      By default, this is false.

    • smol?: boolean

      Use less memory, but make the worker slower.

      Internally, this sets the heap size configuration in JavaScriptCore to be the small heap instead of the large heap.

    • type?: WorkerType

      In Bun, this does nothing.

  • interface ZlibCompressionOptions

    Compression options for Bun.deflateSync and Bun.gzipSync

    • level?: 0 | 1 | 5 | 3 | 4 | 6 | -1 | 2 | 7 | 8 | 9

      The compression level to use. Must be between -1 and 9.

      • A value of -1 uses the default compression level (Currently 6)
      • A value of 0 gives no compression
      • A value of 1 gives least compression, fastest speed
      • A value of 9 gives best compression, slowest speed
    • library?: 'zlib'
    • memLevel?: 1 | 5 | 3 | 4 | 6 | 2 | 7 | 8 | 9

      How much memory should be allocated for the internal compression state.

      A value of 1 uses minimum memory but is slow and reduces compression ratio.

      A value of 9 uses maximum memory for optimal speed. The default is 8.

    • strategy?: number

      Tunes the compression algorithm.

      • Z_DEFAULT_STRATEGY: For normal data (Default)
      • Z_FILTERED: For data produced by a filter or predictor
      • Z_HUFFMAN_ONLY: Force Huffman encoding only (no string match)
      • Z_RLE: Limit match distances to one (run-length encoding)
      • Z_FIXED prevents the use of dynamic Huffman codes

      Z_RLE is designed to be almost as fast as Z_HUFFMAN_ONLY, but give better compression for PNG image data.

      Z_FILTERED forces more Huffman coding and less string matching, it is somewhat intermediate between Z_DEFAULT_STRATEGY and Z_HUFFMAN_ONLY. Filtered data consists mostly of small values with a somewhat random distribution.

    • windowBits?: 25 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 28 | -9 | -10 | -11 | -12 | -13 | -14 | -15 | 26 | 27 | 29 | 30 | 31

      The base 2 logarithm of the window size (the size of the history buffer).

      Larger values of this parameter result in better compression at the expense of memory usage.

      The following value ranges are supported:

      • 9..15: The output will have a zlib header and footer (Deflate)
      • -9..-15: The output will not have a zlib header or footer (Raw Deflate)
      • 25..31 (16+9..15): The output will have a gzip header and footer (gzip)

      The gzip header will have no file name, no extra data, no comment, no modification time (set to zero) and no header CRC.

  • type $ = typeof $
  • type ArrayBufferView<TArrayBuffer extends ArrayBufferLike = ArrayBufferLike> = NodeJS.TypedArray<TArrayBuffer> | DataView<TArrayBuffer>
  • type BeforeExitListener = (code: number) => void
  • type BlobOrStringOrBuffer = string | NodeJS.TypedArray | ArrayBufferLike | Blob
  • type BlobPart = string | Blob | BufferSource
  • type BodyInit = ReadableStream | Bun.XMLHttpRequestBodyInit | URLSearchParams | AsyncGenerator<string | ArrayBuffer | ArrayBufferView> | () => AsyncGenerator<string | ArrayBuffer | ArrayBufferView>
  • type BufferSource = NodeJS.TypedArray | DataView | ArrayBufferLike
  • type BunLockFile =
    • overrides?: Record<string, string>
    • packages: {
      __index[
      pkg: string
       }
      INFO = { prod/dev/optional/peer dependencies, os, cpu, libc (TODO), bin, binDir }

// first index is resolution for each type of package
npm         -> [ "name@version", registry (TODO: remove if default), INFO, integrity]
symlink     -> [ "name@link:path", INFO ]
folder      -> [ "name@file:path", INFO ]
workspace   -> [ "name@workspace:path" ] // workspace is only path
tarball     -> [ "name@tarball", INFO ]
root        -> [ "name@root:", { bin, binDir } ]
git         -> [ "name@git+repo", INFO, .bun-tag string (TODO: remove this) ]
github      -> [ "name@github:user/repo", INFO, .bun-tag string (TODO: remove this) ]
    • patchedDependencies?: Record<string, string>
    • workspaces: {
      __index[
      workspace: string
       }

    Types for bun.lock

  • type BunLockFileBasePackageInfo =
  • type BunLockFilePackageArray = [pkg: string, registry: string, info: BunLockFilePackageInfo, integrity: string] | [pkg: string, info: BunLockFilePackageInfo] | [pkg: string] | [pkg: string, info: BunLockFilePackageInfo, bunTag: string] | [pkg: string, info: Pick<BunLockFileBasePackageInfo, 'bin' | 'binDir'>]
  • type BunLockFilePackageInfo = BunLockFileBasePackageInfo & { bundled: true; cpu: string | string[]; os: string | string[] }
  • type BunLockFileWorkspacePackage = BunLockFileBasePackageInfo & { name: string; version: string }
  • type ColorInput = { a: number; b: number; g: number; r: number } | [number, number, number] | [number, number, number, number] | Uint8Array | Uint8ClampedArray | Float32Array | Float64Array | string | number | { toString(): string }

    Valid inputs for color

  • type CookieSameSite = 'strict' | 'lax' | 'none'
  • type CSRFAlgorithm = 'blake2b256' | 'blake2b512' | 'sha256' | 'sha384' | 'sha512' | 'sha512-256'
  • type DigestEncoding = 'utf8' | 'ucs2' | 'utf16le' | 'latin1' | 'ascii' | 'base64' | 'base64url' | 'hex'
  • type DisconnectListener = () => void
  • type DistributedOmit<T, K extends PropertyKey> = T extends T ? Omit<T, K> : never
  • type DOMHighResTimeStamp = number
  • type Encoding = 'utf-8' | 'windows-1252' | 'utf-16'
  • type ExitListener = (code: number) => void
  • type FFIFunctionCallable = Function & { __ffi_function_callable: FFIFunctionCallableSymbol }
  • type FormDataEntryValue = File | string
  • type HeadersInit = string[][] | Record<string, string | ReadonlyArray<string>> | Headers
  • type HMREvent = `bun:${HMREventNames}` | string & {}

    The event names for the dev server

  • type HMREventNames = 'beforeUpdate' | 'afterUpdate' | 'beforeFullReload' | 'beforePrune' | 'invalidate' | 'error' | 'ws:disconnect' | 'ws:connect'
  • type ImportKind = 'import-statement' | 'require-call' | 'require-resolve' | 'dynamic-import' | 'import-rule' | 'url-token' | 'internal' | 'entry-point-run' | 'entry-point-build'
  • type JavaScriptLoader = 'jsx' | 'js' | 'ts' | 'tsx'
  • type Loader = 'js' | 'jsx' | 'ts' | 'tsx' | 'json' | 'toml' | 'file' | 'napi' | 'wasm' | 'text' | 'css' | 'html'

    https://bun.sh/docs/bundler/loaders

  • type MacroMap = Record<string, Record<string, string>>

    This lets you use macros as regular imports

      {
    "react-relay": {
      "graphql": "bun-macro-relay/bun-macro-relay.tsx"
    }
  }
  • type MessageEventSource = Bun.__internal.UseLibDomIfAvailable<'MessageEventSource', undefined>
  • type MessageListener = (message: unknown, sendHandle: unknown) => void
  • type MultipleResolveType = 'resolve' | 'reject'
  • type NullSubprocess = Subprocess<'ignore' | 'inherit' | null | undefined, 'ignore' | 'inherit' | null | undefined, 'ignore' | 'inherit' | null | undefined>

    Utility type for any process from () with stdin, stdout, stderr all set to null or similar.

  • type NullSyncSubprocess = SyncSubprocess<'ignore' | 'inherit' | null | undefined, 'ignore' | 'inherit' | null | undefined>

    Utility type for any process from () with both stdout and stderr set to null or similar

  • type OnLoadCallback = (args: OnLoadArgs) => OnLoadResult | Promise<OnLoadResult>
  • type OnResolveCallback = (args: OnResolveArgs) => OnResolveResult | Promise<OnResolveResult | undefined | null> | undefined | null
  • type OnStartCallback = () => void | Promise<void>
  • type PathLike = string | NodeJS.TypedArray | ArrayBufferLike | URL
  • type PipedSubprocess = Subprocess<'pipe', 'pipe', 'pipe'>

    Utility type for any process from () with stdin, stdout, stderr all set to "pipe". A combination of ReadableSubprocess and WritableSubprocess

  • type ReadableSubprocess = Subprocess<any, 'pipe', 'pipe'>

    Utility type for any process from () with both stdout and stderr set to "pipe"

  • type ReadableSyncSubprocess = SyncSubprocess<'pipe', 'pipe'>

    Utility type for any process from () with both stdout and stderr set to "pipe"

  • type RejectionHandledListener = (promise: Promise<unknown>) => void
  • type Serve<WebSocketDataType = undefined> = ServeOptions | TLSServeOptions | UnixServeOptions | UnixTLSServeOptions | WebSocketServeOptions<WebSocketDataType> | TLSWebSocketServeOptions<WebSocketDataType> | UnixWebSocketServeOptions<WebSocketDataType> | UnixTLSWebSocketServeOptions<WebSocketDataType>

    The type of options that can be passed to serve

  • type ServeFunctionOptions<T, R extends { [K in keyof R]: RouterTypes.RouteValue<Extract<K, string>> }> = DistributedOmit<Exclude<Serve<T>, WebSocketServeOptions<T>>, 'fetch'> & { fetch: (this: Server, request: Request, server: Server) => Response | Promise<Response>; routes: R } | DistributedOmit<Exclude<Serve<T>, WebSocketServeOptions<T>>, 'routes'> & { fetch: (this: Server, request: Request, server: Server) => Response | Promise<Response>; routes: never } | Omit<WebSocketServeOptions<T>, 'fetch'> & { fetch: (this: Server, request: Request, server: Server) => Response | Promise<Response | void | undefined> | void | undefined; routes: { [K in keyof R]: RouterTypes.RouteValueWithWebSocketUpgrade<Extract<K, string>> } } | Omit<WebSocketServeOptions<T>, 'fetch'> & { fetch: (this: Server, request: Request, server: Server) => Response | Promise<Response | void | undefined> | void | undefined; routes: never }

    The type of options that can be passed to serve, with support for routes and a safer requirement for fetch

  • type ServerWebSocketSendStatus = number

    A status that represents the outcome of a sent message.

    • if 0, the message was dropped.
    • if -1, there is backpressure of messages.
    • if >0, it represents the number of bytes sent.
    const status = ws.send("Hello!");
if (status === 0) {
  console.log("Message was dropped");
} else if (status === -1) {
  console.log("Backpressure was applied");
} else {
  console.log(`Success! Sent ${status} bytes`);
}
  • type SignalsListener = (signal: NodeJS.Signals) => void
  • type SQLOptions =
    • adapter?: string

      Database adapter/driver to use

    • bigint?: boolean

      By default values outside i32 range are returned as strings. If this is true, values outside i32 range are returned as BigInts.

    • connection_timeout?: number

      Maximum time in seconds to wait when establishing a connection (alias for connectionTimeout)

    • connectionTimeout?: number

      Maximum time in seconds to wait when establishing a connection

    • database?: string

      Name of the database to connect to

    • db?: string

      Name of the database to connect to (alias for database)

    • host?: string

      Database server hostname

    • hostname?: string

      Database server hostname (alias for host)

    • idle_timeout?: number

      Maximum time in seconds to wait for connection to become available (alias for idleTimeout)

    • idleTimeout?: number

      Maximum time in seconds to wait for connection to become available

    • max?: number

      Maximum number of connections in the pool

    • max_lifetime?: number

      Maximum lifetime in seconds of a connection (alias for maxLifetime)

    • maxLifetime?: number

      Maximum lifetime in seconds of a connection

    • onclose?: (client: SQL) => void

      Callback function executed when a connection is closed

    • onconnect?: (client: SQL) => void

      Callback function executed when a connection is established

    • pass?: string | () => Promise<string>

      Database password for authentication (alias for password)

    • password?: string | () => Promise<string>

      Database password for authentication

    • port?: number | string

      Database server port number

    • prepare?: boolean

      Automatic creation of prepared statements, defaults to true

    • ssl?: TLSOptions | boolean

      Whether to use TLS/SSL for the connection (alias for tls)

    • tls?: TLSOptions | boolean

      Whether to use TLS/SSL for the connection

    • url?: URL | string

      Connection URL (can be string or URL object)

    • user?: string

      Database user for authentication (alias for username)

    • username?: string

      Database user for authentication

    Configuration options for SQL client connection and behavior

    const config: SQLOptions = {
  host: 'localhost',
  port: 5432,
  user: 'dbuser',
  password: 'secretpass',
  database: 'myapp',
  idleTimeout: 30,
  max: 20,
  onconnect: (client) => {
    console.log('Connected to database');
  }
};
  • type SQLSavepointContextCallback = (sql: SavepointSQL) => Promise<any> | SQLQuery[]

    Callback function type for savepoint contexts

  • type SQLTransactionContextCallback = (sql: TransactionSQL) => Promise<any> | SQLQuery[]

    Callback function type for transaction contexts

  • type StringLike = string | { toString(): string }
  • type StringOrBuffer = string | NodeJS.TypedArray | ArrayBufferLike
  • type SupportedCryptoAlgorithms = 'blake2b256' | 'blake2b512' | 'md4' | 'md5' | 'ripemd160' | 'sha1' | 'sha224' | 'sha256' | 'sha384' | 'sha512' | 'sha512-224' | 'sha512-256' | 'sha3-224' | 'sha3-256' | 'sha3-384' | 'sha3-512' | 'shake128' | 'shake256'
  • type Target = 'bun' | 'node' | 'browser'
  • type TimerHandler = (...args: any[]) => void
  • type UncaughtExceptionOrigin = 'uncaughtException' | 'unhandledRejection'
  • type WarningListener = (warning: Error) => void
  • type WebSocketCompressor = 'disable' | 'shared' | 'dedicated' | '3KB' | '4KB' | '8KB' | '16KB' | '32KB' | '64KB' | '128KB' | '256KB'

    Compression options for WebSocket messages.

  • type WebSocketOptions = WebSocketOptionsProtocolsOrProtocol & WebSocketOptionsTLS & WebSocketOptionsHeaders

    Constructor options for the Bun.WebSocket client

  • type WebSocketOptionsHeaders =
  • type WebSocketOptionsProtocolsOrProtocol = { protocols: string | string[] } | { protocol: string }
  • type WebSocketOptionsTLS =
    • tls?: { rejectUnauthorized: boolean }

      Options for the TLS connection

  • type WebSocketReadyState = 0 | 1 | 2 | 3

    A state that represents if a WebSocket is connected.

    • WebSocket.CONNECTING is 0, the connection is pending.
    • WebSocket.OPEN is 1, the connection is established and send() is possible.
    • WebSocket.CLOSING is 2, the connection is closing.
    • WebSocket.CLOSED is 3, the connection is closed or couldn't be opened.
  • type WorkerType = 'classic' | 'module'
  • type WritableSubprocess = Subprocess<'pipe', any, any>

    Utility type for any process from () with stdin set to "pipe"