bun-types 1.1.37-canary.20241124T140524 → 1.1.37

package/docs/api/streams.md

@@ -0,0 +1,214 @@
+Streams are an important abstraction for working with binary data without loading it all into memory at once. They are commonly used for reading and writing files, sending and receiving network requests, and processing large amounts of data.
+
+Bun implements the Web APIs [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) and [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream).
+
+{% callout %}
+Bun also implements the `node:stream` module, including [`Readable`](https://nodejs.org/api/stream.html#stream_readable_streams), [`Writable`](https://nodejs.org/api/stream.html#stream_writable_streams), and [`Duplex`](https://nodejs.org/api/stream.html#stream_duplex_and_transform_streams). For complete documentation, refer to the [Node.js docs](https://nodejs.org/api/stream.html).
+{% /callout %}
+
+To create a simple `ReadableStream`:
+
+```ts
+const stream = new ReadableStream({
+  start(controller) {
+    controller.enqueue("hello");
+    controller.enqueue("world");
+    controller.close();
+  },
+});
+```
+
+The contents of a `ReadableStream` can be read chunk-by-chunk with `for await` syntax.
+
+```ts
+for await (const chunk of stream) {
+  console.log(chunk);
+  // => "hello"
+  // => "world"
+}
+```
+
+## Direct `ReadableStream`
+
+Bun implements an optimized version of `ReadableStream` that avoid unnecessary data copying & queue management logic. With a traditional `ReadableStream`, chunks of data are _enqueued_. Each chunk is copied into a queue, where it sits until the stream is ready to send more data.
+
+```ts
+const stream = new ReadableStream({
+  start(controller) {
+    controller.enqueue("hello");
+    controller.enqueue("world");
+    controller.close();
+  },
+});
+```
+
+With a direct `ReadableStream`, chunks of data are written directly to the stream. No queueing happens, and there's no need to clone the chunk data into memory. The `controller` API is updated to reflect this; instead of `.enqueue()` you call `.write`.
+
+```ts
+const stream = new ReadableStream({
+  type: "direct",
+  pull(controller) {
+    controller.write("hello");
+    controller.write("world");
+  },
+});
+```
+
+When using a direct `ReadableStream`, all chunk queueing is handled by the destination. The consumer of the stream receives exactly what is passed to `controller.write()`, without any encoding or modification.
+
+## Async generator streams
+
+Bun also supports async generator functions as a source for `Response` and `Request`. This is an easy way to create a `ReadableStream` that fetches data from an asynchronous source.
+
+```ts
+const response = new Response(async function* () {
+  yield "hello";
+  yield "world";
+}());
+
+await response.text(); // "helloworld"
+```
+
+You can also use `[Symbol.asyncIterator]` directly.
+
+```ts
+const response = new Response({
+  [Symbol.asyncIterator]: async function* () {
+    yield "hello";
+    yield "world";
+  },
+});
+
+await response.text(); // "helloworld"
+```
+
+If you need more granular control over the stream, `yield` will return the direct ReadableStream controller.
+
+```ts
+const response = new Response({
+  [Symbol.asyncIterator]: async function* () {
+    const controller = yield "hello";
+    await controller.end();
+  },
+});
+
+await response.text(); // "hello"
+```
+
+## `Bun.ArrayBufferSink`
+
+The `Bun.ArrayBufferSink` class is a fast incremental writer for constructing an `ArrayBuffer` of unknown size.
+
+```ts
+const sink = new Bun.ArrayBufferSink();
+
+sink.write("h");
+sink.write("e");
+sink.write("l");
+sink.write("l");
+sink.write("o");
+
+sink.end();
+// ArrayBuffer(5) [ 104, 101, 108, 108, 111 ]
+```
+
+To instead retrieve the data as a `Uint8Array`, pass the `asUint8Array` option to the `start` method.
+
+```ts-diff
+const sink = new Bun.ArrayBufferSink();
+sink.start({
++ asUint8Array: true
+});
+
+sink.write("h");
+sink.write("e");
+sink.write("l");
+sink.write("l");
+sink.write("o");
+
+sink.end();
+// Uint8Array(5) [ 104, 101, 108, 108, 111 ]
+```
+
+The `.write()` method supports strings, typed arrays, `ArrayBuffer`, and `SharedArrayBuffer`.
+
+```ts
+sink.write("h");
+sink.write(new Uint8Array([101, 108]));
+sink.write(Buffer.from("lo").buffer);
+
+sink.end();
+```
+
+Once `.end()` is called, no more data can be written to the `ArrayBufferSink`. However, in the context of buffering a stream, it's useful to continuously write data and periodically `.flush()` the contents (say, into a `WriteableStream`). To support this, pass `stream: true` to the constructor.
+
+```ts
+const sink = new Bun.ArrayBufferSink();
+sink.start({
+  stream: true,
+});
+
+sink.write("h");
+sink.write("e");
+sink.write("l");
+sink.flush();
+// ArrayBuffer(5) [ 104, 101, 108 ]
+
+sink.write("l");
+sink.write("o");
+sink.flush();
+// ArrayBuffer(5) [ 108, 111 ]
+```
+
+The `.flush()` method returns the buffered data as an `ArrayBuffer` (or `Uint8Array` if `asUint8Array: true`) and clears internal buffer.
+
+To manually set the size of the internal buffer in bytes, pass a value for `highWaterMark`:
+
+```ts
+const sink = new Bun.ArrayBufferSink();
+sink.start({
+  highWaterMark: 1024 * 1024, // 1 MB
+});
+```
+
+{% details summary="Reference" %}
+
+```ts
+/**
+ * Fast incremental writer that becomes an `ArrayBuffer` on end().
+ */
+export class ArrayBufferSink {
+  constructor();
+
+  start(options?: {
+    asUint8Array?: boolean;
+    /**
+     * Preallocate an internal buffer of this size
+     * This can significantly improve performance when the chunk size is small
+     */
+    highWaterMark?: number;
+    /**
+     * On {@link ArrayBufferSink.flush}, return the written data as a `Uint8Array`.
+     * Writes will restart from the beginning of the buffer.
+     */
+    stream?: boolean;
+  }): void;
+
+  write(
+    chunk: string | ArrayBufferView | ArrayBuffer | SharedArrayBuffer,
+  ): number;
+  /**
+   * Flush the internal buffer
+   *
+   * If {@link ArrayBufferSink.start} was passed a `stream` option, this will return a `ArrayBuffer`
+   * If {@link 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
+   */
+  flush(): number | Uint8Array | ArrayBuffer;
+  end(): ArrayBuffer | Uint8Array;
+}
+```
+
+{% /details %}

package/docs/api/tcp.md

@@ -0,0 +1,221 @@
+Use Bun's native TCP API to implement performance sensitive systems like database clients, game servers, or anything that needs to communicate over TCP (instead of HTTP). This is a low-level API intended for library authors and for advanced use cases.
+
+## Start a server (`Bun.listen()`)
+
+To start a TCP server with `Bun.listen`:
+
+```ts
+Bun.listen({
+  hostname: "localhost",
+  port: 8080,
+  socket: {
+    data(socket, data) {}, // message received from client
+    open(socket) {}, // socket opened
+    close(socket) {}, // socket closed
+    drain(socket) {}, // socket ready for more data
+    error(socket, error) {}, // error handler
+  },
+});
+```
+
+{% details summary="An API designed for speed" %}
+
+In Bun, a set of handlers are declared once per server instead of assigning callbacks to each socket, as with Node.js `EventEmitters` or the web-standard `WebSocket` API.
+
+```ts
+Bun.listen({
+  hostname: "localhost",
+  port: 8080,
+  socket: {
+    open(socket) {},
+    data(socket, data) {},
+    drain(socket) {},
+    close(socket) {},
+    error(socket, error) {},
+  },
+});
+```
+
+For performance-sensitive servers, assigning listeners to each socket can cause significant garbage collector pressure and increase memory usage. By contrast, Bun only allocates one handler function for each event and shares it among all sockets. This is a small optimization, but it adds up.
+
+{% /details %}
+
+Contextual data can be attached to a socket in the `open` handler.
+
+```ts
+type SocketData = { sessionId: string };
+
+Bun.listen<SocketData>({
+  hostname: "localhost",
+  port: 8080,
+  socket: {
+    data(socket, data) {
+      socket.write(`${socket.data.sessionId}: ack`);
+    },
+    open(socket) {
+      socket.data = { sessionId: "abcd" };
+    },
+  },
+});
+```
+
+To enable TLS, pass a `tls` object containing `key` and `cert` fields.
+
+```ts
+Bun.listen({
+  hostname: "localhost",
+  port: 8080,
+  socket: {
+    data(socket, data) {},
+  },
+  tls: {
+    // can be string, BunFile, TypedArray, Buffer, or array thereof
+    key: Bun.file("./key.pem"),
+    cert: Bun.file("./cert.pem"),
+  },
+});
+```
+
+The `key` and `cert` fields expect the _contents_ of your TLS key and certificate. This can be a string, `BunFile`, `TypedArray`, or `Buffer`.
+
+```ts
+Bun.listen({
+  // ...
+  tls: {
+    // BunFile
+    key: Bun.file("./key.pem"),
+    // Buffer
+    key: fs.readFileSync("./key.pem"),
+    // string
+    key: fs.readFileSync("./key.pem", "utf8"),
+    // array of above
+    key: [Bun.file("./key1.pem"), Bun.file("./key2.pem")],
+  },
+});
+```
+
+The result of `Bun.listen` is a server that conforms to the `TCPSocket` interface.
+
+```ts
+const server = Bun.listen({
+  /* config*/
+});
+
+// stop listening
+// parameter determines whether active connections are closed
+server.stop(true);
+
+// let Bun process exit even if server is still listening
+server.unref();
+```
+
+## Create a connection (`Bun.connect()`)
+
+Use `Bun.connect` to connect to a TCP server. Specify the server to connect to with `hostname` and `port`. TCP clients can define the same set of handlers as `Bun.listen`, plus a couple client-specific handlers.
+
+```ts
+// The client
+const socket = await Bun.connect({
+  hostname: "localhost",
+  port: 8080,
+
+  socket: {
+    data(socket, data) {},
+    open(socket) {},
+    close(socket) {},
+    drain(socket) {},
+    error(socket, error) {},
+
+    // client-specific handlers
+    connectError(socket, error) {}, // connection failed
+    end(socket) {}, // connection closed by server
+    timeout(socket) {}, // connection timed out
+  },
+});
+```
+
+To require TLS, specify `tls: true`.
+
+```ts
+// The client
+const socket = await Bun.connect({
+  // ... config
+  tls: true,
+});
+```
+
+## Hot reloading
+
+Both TCP servers and sockets can be hot reloaded with new handlers.
+
+{% codetabs %}
+
+```ts#Server
+const server = Bun.listen({ /* config */ })
+
+// reloads handlers for all active server-side sockets
+server.reload({
+  socket: {
+    data(){
+      // new 'data' handler
+    }
+  }
+})
+```
+
+```ts#Client
+const socket = await Bun.connect({ /* config */ })
+socket.reload({
+  data(){
+    // new 'data' handler
+  }
+})
+```
+
+{% /codetabs %}
+
+## Buffering
+
+Currently, TCP sockets in Bun do not buffer data. For performance-sensitive code, it's important to consider buffering carefully. For example, this:
+
+```ts
+socket.write("h");
+socket.write("e");
+socket.write("l");
+socket.write("l");
+socket.write("o");
+```
+
+...performs significantly worse than this:
+
+```ts
+socket.write("hello");
+```
+
+To simplify this for now, consider using Bun's `ArrayBufferSink` with the `{stream: true}` option:
+
+```ts
+import { ArrayBufferSink } from "bun";
+
+const sink = new ArrayBufferSink();
+sink.start({ stream: true, highWaterMark: 1024 });
+
+sink.write("h");
+sink.write("e");
+sink.write("l");
+sink.write("l");
+sink.write("o");
+
+queueMicrotask(() => {
+  const data = sink.flush();
+  const wrote = socket.write(data);
+  if (wrote < data.byteLength) {
+    // put it back in the sink if the socket is full
+    sink.write(data.subarray(wrote));
+  }
+});
+```
+
+{% callout %}
+**Corking** — Support for corking is planned, but in the meantime backpressure must be managed manually with the `drain` handler.
+{% /callout %}

package/docs/api/test.md

@@ -0,0 +1 @@
+See the [`bun test`](https://bun.sh/docs/cli/test) documentation.

package/docs/api/transpiler.md

@@ -0,0 +1,274 @@
+Bun exposes its internal transpiler via the `Bun.Transpiler` class. To create an instance of Bun's transpiler:
+
+```ts
+const transpiler = new Bun.Transpiler({
+  loader: "tsx", // "js | "jsx" | "ts" | "tsx"
+});
+```
+
+## `.transformSync()`
+
+Transpile code synchronously with the `.transformSync()` method. Modules are not resolved and the code is not executed. The result is a string of vanilla JavaScript code.
+
+<!-- It is synchronous and runs in the same thread as other JavaScript code. -->
+
+{% codetabs %}
+
+```js#Example
+const transpiler = new Bun.Transpiler({
+  loader: 'tsx',
+});
+
+const code = `
+import * as whatever from "./whatever.ts"
+export function Home(props: {title: string}){
+  return <p>{props.title}</p>;
+}`;
+
+const result = transpiler.transformSync(code);
+```
+
+```js#Result
+import { __require as require } from "bun:wrap";
+import * as JSX from "react/jsx-dev-runtime";
+var jsx = require(JSX).jsxDEV;
+
+export default jsx(
+  "div",
+  {
+    children: "hi!",
+  },
+  undefined,
+  false,
+  undefined,
+  this,
+);
+```
+
+{% /codetabs %}
+
+To override the default loader specified in the `new Bun.Transpiler()` constructor, pass a second argument to `.transformSync()`.
+
+```ts
+transpiler.transformSync("<div>hi!</div>", "tsx");
+```
+
+{% details summary="Nitty gritty" %}
+When `.transformSync` is called, the transpiler is run in the same thread as the currently executed code.
+
+If a macro is used, it will be run in the same thread as the transpiler, but in a separate event loop from the rest of your application. Currently, globals between macros and regular code are shared, which means it is possible (but not recommended) to share states between macros and regular code. Attempting to use AST nodes outside of a macro is undefined behavior.
+{% /details %}
+
+## `.transform()`
+
+The `transform()` method is an async version of `.transformSync()` that returns a `Promise<string>`.
+
+```js
+const transpiler = new Bun.Transpiler({ loader: "jsx" });
+const result = await transpiler.transform("<div>hi!</div>");
+console.log(result);
+```
+
+Unless you're transpiling _many_ large files, you should probably use `Bun.Transpiler.transformSync`. The cost of the threadpool will often take longer than actually transpiling code.
+
+```ts
+await transpiler.transform("<div>hi!</div>", "tsx");
+```
+
+{% details summary="Nitty gritty" %}
+The `.transform()` method runs the transpiler in Bun's worker threadpool, so if you run it 100 times, it will run it across `Math.floor($cpu_count * 0.8)` threads, without blocking the main JavaScript thread.
+
+If your code uses a macro, it will potentially spawn a new copy of Bun's JavaScript runtime environment in that new thread.
+{% /details %}
+
+## `.scan()`
+
+The `Transpiler` instance can also scan some source code and return a list of its imports and exports, plus additional metadata about each one. [Type-only](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-3-8.html#type-only-imports-and-export) imports and exports are ignored.
+
+{% codetabs %}
+
+```ts#Example
+const transpiler = new Bun.Transpiler({
+  loader: 'tsx',
+});
+
+const code = `
+import React from 'react';
+import type {ReactNode} from 'react';
+const val = require('./cjs.js')
+import('./loader');
+
+export const name = "hello";
+`;
+
+const result = transpiler.scan(code);
+```
+
+```json#Output
+{
+  "exports": [
+    "name"
+  ],
+  "imports": [
+    {
+      "kind": "import-statement",
+      "path": "react"
+    },
+    {
+      "kind": "import-statement",
+      "path": "remix"
+    },
+    {
+      "kind": "dynamic-import",
+      "path": "./loader"
+    }
+  ]
+}
+```
+
+{% /codetabs %}
+
+Each import in the `imports` array has a `path` and `kind`. Bun categories imports into the following kinds:
+
+- `import-statement`: `import React from 'react'`
+- `require-call`: `const val = require('./cjs.js')`
+- `require-resolve`: `require.resolve('./cjs.js')`
+- `dynamic-import`: `import('./loader')`
+- `import-rule`: `@import 'foo.css'`
+- `url-token`: `url('./foo.png')`
+<!-- - `internal`: `import {foo} from 'bun:internal'`
+- `entry-point`: `import {foo} from 'bun:entry'` -->
+
+## `.scanImports()`
+
+For performance-sensitive code, you can use the `.scanImports()` method to get a list of imports. It's faster than `.scan()` (especially for large files) but marginally less accurate due to some performance optimizations.
+
+{% codetabs %}
+
+```ts#Example
+const transpiler = new Bun.Transpiler({
+  loader: 'tsx',
+});
+
+const code = `
+import React from 'react';
+import type {ReactNode} from 'react';
+const val = require('./cjs.js')
+import('./loader');
+
+export const name = "hello";
+`;
+
+const result = transpiler.scanImports(code);
+```
+
+```json#Results
+[
+  {
+    kind: "import-statement",
+    path: "react"
+  }, {
+    kind: "require-call",
+    path: "./cjs.js"
+  }, {
+    kind: "dynamic-import",
+    path: "./loader"
+  }
+]
+```
+
+{% /codetabs %}
+
+## Reference
+
+```ts
+type Loader = "jsx" | "js" | "ts" | "tsx";
+
+interface TranspilerOptions {
+  // Replace key with value. Value must be a JSON string.
+  // { "process.env.NODE_ENV": "\"production\"" }
+  define?: Record<string, string>,
+
+  // Default loader for this transpiler
+  loader?: Loader,
+
+  // Default platform to target
+  // This affects how import and/or require is used
+  target?: "browser" | "bun" | "node",
+
+  // Specify a tsconfig.json file as stringified JSON or an object
+  // Use this to set a custom JSX factory, fragment, or import source
+  // For example, if you want to use Preact instead of React. Or if you want to use Emotion.
+  tsconfig?: string | TSConfig,
+
+  // Replace imports with macros
+  macro?: MacroMap,
+
+  // Specify a set of exports to eliminate
+  // Or rename certain exports
+  exports?: {
+      eliminate?: string[];
+      replace?: Record<string, string>;
+  },
+
+  // Whether to remove unused imports from transpiled file
+  // Default: false
+  trimUnusedImports?: boolean,
+
+  // Whether to enable a set of JSX optimizations
+  // jsxOptimizationInline ...,
+
+  // Experimental whitespace minification
+  minifyWhitespace?: boolean,
+
+  // Whether to inline constant values
+  // Typically improves performance and decreases bundle size
+  // Default: true
+  inline?: boolean,
+}
+
+// Map import paths to macros
+interface MacroMap {
+  // {
+  //   "react-relay": {
+  //     "graphql": "bun-macro-relay/bun-macro-relay.tsx"
+  //   }
+  // }
+  [packagePath: string]: {
+    [importItemName: string]: string,
+  },
+}
+
+class Bun.Transpiler {
+  constructor(options: TranspilerOptions)
+
+  transform(code: string, loader?: Loader): Promise<string>
+  transformSync(code: string, loader?: Loader): string
+
+  scan(code: string): {exports: string[], imports: Import}
+  scanImports(code: string): Import[]
+}
+
+type Import = {
+  path: string,
+  kind:
+  // import foo from 'bar'; in JavaScript
+  | "import-statement"
+  // require("foo") in JavaScript
+  | "require-call"
+  // require.resolve("foo") in JavaScript
+  | "require-resolve"
+  // Dynamic import() in JavaScript
+  | "dynamic-import"
+  // @import() in CSS
+  | "import-rule"
+  // url() in CSS
+  | "url-token"
+  // The import was injected by Bun
+  | "internal" 
+  // Entry point (not common)
+  | "entry-point"
+}
+
+const transpiler = new Bun.Transpiler({ loader: "jsx" });
+```