bun-types 1.3.2-canary.20251104T140728 → 1.3.2-canary.20251106T140813

package/docs/api/transpiler.md

@@ -1,276 +0,0 @@
-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-build`: `import {foo} from 'bun:entry'`
-- `entry-point-run`: `bun ./mymodule` -->
-
-## `.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-build"
-  | "entry-point-run"
-}
-
-const transpiler = new Bun.Transpiler({ loader: "jsx" });
-```

package/docs/api/udp.md

@@ -1,123 +0,0 @@
-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,
-});
-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
-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
-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
-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
-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
-    },
-  },
-});
-```