bun-types 1.2.10-canary.20250414T140624 → 1.2.10-canary.20250415T140641

package/shell.d.ts

@@ -0,0 +1,355 @@
+declare module "bun" {
+  type ShellFunction = (input: Uint8Array) => Uint8Array;
+
+  type ShellExpression =
+    | { toString(): string }
+    | Array<ShellExpression>
+    | string
+    | { raw: string }
+    | Subprocess
+    | SpawnOptions.Readable
+    | SpawnOptions.Writable
+    | ReadableStream;
+
+  /**
+   * The Bun shell
+   *
+   * @category Process Management
+   */
+  function $(strings: TemplateStringsArray, ...expressions: ShellExpression[]): $.ShellPromise;
+
+  namespace $ {
+    const Shell: new () => typeof $;
+
+    /**
+     * Perform bash-like brace expansion on the given pattern.
+     * @param pattern - Brace pattern to expand
+     *
+     * @example
+     * ```js
+     * const result = braces('index.{js,jsx,ts,tsx}');
+     * console.log(result) // ['index.js', 'index.jsx', 'index.ts', 'index.tsx']
+     * ```
+     */
+    function braces(pattern: string): string[];
+
+    /**
+     * Escape strings for input into shell commands.
+     * @param input
+     */
+    function escape(input: string): string;
+
+    /**
+     *
+     * Change the default environment variables for shells created by this instance.
+     *
+     * @param newEnv Default environment variables to use for shells created by this instance.
+     * @default process.env
+     *
+     * ## Example
+     *
+     * ```js
+     * import {$} from 'bun';
+     * $.env({ BUN: "bun" });
+     * await $`echo $BUN`;
+     * // "bun"
+     * ```
+     */
+    function env(newEnv?: Record<string, string | undefined>): typeof $;
+
+    /**
+     *
+     * @param newCwd Default working directory to use for shells created by this instance.
+     */
+    function cwd(newCwd?: string): typeof $;
+
+    /**
+     * Configure the shell to not throw an exception on non-zero exit codes.
+     */
+    function nothrow(): typeof $;
+
+    /**
+     * Configure whether or not the shell should throw an exception on non-zero exit codes.
+     */
+    function throws(shouldThrow: boolean): typeof $;
+
+    class ShellPromise extends Promise<ShellOutput> {
+      get stdin(): WritableStream;
+
+      /**
+       * Change the current working directory of the shell.
+       * @param newCwd - The new working directory
+       */
+      cwd(newCwd: string): this;
+      /**
+       * Set environment variables for the shell.
+       * @param newEnv - The new environment variables
+       *
+       * @example
+       * ```ts
+       * await $`echo $FOO`.env({ ...process.env, FOO: "LOL!" })
+       * expect(stdout.toString()).toBe("LOL!");
+       * ```
+       */
+      env(newEnv: Record<string, string> | undefined): 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.
+       */
+      quiet(): this;
+
+      /**
+       * Read from stdout as a string, line by line
+       *
+       * Automatically calls {@link quiet} to disable echoing to stdout.
+       */
+      lines(): AsyncIterable<string>;
+
+      /**
+       * Read from stdout as a string
+       *
+       * Automatically calls {@link 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
+       * @example
+       *
+       * ## Read as UTF-8 string
+       *
+       * ```ts
+       * const output = await $`echo hello`.text();
+       * console.log(output); // "hello\n"
+       * ```
+       *
+       * ## Read as base64 string
+       *
+       * ```ts
+       * const output = await $`echo ${atob("hello")}`.text("base64");
+       * console.log(output); // "hello\n"
+       * ```
+       *
+       */
+      text(encoding?: BufferEncoding): Promise<string>;
+
+      /**
+       * Read from stdout as a JSON object
+       *
+       * Automatically calls {@link quiet}
+       *
+       * @returns A promise that resolves with stdout as a JSON object
+       * @example
+       *
+       * ```ts
+       * const output = await $`echo '{"hello": 123}'`.json();
+       * console.log(output); // { hello: 123 }
+       * ```
+       *
+       */
+      json(): Promise<any>;
+
+      /**
+       * Read from stdout as an ArrayBuffer
+       *
+       * Automatically calls {@link quiet}
+       * @returns A promise that resolves with stdout as an ArrayBuffer
+       * @example
+       *
+       * ```ts
+       * const output = await $`echo hello`.arrayBuffer();
+       * console.log(output); // ArrayBuffer { byteLength: 6 }
+       * ```
+       */
+      arrayBuffer(): Promise<ArrayBuffer>;
+
+      /**
+       * Read from stdout as a Blob
+       *
+       * Automatically calls {@link quiet}
+       * @returns A promise that resolves with stdout as a Blob
+       * @example
+       * ```ts
+       * const output = await $`echo hello`.blob();
+       * console.log(output); // Blob { size: 6, type: "" }
+       * ```
+       */
+      blob(): Promise<Blob>;
+
+      /**
+       * 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.
+       */
+      nothrow(): this;
+
+      /**
+       * Configure whether or not the shell should throw an exception on non-zero exit codes.
+       *
+       * By default, this is configured to `true`.
+       */
+      throws(shouldThrow: boolean): this;
+    }
+
+    class ShellError extends Error implements ShellOutput {
+      readonly stdout: Buffer;
+      readonly stderr: Buffer;
+      readonly exitCode: number;
+
+      /**
+       * 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
+       * @example
+       *
+       * ## Read as UTF-8 string
+       *
+       * ```ts
+       * const output = await $`echo hello`;
+       * console.log(output.text()); // "hello\n"
+       * ```
+       *
+       * ## Read as base64 string
+       *
+       * ```ts
+       * const output = await $`echo ${atob("hello")}`;
+       * console.log(output.text("base64")); // "hello\n"
+       * ```
+       *
+       */
+      text(encoding?: BufferEncoding): string;
+
+      /**
+       * Read from stdout as a JSON object
+       *
+       * @returns Stdout as a JSON object
+       * @example
+       *
+       * ```ts
+       * const output = await $`echo '{"hello": 123}'`;
+       * console.log(output.json()); // { hello: 123 }
+       * ```
+       *
+       */
+      json(): any;
+
+      /**
+       * Read from stdout as an ArrayBuffer
+       *
+       * @returns Stdout as an ArrayBuffer
+       * @example
+       *
+       * ```ts
+       * const output = await $`echo hello`;
+       * console.log(output.arrayBuffer()); // ArrayBuffer { byteLength: 6 }
+       * ```
+       */
+      arrayBuffer(): ArrayBuffer;
+
+      /**
+       * Read from stdout as a Blob
+       *
+       * @returns Stdout as a blob
+       * @example
+       * ```ts
+       * const output = await $`echo hello`;
+       * console.log(output.blob()); // Blob { size: 6, type: "" }
+       * ```
+       */
+      blob(): Blob;
+
+      /**
+       * Read from stdout as an Uint8Array
+       *
+       * @returns Stdout as an Uint8Array
+       * @example
+       *```ts
+       * const output = await $`echo hello`;
+       * console.log(output.bytes()); // Uint8Array { byteLength: 6 }
+       * ```
+       */
+      bytes(): Uint8Array;
+    }
+
+    interface ShellOutput {
+      readonly stdout: Buffer;
+      readonly stderr: Buffer;
+      readonly exitCode: number;
+
+      /**
+       * 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
+       * @example
+       *
+       * ## Read as UTF-8 string
+       *
+       * ```ts
+       * const output = await $`echo hello`;
+       * console.log(output.text()); // "hello\n"
+       * ```
+       *
+       * ## Read as base64 string
+       *
+       * ```ts
+       * const output = await $`echo ${atob("hello")}`;
+       * console.log(output.text("base64")); // "hello\n"
+       * ```
+       *
+       */
+      text(encoding?: BufferEncoding): string;
+
+      /**
+       * Read from stdout as a JSON object
+       *
+       * @returns Stdout as a JSON object
+       * @example
+       *
+       * ```ts
+       * const output = await $`echo '{"hello": 123}'`;
+       * console.log(output.json()); // { hello: 123 }
+       * ```
+       *
+       */
+      json(): any;
+
+      /**
+       * Read from stdout as an ArrayBuffer
+       *
+       * @returns Stdout as an ArrayBuffer
+       * @example
+       *
+       * ```ts
+       * const output = await $`echo hello`;
+       * console.log(output.arrayBuffer()); // ArrayBuffer { byteLength: 6 }
+       * ```
+       */
+      arrayBuffer(): ArrayBuffer;
+
+      /**
+       * Read from stdout as an Uint8Array
+       *
+       * @returns Stdout as an Uint8Array
+       * @example
+       *
+       * ```ts
+       * const output = await $`echo hello`;
+       * console.log(output.bytes()); // Uint8Array { byteLength: 6 }
+       * ```
+       */
+      bytes(): Uint8Array;
+
+      /**
+       * Read from stdout as a Blob
+       *
+       * @returns Stdout as a blob
+       * @example
+       * ```ts
+       * const output = await $`echo hello`;
+       * console.log(output.blob()); // Blob { size: 6, type: "" }
+       * ```
+       */
+      blob(): Blob;
+    }
+  }
+}

package/sqlite.d.ts

@@ -13,15 +13,15 @@
  *
  * The following types can be used when binding parameters:
  *
- * | JavaScript type | SQLite type |
- * | -------------- | ----------- |
- * | `string` | `TEXT` |
- * | `number` | `INTEGER` or `DECIMAL` |
- * | `boolean` | `INTEGER` (1 or 0) |
- * | `Uint8Array` | `BLOB` |
- * | `Buffer` | `BLOB` |
- * | `bigint` | `INTEGER` |
- * | `null` | `NULL` |
+ * | JavaScript type | SQLite type            |
+ * | --------------- | ---------------------- |
+ * | `string`        | `TEXT`                 |
+ * | `number`        | `INTEGER` or `DECIMAL` |
+ * | `boolean`       | `INTEGER` (1 or 0)     |
+ * | `Uint8Array`    | `BLOB`                 |
+ * | `Buffer`        | `BLOB`                 |
+ * | `bigint`        | `INTEGER`              |
+ * | `null`          | `NULL`                 |
  */
 declare module "bun:sqlite" {
   /**
@@ -159,6 +159,20 @@ declare module "bun:sqlite" {
      *
      * This does not cache the query, so if you want to run a query multiple times, you should use {@link prepare} instead.
      *
+     * Under the hood, this calls `sqlite3_prepare_v3` followed by `sqlite3_step` and `sqlite3_finalize`.
+     *
+     * The following types can be used when binding parameters:
+     *
+     * | JavaScript type | SQLite type            |
+     * | --------------- | ---------------------- |
+     * | `string`        | `TEXT`                 |
+     * | `number`        | `INTEGER` or `DECIMAL` |
+     * | `boolean`       | `INTEGER` (1 or 0)     |
+     * | `Uint8Array`    | `BLOB`                 |
+     * | `Buffer`        | `BLOB`                 |
+     * | `bigint`        | `INTEGER`              |
+     * | `null`          | `NULL`                 |
+     *
      * @example
      * ```ts
      * db.run("CREATE TABLE foo (bar TEXT)");
@@ -184,30 +198,15 @@ declare module "bun:sqlite" {
      * - `CREATE TEMPORARY TABLE`
      *
      * @param sql The SQL query to run
-     *
      * @param bindings Optional bindings for the query
      *
      * @returns `Database` instance
-     *
-     * Under the hood, this calls `sqlite3_prepare_v3` followed by `sqlite3_step` and `sqlite3_finalize`.
-     *
-     *  * The following types can be used when binding parameters:
-     *
-     * | JavaScript type | SQLite type |
-     * | -------------- | ----------- |
-     * | `string` | `TEXT` |
-     * | `number` | `INTEGER` or `DECIMAL` |
-     * | `boolean` | `INTEGER` (1 or 0) |
-     * | `Uint8Array` | `BLOB` |
-     * | `Buffer` | `BLOB` |
-     * | `bigint` | `INTEGER` |
-     * | `null` | `NULL` |
      */
-    run<ParamsType extends SQLQueryBindings[]>(sqlQuery: string, ...bindings: ParamsType[]): Changes;
+    run<ParamsType extends SQLQueryBindings[]>(sql: string, ...bindings: ParamsType[]): Changes;
     /**
-        This is an alias of {@link Database.prototype.run}
+     * This is an alias of {@link Database.run}
      */
-    exec<ParamsType extends SQLQueryBindings[]>(sqlQuery: string, ...bindings: ParamsType[]): Changes;
+    exec<ParamsType extends SQLQueryBindings[]>(sql: string, ...bindings: ParamsType[]): Changes;
 
     /**
      * Compile a SQL query and return a {@link Statement} object. This is the
@@ -216,6 +215,8 @@ declare module "bun:sqlite" {
      * This **does not execute** the query, but instead prepares it for later
      * execution and caches the compiled query if possible.
      *
+     * Under the hood, this calls `sqlite3_prepare_v3`.
+     *
      * @example
      * ```ts
      * // compile the query
@@ -228,21 +229,19 @@ declare module "bun:sqlite" {
      * ```
      *
      * @param sql The SQL query to compile
-     *
      * @returns `Statment` instance
-     *
-     * Under the hood, this calls `sqlite3_prepare_v3`.
      */
     query<ReturnType, ParamsType extends SQLQueryBindings | SQLQueryBindings[]>(
-      sqlQuery: string,
-    ): // eslint-disable-next-line @definitelytyped/no-single-element-tuple-type
-    Statement<ReturnType, ParamsType extends any[] ? ParamsType : [ParamsType]>;
+      sql: string,
+    ): Statement<ReturnType, ParamsType extends any[] ? ParamsType : [ParamsType]>;
 
     /**
      * Compile a SQL query and return a {@link Statement} object.
      *
      * This does not cache the compiled query and does not execute the query.
      *
+     * Under the hood, this calls `sqlite3_prepare_v3`.
+     *
      * @example
      * ```ts
      * // compile the query
@@ -254,15 +253,12 @@ declare module "bun:sqlite" {
      * @param sql The SQL query to compile
      * @param params Optional bindings for the query
      *
-     * @returns `Statment` instance
-     *
-     * Under the hood, this calls `sqlite3_prepare_v3`.
+     * @returns A {@link Statement} instance
      */
     prepare<ReturnType, ParamsType extends SQLQueryBindings | SQLQueryBindings[]>(
-      sqlQuery: string,
+      sql: string,
       params?: ParamsType,
-    ): // eslint-disable-next-line @definitelytyped/no-single-element-tuple-type
-    Statement<ReturnType, ParamsType extends any[] ? ParamsType : [ParamsType]>;
+    ): Statement<ReturnType, ParamsType extends any[] ? ParamsType : [ParamsType]>;
 
     /**
      * Is the database in a transaction?
@@ -646,15 +642,15 @@ declare module "bun:sqlite" {
      *
      * The following types can be used when binding parameters:
      *
-     * | JavaScript type | SQLite type |
-     * | -------------- | ----------- |
-     * | `string` | `TEXT` |
-     * | `number` | `INTEGER` or `DECIMAL` |
-     * | `boolean` | `INTEGER` (1 or 0) |
-     * | `Uint8Array` | `BLOB` |
-     * | `Buffer` | `BLOB` |
-     * | `bigint` | `INTEGER` |
-     * | `null` | `NULL` |
+     * | JavaScript type | SQLite type            |
+     * | --------------- | ---------------------- |
+     * | `string`        | `TEXT`                 |
+     * | `number`        | `INTEGER` or `DECIMAL` |
+     * | `boolean`       | `INTEGER` (1 or 0)     |
+     * | `Uint8Array`    | `BLOB`                 |
+     * | `Buffer`        | `BLOB`                 |
+     * | `bigint`        | `INTEGER`              |
+     * | `null`          | `NULL`                 |
      */
     get(...params: ParamsType): ReturnType | null;
 
@@ -687,15 +683,15 @@ declare module "bun:sqlite" {
      *
      * The following types can be used when binding parameters:
      *
-     * | JavaScript type | SQLite type |
-     * | -------------- | ----------- |
-     * | `string` | `TEXT` |
-     * | `number` | `INTEGER` or `DECIMAL` |
-     * | `boolean` | `INTEGER` (1 or 0) |
-     * | `Uint8Array` | `BLOB` |
-     * | `Buffer` | `BLOB` |
-     * | `bigint` | `INTEGER` |
-     * | `null` | `NULL` |
+     * | JavaScript type | SQLite type            |
+     * | --------------- | ---------------------- |
+     * | `string`        | `TEXT`                 |
+     * | `number`        | `INTEGER` or `DECIMAL` |
+     * | `boolean`       | `INTEGER` (1 or 0)     |
+     * | `Uint8Array`    | `BLOB`                 |
+     * | `Buffer`        | `BLOB`                 |
+     * | `bigint`        | `INTEGER`              |
+     * | `null`          | `NULL`                 |
      */
     run(...params: ParamsType): Changes;
 
@@ -727,15 +723,15 @@ declare module "bun:sqlite" {
      *
      * The following types can be used when binding parameters:
      *
-     * | JavaScript type | SQLite type |
-     * | ---------------|-------------|
-     * | `string` | `TEXT` |
-     * | `number` | `INTEGER` or `DECIMAL` |
-     * | `boolean` | `INTEGER` (1 or 0) |
-     * | `Uint8Array` | `BLOB` |
-     * | `Buffer` | `BLOB` |
-     * | `bigint` | `INTEGER` |
-     * | `null` | `NULL` |
+     * | JavaScript type | SQLite type            |
+     * | --------------- | ---------------------- |
+     * | `string`        | `TEXT`                 |
+     * | `number`        | `INTEGER` or `DECIMAL` |
+     * | `boolean`       | `INTEGER` (1 or 0)     |
+     * | `Uint8Array`    | `BLOB`                 |
+     * | `Buffer`        | `BLOB`                 |
+     * | `bigint`        | `INTEGER`              |
+     * | `null`          | `NULL`                 |
      */
     values(...params: ParamsType): Array<Array<string | bigint | number | boolean | Uint8Array>>;
 

package/test.d.ts

@@ -426,8 +426,13 @@ declare module "bun:test" {
      *
      * @param label the label for the test
      * @param fn the test function
+     * @param options the test timeout or options
      */
-    failing(label: string, fn?: (() => void | Promise<unknown>) | ((done: (err?: unknown) => void) => void)): void;
+    failing(
+      label: string,
+      fn?: (() => void | Promise<unknown>) | ((done: (err?: unknown) => void) => void),
+      options?: number | TestOptions,
+    ): void;
     /**
      * Runs this test, if `condition` is true.
      *