Bun module | API Reference | Bun

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

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

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
}
}

The cause of the error.

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Read from stdout as an ArrayBuffer

Stdout as an ArrayBuffer

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

Read from stdout as a Blob

Stdout as a blob

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

Read from stdout as an Uint8Array

Stdout as an Uint8Array

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

Read from stdout as a JSON object

Stdout as a JSON object

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

Read from stdout as a string

The encoding to use when decoding the output

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"

Create .stack property on a target object

Check if a value is an instance of Error

The value to check

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

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!"

Read from stdout as an ArrayBuffer

Automatically calls quiet

A promise that resolves with stdout as an ArrayBuffer

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

Read from stdout as a Blob

Automatically calls quiet

A promise that resolves with stdout as a Blob

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

Attaches a callback for only the rejection of the Promise.

The callback to execute when the Promise is rejected.

A Promise for the completion of the callback.

Change the current working directory of the shell.

The new working directory

Set environment variables for the shell.

The new environment variables

await $`echo $FOO`.env({ ...process.env, FOO: "LOL!" })
expect(stdout.toString()).toBe("LOL!");

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

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

A Promise for the completion of the callback.

Read from stdout as a JSON object

Automatically calls quiet

A promise that resolves with stdout as a JSON object

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

Read from stdout as a string, line by line

Automatically calls quiet to disable echoing to stdout.

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.

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.

Whether to suppress output. Defaults to true.

Read from stdout as a string.

Automatically calls quiet to disable echoing to stdout.

The encoding to use when decoding the output

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"

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

The callback to execute when the Promise is resolved.

The callback to execute when the Promise is rejected.

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

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

By default, this is configured to true.

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.

An array of Promises.

A new Promise.

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

An array of Promises.

A new Promise.

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.

An array or iterable of Promises.

A new Promise.

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

An array of Promises.

A new Promise.

Creates a new rejected promise for the provided reason.

The reason the promise was rejected.

A new rejected Promise.

Creates a new resolved promise for the provided value.

A promise.

A promise whose internal state matches the provided promise.

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

The function to run

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

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

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!"

Read from stdout as an ArrayBuffer

Stdout as an ArrayBuffer

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

Read from stdout as a Blob

Stdout as a blob

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

Read from stdout as an Uint8Array

Stdout as an Uint8Array

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

Read from stdout as a JSON object

Stdout as a JSON object

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

Read from stdout as a string

The encoding to use when decoding the output

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"

Perform bash-like brace expansion on the given pattern.

Brace pattern to expand

const result = braces('index.{js,jsx,ts,tsx}');
console.log(result) // ['index.js', 'index.jsx', 'index.ts', 'index.tsx']

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

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

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

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

Escape strings for input into shell commands.

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

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

Generate and verify CSRF tokens

Generate a CSRF token.

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

The options for the token.

The generated token.

Verify a CSRF token.

The token to verify.

The options for the token.

True if the token is valid, false otherwise.

DNS Related APIs

Experimental API

Lookup the IP address for a hostname

Uses non-blocking APIs by default

The hostname to lookup

Options for the lookup

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

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

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

Bun supports three DNS resolvers:

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"

Experimental API

Prefetch a hostname.

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

The hostname to prefetch

The port to prefetch. Default is 443. Port helps distinguish between IPv6 vs IPv4-only connections.

import { dns } from 'bun';
dns.prefetch('example.com');
// ... something expensive
await fetch('https://example.com');

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

Supports JSX

The value to inspect

Options for the inspection

That can be used to declare custom inspect functions.

Pretty-print an object or array as a table

Like console.table, except it returns a string

Pretty-print an object or array as a table

Like console.table, except it returns a string

JSON5 related APIs

Parse a JSON5 string into a JavaScript value.

JSON5 is a superset of JSON based on ECMAScript 5.1 that supports comments, trailing commas, unquoted keys, single-quoted strings, hex numbers, Infinity, NaN, and more.

The JSON5 string to parse

A JavaScript value

import { JSON5 } from "bun";

const result = JSON5.parse(`{
// This is a comment
name: 'my-app',
version: '1.0.0', // trailing comma is allowed
hex: 0xDEADbeef,
half: .5,
infinity: Infinity,
}`);

Convert a JavaScript value into a JSON5 string. Object keys that are valid identifiers are unquoted, strings use double quotes, Infinity and NaN are represented as literals, and indented output includes trailing commas.

The JavaScript value to stringify.

Currently not supported.

A number for how many spaces each level of indentation gets, or a string used as indentation. The number is clamped between 0 and 10, and the first 10 characters of the string are used.

A JSON5 string, or undefined if the input is undefined, a function, or a symbol.

import { JSON5 } from "bun";

console.log(JSON5.stringify({ a: 1, b: "two" }));
// {a:1,b:"two"}

console.log(JSON5.stringify({ a: 1, b: 2 }, null, 2));
// {
// a: 1,
// b: 2,
// }

JSONC related APIs

Parse a JSONC (JSON with Comments) string into a JavaScript value.

Supports both single-line (http://) and block comments (/* ... */), as well as trailing commas in objects and arrays.

The JSONC string to parse

A JavaScript value

const result = Bun.JSONC.parse(`{
// This is a comment
"name": "my-app",
"version": "1.0.0", // trailing comma is allowed
}`);

JSONL (JSON Lines) related APIs.

Each line in the input is expected to be a valid JSON value separated by newlines.

The result of Bun.JSONL.parseChunk.

true if all input was consumed successfully. false if the input ends with an incomplete value or a parse error occurred.

A SyntaxError if a parse error occurred, otherwise null. Values parsed before the error are still available in values.

How far into the input was consumed. When the input is a string, this is a character offset. When the input is a TypedArray, this is a byte offset. Use input.slice(read) or input.subarray(read) to get the unconsumed remainder.

The successfully parsed JSON values.

Parse a JSONL (JSON Lines) string into an array of JavaScript values.

If a parse error occurs and no values were successfully parsed, throws a SyntaxError. If values were parsed before the error, returns the successfully parsed values without throwing.

Incomplete trailing values (e.g. from a partial chunk) are silently ignored and not included in the result.

When a TypedArray is passed, the bytes are parsed directly without copying if the content is ASCII.

The JSONL string or typed array to parse

An array of parsed values

const items = Bun.JSONL.parse('{"a":1}\n{"b":2}\n');
// [{ a: 1 }, { b: 2 }]

// From a Uint8Array (zero-copy for ASCII):
const buf = new TextEncoder().encode('{"a":1}\n{"b":2}\n');
const items = Bun.JSONL.parse(buf);
// [{ a: 1 }, { b: 2 }]

// Partial results on error after valid values:
const partial = Bun.JSONL.parse('{"a":1}\n{bad}\n');
// [{ a: 1 }]

// Throws when no valid values precede the error:
Bun.JSONL.parse('{bad}\n'); // throws SyntaxError

Parse a JSONL chunk, designed for streaming use.

Never throws on parse errors. Instead, returns whatever values were successfully parsed along with an error property containing the SyntaxError (or null on success). Use read to determine how much input was consumed and done to check if all input was parsed.

When a TypedArray is passed, the bytes are parsed directly without copying if the content is ASCII. Optional start and end parameters select a window of the input without copying. For typed arrays these are byte offsets and read will be a byte offset into the original typed array. For strings these are character offsets and read will be a character offset into the original string.

The JSONL string or typed array to parse

Offset to start parsing from (bytes for typed arrays, characters for strings, default: 0)

Offset to stop parsing at (bytes for typed arrays, characters for strings, default: input length)

An object with values, read, done, and error properties

let buffer = new Uint8Array(0);
for await (const chunk of stream) {
buffer = Buffer.concat([buffer, chunk]);
const { values, read, error } = Bun.JSONL.parseChunk(buffer);
if (error) throw error;
for (const value of values) handle(value);
buffer = buffer.subarray(read);
}

Markdown related APIs.

Provides fast markdown parsing and rendering with three output modes:

Supports GFM extensions (tables, strikethrough, task lists, autolinks) and component overrides to replace default HTML tags with custom components.

// Render markdown to HTML
const html = Bun.markdown.html("# Hello **world**");
// "Hello world\n"

// Render with custom callbacks
const ansi = Bun.markdown.render("# Hello **world**", {
heading: (children, { level }) => `\x1b[1m${children}\x1b[0m\n`,
strong: (children) => `\x1b[1m${children}\x1b[22m`,
paragraph: (children) => children + "\n",
});

// Render as a React component
function Markdown({ text }: { text: string }) {
return Bun.markdown.react(text);
}

// With component overrides
const element = Bun.markdown.react("# Hello", { h1: MyHeadingComponent });

Theme for ANSI terminal rendering.

Emit ANSI color + styling escape sequences. When false, the renderer falls back to plain ASCII chrome (no box drawing, no emoji, no escape codes).

Line width used for word-wrapping paragraphs and headings and for the horizontal rule. Pass 0 to disable wrapping.

Emit OSC 8 hyperlinks (clickable links in modern terminals). When false, links render as text (url).

Inline images using the Kitty Graphics Protocol when the src resolves to a local file on disk. Falls through to the text alt for remote URLs. Supported by Kitty, WezTerm, and Ghostty.

True when the terminal background is light. Affects the color palette chosen for inline code backgrounds. Defaults to detecting from the COLORFGBG environment variable.

Meta passed to th and td callbacks.

Column alignment.

Column alignment.

Meta passed to the code callback.

The info-string language (e.g. "js").

The info-string language (e.g. "js").

Component overrides for react().

Replace default HTML tags with custom React components. Each override receives the same props the default element would get.

function Code({ language, children }: { language?: string; children: React.ReactNode }) {
return pre data-language={language}>code>{children}code>pre>;
}
Bun.markdown.react(text, { pre: Code });

Meta passed to the heading callback.

Heading ID slug. Set when headings: { ids: true } is enabled.

Heading level (1–6).

Heading ID slug. Set when headings: { ids: true } is enabled.

Meta passed to the image callback.

Image URL.

Image title attribute.

Alt text.

Image URL.

Image title attribute.

Meta passed to the link callback.

Link URL.

Link title attribute.

Link URL.

Link title attribute.

Meta passed to the listItem callback.

Task list checked state. Set for - [x] / - [ ] items.

Nesting depth of the parent list. 0 for items in a top-level list.

0-based index of this item within its parent list.

Whether the parent list is ordered.

The start number of the parent list (only set when ordered is true).

Task list checked state. Set for - [x] / - [ ] items.

Meta passed to the list callback.

Nesting depth. 0 for a top-level list, 1 for a list inside a list item, etc.

Whether this is an ordered list.

The start number for ordered lists.

Options for configuring the markdown parser.

By default, GFM extensions (tables, strikethrough, task lists) are enabled.

Enable autolinks. Pass true to enable all autolink types (URL, WWW, email), or an object to enable individually.

// Enable all autolinks
{ autolinks: true }
// Enable only URL and email autolinks
{ autolinks: { url: true, email: true } }

Collapse whitespace in text content. Default: false.

Treat soft line breaks as hard line breaks. Default: false.

Configure heading IDs and autolink headings. Pass true to enable both heading IDs and autolink headings, or an object to configure individually.

// Enable both heading IDs and autolink headings
{ headings: true }
// Enable only heading IDs
{ headings: { ids: true } }

Enable LaTeX math ($inline$ and $$display$$). Default: false.

Disable HTML blocks. Default: false.

Disable inline HTML spans. Default: false.

Disable indented code blocks. Default: false.

Allow ATX headers without a space after #. Default: false.

Enable GFM strikethrough (~~text~~). Default: true.

Enable GFM tables. Default: true.

Collapse whitespace in text content. Default: false.

Treat soft line breaks as hard line breaks. Default: false.

Configure heading IDs and autolink headings. Pass true to enable both heading IDs and autolink headings, or an object to configure individually.

// Enable both heading IDs and autolink headings
{ headings: true }
// Enable only heading IDs
{ headings: { ids: true } }

Enable LaTeX math ($inline$ and $$display$$). Default: false.

Disable HTML blocks. Default: false.

Disable inline HTML spans. Default: false.

Disable indented code blocks. Default: false.

Allow ATX headers without a space after #. Default: false.

Which $$typeof symbol to use on the generated elements.

Enable GFM strikethrough (~~text~~). Default: true.

Enable GFM tables. Default: true.

Render markdown to an HTML string.

The markdown string or buffer to render

Parser options

An HTML string

const html = Bun.markdown.html("# Hello **world**");
// "Hello world\n"

// With options
const html = Bun.markdown.html("## Hello", { headings: { ids: true } });
// 'Hello\n'

Render markdown to React JSX elements.

Returns a React Fragment containing the parsed markdown as children. Can be returned directly from a component or passed to renderToString().

Override any HTML element with a custom component by passing it in the second argument, keyed by tag name. Custom components receive the same props the default elements would (e.g. href for links, language for code blocks).

Parser options (including reactVersion) are passed as a separate third argument. Uses Symbol.for('react.transitional.element') by default (React 19). Pass reactVersion: 18 for React 18 and older.

The markdown string or buffer to parse

Component overrides keyed by HTML tag name

Parser options and element symbol configuration

A React Fragment element containing the parsed markdown

// Use directly as a component return value
function Markdown({ text }: { text: string }) {
return Bun.markdown.react(text);
}

// Server-side rendering
import { renderToString } from "react-dom/server";
const html = renderToString(Bun.markdown.react("# Hello **world**"));

// Custom components receive element props
function Code({ language, children }: { language?: string; children: React.ReactNode }) {
return pre data-language={language}>code>{children}code>pre>;
}
function Link({ href, children }: { href: string; children: React.ReactNode }) {
return a href={href} target="_blank">{children}a>;
}
const el = Bun.markdown.react(text, { pre: Code, a: Link });

// For React 18 and older
const el18 = Bun.markdown.react(text, undefined, { reactVersion: 18 });

Render markdown with custom JavaScript callbacks for each element.

Each callback receives the accumulated children as a string and optional metadata, and returns a string. Return null or undefined to omit an element. If no callback is registered, children pass through unchanged.

Parser options are passed as a separate third argument.

The markdown string to render

Callbacks for each element type

Parser options

The accumulated string output

// Custom HTML with classes
const html = Bun.markdown.render("# Title\n\nHello **world**", {
heading: (children, { level }) => `${level} class="title">${children}${level}>`,
paragraph: (children) => `
${children}
`,
strong: (children) => `${children}`,
});

// ANSI terminal output
const ansi = Bun.markdown.render("# Hello\n\n**bold**", {
heading: (children) => `\x1b[1;4m${children}\x1b[0m\n`,
paragraph: (children) => children + "\n",
strong: (children) => `\x1b[1m${children}\x1b[22m`,
});

// With parser options as third argument
const text = Bun.markdown.render("Visit www.example.com", {
link: (children, { href }) => `[${children}](${href})`,
paragraph: (children) => children,
}, { autolinks: true });

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

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

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.

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

The cause of the error.

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Create .stack property on a target object

Check if a value is an instance of Error

The value to check

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

The cause of the error.

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Create .stack property on a target object

Check if a value is an instance of Error

The value to check

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

The cause of the error.

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Create .stack property on a target object

Check if a value is an instance of Error

The value to check

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

The cause of the error.

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Create .stack property on a target object

Check if a value is an instance of Error

The value to check

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

SQL.Helper represents a parameter or serializable value inside of a query.

const helper = sql(users, 'id');
await sql`insert into users ${helper}`;

Database adapter/driver to use

By default values outside i32 range are returned as strings. If this is true, values outside i32 range are returned as BigInts.

Postgres client runtime configuration options

Maximum time in seconds to wait when establishing a connection

Name of the database to connect to

Database server hostname

Maximum time in seconds to wait for connection to become available

Maximum number of connections in the pool

Maximum lifetime in seconds of a connection

Callback executed when a connection is closed Receives the closing Error or null.

Callback executed when a connection attempt completes Receives an Error on failure, or null on success.

Database password for authentication

Unix domain socket path for connection

Database server port number

Automatic creation of prepared statements

Whether to use TLS/SSL for the connection

Connection URL (can be string or URL object)

Database user for authentication

Represents a SQL query that can be executed, with additional control methods Extends Promise to allow for async/await usage

Indicates if the query is currently executing

Indicates if the query has been cancelled

Cancels the executing query

Attaches a callback for only the rejection of the Promise.

The callback to execute when the Promise is rejected.

A Promise for the completion of the callback.

Executes the query

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

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

A Promise for the completion of the callback.

Returns the raw query result

Executes the query as a simple query, no parameters are allowed but can execute multiple commands separated by semicolons

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

The callback to execute when the Promise is resolved.

The callback to execute when the Promise is rejected.

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

Returns only the values from the query result

Options for Database

Allow creating a new database

Equivalent to constants.SQLITE_OPEN_CREATE

Specify the path to the database file

Examples:

Callback executed when a connection is closed (SQLite) Receives the closing Error or null.

Callback executed when a connection attempt completes (SQLite) Receives an Error on failure, or null on success.

Open the database as read-only (no write operations, no create).

Equivalent to constants.SQLITE_OPEN_READONLY

Open the database as read-write

Equivalent to constants.SQLITE_OPEN_READWRITE

When set to true, integers are returned as bigint types.

When set to false, integers are returned as number types and truncated to 52 bits.

When set to false or undefined:

const db = new Database(":memory:", { strict: false });
db.run("INSERT INTO foo (name) VALUES ($name)", { $name: "foo" });

When set to true:

Configuration options for SQL client connection and behavior

const config: Bun.SQL.Options = {
host: 'localhost',
port: 5432,
user: 'dbuser',
password: 'secretpass',
database: 'myapp',
idleTimeout: 30,
max: 20,
onconnect: (client) => {
console.log('Connected to database');
}
};

Callback function type for savepoint contexts

Callback function type for transaction contexts

TOML related APIs

Parse a TOML string into a JavaScript object.

The TOML string to parse

A JavaScript object

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.

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.

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

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

BUN_GARBAGE_COLLECTOR_LEVEL environment variable is also supported.

The previous level

Accurate per-process memory footprint in bytes.

Unlike process.memoryUsage.rss(), this excludes pages already returned to the OS that the kernel keeps mapped lazily (Darwin's MADV_FREE_REUSABLE), so leak tests are platform-comparable.

Backed by task_info(TASK_VM_INFO).phys_footprint on Darwin, Pss: from /proc/self/smaps_rollup on Linux, and PrivateUsage on Windows. Returns undefined on platforms with no accurate accessor; callers should fall back: Bun.unsafe.memoryFootprint() ?? process.memoryUsage.rss().

Dump the mimalloc heap to the console

YAML related APIs

Parse a YAML string into a JavaScript value

The YAML string to parse

A JavaScript value

import { YAML } from "bun";

console.log(YAML.parse("123")) // 123
console.log(YAML.parse("null")) // null
console.log(YAML.parse("false")) // false
console.log(YAML.parse("abc")) // "abc"
console.log(YAML.parse("- abc")) // [ "abc" ]
console.log(YAML.parse("abc: def")) // { "abc": "def" }

Convert a JavaScript value into a YAML string. Strings are double quoted if they contain keywords, non-printable or escaped characters, or if a YAML parser would parse them as numbers. Anchors and aliases are inferred from objects, allowing cycles.

The JavaScript value to stringify.

Currently not supported.

A number for how many spaces each level of indentation gets, or a string used as indentation. Without this parameter, outputs flow-style (single-line) YAML. With this parameter, outputs block-style (multi-line) YAML. The number is clamped between 0 and 10, and the first 10 characters of the string are used.

A string containing the YAML document.

import { YAML } from "bun";

const input = {
abc: "def",
num: 123
};

// Without space - flow style (single-line)
console.log(YAML.stringify(input));
// {abc: def,num: 123}

// With space - block style (multi-line)
console.log(YAML.stringify(input, null, 2));
// abc: def
// num: 123

const cycle = {};
cycle.obj = cycle;
console.log(YAML.stringify(cycle, null, 2));
// &1
// obj: *1

A class for creating and extracting tar archives with optional gzip compression.

Bun.Archive provides a fast, native implementation for working with tar archives. It supports creating archives from in-memory data or extracting existing archives to disk or memory.

Create an archive from an object:

const archive = new Bun.Archive({
"hello.txt": "Hello, World!",
"data.json": JSON.stringify({ foo: "bar" }),
"binary.bin": new Uint8Array([1, 2, 3, 4]),
});

Get the archive contents as a Blob.

Uses the compression settings specified when the Archive was created.

A promise that resolves with the archive data as a Blob

Get tarball as Blob:

const archive = new Bun.Archive(data);
const blob = await archive.blob();

Get the archive contents as a Uint8Array.

Uses the compression settings specified when the Archive was created.

A promise that resolves with the archive data as a Uint8Array

Get tarball bytes:

const archive = new Bun.Archive(data);
const bytes = await archive.bytes();

Extract the archive contents to a directory on disk.

Creates the target directory and any necessary parent directories if they don't exist. Existing files will be overwritten.

The directory path to extract to

Optional extraction options

A promise that resolves with the number of entries extracted (files, directories, and symlinks)

Extract all entries:

const archive = new Bun.Archive(tarballBytes);
const count = await archive.extract("./extracted");
console.log(`Extracted ${count} entries`);

Get the archive contents as a Map of File objects.

Each file in the archive is returned as a File object with:

Only regular files are included; directories are not returned. File contents are loaded into memory, so for large archives consider using extract() instead.

Optional glob pattern(s) to filter files. Supports the same syntax as Bun.Glob, including negation patterns (prefixed with !). Patterns are matched against paths normalized to use forward slashes (/).

A promise that resolves with a Map where keys are file paths (always using forward slashes / as separators) and values are File objects

Get all files:

const entries = await archive.files();
for (const [path, file] of entries) {
console.log(`${path}: ${file.size} bytes`);
}

Create and write an archive directly to disk in one operation.

This is more efficient than creating an archive and then writing it separately, as it streams the data directly to disk.

The file path to write the archive to

The input data for the archive (same as new Archive())

Optional archive options including compression settings

A promise that resolves when the write is complete

Write uncompressed tarball:

await Bun.Archive.write("output.tar", {
"file1.txt": "content1",
"file2.txt": "content2",
});

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

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

A class for working with a single cookie

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

The domain of the cookie

The expiration date of the cookie

Whether the cookie is HTTP-only

The maximum age of the cookie in seconds

The name of the cookie

Whether the cookie is partitioned

The path of the cookie

The same-site attribute of the cookie

Whether the cookie is secure

The value of the cookie

Whether the cookie is expired

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

Serialize the cookie to a string

Alias of Cookie.serialize

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

Parse a cookie string into a Cookie object

The cookie string

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

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

The number of cookies in the map.

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

An iterator for the entries in the map

Removes a cookie from the map.

The name of the cookie to delete

Removes a cookie from the map.

The options for the cookie to delete

Removes a cookie from the map.

The name of the cookie to delete

The options for the cookie to delete

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

An iterator for the entries in the map

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

Function to execute for each entry

Gets the value of a cookie with the specified name.

The name of the cookie to retrieve

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

Checks if a cookie with the given name exists.

The name of the cookie to check

true if the cookie exists, false otherwise

Returns an iterator of all cookie names in the map.

An iterator for the cookie names

Adds or updates a cookie in the map.

The name of the cookie

The value of the cookie

Optional cookie attributes

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

Cookie options including name and value

Converts the cookie map to a serializable format.

An array of name/value pairs

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

An array of values for Set-Cookie headers

Returns an iterator of all cookie values in the map.

An iterator for the cookie values

Hardware-accelerated cryptographic hash functions

Used for crypto.createHash()

The algorithm chosen to hash the data

The length of the output hash in bytes

List of supported hash algorithms

These are hardware accelerated with BoringSSL

Perform a deep copy of the hasher

Finalize the hash. Resets the CryptoHasher so it can be reused.

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

Finalize the hash and return a Buffer

Finalize the hash

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

Update the hash with data

Run the hash over the given data

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

Run the hash over the given data

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

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

Run the hash over the given data

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

DigestEncoding to return the hash in

This class only exists in types

Finalize the hash

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

Finalize the hash

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

Update the hash with data

Run the hash over the given data

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

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

Run the hash over the given data

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

DigestEncoding to return the hash in

Match files using glob patterns.

The supported pattern syntax for is:

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

Match the glob against a string

const glob = new Glob("*.{ts,tsx}");
expect(glob.match('foo.ts')).toBeTrue();

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' }))

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' }))

Decode, transform and re-encode images. Ships JPEG, PNG and WebP via statically-linked libjpeg-turbo / libspng / libwebp; resize and rotate are SIMD kernels — no native module install, no sharp.

The constructor and every chainable method only record settings; the decode → transform → encode pipeline runs on a worker thread when a terminal (bytes, buffer, blob, toBase64, metadata) is awaited.

Chainables overwrite (calling .resize() twice keeps the second). Order of execution is fixed regardless of call order: autoOrient → rotate → flip/flop → resize → modulate.

The source ICC colour profile (Display P3, Adobe RGB, Jpegli XYB, etc.) is preserved through re-encode to JPEG, PNG, and WebP so non-sRGB images don't shift colour.

const thumb = await new Bun.Image("photo.jpg")
.resize(400, 400, { fit: "inside", withoutEnlargement: true })
.webp({ quality: 80 })
.bytes();

Populated after the first awaited terminal; -1 before.

Process-global pipeline backend.

Set before awaiting a pipeline; in-flight tasks read the value as of when they were scheduled.

Set output format to AVIF. Requires an OS AV1 encoder (macOS on Apple Silicon M3+, or Windows with the AV1 Video Extension) — the terminal rejects with error.code === "ERR_IMAGE_FORMAT_UNSUPPORTED" elsewhere.

Run the pipeline and return a Blob with the matching type.

Like bytes but as a Node Buffer.

Run the pipeline and return the encoded bytes. If no format setter was called, re-encodes in the source format.

Like toBase64 with a data:image/{format};base64, prefix. Drops straight into .

Mirror about the x-axis (vertical).

Mirror about the y-axis (horizontal).

Set output format to HEIC. macOS / Windows-with-HEIF-Extension only — the terminal rejects with error.code === "ERR_IMAGE_FORMAT_UNSUPPORTED" elsewhere.

Set output format to JPEG.

Decode just enough to read width/height/format.

Adjust brightness/saturation.

A ThumbHash-rendered low-quality placeholder of the source image as a data:image/png;base64,… URL — a ≤32px blur with the right average colour, aspect ratio and rough structure, ~400–700 bytes. Ready for or Next's blurDataURL; no client-side decoder needed.

const lqip = await Bun.file("hero.jpg").image().placeholder();
// "data:image/png;base64,iVBORw0KGgoAAAANSUhE…"

Set output format to PNG.

Set target dimensions. Omit height to keep the source aspect ratio.

Rotate by a multiple of 90°.

Run the pipeline and return base64-encoded output.

Sharp-compatible alias for buffer.

Set output format to WebP.

Run the pipeline and write the encoded result via Bun.write — dest may be a path string, BunFile, S3File, or fd. Resolves to the number of bytes written.

If no format method was chained and dest is a path string, the format is inferred from its extension when it's one Bun can encode (.jpg/.png/.webp/.heic/.avif); otherwise the source format is reused.

Monotone counter that increments on every system-wide clipboard write. Poll this and only call hasClipboardImage when it moves. -1 on Linux.

Read an image from the system clipboard.

Returns a Bun.Image wrapping whatever container the clipboard holds (PNG, TIFF, HEIC, JPEG, BMP, …); call metadata, resize, etc. as usual. null if no image is present.

Cheap probe — true if fromClipboard would return non-null.

This class only exists in types

The number of bytes the hash will produce

Finalize the hash

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

Finalize the hash

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

Update the hash with data

Run the hash over the given data

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

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

Run the hash over the given data

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

DigestEncoding to return the hash in

This class only exists in types

The number of bytes the hash will produce

Finalize the hash

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

Finalize the hash

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

Update the hash with data

Run the hash over the given data

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

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

Run the hash over the given data

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

DigestEncoding to return the hash in

Amount of data buffered in bytes

Whether the client is connected to the Redis server

Callback fired when the client disconnects from the Redis server

Callback fired when the client connects to the Redis server

Append a value to a key

The key to append to

The value to append

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

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

The key to count bits in

Promise that resolves with the number of bits set to 1

Blocking move from one list to another

Atomically moves an element from source to destination list, blocking until an element is available or the timeout expires. Allows specifying which end to pop from (LEFT/RIGHT) and which end to push to (LEFT/RIGHT).

Source list key

Destination list key

Direction to pop from source: "LEFT" or "RIGHT"

Direction to push to destination: "LEFT" or "RIGHT"

Timeout in seconds (can be fractional, 0 = block indefinitely)

Promise that resolves with the moved element or null on timeout

// Move from right of source to left of destination (like BRPOPLPUSH)
const element = await redis.blmove("mylist", "otherlist", "RIGHT", "LEFT", 1.0);
if (element) {
console.log(`Moved element: ${element}`);
}

// Move from left to left
await redis.blmove("list1", "list2", "LEFT", "LEFT", 0.5);

Blocking pop multiple elements from lists

Blocks until an element is available from one of the specified lists or the timeout expires. Can pop from the LEFT or RIGHT end and optionally pop multiple elements at once using COUNT.

Timeout in seconds (can be fractional, 0 = block indefinitely)

Number of keys that follow

Keys, direction ("LEFT" or "RIGHT"), and optional COUNT modifier

Promise that resolves with [key, [elements]] or null on timeout

// Pop from left end of first available list, wait 1 second
const result = await redis.blmpop(1.0, 2, "list1", "list2", "LEFT");
if (result) {
const [key, elements] = result;
console.log(`Popped from ${key}: ${elements.join(", ")}`);
}

// Pop 3 elements from right end
const result2 = await redis.blmpop(0.5, 1, "mylist", "RIGHT", "COUNT", 3);
// Returns: ["mylist", ["elem1", "elem2", "elem3"]] or null if timeout

Blocking pop from head of one or more lists

Blocks until an element is available in one of the lists or the timeout expires. Checks keys in order and pops from the first non-empty list.

Keys followed by timeout in seconds (can be fractional, 0 = block indefinitely)

Promise that resolves with [key, element] or null on timeout

// Block for up to 1 second
const result = await redis.blpop("mylist", 1.0);
if (result) {
const [key, element] = result;
console.log(`Popped ${element} from ${key}`);
}

// Block indefinitely (timeout = 0)
const result2 = await redis.blpop("list1", "list2", 0);

Blocking pop from tail of one or more lists

Blocks until an element is available in one of the lists or the timeout expires. Checks keys in order and pops from the first non-empty list.

Keys followed by timeout in seconds (can be fractional, 0 = block indefinitely)

Promise that resolves with [key, element] or null on timeout

// Block for up to 1 second
const result = await redis.brpop("mylist", 1.0);
if (result) {
const [key, element] = result;
console.log(`Popped ${element} from ${key}`);
}

// Block indefinitely (timeout = 0)
const result2 = await redis.brpop("list1", "list2", 0);

Blocking right pop from source and left push to destination

Atomically pops an element from the tail of source list and pushes it to the head of destination list, blocking until an element is available or the timeout expires. This is the blocking version of RPOPLPUSH.

Source list key

Destination list key

Timeout in seconds (can be fractional, 0 = block indefinitely)

Promise that resolves with the moved element or null on timeout

// Block for up to 1 second
const element = await redis.brpoplpush("tasks", "processing", 1.0);
if (element) {
console.log(`Processing task: ${element}`);
} else {
console.log("No tasks available");
}

// Block indefinitely (timeout = 0)
const task = await redis.brpoplpush("queue", "active", 0);

Blocking version of ZMPOP. Blocks until a member is available or timeout expires.

// Block for 5 seconds waiting for a member
const result1 = await redis.bzmpop(5, 1, "myzset", "MIN");
// Returns: ["myzset", [["member1", 1]]] or null if timeout

// Block indefinitely (timeout 0)
const result2 = await redis.bzmpop(0, 2, "zset1", "zset2", "MAX");
// Returns: ["zset1", [["member5", 5]]]

// Block with COUNT option
const result3 = await redis.bzmpop(1, 1, "myzset", "MIN", "COUNT", 2);
// Returns: ["myzset", [["member1", 1], ["member2", 2]]] or null if timeout

Remove and return the member with the highest score from one or more sorted sets, or block until one is available

Keys followed by timeout in seconds (e.g., "key1", "key2", 1.0)

Promise that resolves with [key, member, score] or null if timeout

// Block for up to 1 second waiting for an element
const result = await redis.bzpopmax("myzset", 1.0);
if (result) {
const [key, member, score] = result;
console.log(`Popped ${member} with score ${score} from ${key}`);
}

Remove and return the member with the lowest score from one or more sorted sets, or block until one is available

Keys followed by timeout in seconds (e.g., "key1", "key2", 1.0)

Promise that resolves with [key, member, score] or null if timeout

// Block for up to 1 second waiting for an element
const result = await redis.bzpopmin("myzset", 1.0);
if (result) {
const [key, member, score] = result;
console.log(`Popped ${member} with score ${score} from ${key}`);
}

Disconnect from the Redis server

Connect to the Redis server

A promise that resolves when connected

Copy the value stored at the source key to the destination key

By default, the destination key is created in the logical database used by the connection. The REPLACE option removes the destination key before copying the value to it.

The source key to copy from

The destination key to copy to

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

await redis.set("mykey", "Hello");
await redis.copy("mykey", "myotherkey");
console.log(await redis.get("myotherkey")); // "Hello"

Copy the value stored at the source key to the destination key, optionally replacing it

The REPLACE option removes the destination key before copying the value to it.

The source key to copy from

The destination key to copy to

"REPLACE" - Remove the destination key before copying

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

await redis.set("mykey", "Hello");
await redis.set("myotherkey", "World");
await redis.copy("mykey", "myotherkey", "REPLACE");
console.log(await redis.get("myotherkey")); // "Hello"

Decrement the integer value of a key by one

The key to decrement

Promise that resolves with the new value

Decrement the integer value of a key by the given amount

The key to decrement

The amount to decrement by

Promise that resolves with the new value after decrementing

Delete a key(s)

The keys to delete

Promise that resolves with the number of keys removed

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

The key to dump

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

Determine if a key exists

The key to check

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

Set a key's time to live in seconds

The key to set the expiration for

The number of seconds until expiration

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

Set the expiration for a key as a Unix timestamp (in seconds)

The key to set expiration on

Unix timestamp in seconds when the key should expire

Promise that resolves with 1 if timeout was set, 0 if key does not exist

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

The key to check

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

Get the value of a key

The key to get

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

Returns the bit value at offset in the string value stored at key

The key containing the string value

The bit offset (zero-based)

Promise that resolves with the bit value (0 or 1) at the specified offset

Get the value of a key as a Uint8Array

The key to get

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

Get the value of a key and delete the key

The key to get and delete

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

Get the value of a key and optionally set its expiration

The key to get

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

Get the value of a key and set its expiration in seconds

The key to get

Set the specified expire time, in seconds

The number of seconds until expiration

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

Get the value of a key and set its expiration in milliseconds

The key to get

Set the specified expire time, in milliseconds

The number of milliseconds until expiration

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

Get the value of a key and set its expiration at a specific Unix timestamp in seconds

The key to get

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

The Unix timestamp in seconds

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

Get the value of a key and set its expiration at a specific Unix timestamp in milliseconds

The key to get

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

The Unix timestamp in milliseconds

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

Get the value of a key and remove its expiration

The key to get

Remove the expiration from the key

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

Get a substring of the string stored at a key

The key to get the substring from

The starting offset (can be negative to count from the end)

The ending offset (can be negative to count from the end)

Promise that resolves with the substring, or an empty string if the key doesn't exist

Set the value of a key and return its old value

The key to set

The value to set

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

Delete one or more hash fields

The hash key

The field to delete

Additional fields to delete

Promise that resolves with the number of fields that were removed

Determine if a hash field exists

The hash key

The field to check

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

Set expiration for hash fields (Redis 7.4+) Syntax: HEXPIRE key seconds [NX | XX | GT | LT] FIELDS numfields field [field ...]

Array where each element is: -2 (field doesn't exist), 0 (condition not met), 1 (expiration set), 2 (field deleted)

redis.hexpire("mykey", 10, "FIELDS", 1, "field1")

Set expiration for hash fields (Redis 7.4+) Syntax: HEXPIRE key seconds [NX | XX | GT | LT] FIELDS numfields field [field ...]

Array where each element is: -2 (field doesn't exist), 0 (condition not met), 1 (expiration set), 2 (field deleted)

redis.hexpire("mykey", 10, "FIELDS", 1, "field1")

Set expiration for hash fields using Unix timestamp in seconds (Redis 7.4+) Syntax: HEXPIREAT key unix-time-seconds [NX | XX | GT | LT] FIELDS numfields field [field ...]

Array where each element is: -2 (field doesn't exist), 0 (condition not met), 1 (expiration set), 2 (field deleted)

redis.hexpireat("mykey", 1735689600, "FIELDS", 1, "field1")

Set expiration for hash fields using Unix timestamp in seconds (Redis 7.4+) Syntax: HEXPIREAT key unix-time-seconds [NX | XX | GT | LT] FIELDS numfields field [field ...]

Array where each element is: -2 (field doesn't exist), 0 (condition not met), 1 (expiration set), 2 (field deleted)

redis.hexpireat("mykey", 1735689600, "FIELDS", 1, "field1")

Get expiration time of hash fields as Unix timestamp in seconds (Redis 7.4+) Syntax: HEXPIRETIME key FIELDS numfields field [field ...]

Array where each element is: -2 (field doesn't exist), -1 (no expiration), Unix timestamp in seconds

redis.hexpiretime("mykey", "FIELDS", 2, "field1", "field2")

Get the value of a hash field

The hash key

The field to get

Promise that resolves with the field value or null if the field doesn't exist

Get all the fields and values in a hash

The hash key

Promise that resolves with an object containing all fields and values, or empty object if key does not exist

Get and delete one or more hash fields (Redis 8.0.0+) Syntax: HGETDEL key FIELDS numfields field [field ...]

The hash key

Must be the literal string "FIELDS"

Number of fields to follow

The field names to get and delete

Promise that resolves with array of field values (null for non-existent fields)

redis.hgetdel("mykey", "FIELDS", 2, "field1", "field2")

Get hash field values with expiration options (Redis 8.0.0+) Syntax: HGETEX key [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | PERSIST] FIELDS numfields field [field ...]

redis.hgetex("mykey", "FIELDS", 1, "field1")

Get hash field values with expiration options (Redis 8.0.0+) Syntax: HGETEX key [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | PERSIST] FIELDS numfields field [field ...]

redis.hgetex("mykey", "FIELDS", 1, "field1")

Get hash field values with expiration options (Redis 8.0.0+) Syntax: HGETEX key [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | PERSIST] FIELDS numfields field [field ...]

redis.hgetex("mykey", "FIELDS", 1, "field1")

Get hash field values with expiration options (Redis 8.0.0+) Syntax: HGETEX key [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | PERSIST] FIELDS numfields field [field ...]

redis.hgetex("mykey", "FIELDS", 1, "field1")

Get hash field values with expiration options (Redis 8.0.0+) Syntax: HGETEX key [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | PERSIST] FIELDS numfields field [field ...]

redis.hgetex("mykey", "FIELDS", 1, "field1")

Get hash field values with expiration options (Redis 8.0.0+) Syntax: HGETEX key [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | PERSIST] FIELDS numfields field [field ...]

redis.hgetex("mykey", "FIELDS", 1, "field1")

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

The hash key

The field to increment

The amount to increment by

Promise that resolves with the new value

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

The hash key

The field to increment

The amount to increment by

Promise that resolves with the new value as a string

Get all field names in a hash

The hash key

Promise that resolves with an array of field names

Get the number of fields in a hash

The hash key

Promise that resolves with the number of fields

Get the values of all the given hash fields

The hash key

The fields to get

Promise that resolves with an array of values

Remove expiration from hash fields (Redis 7.4+) Syntax: HPERSIST key FIELDS numfields field [field ...]

Array where each element is: -2 (field doesn't exist), -1 (no expiration), 1 (expiration removed)

redis.hpersist("mykey", "FIELDS", 1, "field1")

Set expiration for hash fields in milliseconds (Redis 7.4+) Syntax: HPEXPIRE key milliseconds [NX | XX | GT | LT] FIELDS numfields field [field ...]

Array where each element is: -2 (field doesn't exist), 0 (condition not met), 1 (expiration set), 2 (field deleted)

redis.hpexpire("mykey", 10000, "FIELDS", 1, "field1")

Set expiration for hash fields in milliseconds (Redis 7.4+) Syntax: HPEXPIRE key milliseconds [NX | XX | GT | LT] FIELDS numfields field [field ...]

Array where each element is: -2 (field doesn't exist), 0 (condition not met), 1 (expiration set), 2 (field deleted)

redis.hpexpire("mykey", 10000, "FIELDS", 1, "field1")

Set expiration for hash fields using Unix timestamp in milliseconds (Redis 7.4+) Syntax: HPEXPIREAT key unix-time-milliseconds [NX | XX | GT | LT] FIELDS numfields field [field ...]

Array where each element is: -2 (field doesn't exist), 0 (condition not met), 1 (expiration set), 2 (field deleted)

redis.hpexpireat("mykey", 1735689600000, "FIELDS", 1, "field1")

Set expiration for hash fields using Unix timestamp in milliseconds (Redis 7.4+) Syntax: HPEXPIREAT key unix-time-milliseconds [NX | XX | GT | LT] FIELDS numfields field [field ...]

Array where each element is: -2 (field doesn't exist), 0 (condition not met), 1 (expiration set), 2 (field deleted)

redis.hpexpireat("mykey", 1735689600000, "FIELDS", 1, "field1")

Get expiration time of hash fields as Unix timestamp in milliseconds (Redis 7.4+) Syntax: HPEXPIRETIME key FIELDS numfields field [field ...]

Array where each element is: -2 (field doesn't exist), -1 (no expiration), Unix timestamp in milliseconds

redis.hpexpiretime("mykey", "FIELDS", 2, "field1", "field2")

Get TTL of hash fields in milliseconds (Redis 7.4+) Syntax: HPTTL key FIELDS numfields field [field ...]

Array where each element is: -2 (field doesn't exist), -1 (no expiration), TTL in milliseconds

redis.hpttl("mykey", "FIELDS", 2, "field1", "field2")

Get one or multiple random fields from a hash

The hash key

Promise that resolves with a random field name, or null if the hash doesn't exist

Get one or multiple random fields from a hash

The hash key

The number of fields to return (positive for unique fields, negative for potentially duplicate fields)

Promise that resolves with an array of random field names

Get one or multiple random fields with values from a hash

The hash key

The number of fields to return

Literal "WITHVALUES" to include values

Promise that resolves with an array of alternating field names and values

Incrementally iterate hash fields and values

The hash key

The cursor value (0 to start iteration)

Promise that resolves with [next_cursor, [field1, value1, field2, value2, ...]]

Incrementally iterate hash fields and values with pattern matching

The hash key

The cursor value (0 to start iteration)

Literal "MATCH"

Pattern to match field names against

Promise that resolves with [next_cursor, [field1, value1, field2, value2, ...]]

Incrementally iterate hash fields and values with count limit

The hash key

The cursor value (0 to start iteration)

Literal "COUNT"

Maximum number of fields to return per call

Promise that resolves with [next_cursor, [field1, value1, field2, value2, ...]]

Incrementally iterate hash fields and values with pattern and count

The hash key

The cursor value (0 to start iteration)

Literal "MATCH"

Pattern to match field names against

Literal "COUNT"

Maximum number of fields to return per call

Promise that resolves with [next_cursor, [field1, value1, field2, value2, ...]]

Set the value of a hash field or multiple fields

The hash key

Object/Record with field-value pairs

Promise that resolves with the number of fields that were added

Set the value of a hash field or multiple fields (variadic)

The hash key

The field name

The value to set

Additional field-value pairs

Promise that resolves with the number of fields that were added

Set hash fields with expiration options (Redis 8.0.0+) Syntax: HSETEX key [FNX | FXX] [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL] FIELDS numfields field value [field value ...]

redis.hsetex("mykey", "FIELDS", 1, "field1", "value1")

Set hash fields with expiration options (Redis 8.0.0+) Syntax: HSETEX key [FNX | FXX] [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL] FIELDS numfields field value [field value ...]

redis.hsetex("mykey", "FIELDS", 1, "field1", "value1")

Set hash fields with expiration options (Redis 8.0.0+) Syntax: HSETEX key [FNX | FXX] [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL] FIELDS numfields field value [field value ...]

redis.hsetex("mykey", "FIELDS", 1, "field1", "value1")

Set hash fields with expiration options (Redis 8.0.0+) Syntax: HSETEX key [FNX | FXX] [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL] FIELDS numfields field value [field value ...]

redis.hsetex("mykey", "FIELDS", 1, "field1", "value1")

Set hash fields with expiration options (Redis 8.0.0+) Syntax: HSETEX key [FNX | FXX] [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL] FIELDS numfields field value [field value ...]

redis.hsetex("mykey", "FIELDS", 1, "field1", "value1")

Set hash fields with expiration options (Redis 8.0.0+) Syntax: HSETEX key [FNX | FXX] [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL] FIELDS numfields field value [field value ...]

redis.hsetex("mykey", "FIELDS", 1, "field1", "value1")

Set hash fields with expiration options (Redis 8.0.0+) Syntax: HSETEX key [FNX | FXX] [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL] FIELDS numfields field value [field value ...]

redis.hsetex("mykey", "FIELDS", 1, "field1", "value1")

Set hash fields with expiration options (Redis 8.0.0+) Syntax: HSETEX key [FNX | FXX] [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL] FIELDS numfields field value [field value ...]

redis.hsetex("mykey", "FIELDS", 1, "field1", "value1")

Set hash fields with expiration options (Redis 8.0.0+) Syntax: HSETEX key [FNX | FXX] [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL] FIELDS numfields field value [field value ...]

redis.hsetex("mykey", "FIELDS", 1, "field1", "value1")

Set hash fields with expiration options (Redis 8.0.0+) Syntax: HSETEX key [FNX | FXX] [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL] FIELDS numfields field value [field value ...]

redis.hsetex("mykey", "FIELDS", 1, "field1", "value1")

Set hash fields with expiration options (Redis 8.0.0+) Syntax: HSETEX key [FNX | FXX] [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL] FIELDS numfields field value [field value ...]

redis.hsetex("mykey", "FIELDS", 1, "field1", "value1")

Set hash fields with expiration options (Redis 8.0.0+) Syntax: HSETEX key [FNX | FXX] [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL] FIELDS numfields field value [field value ...]

redis.hsetex("mykey", "FIELDS", 1, "field1", "value1")

Set hash fields with expiration options (Redis 8.0.0+) Syntax: HSETEX key [FNX | FXX] [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL] FIELDS numfields field value [field value ...]

redis.hsetex("mykey", "FIELDS", 1, "field1", "value1")

Set hash fields with expiration options (Redis 8.0.0+) Syntax: HSETEX key [FNX | FXX] [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL] FIELDS numfields field value [field value ...]

redis.hsetex("mykey", "FIELDS", 1, "field1", "value1")

Set hash fields with expiration options (Redis 8.0.0+) Syntax: HSETEX key [FNX | FXX] [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL] FIELDS numfields field value [field value ...]

redis.hsetex("mykey", "FIELDS", 1, "field1", "value1")

Set hash fields with expiration options (Redis 8.0.0+) Syntax: HSETEX key [FNX | FXX] [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL] FIELDS numfields field value [field value ...]

redis.hsetex("mykey", "FIELDS", 1, "field1", "value1")

Set hash fields with expiration options (Redis 8.0.0+) Syntax: HSETEX key [FNX | FXX] [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL] FIELDS numfields field value [field value ...]

redis.hsetex("mykey", "FIELDS", 1, "field1", "value1")

Set hash fields with expiration options (Redis 8.0.0+) Syntax: HSETEX key [FNX | FXX] [EX seconds | PX milliseconds | EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL] FIELDS numfields field value [field value ...]

redis.hsetex("mykey", "FIELDS", 1, "field1", "value1")

Set the value of a hash field, only if the field does not exist

The hash key

The field to set

The value to set

Promise that resolves with true if field was set, false if field already exists

Get the string length of the value stored in a hash field

The hash key

The field name

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

Get TTL of hash fields in seconds (Redis 7.4+) Syntax: HTTL key FIELDS numfields field [field ...]

Array where each element is: -2 (field doesn't exist), -1 (no expiration), TTL in seconds

redis.httl("mykey", "FIELDS", 2, "field1", "field2")

Get all values in a hash

The hash key

Promise that resolves with an array of values

Increment the integer value of a key by one

The key to increment

Promise that resolves with the new value

Increment the integer value of a key by the given amount

The key to increment

The amount to increment by

Promise that resolves with the new value after incrementing

Increment the float value of a key by the given amount

The key to increment

The amount to increment by (can be a float)

Promise that resolves with the new value as a string after incrementing

Find all keys matching the given pattern

The pattern to match

Promise that resolves with an array of matching keys

Get element at index from a list

The list key

Zero-based index (negative indexes count from the end, -1 is last element)

Promise that resolves with the element at index, or null if index is out of range

await redis.lpush("mylist", "three", "two", "one");
console.log(await redis.lindex("mylist", 0)); // "one"
console.log(await redis.lindex("mylist", -1)); // "three"
console.log(await redis.lindex("mylist", 5)); // null

Insert an element before or after another element in a list

The list key

"BEFORE" or "AFTER" to specify where to insert

The pivot element to insert before or after

The element to insert

Promise that resolves with the length of the list after insert, -1 if pivot not found, or 0 if key doesn't exist

await redis.lpush("mylist", "World");
await redis.lpush("mylist", "Hello");
await redis.linsert("mylist", "BEFORE", "World", "There");
// List is now: ["Hello", "There", "World"]

Get the length of a list

The list key

Promise that resolves with the length of the list

Atomically pop an element from a source list and push it to a destination list

Pops an element from the source list (from LEFT or RIGHT) and pushes it to the destination list (to LEFT or RIGHT).

The source list key

The destination list key

Direction to pop from source: "LEFT" (head) or "RIGHT" (tail)

Direction to push to destination: "LEFT" (head) or "RIGHT" (tail)

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

await redis.lpush("source", "a", "b", "c");
const result1 = await redis.lmove("source", "dest", "LEFT", "RIGHT");
// result1: "c" (popped from head of source, pushed to tail of dest)

const result2 = await redis.lmove("source", "dest", "RIGHT", "LEFT");
// result2: "a" (popped from tail of source, pushed to head of dest)

Pop one or more elements from one or more lists

Pops elements from the first non-empty list in the specified order (LEFT = from head, RIGHT = from tail). Optionally specify COUNT to pop multiple elements at once.

The number of keys that follow

Keys followed by LEFT or RIGHT, optionally followed by "COUNT" and count value

Promise that resolves with [key, [elements]] or null if all lists are empty

await redis.lpush("list1", "a", "b", "c");
const result1 = await redis.lmpop(1, "list1", "LEFT");
// result1: ["list1", ["c"]]

const result2 = await redis.lmpop(1, "list1", "RIGHT", "COUNT", 2);
// result2: ["list1", ["a", "b"]]

const result3 = await redis.lmpop(2, "emptylist", "list1", "LEFT");
// result3: null (if both lists are empty)

Remove and get the first element in a list

The list key

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

Remove and get the first count elements in a list

The list key

Promise that resolves with a list of elements, or null if the list doesn't exist

Find the position(s) of an element in a list

Returns the index of matching elements inside a Redis list. By default, returns the index of the first match. Use RANK to find the nth occurrence, COUNT to get multiple positions, and MAXLEN to limit the search.

The list key

The element to search for

Optional arguments: "RANK", rank, "COUNT", num, "MAXLEN", len

Promise that resolves with the index (number), an array of indices (number[]), or null if element is not found. Returns array when COUNT option is used.

await redis.lpush("mylist", "a", "b", "c", "b", "d");
const pos1 = await redis.lpos("mylist", "b");
// pos1: 1 (first occurrence of "b")

const pos2 = await redis.lpos("mylist", "b", "RANK", 2);
// pos2: 3 (second occurrence of "b")

const positions = await redis.lpos("mylist", "b", "COUNT", 0);
// positions: [1, 3] (all occurrences of "b")

const pos3 = await redis.lpos("mylist", "x");
// pos3: null (element not found)

Prepend one or multiple values to a list

The list key

The value to prepend

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

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

The list key

The value to prepend

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

Get a range of elements from a list

The list key

Zero-based start index (negative indexes count from the end)

Zero-based stop index (negative indexes count from the end)

Promise that resolves with array of elements in the specified range

await redis.lpush("mylist", "three", "two", "one");
console.log(await redis.lrange("mylist", 0, -1)); // ["one", "two", "three"]
console.log(await redis.lrange("mylist", 0, 1)); // ["one", "two"]
console.log(await redis.lrange("mylist", -2, -1)); // ["two", "three"]

Remove elements from a list

The list key

Number of elements to remove

The element to remove

Promise that resolves with the number of elements removed

await redis.rpush("mylist", "hello", "hello", "world", "hello");
await redis.lrem("mylist", 2, "hello"); // Removes first 2 "hello"
// List is now: ["world", "hello"]

Set element at index in a list

The list key

Zero-based index (negative indexes count from the end)

The value to set

Promise that resolves with "OK" on success

await redis.lpush("mylist", "three", "two", "one");
await redis.lset("mylist", 0, "zero");
console.log(await redis.lrange("mylist", 0, -1)); // ["zero", "two", "three"]
await redis.lset("mylist", -1, "last");
console.log(await redis.lrange("mylist", 0, -1)); // ["zero", "two", "last"]

Trim a list to the specified range

The list key

The start index (0-based, can be negative)

The stop index (0-based, can be negative)

Promise that resolves with "OK"

await redis.rpush("mylist", "one", "two", "three", "four");
await redis.ltrim("mylist", 1, 2);
// List is now: ["two", "three"]

Get the values of all specified keys

The keys to get

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

Set multiple keys to multiple values atomically

Sets the given keys to their respective values. MSET replaces existing values with new values, just as regular SET. Use MSETNX if you don't want to overwrite existing values.

MSET is atomic, so all given keys are set at once. It is not possible for clients to see that some of the keys were updated while others are unchanged.

Alternating keys and values (key1, value1, key2, value2, ...)

Promise that resolves with "OK" on success

await redis.mset("key1", "value1", "key2", "value2");

Set multiple keys to multiple values, only if none of the keys exist

Sets the given keys to their respective values. MSETNX will not perform any operation at all even if just a single key already exists.

Because of this semantic, MSETNX can be used in order to set different keys representing different fields of a unique logic object in a way that ensures that either all the fields or none at all are set.

MSETNX is atomic, so all given keys are set at once. It is not possible for clients to see that some of the keys were updated while others are unchanged.

Alternating keys and values (key1, value1, key2, value2, ...)

Promise that resolves with 1 if all keys were set, 0 if no key was set

// Returns 1 if keys don't exist
await redis.msetnx("key1", "value1", "key2", "value2");

// Returns 0 if any key already exists
await redis.msetnx("key1", "newvalue", "key3", "value3");

Remove the expiration from a key

The key to persist

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

Set a key's time to live in milliseconds

The key to set the expiration for

The number of milliseconds until expiration

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

Set the expiration for a key as a Unix timestamp in milliseconds

The key to set expiration on

Unix timestamp in milliseconds when the key should expire

Promise that resolves with 1 if timeout was set, 0 if key does not exist

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

The key to check

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

Add one or more members to a HyperLogLog

The HyperLogLog key

The element to add

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

Ping the server

Promise that resolves with "PONG" if the server is reachable, or throws an error if the server is not reachable

Ping the server with a message

The message to send to the server

Promise that resolves with the message if the server is reachable, or throws an error if the server is not reachable

Set key to hold the string value with expiration time in milliseconds

The key to set

The expiration time in milliseconds

The value to set

Promise that resolves with "OK" on success

await redis.psetex("mykey", 10000, "Hello");
// Key will expire after 10000 milliseconds (10 seconds)

Get the time to live for a key in milliseconds

The key to check

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

Publish a message to a Redis channel.

The channel to publish to.

The message to publish.

The number of clients that received the message. Note that in a cluster this returns the total number of clients in the same node.

Return a random key from the keyspace

Returns a random key from the currently selected database.

Promise that resolves with a random key name, or null if the database is empty

await redis.set("key1", "value1");
await redis.set("key2", "value2");
await redis.set("key3", "value3");
const randomKey = await redis.randomkey();
console.log(randomKey); // One of: "key1", "key2", or "key3"

Rename a key to a new key

Renames key to newkey. If newkey already exists, it is overwritten. If key does not exist, an error is returned.

The key to rename

The new key name

Promise that resolves with "OK" on success

await redis.set("mykey", "Hello");
await redis.rename("mykey", "myotherkey");
const value = await redis.get("myotherkey"); // "Hello"
const oldValue = await redis.get("mykey"); // null

Rename a key to a new key only if the new key does not exist

Renames key to newkey only if newkey does not yet exist. If key does not exist, an error is returned.

The key to rename

The new key name

Promise that resolves with 1 if the key was renamed, 0 if newkey already exists

await redis.set("mykey", "Hello");
await redis.renamenx("mykey", "myotherkey"); // Returns 1
await redis.set("mykey2", "World");
await redis.renamenx("mykey2", "myotherkey"); // Returns 0 (myotherkey exists)

Remove and get the last element in a list

The list key

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

Remove and get the last element in a list

The list key

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

Atomically pop the last element from a source list and push it to the head of a destination list

This is equivalent to LMOVE with "RIGHT" "LEFT". It's an atomic operation that removes the last element (tail) from the source list and pushes it to the head of the destination list.

The source list key

The destination list key

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

await redis.lpush("source", "a", "b", "c");
// source: ["c", "b", "a"]

const result = await redis.rpoplpush("source", "dest");
// result: "a" (removed from tail of source, added to head of dest)
// source: ["c", "b"]
// dest: ["a"]

Append one or multiple values to a list

The list key

The value to append

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

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

The list key

The value to append

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

Add one or more members to a set

The set key

The members to add

Promise that resolves with the number of members added

Incrementally iterate the keyspace

The SCAN command is used to incrementally iterate over a collection of elements. SCAN iterates the set of keys in the currently selected Redis database.

SCAN is a cursor based iterator. This means that at every call of the command, the server returns an updated cursor that the user needs to use as the cursor argument in the next call.

An iteration starts when the cursor is set to "0", and terminates when the cursor returned by the server is "0".

The cursor value (use "0" to start a new iteration)

Promise that resolves with a tuple [cursor, keys[]] where cursor is the next cursor to use (or "0" if iteration is complete) and keys is an array of matching keys

// Basic scan - iterate all keys
let cursor = "0";
const allKeys: string[] = [];
do {
const [nextCursor, keys] = await redis.scan(cursor);
allKeys.push(...keys);
cursor = nextCursor;
} while (cursor !== "0");

Incrementally iterate the keyspace with a pattern match

The cursor value (use "0" to start a new iteration)

The "MATCH" keyword

The pattern to match (supports glob-style patterns like "user:*")

Promise that resolves with a tuple [cursor, keys[]]

Incrementally iterate the keyspace with a count hint

The cursor value (use "0" to start a new iteration)

The "COUNT" keyword

The number of elements to return per call (hint only, not exact)

Promise that resolves with a tuple [cursor, keys[]]

Incrementally iterate the keyspace with pattern match and count hint

The cursor value (use "0" to start a new iteration)

The "MATCH" keyword

The pattern to match

The "COUNT" keyword

The number of elements to return per call

Promise that resolves with a tuple [cursor, keys[]]

Incrementally iterate the keyspace with options

The cursor value

Additional SCAN options (MATCH pattern, COUNT hint, etc.)

Promise that resolves with a tuple [cursor, keys[]]

Get the number of members in a set

The set key

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

Get the difference of multiple sets

The first set key

Additional set keys to subtract from the first set

Promise that resolves with an array of members in the difference

Store the difference of multiple sets in a key

The destination key to store the result

The first set key

Additional set keys to subtract from the first set

Promise that resolves with the number of elements in the resulting set

Send a raw command to the Redis server

The command to send

The arguments to the command

A promise that resolves with the command result

Set key to hold the string value

The key to set

The value to set

Promise that resolves with "OK" on success

Set key to hold the string value with expiration

The key to set

The value to set

Set the specified expire time, in seconds

Promise that resolves with "OK" on success

Set key to hold the string value with expiration

The key to set

The value to set

Set the specified expire time, in milliseconds

Promise that resolves with "OK" on success

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

The key to set

The value to set

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

Promise that resolves with "OK" on success

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

The key to set

The value to set

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

Promise that resolves with "OK" on success

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

The key to set

The value to set

Only set the key if it does not already exist

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

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

The key to set

The value to set

Only set the key if it already exists

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

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

The key to set

The value to set

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

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

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

The key to set

The value to set

Retain the time to live associated with the key

Promise that resolves with "OK" on success

Set key to hold the string value with various options

The key to set

The value to set

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

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

Sets or clears the bit at offset in the string value stored at key

The key to modify

The bit offset (zero-based)

The bit value to set (0 or 1)

Promise that resolves with the original bit value stored at offset

Set key to hold the string value with expiration time in seconds

The key to set

The expiration time in seconds

The value to set

Promise that resolves with "OK" on success

await redis.setex("mykey", 10, "Hello");
// Key will expire after 10 seconds

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

The key to set

The value to set

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

Overwrite part of a string at key starting at the specified offset

The key to modify

The offset at which to start overwriting (zero-based)

The string value to write at the offset

Promise that resolves with the length of the string after modification

Get the intersection of multiple sets

The first set key

Additional set keys to intersect

Promise that resolves with an array of members in the intersection

Get the cardinality of the intersection of multiple sets

The number of keys to intersect

The first set key

Additional set keys and optional LIMIT argument

Promise that resolves with the number of elements in the intersection

Store the intersection of multiple sets in a key

The destination key to store the result

The first set key

Additional set keys to intersect

Promise that resolves with the number of elements in the resulting set

Check if a value is a member of a set

The set key

The member to check

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

Get all the members in a set

The set key

Promise that resolves with an array of all members

Check if multiple members are members of a set

The set key

The first member to check

Additional members to check

Promise that resolves with an array of 1s and 0s indicating membership

Move a member from one set to another

The source set key

The destination set key

The member to move

Promise that resolves with true if the element was moved, false if it wasn't a member of source

Remove and return a random member from a set

The set key

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

Remove and return count members from the set

The set key

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

Post a message to a shard channel

The shard channel name

The message to publish

Promise that resolves with the number of clients that received the message

Get a random member from a set

The set key

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

Get count random members from a set

The set key

Promise that resolves with an array of up to count random members, or null if the set doesn't exist

Remove one or more members from a set

The set key

The members to remove

Promise that resolves with the number of members removed

Incrementally iterate over a set

The set key

The cursor value

Additional SSCAN options (MATCH pattern, COUNT hint)

Promise that resolves with a tuple [cursor, members[]]

Get the length of the value stored in a key

The key to check

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

Subscribe to a Redis channel.

Subscribing disables automatic pipelining, so all commands will be received immediately.

Subscribing moves the channel to a dedicated subscription state which prevents most other commands from being executed until unsubscribed. Only .ping(), .subscribe(), and .unsubscribe() are legal to invoke in a subscribed upon channel.

The channel to subscribe to.

The listener to call when a message is received on the channel. The listener will receive the message as the first argument and the channel as the second argument.

await client.subscribe("my-channel", (message, channel) => {
console.log(`Received message on ${channel}: ${message}`);
});

Subscribe to multiple Redis channels.

Subscribing disables automatic pipelining, so all commands will be received immediately.

Subscribing moves the channels to a dedicated subscription state in which only a limited set of commands can be executed.

An array of channels to subscribe to.

The listener to call when a message is received on any of the subscribed channels. The listener will receive the message as the first argument and the channel as the second argument.

Get the union of multiple sets

The first set key

Additional set keys to union

Promise that resolves with an array of members in the union

Store the union of multiple sets in a key

The destination key to store the result

The first set key

Additional set keys to union

Promise that resolves with the number of elements in the resulting set

Alters the last access time of one or more keys

A key is ignored if it does not exist. The command returns the number of keys that were touched.

This command is useful in conjunction with maxmemory-policy allkeys-lru / volatile-lru to change the last access time of keys for eviction purposes.

One or more keys to touch

Promise that resolves with the number of keys that were touched

await redis.set("key1", "Hello");
await redis.set("key2", "World");
const touched = await redis.touch("key1", "key2", "key3");
console.log(touched); // 2 (key3 doesn't exist)

Get the time to live for a key in seconds

The key to get the TTL for

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

Determine the type of value stored at key

The TYPE command returns the string representation of the type of the value stored at key. The different types that can be returned are: string, list, set, zset, hash and stream.

The key to check

Promise that resolves with the type of value stored at key, or "none" if the key doesn't exist

await redis.set("mykey", "Hello");
console.log(await redis.type("mykey")); // "string"

await redis.lpush("mylist", "value");
console.log(await redis.type("mylist")); // "list"

await redis.sadd("myset", "value");
console.log(await redis.type("myset")); // "set"

await redis.hset("myhash", "field", "value");
console.log(await redis.type("myhash")); // "hash"

console.log(await redis.type("nonexistent")); // "none"

Asynchronously delete one or more keys

This command is very similar to DEL: it removes the specified keys. Just like DEL a key is ignored if it does not exist. However, the command performs the actual memory reclaiming in a different thread, so it is not blocking, while DEL is. This is particularly useful when deleting large values or large numbers of keys.

The keys to delete

Promise that resolves with the number of keys that were unlinked

await redis.set("key1", "Hello");
await redis.set("key2", "World");
const count = await redis.unlink("key1", "key2", "key3");
console.log(count); // 2

Unsubscribe from a singular Redis channel.

The channel to unsubscribe from.

If there are no more channels subscribed to, the client automatically re-enables pipelining if it was previously enabled.

Unsubscribing moves the channel back to a normal state out of the subscription state if all channels have been unsubscribed from. For further details on the subscription state, see .subscribe().

Remove a listener from a given Redis channel.

If there are no more channels subscribed to, the client automatically re-enables pipelining if it was previously enabled.

Unsubscribing moves the channel back to a normal state out of the subscription state if all channels have been unsubscribed from. For further details on the subscription state, see .subscribe().

The channel to unsubscribe from.

The listener to remove. This is tested against referential equality so you must pass the exact same listener instance as when subscribing.

Unsubscribe from all registered Redis channels.

The client will automatically re-enable pipelining if it was previously enabled.

Unsubscribing moves the channel back to a normal state out of the subscription state if all channels have been unsubscribed from. For further details on the subscription state, see .subscribe().

Unsubscribe from multiple Redis channels.

An array of channels to unsubscribe from.

If there are no more channels subscribed to, the client automatically re-enables pipelining if it was previously enabled.

Unsubscribing moves the channel back to a normal state out of the subscription state if all channels have been unsubscribed from. For further details on the subscription state, see .subscribe().

Add one or more members to a sorted set, or update scores if they already exist

ZADD adds all the specified members with the specified scores to the sorted set stored at key. It is possible to specify multiple score / member pairs. If a specified member is already a member of the sorted set, the score is updated and the element reinserted at the right position to ensure the correct ordering.

If key does not exist, a new sorted set with the specified members as sole members is created. If the key exists but does not hold a sorted set, an error is returned.

The score values should be the string representation of a double precision floating point number. +inf and -inf values are valid values as well.

Options:

Note: The GT, LT and NX options are mutually exclusive.

The sorted set key

Score-member pairs and optional flags (NX, XX, GT, LT, CH, INCR)

Promise that resolves with the number of elements added (or changed if CH is used, or new score if INCR is used)

// Add members with scores
await redis.zadd("myzset", "1", "one", "2", "two", "3", "three");

// Add with NX option (only if member doesn't exist)
await redis.zadd("myzset", "NX", "4", "four");

// Add with XX option (only if member exists)
await redis.zadd("myzset", "XX", "2.5", "two");

// Add with CH option (return count of changed elements)
await redis.zadd("myzset", "CH", "5", "five", "2.1", "two");

// Use INCR option (increment score)
await redis.zadd("myzset", "INCR", "1.5", "one");

Get the number of members in a sorted set

The sorted set key

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

Count the members in a sorted set with scores within the given range

The sorted set key

Minimum score (inclusive, use "-inf" for negative infinity)

Maximum score (inclusive, use "+inf" for positive infinity)

Promise that resolves with the count of elements in the specified score range

Compute the difference between sorted sets with scores

The number of sorted set keys

Promise that resolves with an array of [member, score] pairs

await redis.send("ZADD", ["zset1", "1", "one", "2", "two", "3", "three"]);
await redis.send("ZADD", ["zset2", "1", "one", "2", "two"]);
const diff = await redis.zdiff(2, "zset1", "zset2", "WITHSCORES");
console.log(diff); // ["three", "3"]

Compute the difference between the first sorted set and all successive sorted sets

Returns the members of the sorted set resulting from the difference between the first sorted set and all the successive sorted sets. The first key is the only one used to compute the members of the difference.

The number of sorted set keys

The sorted set keys to compare

Promise that resolves with an array of members

await redis.send("ZADD", ["zset1", "1", "one", "2", "two", "3", "three"]);
await redis.send("ZADD", ["zset2", "1", "one", "2", "two"]);
const diff = await redis.zdiff(2, "zset1", "zset2");
console.log(diff); // ["three"]

Compute the difference between sorted sets and store the result

Computes the difference between the first and all successive sorted sets given by the specified keys and stores the result in destination. Keys that do not exist are considered to be empty sets.

The destination key to store the result

The number of input sorted set keys

The sorted set keys to compare

Promise that resolves with the number of elements in the resulting sorted set

await redis.send("ZADD", ["zset1", "1", "one", "2", "two", "3", "three"]);
await redis.send("ZADD", ["zset2", "1", "one"]);
const count = await redis.zdiffstore("out", 2, "zset1", "zset2");
console.log(count); // 2 (two, three)

Increment the score of a member in a sorted set

The sorted set key

The increment value

The member to increment

Promise that resolves with the new score

Compute the intersection of multiple sorted sets

Returns the members of the set resulting from the intersection of all the given sorted sets. Keys that do not exist are considered to be empty sets.

By default, the resulting score of each member is the sum of its scores in the sorted sets where it exists.

Options:

The number of input keys (sorted sets)

Promise that resolves with an array of members (or [member, score] pairs if WITHSCORES)

// Set up sorted sets
await redis.zadd("zset1", "1", "a", "2", "b", "3", "c");
await redis.zadd("zset2", "1", "b", "2", "c", "3", "d");

// Basic intersection - returns members that exist in all sets
const result1 = await redis.zinter(2, "zset1", "zset2");
// Returns: ["b", "c"]

// With scores (sum by default)
const result2 = await redis.zinter(2, "zset1", "zset2", "WITHSCORES");
// Returns: ["b", "3", "c", "5"] (b: 2+1=3, c: 3+2=5)

// With weights
const result3 = await redis.zinter(2, "zset1", "zset2", "WEIGHTS", "2", "3", "WITHSCORES");
// Returns: ["b", "7", "c", "12"] (b: 2*2+1*3=7, c: 3*2+2*3=12)

// With MIN aggregation
const result4 = await redis.zinter(2, "zset1", "zset2", "AGGREGATE", "MIN", "WITHSCORES");
// Returns: ["b", "1", "c", "2"] (minimum scores)

Compute the intersection of multiple sorted sets

Returns the members of the set resulting from the intersection of all the given sorted sets. Keys that do not exist are considered to be empty sets.

By default, the resulting score of each member is the sum of its scores in the sorted sets where it exists.

Options:

The number of input keys (sorted sets)

Promise that resolves with an array of members (or [member, score] pairs if WITHSCORES)

// Set up sorted sets
await redis.zadd("zset1", "1", "a", "2", "b", "3", "c");
await redis.zadd("zset2", "1", "b", "2", "c", "3", "d");

// Basic intersection - returns members that exist in all sets
const result1 = await redis.zinter(2, "zset1", "zset2");
// Returns: ["b", "c"]

// With scores (sum by default)
const result2 = await redis.zinter(2, "zset1", "zset2", "WITHSCORES");
// Returns: ["b", "3", "c", "5"] (b: 2+1=3, c: 3+2=5)

// With weights
const result3 = await redis.zinter(2, "zset1", "zset2", "WEIGHTS", "2", "3", "WITHSCORES");
// Returns: ["b", "7", "c", "12"] (b: 2*2+1*3=7, c: 3*2+2*3=12)

// With MIN aggregation
const result4 = await redis.zinter(2, "zset1", "zset2", "AGGREGATE", "MIN", "WITHSCORES");
// Returns: ["b", "1", "c", "2"] (minimum scores)

Count the number of members in the intersection of multiple sorted sets

Computes the cardinality of the intersection of the sorted sets at the specified keys. The intersection includes only elements that exist in all of the given sorted sets.

When a LIMIT is provided, the command stops counting once the limit is reached, which is useful for performance when you only need to know if the cardinality exceeds a certain threshold.

The number of sorted set keys

The sorted set keys to intersect

Promise that resolves with the number of elements in the intersection

await redis.send("ZADD", ["zset1", "1", "one", "2", "two", "3", "three"]);
await redis.send("ZADD", ["zset2", "1", "one", "2", "two", "4", "four"]);
const count = await redis.zintercard(2, "zset1", "zset2");
console.log(count); // 2 (one, two)

Count the number of members in the intersection with a limit

The number of sorted set keys

Promise that resolves with the number of elements (up to limit)

await redis.send("ZADD", ["zset1", "1", "a", "2", "b", "3", "c"]);
await redis.send("ZADD", ["zset2", "1", "a", "2", "b", "3", "c"]);
const count = await redis.zintercard(2, "zset1", "zset2", "LIMIT", 2);
console.log(count); // 2 (stopped at limit)

Compute the intersection of multiple sorted sets and store in destination

This command is similar to ZINTER, but instead of returning the result, it stores it in the destination key. If the destination key already exists, it is overwritten.

Options:

The destination key to store the result

The number of input keys (sorted sets)

Promise that resolves with the number of elements in the resulting sorted set

// Set up sorted sets
await redis.zadd("zset1", "1", "a", "2", "b", "3", "c");
await redis.zadd("zset2", "1", "b", "2", "c", "3", "d");

// Basic intersection store
const count1 = await redis.zinterstore("out", 2, "zset1", "zset2");
// Returns: 2 (stored "b" and "c" in "out")

// With weights
const count2 = await redis.zinterstore("out2", 2, "zset1", "zset2", "WEIGHTS", "2", "3");
// Returns: 2

// With MAX aggregation
const count3 = await redis.zinterstore("out3", 2, "zset1", "zset2", "AGGREGATE", "MAX");
// Returns: 2 (stores maximum scores)

Count the members in a sorted set within a lexicographical range

The sorted set key

Minimum value (use "[" for inclusive, "(" for exclusive, e.g., "[aaa")

Maximum value (use "[" for inclusive, "(" for exclusive, e.g., "[zzz")

Promise that resolves with the count of elements in the specified range

Remove and return members with scores from one or more sorted sets. Pops from the first non-empty sorted set.

// Pop lowest score from one set
const result1 = await redis.zmpop(1, "myzset", "MIN");
// Returns: ["myzset", [["member1", 1]]]

// Pop highest score from multiple sets
const result2 = await redis.zmpop(2, "zset1", "zset2", "MAX");
// Returns: ["zset1", [["member5", 5]]] (pops from first non-empty)

// Pop multiple members
const result3 = await redis.zmpop(1, "myzset", "MIN", "COUNT", 3);
// Returns: ["myzset", [["member1", 1], ["member2", 2], ["member3", 3]]]

// Empty set returns null
const result4 = await redis.zmpop(1, "emptyset", "MIN");
// Returns: null

Returns the scores associated with the specified members in the sorted set

The sorted set key

The first member to get the score for

Additional members to get scores for

Promise that resolves with an array of scores (number for each score, or null if member doesn't exist)

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

The sorted set key

Promise that resolves with either [member, score] or empty array if the set is empty

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

The sorted set key

Optional number of members to pop (default: 1)

Promise that resolves with an array of [member, score] tuples

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

The sorted set key

Promise that resolves with array of [member, score] tuples, or empty array if the set is empty

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

The sorted set key

Optional number of members to pop (default: 1)

Promise that resolves with an array of [member, score] tuples

Get one or multiple random members from a sorted set

The sorted set key

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

Get one or multiple random members from a sorted set

The sorted set key

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

Get one or multiple random members from a sorted set, with scores

The sorted set key

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

Return a range of members in a sorted set with their scores

The sorted set key

The starting index

The stopping index

Return members with their scores

Promise that resolves with an array of [member, score, member, score, ...]

const results = await redis.zrange("myzset", 0, -1, "WITHSCORES");
// Returns ["member1", "1.5", "member2", "2.5", ...]

Return a range of members in a sorted set by score

The sorted set key

The minimum score (use "-inf" for negative infinity, "(" prefix for exclusive)

The maximum score (use "+inf" for positive infinity, "(" prefix for exclusive)

Indicates score-based range

Promise that resolves with an array of members with scores in the range

// Get members with score between 1 and 3
const members = await redis.zrange("myzset", "1", "3", "BYSCORE");

// Get members with score > 1 and
const members2 = await redis.zrange("myzset", "(1", "3", "BYSCORE");

Return a range of members in a sorted set lexicographically

The sorted set key

The minimum lexicographical value (use "-" for start, "[" for inclusive, "(" for exclusive)

The maximum lexicographical value (use "+" for end, "[" for inclusive, "(" for exclusive)

Indicates lexicographical range

Promise that resolves with an array of members in the lexicographical range

// Get members lexicographically from "a" to "c" (inclusive)
const members = await redis.zrange("myzset", "[a", "[c", "BYLEX");

Return a range of members in a sorted set with various options

The sorted set key

The starting value (index, score, or lex depending on options)

The stopping value

Additional options (BYSCORE, BYLEX, REV, LIMIT offset count, WITHSCORES)

Promise that resolves with an array of members (or with scores if WITHSCORES)

// Get members by score with limit
const members = await redis.zrange("myzset", "1", "10", "BYSCORE", "LIMIT", "0", "5");

// Get members in reverse order with scores
const reversed = await redis.zrange("myzset", "0", "-1", "REV", "WITHSCORES");

Return a range of members in a sorted set

Returns the specified range of elements in the sorted set stored at key. The elements are considered to be ordered from the lowest to the highest score by default.

The sorted set key

The starting index (0-based, can be negative to count from end)

The stopping index (0-based, can be negative to count from end)

Promise that resolves with an array of members in the specified range

// Get all members
const members = await redis.zrange("myzset", 0, -1);

// Get first 3 members
const top3 = await redis.zrange("myzset", 0, 2);

Return members in a sorted set within a lexicographical range

When all the elements in a sorted set have the same score, this command returns the elements between min and max in lexicographical order.

Lex ranges:

The sorted set key (all members must have the same score)

Minimum lexicographical value (use "-" for negative infinity, "[" or "(" for inclusive/exclusive)

Maximum lexicographical value (use "+" for positive infinity, "[" or "(" for inclusive/exclusive)

Promise that resolves with array of members

await redis.send("ZADD", ["myzset", "0", "apple", "0", "banana", "0", "cherry"]);
const members = await redis.zrangebylex("myzset", "[banana", "[cherry");
// Returns: ["banana", "cherry"]

Return members in a sorted set within a lexicographical range, with pagination

The sorted set key

Minimum lexicographical value

Maximum lexicographical value

The "LIMIT" keyword

The number of elements to skip

The maximum number of elements to return

Promise that resolves with array of members

await redis.send("ZADD", ["myzset", "0", "a", "0", "b", "0", "c", "0", "d"]);
const result = await redis.zrangebylex("myzset", "-", "+", "LIMIT", 1, 2);
// Returns: ["b", "c"]

Return members in a sorted set within a lexicographical range, with options

The sorted set key

Minimum lexicographical value

Maximum lexicographical value

Additional options (LIMIT offset count)

Promise that resolves with array of members

Return members in a sorted set with scores within a given range

Returns all the elements in the sorted set at key with a score between min and max (inclusive by default). The elements are considered to be ordered from low to high scores.

Score ranges support:

The sorted set key

Minimum score (can be "-inf", a number, or prefixed with "(" for exclusive)

Maximum score (can be "+inf", a number, or prefixed with "(" for exclusive)

Promise that resolves with array of members

await redis.send("ZADD", ["myzset", "1", "one", "2", "two", "3", "three"]);
const members = await redis.zrangebyscore("myzset", 1, 2);
// Returns: ["one", "two"]

Return members in a sorted set with scores within a given range, with scores

The sorted set key

Minimum score

Maximum score

The "WITHSCORES" keyword to return scores along with members

Promise that resolves with array of [member, score, member, score, ...]

await redis.send("ZADD", ["myzset", "1", "one", "2", "two", "3", "three"]);
const result = await redis.zrangebyscore("myzset", 1, 2, "WITHSCORES");
// Returns: ["one", "1", "two", "2"]

Return members in a sorted set with scores within a given range, with pagination

The sorted set key

Minimum score

Maximum score

The "LIMIT" keyword

The number of elements to skip

The maximum number of elements to return

Promise that resolves with array of members

await redis.send("ZADD", ["myzset", "1", "one", "2", "two", "3", "three", "4", "four"]);
const result = await redis.zrangebyscore("myzset", "-inf", "+inf", "LIMIT", 1, 2);
// Returns: ["two", "three"]

Return members in a sorted set with scores within a given range, with the score values

The sorted set key

Minimum score

Maximum score

Additional options (WITHSCORES, LIMIT offset count)

Promise that resolves with array of members (and scores if WITHSCORES is used)

Return members in a sorted set with scores within a given range, with the score values

The sorted set key

Minimum score

Maximum score

Additional options (WITHSCORES, LIMIT offset count)

Promise that resolves with array of members (and scores if WITHSCORES is used)

Return members in a sorted set with scores within a given range, with various options

The sorted set key

Minimum score

Maximum score

Additional options (WITHSCORES, LIMIT offset count)

Promise that resolves with array of members (and scores if WITHSCORES is used)

Store a range of members from a sorted set into a destination key

This command is like ZRANGE but stores the result in a destination key instead of returning it. Supports all the same options as ZRANGE including BYSCORE, BYLEX, REV, and LIMIT.

The destination key to store results

The source sorted set key

The starting index or score

The ending index or score

Optional flags: ["BYSCORE"], ["BYLEX"], ["REV"], ["LIMIT", offset, count]

Promise that resolves with the number of elements in the resulting sorted set

// Add members to source set
await redis.send("ZADD", ["source", "1", "one", "2", "two", "3", "three"]);

// Store range by rank
const count1 = await redis.zrangestore("dest1", "source", 0, 1);
console.log(count1); // 2

// Store range by score
const count2 = await redis.zrangestore("dest2", "source", "1", "2", "BYSCORE");
console.log(count2); // 2

// Store in reverse order with limit
const count3 = await redis.zrangestore("dest3", "source", "0", "-1", "REV", "LIMIT", "0", "2");
console.log(count3); // 2

Determine the index of a member in a sorted set

The sorted set key

The member to find

Promise that resolves with the rank (index) of the member, or null if the member doesn't exist

Determine the index of a member in a sorted set with score

The sorted set key

The member to find

"WITHSCORE" to include the score

Promise that resolves with [rank, score] or null if the member doesn't exist

Remove one or more members from a sorted set

The sorted set key

The first member to remove

Additional members to remove

Promise that resolves with the number of members removed (not including non-existing members)

Remove all members in a sorted set within the given lexicographical range

The sorted set key

Minimum value (use "[" for inclusive, "(" for exclusive, e.g., "[aaa")

Maximum value (use "[" for inclusive, "(" for exclusive, e.g., "[zzz")

Promise that resolves with the number of elements removed

Remove all members in a sorted set within the given rank range

The sorted set key

Start rank (0-based, can be negative to indicate offset from end)

Stop rank (0-based, can be negative to indicate offset from end)

Promise that resolves with the number of elements removed

Remove all members in a sorted set within the given score range

The sorted set key

Minimum score (inclusive, use "-inf" for negative infinity, "(" prefix for exclusive)

Maximum score (inclusive, use "+inf" for positive infinity, "(" prefix for exclusive)

Promise that resolves with the number of elements removed

Return a range of members in a sorted set, by index, with scores ordered from high to low

This is equivalent to ZRANGE with the REV option. Returns members in reverse order.

The sorted set key

The starting index (0-based, can be negative to count from end)

The stopping index (0-based, can be negative to count from end)

Promise that resolves with an array of members in reverse order

// Get all members in reverse order (highest to lowest score)
const members = await redis.zrevrange("myzset", 0, -1);

// Get top 3 members with highest scores
const top3 = await redis.zrevrange("myzset", 0, 2);

Return a range of members in a sorted set with their scores, ordered from high to low

The sorted set key

The starting index

The stopping index

Return members with their scores

Promise that resolves with an array of [member, score, member, score, ...] in reverse order

const results = await redis.zrevrange("myzset", 0, -1, "WITHSCORES");
// Returns ["member3", "3.5", "member2", "2.5", "member1", "1.5", ...]

Return a range of members in a sorted set with options, ordered from high to low

The sorted set key

The starting index

The stopping index

Additional options (WITHSCORES)

Promise that resolves with an array of members (or with scores if WITHSCORES)

Return members in a sorted set within a lexicographical range, ordered from high to low

All members in a sorted set must have the same score for this command to work correctly. The max and min arguments have the same meaning as in ZRANGEBYLEX, but in reverse order.

Use "[" for inclusive bounds and "(" for exclusive bounds. Use "-" for negative infinity and "+" for positive infinity.

The sorted set key

The maximum lexicographical value (inclusive with "[", exclusive with "(")

The minimum lexicographical value (inclusive with "[", exclusive with "(")

Optional LIMIT clause: ["LIMIT", offset, count]

Promise that resolves with an array of members in reverse lexicographical order

// Add members with same score
await redis.send("ZADD", ["myzset", "0", "a", "0", "b", "0", "c", "0", "d"]);

// Get range from highest to lowest
const members = await redis.zrevrangebylex("myzset", "[d", "[b");
console.log(members); // ["d", "c", "b"]

// With LIMIT
const limited = await redis.zrevrangebylex("myzset", "+", "-", "LIMIT", "0", "2");
console.log(limited); // ["d", "c"] (first 2 members)

Return members in a sorted set with scores within a given range, ordered from high to low

Returns all the elements in the sorted set at key with a score between max and min (note: max comes before min). The elements are considered to be ordered from high to low scores.

Score ranges support:

The sorted set key

Maximum score (can be "+inf", a number, or prefixed with "(" for exclusive)

Minimum score (can be "-inf", a number, or prefixed with "(" for exclusive)

Promise that resolves with array of members

await redis.send("ZADD", ["myzset", "1", "one", "2", "two", "3", "three"]);
const members = await redis.zrevrangebyscore("myzset", 2, 1);
// Returns: ["two", "one"]

Return members in a sorted set with scores within a given range, ordered from high to low, with scores

The sorted set key

Maximum score

Minimum score

The "WITHSCORES" keyword to return scores along with members

Promise that resolves with array of [member, score, member, score, ...]

await redis.send("ZADD", ["myzset", "1", "one", "2", "two", "3", "three"]);
const result = await redis.zrevrangebyscore("myzset", 2, 1, "WITHSCORES");
// Returns: ["two", "2", "one", "1"]

Return members in a sorted set with scores within a given range, ordered from high to low, with pagination

The sorted set key

Maximum score

Minimum score

The "LIMIT" keyword

The number of elements to skip

The maximum number of elements to return

Promise that resolves with array of members

Return members in a sorted set with scores within a given range, ordered from high to low, with options

The sorted set key

Maximum score

Minimum score

Additional options (WITHSCORES, LIMIT offset count)

Promise that resolves with array of members (and scores if WITHSCORES is used)

Determine the index of a member in a sorted set, with scores ordered from high to low

The sorted set key

The member to find

Promise that resolves with the rank (index) of the member, or null if the member doesn't exist

Determine the index of a member in a sorted set with score, with scores ordered from high to low

The sorted set key

The member to find

"WITHSCORE" to include the score

Promise that resolves with [rank, score] or null if the member doesn't exist

Incrementally iterate sorted set elements and their scores

The ZSCAN command is used in order to incrementally iterate over sorted set elements and their scores. ZSCAN is a cursor based iterator. This means that at every call of the command, the server returns an updated cursor that the user needs to use as the cursor argument in the next call.

An iteration starts when the cursor is set to 0, and terminates when the cursor returned by the server is 0.

ZSCAN and the other SCAN family commands are able to provide to the user a set of guarantees associated to full iterations:

Options:

The sorted set key

The cursor value (use 0 to start a new iteration)

Additional ZSCAN options (MATCH pattern, COUNT hint, etc.)

Promise that resolves with a tuple [cursor, [member1, score1, member2, score2, ...]]

// Basic scan - iterate all elements
let cursor = "0";
const allElements: string[] = [];
do {
const [nextCursor, elements] = await redis.zscan("myzset", cursor);
allElements.push(...elements);
cursor = nextCursor;
} while (cursor !== "0");

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

The sorted set key

The member to get the score for

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

Compute the union of multiple sorted sets

Returns the union of the sorted sets given by the specified keys. For every element that appears in at least one of the input sorted sets, the output will contain that element.

Options:

The number of input keys (sorted sets)

Promise that resolves with an array of members (or members with scores if WITHSCORES is used)

// Set up sorted sets
await redis.zadd("zset1", "1", "a", "2", "b", "3", "c");
await redis.zadd("zset2", "4", "b", "5", "c", "6", "d");

// Basic union
const members1 = await redis.zunion(2, "zset1", "zset2");
// Returns: ["a", "b", "c", "d"]

// With weights
const members2 = await redis.zunion(2, "zset1", "zset2", "WEIGHTS", "2", "3");
// Returns: ["a", "b", "c", "d"] with calculated scores

// With MIN aggregation
const members3 = await redis.zunion(2, "zset1", "zset2", "AGGREGATE", "MIN");
// Returns: ["a", "b", "c", "d"] with minimum scores

// With scores
const withScores = await redis.zunion(2, "zset1", "zset2", "WITHSCORES");
// Returns: ["a", "1", "b", "2", "c", "3", "d", "6"] (alternating member and score)

Compute the union of multiple sorted sets

Returns the union of the sorted sets given by the specified keys. For every element that appears in at least one of the input sorted sets, the output will contain that element.

Options:

The number of input keys (sorted sets)

Promise that resolves with an array of members (or members with scores if WITHSCORES is used)

// Set up sorted sets
await redis.zadd("zset1", "1", "a", "2", "b", "3", "c");
await redis.zadd("zset2", "4", "b", "5", "c", "6", "d");

// Basic union
const members1 = await redis.zunion(2, "zset1", "zset2");
// Returns: ["a", "b", "c", "d"]

// With weights
const members2 = await redis.zunion(2, "zset1", "zset2", "WEIGHTS", "2", "3");
// Returns: ["a", "b", "c", "d"] with calculated scores

// With MIN aggregation
const members3 = await redis.zunion(2, "zset1", "zset2", "AGGREGATE", "MIN");
// Returns: ["a", "b", "c", "d"] with minimum scores

// With scores
const withScores = await redis.zunion(2, "zset1", "zset2", "WITHSCORES");
// Returns: ["a", "1", "b", "2", "c", "3", "d", "6"] (alternating member and score)

Compute the union of multiple sorted sets and store in destination

This command is similar to ZUNION, but instead of returning the result, it stores it in the destination key. If the destination key already exists, it is overwritten.

Options:

The destination key to store the result

The number of input keys (sorted sets)

Promise that resolves with the number of elements in the resulting sorted set

// Set up sorted sets
await redis.zadd("zset1", "1", "a", "2", "b", "3", "c");
await redis.zadd("zset2", "4", "b", "5", "c", "6", "d");

// Basic union store
const count1 = await redis.zunionstore("out", 2, "zset1", "zset2");
// Returns: 4 (stored "a", "b", "c", "d" in "out")

// With weights
const count2 = await redis.zunionstore("out2", 2, "zset1", "zset2", "WEIGHTS", "2", "3");
// Returns: 4

// With MAX aggregation
const count3 = await redis.zunionstore("out3", 2, "zset1", "zset2", "AGGREGATE", "MAX");
// Returns: 4 (stores maximum scores)

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");

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

The path to the file in the bucket

Additional S3 options to override defaults

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);
}

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

The path to the file in the bucket

Additional S3 options to override defaults

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);
}

Creates an S3File instance for the given path.

The path to the file in the bucket

Additional S3 options to override defaults

An S3File instance

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

const configFile = bucket.file("config.json", {
type: "application/json",
acl: "private"
});

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.

Options for listing objects in the bucket

Additional S3 options to override defaults

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,
});
}

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

The path to the file in the bucket

Options for generating the presigned URL

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"
});

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

The path to the file in the bucket

Additional S3 options to override defaults

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");
}

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

The path to the file in the bucket

Additional S3 options to override defaults

A promise that resolves to the file stats

const stat = await bucket.stat("my-file.txt");

Delete a file from the bucket.

The path to the file in the bucket

Additional S3 options to override defaults

A promise that resolves when deletion is complete

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

// With error handling
try {
await bucket.unlink("file.dat");
console.log("File deleted");
} catch (err) {
console.error("Delete failed:", err);
}

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

The path to the file in the bucket

The data to write to the file

Additional S3 options to override defaults

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"
});

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

The path to the file in the bucket

S3 credentials and configuration options

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);
}

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

The path to the file in the bucket

S3 credentials and configuration options

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);
}

Creates an S3File instance for the given path.

The path to the file in the bucket

S3 credentials and configuration options

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"
});

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.

Options for listing objects in the bucket

S3 credentials and configuration options

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);
}

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

The path to the file in the bucket

S3 credentials and presigned URL configuration

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"
});

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

The path to the file in the bucket

S3 credentials and configuration options

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");
}

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

The path to the file in the bucket

S3 credentials and configuration options

A promise that resolves to the file stats

const stat = await S3Client.stat("my-file.txt", credentials);

Delete a file from the bucket.

The path to the file in the bucket

S3 credentials and configuration options

A promise that resolves when deletion is complete

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

// With error handling
try {
await S3Client.unlink("file.dat", credentials);
console.log("File deleted");
} catch (err) {
console.error("Delete failed:", err);
}

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

The path to the file in the bucket

The data to write to the file

S3 credentials and configuration options

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"
});

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

The number of bytes the hash will produce

Finalize the hash

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

Finalize the hash

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

Update the hash with data

Run the hash over the given data

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

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

Run the hash over the given data

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

DigestEncoding to return the hash in

This class only exists in types

The number of bytes the hash will produce

Finalize the hash

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

Finalize the hash

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

Update the hash with data

Run the hash over the given data

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

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

Run the hash over the given data

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

DigestEncoding to return the hash in

This class only exists in types

The number of bytes the hash will produce

Finalize the hash

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

Finalize the hash

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

Update the hash with data

Run the hash over the given data

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

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

Run the hash over the given data

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

DigestEncoding to return the hash in

This class only exists in types

The number of bytes the hash will produce

Finalize the hash

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

Finalize the hash

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

Update the hash with data

Run the hash over the given data

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

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

Run the hash over the given data

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

DigestEncoding to return the hash in

This class only exists in types

The number of bytes the hash will produce

Finalize the hash

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

Finalize the hash

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

Update the hash with data

Run the hash over the given data

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

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

Run the hash over the given data

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

DigestEncoding to return the hash in

See also sha

The number of bytes the hash will produce

Finalize the hash

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

Finalize the hash

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

Update the hash with data

Run the hash over the given data

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

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

Run the hash over the given data

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

DigestEncoding to return the hash in

Main SQL client interface providing connection and transaction management

Current client options

Creates a new SQL array parameter

The values to create the array parameter from

The type name or type ID to create the array parameter from, if omitted it will default to JSON

A new SQL array parameter

const array = sql.array([1, 2, 3], "INT");
await sql`CREATE TABLE users_posts (user_id INT, posts_id INT[])`;
await sql`INSERT INTO users_posts (user_id, posts_id) VALUES (${user.id}, ${array})`;

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]
})

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]
})

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");

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.

The options for the close

await sql.close({ timeout: 1 });

Commits a distributed transaction also know as prepared transaction in postgres or XA transaction in MySQL

The name of the distributed transaction

await sql.commitDistributed("my_distributed_transaction");

Waits for the database connection to be established

await sql.connect();

Alternative method to begin a distributed transaction

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. This is an alias of SQL.close

The options for the close

await sql.end({ timeout: 1 });

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]);

Flushes any pending operations

sql.flush();

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();
}

// Bun supports Symbol.dispose and Symbol.asyncDispose
// always release after context (safer)
using reserved = await sql.reserve()
await reserved`select * from users`

Rolls back a distributed transaction also know as prepared transaction in postgres or XA transaction in MySQL

The name of the distributed transaction

await sql.rollbackDistributed("my_distributed_transaction");

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]
})

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]
});

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}`)

A pseudo-terminal (PTY) that can be used to spawn interactive terminal programs.

await using terminal = new Bun.Terminal({
cols: 80,
rows: 24,
data(term, data) {
console.log("Received:", new TextDecoder().decode(data));
},
});

// Spawn a shell connected to the PTY
const proc = Bun.spawn(["bash"], { terminal });

// Write to the terminal
terminal.write("echo hello\n");

// Wait for process to exit
await proc.exited;

// Terminal is closed automatically by `await using`

Whether the terminal is closed.

Terminal control flags (c_cflag from termios). Controls hardware characteristics like CSIZE, PARENB, etc. Returns 0 if terminal is closed. Setting returns true on success, false on failure.

Terminal input flags (c_iflag from termios). Controls input processing behavior like ICRNL, IXON, etc. Returns 0 if terminal is closed. Setting returns true on success, false on failure.

Terminal local flags (c_lflag from termios). Controls local processing like ICANON, ECHO, ISIG, etc. Returns 0 if terminal is closed. Setting returns true on success, false on failure.

Terminal output flags (c_oflag from termios). Controls output processing behavior like OPOST, ONLCR, etc. Returns 0 if terminal is closed. Setting returns true on success, false on failure.

Async dispose for use with await using.

Close the terminal.

Reference the terminal to keep the event loop alive.

Resize the terminal.

New number of columns

New number of rows

Set raw mode on the terminal. In raw mode, input is passed directly without processing.

Whether to enable raw mode

Unreference the terminal to allow the event loop to exit.

Write data to the terminal.

The data to write (string or BufferSource)

The number of bytes written

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

const transpiler = new Bun.Transpiler();
transpiler.transformSync(`
const App = () => Hello World;
export default App;
`);
// This outputs:
const output = `
const App = () => jsx("div", {
children: "Hello World"
}, undefined, false, undefined, this);
export default App;
`

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

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"]

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

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.

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

The code to transpile

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

The code to transpile

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

The code to transpile

An object to pass to macros

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

The code to transpile

A headless browser view for automation. WKWebView on macOS (zero dependencies), Chrome DevTools Protocol elsewhere (or with backend: "chrome").

Each view runs its page in a separate renderer process. All input methods dispatch native events — the resulting DOM events have isTrusted: true.

await using view = new Bun.WebView({ width: 800, height: 600 });
await view.navigate("https://example.com");
await view.click("button[type=submit]"); // waits for actionability
const title = await view.evaluate("document.title");
const png = await view.screenshot();

True while a navigation is in flight.

Fired when a navigation completes successfully. The callback runs before the corresponding navigate() promise resolves.

Fired when a navigation fails. The callback runs before the corresponding navigate() promise rejects.

The page's . Updated when a navigation completes.

The last-navigated URL. Updated when a navigation completes.

Alias for close. Enables await using view = new Bun.WebView(...).

Alias for close. Enables using view = new Bun.WebView(...).

Subscribe to CDP events. Chrome backend only.

Event types are CDP method names directly — "Network.responseReceived", "Page.frameStartedLoading", "DOM.documentUpdated", etc. The listener receives a MessageEvent with the CDP params as event.data.

Enable the domain first with cdp("Domain.enable"), or Chrome won't send those events. Events without a registered listener are dropped before JSON parsing (no overhead for domains you enabled but don't fully listen to).

await view.navigate("about:blank");
await view.cdp("Network.enable");
view.addEventListener("Network.responseReceived", e => {
console.log(e.data.response.status, e.data.response.url);
});
await view.navigate("https://example.com");

Adds a new handler for the type event. Any given listener is added only once per type and per capture option value.

If the once option is true, the listener is removed after the next time a type event is dispatched.

The capture option is not used by Node.js in any functional way other than tracking registered event listeners per the EventTarget specification. Specifically, the capture option is used as part of the key when registering a listener. Any individual listener may be added once with capture = false, and once with capture = true.

Navigate back in session history.

Send a raw Chrome DevTools Protocol command. Chrome backend only.

The command is scoped to this view's session (targets the current tab). Returns the decoded result object from the CDP response, or rejects with the error.message if Chrome reports a protocol error.

Call await view.navigate(...) at least once before using cdp() — the first navigate sets up the CDP session.

Domain-qualified method name, e.g. "Runtime.evaluate", "DOM.querySelector", "Emulation.setUserAgentOverride".

Command parameters. Must be JSON-serializable.

const view = new Bun.WebView({ backend: "chrome" });
await view.navigate("https://example.com");

const { root } = await view.cdp("DOM.getDocument");
const { nodeId } = await view.cdp("DOM.querySelector", {
nodeId: root.nodeId,
selector: "input#search",
});
await view.cdp("DOM.focus", { nodeId });

Click at the given viewport coordinates.

Fires native pointerdown/mousedown/pointerup/mouseup/click events with isTrusted: true. The promise resolves after WebContent has processed the full event sequence (including all JS handlers) — no polling, WebKit's own mouse-queue-drain barrier.

Wait for an element to become actionable, then click its center.

Actionability is checked page-side at rAF rate: the element must be attached, have non-zero size, be in the viewport, be stable (bounding box unchanged for 2 consecutive frames), and be the topmost element at its center point (not obscured). Once actionable, a native click fires at the center coordinates.

// Waits for the button to appear and stop animating, then clicks.
await view.click("#submit");

Close the view and release its WebContent process. After close, all methods throw. Idempotent.

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.

Run a JavaScript expression in the page's main frame and return the result as a native JS value.

The expression is wrapped as await (${script}) — if it evaluates to a Promise, the promise is awaited. The resolved value is serialized page-side via JSON.stringify and deserialized here, so arrays and objects come back as real structures:

await view.evaluate("document.title"); // string
await view.evaluate("[1, 2, 3]"); // number[]
await view.evaluate("({ a: 1, b: true })"); // { a: number, b: boolean }
await view.evaluate("fetch('/api').then(r => r.json())"); // awaited

script must be an expression. For statement sequences, wrap in an IIFE: evaluate("(() => { let x = f(); return x + 1 })()").

Values that JSON.stringify collapses to undefined (functions, symbols, undefined itself) resolve to undefined. Circular references reject.

Only one evaluate() may be in flight at a time per view; a second concurrent call throws ERR_INVALID_STATE.

Navigate forward in session history.

Navigate to a URL. Resolves when the main frame's load completes (WKNavigationDelegate didFinishNavigation).

await view.navigate("https://example.com");
await view.navigate("data:text/html,hello");

Press a key.

Named keys ("Enter", "Backspace", "ArrowLeft", etc.) map to editing commands where available and resolve when WebContent has processed them. "Escape" and keys with modifiers fall back to raw keyDown/keyUp (no WebKit barrier exists for keyboard events — a following evaluate() serializes).

A single character (e.g. "a") combined with modifiers sends a chord like Cmd+A.

Reload the current page.

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

MDN Reference

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

Resize the viewport.

Capture a screenshot of the current viewport.

encoding controls the return type:

const { name, size } = await view.screenshot({ encoding: "shmem" });
process.stdout.write(
`\x1b_Gf=100,t=s,a=T,S=${size};${btoa(name)}\x1b\\`
);
// Kitty shm_open's the name, reads ${size} PNG bytes, unlinks.

Capture a screenshot of the current viewport.

encoding controls the return type:

const { name, size } = await view.screenshot({ encoding: "shmem" });
process.stdout.write(
`\x1b_Gf=100,t=s,a=T,S=${size};${btoa(name)}\x1b\\`
);
// Kitty shm_open's the name, reads ${size} PNG bytes, unlinks.

Capture a screenshot of the current viewport.

encoding controls the return type:

const { name, size } = await view.screenshot({ encoding: "shmem" });
process.stdout.write(
`\x1b_Gf=100,t=s,a=T,S=${size};${btoa(name)}\x1b\\`
);
// Kitty shm_open's the name, reads ${size} PNG bytes, unlinks.

Capture a screenshot of the current viewport.

encoding controls the return type:

const { name, size } = await view.screenshot({ encoding: "shmem" });
process.stdout.write(
`\x1b_Gf=100,t=s,a=T,S=${size};${btoa(name)}\x1b\\`
);
// Kitty shm_open's the name, reads ${size} PNG bytes, unlinks.

Scroll the viewport by the given pixel delta.

Fires a native wheel event with isTrusted: true at the viewport center. Positive dy scrolls down (content up), matching window.scrollBy semantics.

Wait for an element to exist, then scroll it into view.

Uses Element.scrollIntoView({ block, behavior: 'instant' }) — scrolls every scrollable ancestor in the chain, not just the document. scrollY is updated synchronously before the promise resolves. No wheel event fires (this is a programmatic scroll).

await view.scrollTo("#footer"); // center (default)
await view.scrollTo("#hero", { block: "start" });
await view.scrollTo(".item", { block: "nearest" }); // minimal scroll

Insert text into the focused element.

Uses WebKit's InsertText editing command (not keystroke simulation), so no keydown events fire — this is the same path as paste. No IME, no smart-quote substitution; the text lands exactly as given. Fires beforeinput/input with isTrusted: true.

Force-kill all browser subprocesses (Chrome and the WKWebView host). Pending promises on all views reject on the next event loop tick.

Called automatically at process exit. Call manually to reclaim browser resources early — subsequent new Bun.WebView() calls will respawn. Idempotent: calling when no subprocesses are alive is a no-op.

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.

const file = Bun.file("./hello.json");
console.log(file.type); // "application/json"
console.log(await file.text()); // '{"hello":"world"}'

A UNIX timestamp indicating when the file was last modified.

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

MDN Reference

MDN Reference

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

MDN Reference

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())

Deletes the file (same as unlink)

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.

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.

Wrap this blob in a Bun.Image pipeline. Equivalent to new Bun.Image(this, options) — the constructor is synchronous (the underlying read happens lazily when an Image terminal is awaited), so this works on Bun.file(), Bun.s3(), fd-backed and in-memory blobs alike:

await Bun.file("photo.jpg").image().resize(400).webp().write("thumb.webp");

Read the data from the blob as a JSON object.

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

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

start offset in bytes

absolute offset in bytes (relative to 0)

MIME type for the new BunFile

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

start offset in bytes

MIME type for the new BunFile

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

MIME type for the new BunFile

Provides useful information about the file.

MDN Reference

Returns a readable stream of the blob's contents

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

Deletes the file.

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

The data to write.

The options to use for the write.

Incremental writer for files and pipes.

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

The bucket name containing the file.

const file = s3.file("s3:http://my-bucket/file.txt");
console.log(file.bucket); // "my-bucket"

The name or path of the file in the bucket.

const file = s3.file("folder/image.jpg");
console.log(file.name); // "folder/image.jpg"

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);
}

MDN Reference

MDN Reference

Alias for delete() method. Provided for compatibility with Node.js fs API naming.

await file.unlink();

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

MDN Reference

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())

Deletes the file from S3.

Promise that resolves when deletion is complete

// Basic deletion
await file.delete();

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

Promise resolving to true if file exists, false otherwise

// Basic existence check
if (await file.exists()) {
console.log("File exists in S3");
}

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.

Wrap this blob in a Bun.Image pipeline. Equivalent to new Bun.Image(this, options) — the constructor is synchronous (the underlying read happens lazily when an Image terminal is awaited), so this works on Bun.file(), Bun.s3(), fd-backed and in-memory blobs alike:

await Bun.file("photo.jpg").image().resize(400).webp().write("thumb.webp");

Read the data from the blob as a JSON object.

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

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

Configuration for the presigned URL

Presigned URL string

// Basic download URL
const url = file.presign({
expiresIn: 3600 // 1 hour
});

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

Starting byte offset

Ending byte offset (exclusive)

Optional MIME type for the slice

A new S3File representing the specified range

// Reading file header
const header = file.slice(0, 1024);
const headerText = await header.text();

MDN Reference

MDN Reference

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

Promise resolving to S3Stat

MDN Reference

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

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

The data to upload

Upload configuration options

Promise resolving to number of bytes written

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

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

Configuration for the upload

A NetworkSink for writing data

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

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.

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.

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"

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.

How many requests are in-flight right now?

How many ServerWebSockets are in-flight right now?

The port the server is listening on.

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

3000

The protocol the server is listening on.

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

Send a message to all connected ServerWebSocket subscribed to a topic

The topic to publish to

The data to send

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

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

server.publish("chat", "Hello World");

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.

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.

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));
}
}

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.

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

A count of connections subscribed to a given topic

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

the websocket topic to check how many subscribers are connected to

the number of subscribers

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");
}
}

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 a Request to a ServerWebSocket

The Request to upgrade

Pass headers or attach data to the ServerWebSocket

true if the upgrade was successful and false if it failed

import { serve } from "bun";
const server: Bun.Server: string }> = 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, {
data: {user: "John Doe"}
});
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

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.

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.

Are ANSI colors enabled for stdin and stdout?

Used for console.log

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.

Hash a string or array buffer using Wyhash

This is not a cryptographic hash function.

Is the current global scope the main thread?

What script launched Bun?

Absolute file path

"/never-gonna-give-you-up.js"

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

Default Redis client

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

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

"a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"

A default instance of S3Client

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

Securely store and retrieve sensitive credentials using the operating system's native credential storage.

Uses platform-specific secure storage:

import { secrets } from "bun";

// Store a credential
await secrets.set({
service: "my-cli-tool",
name: "github-token",
value: "ghp_xxxxxxxxxxxxxxxxxxxx"
});

// Retrieve a credential
const token = await secrets.get({
service: "my-cli-tool",
name: "github-token"
});

if (token) {
console.log("Token found:", token);
} else {
console.log("Token not found");
}

// Delete a credential
const deleted = await secrets.delete({
service: "my-cli-tool",
name: "github-token"
});
console.log("Deleted:", deleted); // true if deleted, false if not found

SQL client

Write to stderr

Read from stdin

This is a read-only BunFile

Write to stdout

The current version of Bun

"1.2.0"

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

"v1.2.0 (a1b2c3d4)"

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

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

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
}
}

The cause of the error.

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Read from stdout as an ArrayBuffer

Stdout as an ArrayBuffer

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

Read from stdout as a Blob

Stdout as a blob

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

Read from stdout as an Uint8Array

Stdout as an Uint8Array

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

Read from stdout as a JSON object

Stdout as a JSON object

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

Read from stdout as a string

The encoding to use when decoding the output

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"

Create .stack property on a target object

Check if a value is an instance of Error

The value to check

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

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!"

Read from stdout as an ArrayBuffer

Automatically calls quiet

A promise that resolves with stdout as an ArrayBuffer

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

Read from stdout as a Blob

Automatically calls quiet

A promise that resolves with stdout as a Blob

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

Attaches a callback for only the rejection of the Promise.

The callback to execute when the Promise is rejected.

A Promise for the completion of the callback.

Change the current working directory of the shell.

The new working directory

Set environment variables for the shell.

The new environment variables

await $`echo $FOO`.env({ ...process.env, FOO: "LOL!" })
expect(stdout.toString()).toBe("LOL!");

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

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

A Promise for the completion of the callback.

Read from stdout as a JSON object

Automatically calls quiet

A promise that resolves with stdout as a JSON object

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

Read from stdout as a string, line by line

Automatically calls quiet to disable echoing to stdout.

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.

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.

Whether to suppress output. Defaults to true.

Read from stdout as a string.

Automatically calls quiet to disable echoing to stdout.

The encoding to use when decoding the output

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"

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

The callback to execute when the Promise is resolved.

The callback to execute when the Promise is rejected.

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

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

By default, this is configured to true.

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.

An array of Promises.

A new Promise.

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

An array of Promises.

A new Promise.

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.

An array or iterable of Promises.

A new Promise.

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

An array of Promises.

A new Promise.

Creates a new rejected promise for the provided reason.

The reason the promise was rejected.

A new rejected Promise.

Creates a new resolved promise for the provided value.

A promise.

A promise whose internal state matches the provided promise.

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

The function to run

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

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

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!"

Read from stdout as an ArrayBuffer

Stdout as an ArrayBuffer

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

Read from stdout as a Blob

Stdout as a blob

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

Read from stdout as an Uint8Array

Stdout as an Uint8Array

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

Read from stdout as a JSON object

Stdout as a JSON object

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

Read from stdout as a string

The encoding to use when decoding the output

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"

Perform bash-like brace expansion on the given pattern.

Brace pattern to expand

const result = braces('index.{js,jsx,ts,tsx}');
console.log(result) // ['index.js', 'index.jsx', 'index.ts', 'index.tsx']

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

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

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

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

Escape strings for input into shell commands.

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

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

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.

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

Build configuration options

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);
}

Converts formats of colors

A value that could possibly be a color

An optional output format

Convert any color input to rgb

Any color input

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

Convert any color input to rgba

Any color input

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

Convert any color input to a number

Any color input

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

Convert any color input to rgba

Any color input

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

Convert any color input to a number

Any color input

Specify number to output as a 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.

An array of typed arrays to concatenate.

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.

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.

An array of typed arrays to concatenate.

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.

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.

An array of typed arrays to concatenate.

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.

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

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

Fast deep-equality check two objects.

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

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

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

Compresses a chunk of data with zlib DEFLATE algorithm.

The buffer of data to compress

Compression options to use

The output buffer with the compressed data

Escape the following characters in a string:

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.

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

const file = Bun.file("./hello.json");
console.log(file.type); // "application/json"
console.log(await file.json()); // { hello: "world" }

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

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

const file = Bun.file(new TextEncoder.encode("./hello.json"));
console.log(file.type); // "application/json"

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.

The file descriptor of the file

const file = Bun.file(fd);

Convert a URL to a filesystem path.

The URL to convert.

A filesystem path.

const path = Bun.fileURLToPath(new URL("file:http:///foo/bar.txt"));
console.log(path); // "/foo/bar.txt"

Manually trigger the garbage collector

This does two things:

Synchronously run the garbage collector

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

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);

Show precise statistics about memory usage of your application

Generate a V8 Heap Snapshot as an ArrayBuffer.

This avoids the overhead of creating a JavaScript string for large heap snapshots. The ArrayBuffer contains the UTF-8 encoded JSON.

const snapshot = Bun.generateHeapSnapshot("v8", "arraybuffer");
await Bun.write("heap.heapsnapshot", snapshot);

Decompresses a chunk of data with zlib GUNZIP algorithm.

The buffer of data to decompress

The output buffer with the decompressed data

Compresses a chunk of data with zlib GZIP algorithm.

The buffer of data to compress

Compression options to use

The output buffer with the compressed data

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

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

Decompresses a chunk of data with zlib INFLATE algorithm.

The buffer of data to decompress

The output buffer with the decompressed data

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

Supports JSX

The value to inspect

Options for the inspection

That can be used to declare custom inspect functions.

Pretty-print an object or array as a table

Like console.table, except it returns a string

Pretty-print an object or array as a table

Like console.table, except it returns a string

Create a TCP server that listens on a port

Create a TCP server that listens on a unix socket

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

This uses the mmap() syscall under the hood.

This API inherently has some rough edges:

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

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.

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

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

path to open

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

The path to convert.

A URL with the file:// scheme.

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

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

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

Generate a UUIDv5, which is a name-based UUID based on the SHA-1 hash of a namespace UUID and a name.

The name to use for the UUID

The namespace to use for the UUID

The encoding to use for the UUID

import { randomUUIDv5 } from "bun";
const uuid = randomUUIDv5("www.example.com", "dns");
console.log(uuid); // "6ba7b810-9dad-11d1-80b4-00c04fd430c8"

import { randomUUIDv5 } from "bun";
const uuid = randomUUIDv5("www.example.com", "url");
console.log(uuid); // "6ba7b811-9dad-11d1-80b4-00c04fd430c8"

Generate a UUIDv5 as a Buffer

The name to use for the UUID

The namespace to use for the UUID

The encoding to use for the UUID

import { randomUUIDv5 } from "bun";
const uuid = randomUUIDv5("www.example.com", "url", "buffer");
console.log(uuid); //

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.

"hex" | "base64" | "base64url"

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"
]

Generate a UUIDv7 as a Buffer

"buffer"

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

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

The stream to consume

A promise that resolves with the chunks as an array

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

The stream to consume.

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

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

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

The stream to consume.

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

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"

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.

Synchronously resolve a moduleId as though it were imported from parent

On failure, throws a ResolveMessage

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.

Server configuration options

Basic Usage

Bun.serve({
port: 3000,
fetch(req) {
return new Response("Hello World");
}
});

Hash input using SHA-2 512/256

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

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

Hash input using SHA-2 512/256

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

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

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

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.

import { sleep } from "bun";

await sleep(1000);

await Bun.sleep(10);

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.

Sleep the thread for a given number of milliseconds

This is a blocking function.

Internally, it calls nanosleep(2)

Slice a string by visible column width, preserving ANSI escape codes.

Like String.prototype.slice, but indices are terminal column widths (accounting for wide CJK characters, emoji grapheme clusters, and zero-width joiners), and ANSI escape sequences (SGR colors, OSC 8 hyperlinks, etc.) are preserved and correctly re-opened/closed at the slice boundaries.

The string to slice

Starting column (default 0). Negative counts from end.

Ending column, exclusive (default end of string). Negative counts from end.

Optional behavior flags (e.g. ellipsis for truncation)

ambiguousIsNarrow as a positional arg, usable when the 4th arg is an ellipsis string (or undefined). Lets you pass both options without an object: sliceAnsi(s, 0, n, "\u2026", false).

The sliced string with ANSI codes intact

import { sliceAnsi } from "bun";

// Plain slice (replaces the `slice-ansi` npm package)
sliceAnsi("hello", 1, 4); // "ell"
sliceAnsi("\u001b[31mhello\u001b[39m", 1, 4); // "\u001b[31mell\u001b[39m"
sliceAnsi("\u5b89\u5b81\u54c8", 0, 4); // "\u5b89\u5b81" (CJK: width 2 each)

// Truncation (replaces the `cli-truncate` npm package)
sliceAnsi("unicorn", 0, 4, "\u2026"); // "uni\u2026"
sliceAnsi("unicorn", -4, undefined, "\u2026"); // "\u2026orn"

Spawn a new process

Spawn a new process

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

Internally, this uses posix_spawn(2)

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).

Spawn a new process

Synchronously spawn a new process

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

Internally, this uses posix_spawn(2)

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).

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:

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

The string to measure

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

Remove ANSI escape codes from a string.

The string to remove ANSI escape codes from.

The string with ANSI escape codes removed.

import { stripANSI } from "bun";

console.log(stripANSI("\u001b[31mhello\u001b[39m")); // "hello"

Create a UDP socket

The options to use when creating the server

Create a UDP socket

The options to use when creating the server

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

The name of the executable or script to find

Options for the search

Wrap a string to fit within the specified column width, preserving ANSI escape codes.

This function is designed to be compatible with the popular "wrap-ansi" NPM package.

Features:

The string to wrap

The maximum column width

Wrapping options

The wrapped string

import { wrapAnsi } from "bun";

console.log(wrapAnsi("hello world", 5));
// Output:
// hello
// world

// Preserves ANSI colors across line breaks
console.log(wrapAnsi("\u001b[31mhello world\u001b[0m", 5));
// Output:
// \u001b[31mhello\u001b[0m
// \u001b[31mworld\u001b[0m

// Hard wrap long words
console.log(wrapAnsi("abcdefghij", 3, { hard: true }));
// Output:
// abc
// def
// ghi
// j

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.

The file or file path to write to

The data to copy into destination.

Options for the write

A promise that resolves with the number of bytes written.

Persist a Response body to disk.

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.

Response object

Options for the write

A promise that resolves with the number of bytes written.

Persist a Response body to disk.

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.

Response object

A promise that resolves with the number of bytes written.

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()

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.

The file to copy from.

A promise that resolves with the number of bytes written.

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()

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.

The file to copy from.

A promise that resolves with the number of bytes written.

Compresses a chunk of data with the Zstandard (zstd) compression algorithm.

The buffer of data to compress

Compression options to use

A promise that resolves to the output buffer with the compressed data

Compresses a chunk of data with the Zstandard (zstd) compression algorithm.

The buffer of data to compress

Compression options to use

The output buffer with the compressed data

Decompresses a chunk of data with the Zstandard (zstd) decompression algorithm.

The buffer of data to decompress

A promise that resolves to the output buffer with the decompressed data

Decompresses a chunk of data with the Zstandard (zstd) decompression algorithm.

The buffer of data to decompress

The output buffer with the decompressed data

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

MDN Reference

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

Returns the URL providing the event stream.

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

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

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

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

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

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.

Keep the event loop alive while connection is open or reconnecting

Not available in browsers

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

MDN Reference

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

MDN Reference

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

MDN Reference

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

Not available in browsers

A WebSocket client implementation

const ws = new WebSocket("ws:http://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();

The type of binary data being received.

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

The extensions selected by the server

Event handler for close event

Event handler for error event

Event handler for message event

Event handler for open event

The protocol selected by the server

The current state of the connection

The URL of the WebSocket connection

Registers an event handler of a specific event type on the WebSocket.

A case-sensitive string representing the event type to listen for

The function to be called when the event occurs

An options object that specifies characteristics about the event listener

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.