DocsReferenceGuidesBlog
Discord logo
Discord
GitHub logo

$

Bun

Symbol

$

namespace $

    • cause?: unknown

      The cause of the error.

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

      Optional override for formatting stack traces

    • static stackTraceLimit: number

      The maximum number of stack frames to capture.

    • Read from stdout as an ArrayBuffer

      @returns

      Stdout as an ArrayBuffer

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

    • Read from stdout as a Blob

      @returns

      Stdout as a blob

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

    • Read from stdout as an Uint8Array

      @returns

      Stdout as an Uint8Array

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

      Read from stdout as a JSON object

      @returns

      Stdout as a JSON object

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

      Read from stdout as a string

      @param encoding

      The encoding to use when decoding the output

      @returns

      Stdout as a string with the given encoding

      Read as UTF-8 string

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

      Read as base64 string

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

      Create .stack property on a target object

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

      Check if a value is an instance of Error

      @param value

      The value to check

      @returns

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

    • readonly [Symbol.toStringTag]: string

    • Read from stdout as an ArrayBuffer

      Automatically calls quiet

      @returns

      A promise that resolves with stdout as an ArrayBuffer

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

      Read from stdout as a Blob

      Automatically calls quiet

      @returns

      A promise that resolves with stdout as a Blob

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

      Attaches a callback for only the rejection of the Promise.

      @param onrejected

      The callback to execute when the Promise is rejected.

      @returns

      A Promise for the completion of the callback.

    • cwd(newCwd: string): this

      Change the current working directory of the shell.

      @param newCwd

      The new working directory

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

      Set environment variables for the shell.

      @param newEnv

      The new environment variables

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

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

      @param onfinally

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

      @returns

      A Promise for the completion of the callback.

    • json(): Promise<any>

      Read from stdout as a JSON object

      Automatically calls quiet

      @returns

      A promise that resolves with stdout as a JSON object

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

      Read from stdout as a string, line by line

      Automatically calls quiet to disable echoing to stdout.

    • nothrow(): this

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

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

    • quiet(): this

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

      This configures the shell to only buffer the output.

    • text(encoding?: BufferEncoding): Promise<string>

      Read from stdout as a string

      Automatically calls quiet to disable echoing to stdout.

      @param encoding

      The encoding to use when decoding the output

      @returns

      A promise that resolves with stdout as a string

      Read as UTF-8 string

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

      Read as base64 string

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

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

      @param onfulfilled

      The callback to execute when the Promise is resolved.

      @param onrejected

      The callback to execute when the Promise is rejected.

      @returns

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

    • throws(shouldThrow: boolean): this

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

      By default, this is configured to true.

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

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

      @param values

      An array of Promises.

      @returns

      A new Promise.

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

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

      @param values

      An array of Promises.

      @returns

      A new Promise.

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

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

      @param values

      An array or iterable of Promises.

      @returns

      A new Promise.

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

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

      @param values

      An array of Promises.

      @returns

      A new Promise.

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

      Creates a new rejected promise for the provided reason.

      @param reason

      The reason the promise was rejected.

      @returns

      A new rejected Promise.

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

      Creates a new resolved promise for the provided value.

      @param value

      A promise.

      @returns

      A promise whose internal state matches the provided promise.

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

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

      @param fn

      The function to run

      @param args

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

      @returns

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

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

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

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

      Example

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

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

await promise; // "Hello world!"

      Promise.withResolvers() is a stage3 proposal.

  • interface ShellOutput

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

    • Read from stdout as an ArrayBuffer

      @returns

      Stdout as an ArrayBuffer

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

    • Read from stdout as a Blob

      @returns

      Stdout as a blob

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

    • Read from stdout as an Uint8Array

      @returns

      Stdout as an Uint8Array

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

      Read from stdout as a JSON object

      @returns

      Stdout as a JSON object

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

      Read from stdout as a string

      @param encoding

      The encoding to use when decoding the output

      @returns

      Stdout as a string with the given encoding

      Read as UTF-8 string

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

      Read as base64 string

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

    Perform bash-like brace expansion on the given pattern.

    @param pattern

    Brace pattern to expand

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

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

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

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

    @param newEnv

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

  • function escape(input: string): string

    Escape strings for input into shell commands.

  • function nothrow(): typeof $

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

  • function throws(shouldThrow: boolean): typeof $

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