bun-types 0.1.11 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bun-types",
-  "version": "0.1.11",
+  "version": "0.2.0",
   "description": "Type definitions for Bun, an incredibly fast JavaScript runtime",
   "types": "types.d.ts",
   "files": [

package/types.d.ts

@@ -1,4 +1,4 @@
-// Type definitions for bun 0.1.11
+// Type definitions for bun 0.2.0
 // Project: https://github.com/oven-sh/bun
 // Definitions by: Jarred Sumner <https://github.com/Jarred-Sumner>
 // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
@@ -823,7 +823,10 @@ interface ResponseInit {
  * ```
  */
 declare class Response implements BlobInterface {
-  constructor(body: BlobPart | BlobPart[], options?: ResponseInit);
+  constructor(
+    body?: ReadableStream | BlobPart | BlobPart[] | null,
+    options?: ResponseInit
+  );
 
   /**
    * Create a new {@link Response} with a JSON body
@@ -885,6 +888,21 @@ declare class Response implements BlobInterface {
    */
   readonly headers: Headers;
 
+  /**
+   * HTTP response body as a [ReadableStream](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream)
+   *
+   * This is part of web Streams
+   *
+   * @example
+   * ```ts
+   * const {body} = await fetch("https://remix.run");
+   * const reader = body.getReader();
+   * const {done, value} = await reader.read();
+   * console.log(value); // Uint8Array
+   * ```
+   */
+  readonly body: ReadableStream | null;
+
   /**
    * Has the body of the response already been consumed?
    */
@@ -1020,7 +1038,9 @@ interface RequestInit {
   /**
    * A boolean to set request's keepalive.
    *
-   * Note: as of Bun v0.0.74, this is not implemented yet.
+   * Available in Bun v0.2.0 and above.
+   *
+   * This is enabled by default
    */
   keepalive?: boolean;
   /**
@@ -1055,6 +1075,11 @@ interface RequestInit {
    * This does nothing in Bun
    */
   window?: any;
+
+  /**
+   * Enable or disable HTTP request timeout
+   */
+  timeout?: boolean;
 }
 
 /**
@@ -1105,6 +1130,19 @@ declare class Request implements BlobInterface {
    */
   text(): Promise<string>;
 
+  /**
+   * Consume the [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) body as a {@link ReadableStream}.
+   *
+   * Streaming **outgoing** HTTP request bodies via `fetch()` is not yet supported in
+   * Bun.
+   *
+   * Reading **incoming** HTTP request bodies via `ReadableStream` in `Bun.serve()` is supported
+   * as of Bun v0.2.0.
+   *
+   *
+   */
+  get body(): ReadableStream | null;
+
   /**
    * Consume the [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) body as an ArrayBuffer.
    *
@@ -1436,7 +1474,21 @@ declare function clearTimeout(id?: number): void;
  *
  *
  */
-declare function fetch(url: string, init?: RequestInit): Promise<Response>;
+declare function fetch(
+  url: string,
+  init?: RequestInit,
+  /**
+   * This is a custom property that is not part of the Fetch API specification.
+   * It exists mostly as a debugging tool
+   */
+  bunOnlyOptions?: {
+    /**
+     * Log the raw HTTP request & response to stdout. This API may be
+     * removed in a future version of Bun without notice.
+     */
+    verbose: boolean;
+  }
+): Promise<Response>;
 
 /**
  * Send a HTTP(s) request
@@ -1449,7 +1501,21 @@ declare function fetch(url: string, init?: RequestInit): Promise<Response>;
  *
  */
 // tslint:disable-next-line:unified-signatures
-declare function fetch(request: Request, init?: RequestInit): Promise<Response>;
+declare function fetch(
+  request: Request,
+  init?: RequestInit,
+  /**
+   * This is a custom property that is not part of the Fetch API specification.
+   * It exists mostly as a debugging tool
+   */
+  bunOnlyOptions?: {
+    /**
+     * Log the raw HTTP request & response to stdout. This API may be
+     * removed in a future version of Bun without notice.
+     */
+    verbose: boolean;
+  }
+): Promise<Response>;
 
 declare function queueMicrotask(callback: () => void): void;
 /**
@@ -2108,17 +2174,9 @@ declare var Loader: {
    * instead.
    *
    * @param specifier - module specifier as it appears in transpiled source code
+   * @param referrer - module specifier that is resolving this specifier
    */
-  resolve: (specifier: string) => Promise<string>;
-  /**
-   * Synchronously resolve a module specifier
-   *
-   * This may return a path to `node_modules.server.bun`, which will be confusing.
-   *
-   * Consider {@link Bun.resolveSync}
-   * instead.
-   */
-  resolveSync: (specifier: string, from: string) => string;
+  resolve: (specifier: strin, referrer: string) => string;
 };
 
 /** This Streams API interface represents a readable stream of byte data. The Fetch API offers a concrete instance of a ReadableStream through the body property of a Response object. */
@@ -2139,6 +2197,8 @@ interface ReadableStream<R = any> {
     callbackfn: (value: any, key: number, parent: ReadableStream<R>) => void,
     thisArg?: any
   ): void;
+  [Symbol.asyncIterator](): AsyncIterableIterator<R>;
+  values(options: { preventCancel: boolean }): AsyncIterableIterator<R>;
 }
 
 declare var ReadableStream: {
@@ -13440,6 +13500,28 @@ declare module "bun" {
     end(): ArrayBuffer | Uint8Array;
   }
 
+  /**
+   * Fast incremental writer for files and pipes.
+   *
+   * This uses the same interface as {@link ArrayBufferSink}, but writes to a file or pipe.
+   */
+  export interface FileSink {
+    /**
+     * Write a chunk of data to the file.
+     *
+     * If the file descriptor is not writable yet, the data is buffered.
+     */
+    write(chunk: string | ArrayBufferView | ArrayBuffer): number;
+    /**
+     * Flush the internal buffer, committing the data to disk or the pipe.
+     */
+    flush(): number | Promise<number>;
+    /**
+     * Close the file descriptor. This also flushes the internal buffer.
+     */
+    end(error?: Error): number | Promise<number>;
+  }
+
   /**
    * [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) powered by the fastest system calls available for operating on files.
    *
@@ -13476,6 +13558,15 @@ declare module "bun" {
      * @param end - absolute offset in bytes (relative to 0)
      */
     slice(begin?: number, end?: number): FileBlob;
+
+    /**
+     * Incremental writer for files and pipes.
+     */
+    writer(): FileSink;
+
+    readonly readable: ReadableStream;
+
+    // TODO: writable: WritableStream;
   }
 
   /**
@@ -13876,12 +13967,65 @@ declare module "bun" {
      */
     stop(): void;
 
+    /**
+     * 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.
+     *
+     * @example
+     *
+     * ```js
+     * // create the server
+     * const server = Bun.serve({
+     *  fetch(request) {
+     *    return new Response("Hello World v1")
+     *  }
+     * });
+     *
+     * // Update the server to return a different response
+     * server.update({
+     *   fetch(request) {
+     *     return new Response("Hello World v2")
+     *   }
+     * });
+     * ```
+     *
+     * Passing other options such as `port` or `hostname` won't do anything.
+     */
+    reload(options: Serve): void;
+
+    /**
+     * 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
+     */
+    fetch(request: Request): Response | Promise<Response>;
+
     /**
      * How many requests are in-flight right now?
      */
     readonly pendingRequests: number;
     readonly port: number;
+    /**
+     * The hostname the server is listening on. Does not include the port
+     * @example
+     * ```js
+     * "localhost"
+     * ```
+     */
     readonly hostname: string;
+    /**
+     * Is the server running in development mode?
+     *
+     * In development mode, `Bun.serve()` returns rendered error messages with
+     * stack traces instead of a generic 500 error. This makes debugging easier,
+     * but development mode shouldn't be used in production or you will risk
+     * leaking sensitive information.
+     *
+     */
     readonly development: boolean;
   }
 
@@ -14653,6 +14797,271 @@ declare module "bun" {
   }
 
   var plugin: BunPlugin;
+
+  declare namespace SpawnOptions {
+    type Readable =
+      | "inherit"
+      | "pipe"
+      | null
+      | undefined
+      | FileBlob
+      | ArrayBufferView
+      | number;
+
+    type Writable =
+      | "inherit"
+      | "pipe"
+      | null
+      | undefined
+      | FileBlob
+      | ArrayBufferView
+      | Blob
+      | number
+      | Response
+      | Request;
+
+    interface OptionsObject {
+      /**
+       * The current working directory of the process
+       *
+       * Defaults to `process.cwd()`
+       */
+      cwd?: string;
+
+      /**
+       * The environment variables of the process
+       *
+       * Defaults to `process.env` as it was when the current Bun process launched.
+       *
+       * Changes to `process.env` at runtime won't automatically be reflected in the default value. For that, you can pass `process.env` explicitly.
+       *
+       */
+      env?: Record<string, string>;
+
+      /**
+       * The standard file descriptors of the process
+       * - `inherit`: The process will inherit the standard input of the current process
+       * - `pipe`: The process will have a new pipe for standard input
+       * - `null`: The process will have no standard input
+       * - `ArrayBufferView`, `Blob`: The process will read from the buffer
+       * - `number`: The process will read from the file descriptor
+       * - `undefined`: The default value
+       */
+      stdio?: [
+        SpawnOptions.Writable,
+        SpawnOptions.Readable,
+        SpawnOptions.Readable
+      ];
+      stdin?: SpawnOptions.Writable;
+      stdout?: SpawnOptions.Readable;
+      stderr?: SpawnOptions.Readable;
+
+      /**
+       * Callback that runs when the {@link Subprocess} exits
+       *
+       * You can also do `await subprocess.exited` to wait for the process to exit.
+       *
+       * @example
+       *
+       * ```ts
+       * const subprocess = spawn({
+       *  cmd: ["echo", "hello"],
+       *  onExit: (code) => {
+       *    console.log(`Process exited with code ${code}`);
+       *   },
+       * });
+       * ```
+       */
+      onExit?: (exitCode: number) => void | Promise<void>;
+    }
+  }
+
+  interface Subprocess {
+    readonly stdin: undefined | number | FileSink;
+    readonly stdout: undefined | number | ReadableStream;
+    readonly stderr: undefined | number | ReadableStream;
+
+    /**
+     * This returns the same value as {@link Subprocess.stdout}
+     *
+     * It exists for compatibility with {@link ReadableStream.pipeThrough}
+     */
+    readonly readable: undefined | number | ReadableStream;
+
+    /**
+     * The process ID of the child process
+     * @example
+     * ```ts
+     * const { pid } = Bun.spawn({ cmd: ["echo", "hello"] });
+     * console.log(pid); // 1234
+     * ```
+     */
+    readonly pid: number;
+    /**
+     * The exit code of the process
+     *
+     * The promise will resolve when the process exits
+     */
+    readonly exited: Promise<number>;
+
+    /**
+     * Has the process exited?
+     */
+    readonly killed: boolean;
+
+    /**
+     * Kill the process
+     * @param exitCode The exitCode to send to the process
+     */
+    kill(exitCode?: number): void;
+
+    /**
+     * This method will tell Bun to wait for this process to exit after you already
+     * called `unref()`.
+     *
+     * Before shutting down, Bun will wait for all subprocesses to exit by default
+     */
+    ref(): void;
+
+    /**
+     * Before shutting down, Bun will wait for all subprocesses to exit by default
+     *
+     * This method will tell Bun to not wait for this process to exit before shutting down.
+     */
+    unref(): void;
+  }
+
+  interface SyncSubprocess {
+    stdout?: Buffer;
+    stderr?: Buffer;
+    exitCode: number;
+    success: boolean;
+  }
+
+  /**
+   * Spawn a new process
+   *
+   * ```js
+   * const subprocess = Bun.spawn({
+   *  cmd: ["echo", "hello"],
+   *  stdout: "pipe",
+   * });
+   * const text = await readableStreamToText(subprocess.stdout);
+   * console.log(text); // "hello\n"
+   * ```
+   *
+   * Internally, this uses [posix_spawn(2)](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/posix_spawn.2.html)
+   */
+  function spawn(
+    options: SpawnOptions.OptionsObject & {
+      /**
+       * 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)`.
+       *
+       */
+      cmd: [string, ...string[]];
+    }
+  ): Subprocess;
+
+  /**
+   * Spawn a new process
+   *
+   * ```js
+   * const {stdout} = Bun.spawn(["echo", "hello"]));
+   * const text = await readableStreamToText(stdout);
+   * console.log(text); // "hello\n"
+   * ```
+   *
+   * Internally, this uses [posix_spawn(2)](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/posix_spawn.2.html)
+   */
+  function spawn(
+    /**
+     * The command to run
+     * @example
+     * ```ts
+     * const subprocess = Bun.spawn(["echo", "hello"]);
+     */
+    cmds: [
+      /** One command is required */
+      string,
+      /** Additional arguments */
+      ...string[]
+    ],
+    options?: SpawnOptions.OptionsObject
+  ): Subprocess;
+
+  /**
+   * Spawn a new process
+   *
+   * ```js
+   * const {stdout} = Bun.spawnSync({
+   *  cmd: ["echo", "hello"],
+   * });
+   * console.log(stdout.toString()); // "hello\n"
+   * ```
+   *
+   * Internally, this uses [posix_spawn(2)](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/posix_spawn.2.html)
+   */
+  function spawnSync(
+    options: SpawnOptions.OptionsObject & {
+      /**
+       * 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)`.
+       *
+       */
+      cmd: [string, ...string[]];
+    }
+  ): SyncSubprocess;
+
+  /**
+   * Synchronously spawn a new process
+   *
+   * ```js
+   * const {stdout} = Bun.spawnSync(["echo", "hello"]));
+   * console.log(stdout.toString()); // "hello\n"
+   * ```
+   *
+   * Internally, this uses [posix_spawn(2)](https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/posix_spawn.2.html)
+   */
+  function spawnSync(
+    /**
+     * The command to run
+     * @example
+     * ```ts
+     * const subprocess = Bun.spawn(["echo", "hello"]);
+     */
+    cmds: [
+      /** One command is required */
+      string,
+      /** Additional arguments */
+      ...string[]
+    ],
+    options?: SpawnOptions.OptionsObject
+  ): SyncSubprocess;
+
+  /**
+   * The current version of Bun
+   * @example
+   * "0.2.0"
+   */
+  export const version: string;
+
+  /**
+   * The git sha at the time the currently-running version of Bun was compiled
+   * @example
+   * "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
+   */
+  export const revision: string;
 }
 
 type TypedArray =