@depup/bun-types 1.3.11-depup.0

package/docs/runtime/networking/tcp.mdx

@@ -0,0 +1,239 @@
+---
+title: TCP
+description: 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 server.ts icon="/icons/typescript.svg"
+Bun.listen({
+  hostname: "localhost",
+  port: 8080,
+  socket: {
+    data(socket, data) {}, // message received from client
+    open(socket) {}, // socket opened
+    close(socket, error) {}, // socket closed
+    drain(socket) {}, // socket ready for more data
+    error(socket, error) {}, // error handler
+  },
+});
+```
+
+<Accordion title="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 server.ts icon="/icons/typescript.svg"
+Bun.listen({
+  hostname: "localhost",
+  port: 8080,
+  socket: {
+    open(socket) {},
+    data(socket, data) {},
+    drain(socket) {},
+    close(socket, error) {},
+    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.
+
+</Accordion>
+
+Contextual data can be attached to a socket in the `open` handler.
+
+```ts server.ts icon="/icons/typescript.svg"
+type SocketData = { sessionId: string };
+
+Bun.listen<SocketData>({
+  hostname: "localhost",
+  port: 8080,
+  socket: {
+    data(socket, data) {
+      socket.write(`${socket.data.sessionId}: ack`); // [!code ++]
+    },
+    open(socket) {
+      socket.data = { sessionId: "abcd" }; // [!code ++]
+    },
+  },
+});
+```
+
+To enable TLS, pass a `tls` object containing `key` and `cert` fields.
+
+```ts server.ts icon="/icons/typescript.svg"
+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"), // [!code ++]
+    cert: Bun.file("./cert.pem"), // [!code ++]
+  },
+});
+```
+
+The `key` and `cert` fields expect the _contents_ of your TLS key and certificate. This can be a string, `BunFile`, `TypedArray`, or `Buffer`.
+
+```ts server.ts icon="/icons/typescript.svg"
+Bun.listen({
+  // ...
+  tls: {
+    key: Bun.file("./key.pem"), // BunFile
+    key: fs.readFileSync("./key.pem"), // Buffer
+    key: fs.readFileSync("./key.pem", "utf8"), // string
+    key: [Bun.file("./key1.pem"), Bun.file("./key2.pem")], // array of above
+  },
+});
+```
+
+The result of `Bun.listen` is a server that conforms to the `TCPSocket` interface.
+
+```ts server.ts icon="/icons/typescript.svg"
+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 server.ts icon="/icons/typescript.svg"
+// The client
+const socket = await Bun.connect({
+  hostname: "localhost",
+  port: 8080,
+
+  socket: {
+    data(socket, data) {},
+    open(socket) {},
+    close(socket, error) {},
+    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, // [!code ++]
+});
+```
+
+---
+
+## Hot reloading
+
+Both TCP servers and sockets can be hot reloaded with new handlers.
+
+<CodeGroup>
+
+```ts server.ts icon="/icons/typescript.svg"
+const server = Bun.listen({
+  /* config */
+});
+
+// reloads handlers for all active server-side sockets
+server.reload({
+  socket: {
+    data() {
+      // new 'data' handler
+    },
+  },
+});
+```
+
+```ts client.ts icon="/icons/typescript.svg"
+const socket = await Bun.connect({
+  /* config */
+});
+
+socket.reload({
+  data() {
+    // new 'data' handler
+  },
+});
+```
+
+</CodeGroup>
+
+---
+
+## 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 server.ts icon="/icons/typescript.svg"
+import { ArrayBufferSink } from "bun";
+
+const sink = new ArrayBufferSink();
+sink.start({
+  stream: true, // [!code ++]
+  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));
+  }
+});
+```
+
+<Note>
+**Corking**
+
+Support for corking is planned, but in the meantime backpressure must be managed manually with the `drain` handler.
+
+</Note>

package/docs/runtime/networking/udp.mdx

@@ -0,0 +1,180 @@
+---
+title: UDP
+description: Use Bun's UDP API to implement services with advanced real-time requirements, such as voice chat.
+---
+
+## Bind a UDP socket (`Bun.udpSocket()`)
+
+To create a new (bound) UDP socket:
+
+```ts
+const socket = await Bun.udpSocket({});
+console.log(socket.port); // assigned by the operating system
+```
+
+Specify a port:
+
+```ts
+const socket = await Bun.udpSocket({
+  port: 41234, // [!code ++]
+});
+
+console.log(socket.port); // 41234
+```
+
+### Send a datagram
+
+Specify the data to send, as well as the destination port and address.
+
+```ts
+socket.send("Hello, world!", 41234, "127.0.0.1");
+```
+
+Note that the address must be a valid IP address - `send` does not perform
+DNS resolution, as it is intended for low-latency operations.
+
+### Receive datagrams
+
+When creating your socket, add a callback to specify what should be done when packets are received:
+
+```ts server.ts icon="/icons/typescript.svg"
+const server = await Bun.udpSocket({
+  socket: {
+    data(socket, buf, port, addr) {
+      console.log(`message from ${addr}:${port}:`);
+      console.log(buf.toString());
+    },
+  },
+});
+
+const client = await Bun.udpSocket({});
+client.send("Hello!", server.port, "127.0.0.1");
+```
+
+### Connections
+
+While UDP does not have a concept of a connection, many UDP communications (especially as a client) involve only one peer.
+In such cases it can be beneficial to connect the socket to that peer, which specifies to which address all packets are sent
+and restricts incoming packets to that peer only.
+
+```ts server.ts icon="/icons/typescript.svg"
+const server = await Bun.udpSocket({
+  socket: {
+    data(socket, buf, port, addr) {
+      console.log(`message from ${addr}:${port}:`);
+      console.log(buf.toString());
+    },
+  },
+});
+
+const client = await Bun.udpSocket({
+  connect: {
+    port: server.port,
+    hostname: "127.0.0.1",
+  },
+});
+
+client.send("Hello");
+```
+
+Because connections are implemented on the operating system level, you can potentially observe performance benefits, too.
+
+### Send many packets at once using `sendMany()`
+
+If you want to send a large volume of packets at once, it can make sense to batch them all together to avoid the overhead
+of making a system call for each. This is made possible by the `sendMany()` API:
+
+For an unconnected socket, `sendMany` takes an array as its only argument. Each set of three array elements describes a packet:
+The first item is the data to be sent, the second is the target port, and the last is the target address.
+
+```ts server.ts icon="/icons/typescript.svg"
+const socket = await Bun.udpSocket({});
+
+// sends 'Hello' to 127.0.0.1:41234, and 'foo' to 1.1.1.1:53 in a single operation
+socket.sendMany(["Hello", 41234, "127.0.0.1", "foo", 53, "1.1.1.1"]);
+```
+
+With a connected socket, `sendMany` simply takes an array, where each element represents the data to be sent to the peer.
+
+```ts server.ts icon="/icons/typescript.svg"
+const socket = await Bun.udpSocket({
+  connect: {
+    port: 41234,
+    hostname: "localhost",
+  },
+});
+
+socket.sendMany(["foo", "bar", "baz"]);
+```
+
+`sendMany` returns the number of packets that were successfully sent. As with `send`, `sendMany` only takes valid IP addresses
+as destinations, as it does not perform DNS resolution.
+
+### Handle backpressure
+
+It may happen that a packet that you're sending does not fit into the operating system's packet buffer. You can detect that this
+has happened when:
+
+- `send` returns `false`
+- `sendMany` returns a number smaller than the number of packets you specified. In this case, the `drain` socket handler will be called once the socket becomes writable again:
+
+```ts
+const socket = await Bun.udpSocket({
+  socket: {
+    drain(socket) {
+      // continue sending data
+    },
+  },
+});
+```
+
+### Socket options
+
+UDP sockets support setting various socket options:
+
+```ts
+const socket = await Bun.udpSocket({});
+
+// Enable broadcasting to send packets to a broadcast address
+socket.setBroadcast(true);
+
+// Set the IP TTL (time to live) for outgoing packets
+socket.setTTL(64);
+```
+
+### Multicast
+
+Bun supports multicast operations for UDP sockets. Use `addMembership` and `dropMembership` to join and leave multicast groups:
+
+```ts
+const socket = await Bun.udpSocket({});
+
+// Join a multicast group
+socket.addMembership("224.0.0.1");
+
+// Join with a specific interface
+socket.addMembership("224.0.0.1", "192.168.1.100");
+
+// Leave a multicast group
+socket.dropMembership("224.0.0.1");
+```
+
+Additional multicast options:
+
+```ts
+// Set TTL for multicast packets (number of network hops)
+socket.setMulticastTTL(2);
+
+// Control whether multicast packets loop back to the local socket
+socket.setMulticastLoopback(true);
+
+// Specify which interface to use for outgoing multicast packets
+socket.setMulticastInterface("192.168.1.100");
+```
+
+For source-specific multicast (SSM), use `addSourceSpecificMembership` and `dropSourceSpecificMembership`:
+
+```ts
+socket.addSourceSpecificMembership("10.0.0.1", "232.0.0.1");
+socket.dropSourceSpecificMembership("10.0.0.1", "232.0.0.1");
+```

package/docs/runtime/node-api.mdx

@@ -0,0 +1,19 @@
+---
+title: Node-API
+description: Use Bun's Node-API module to build native add-ons to Node.js
+---
+
+Node-API is an interface for building native add-ons to Node.js. Bun implements 95% of this interface from scratch, so most existing Node-API extensions will work with Bun out of the box. Track the completion status of it in [this issue](https://github.com/oven-sh/bun/issues/158).
+
+As in Node.js, `.node` files (Node-API modules) can be required directly in Bun.
+
+```js
+const napi = require("./my-node-module.node");
+```
+
+Alternatively, use `process.dlopen`:
+
+```js
+let mod = { exports: {} };
+process.dlopen(mod, "./my-node-module.node");
+```