@depup/bun-types 1.3.11-depup.0

package/docs/runtime/toml.mdx

@@ -0,0 +1,238 @@
+---
+title: TOML
+description: Use Bun's built-in support for TOML files through both runtime APIs and bundler integration
+---
+
+In Bun, TOML is a first-class citizen alongside JSON, JSON5, and YAML. You can:
+
+- Parse TOML strings with `Bun.TOML.parse`
+- `import` & `require` TOML files as modules at runtime (including hot reloading & watch mode support)
+- `import` & `require` TOML files in frontend apps via Bun's bundler
+
+---
+
+## Runtime API
+
+### `Bun.TOML.parse()`
+
+Parse a TOML string into a JavaScript object.
+
+```ts
+import { TOML } from "bun";
+const text = `
+name = "my-app"
+version = "1.0.0"
+debug = true
+
+[database]
+host = "localhost"
+port = 5432
+
+[features]
+tags = ["web", "api"]
+`;
+
+const data = TOML.parse(text);
+console.log(data);
+// {
+//   name: "my-app",
+//   version: "1.0.0",
+//   debug: true,
+//   database: { host: "localhost", port: 5432 },
+//   features: { tags: ["web", "api"] }
+// }
+```
+
+#### Supported TOML Features
+
+Bun's TOML parser supports the [TOML v1.0 specification](https://toml.io/en/v1.0.0), including:
+
+- **Strings**: basic (`"..."`) and literal (`'...'`), including multi-line
+- **Integers**: decimal, hex (`0x`), octal (`0o`), and binary (`0b`)
+- **Floats**: including `inf` and `nan`
+- **Booleans**: `true` and `false`
+- **Arrays**: including mixed types and nested arrays
+- **Tables**: standard (`[table]`) and inline (`{ key = "value" }`)
+- **Array of tables**: `[[array]]`
+- **Dotted keys**: `a.b.c = "value"`
+- **Comments**: using `#`
+
+```ts
+const data = Bun.TOML.parse(`
+# Application config
+title = "My App"
+
+[owner]
+name = "John Doe"
+
+[database]
+enabled = true
+ports = [8000, 8001, 8002]
+connection_max = 5000
+
+[servers.alpha]
+ip = "10.0.0.1"
+role = "frontend"
+
+[servers.beta]
+ip = "10.0.0.2"
+role = "backend"
+`);
+```
+
+#### Error Handling
+
+`Bun.TOML.parse()` throws if the TOML is invalid:
+
+```ts
+try {
+  Bun.TOML.parse("invalid = = =");
+} catch (error) {
+  console.error("Failed to parse TOML:", error.message);
+}
+```
+
+---
+
+## Module Import
+
+### ES Modules
+
+You can import TOML files directly as ES modules. The TOML content is parsed and made available as both default and named exports:
+
+```toml config.toml
+[database]
+host = "localhost"
+port = 5432
+name = "myapp"
+
+[redis]
+host = "localhost"
+port = 6379
+
+[features]
+auth = true
+rateLimit = true
+analytics = false
+```
+
+#### Default Import
+
+```ts app.ts icon="/icons/typescript.svg"
+import config from "./config.toml";
+
+console.log(config.database.host); // "localhost"
+console.log(config.redis.port); // 6379
+```
+
+#### Named Imports
+
+You can destructure top-level TOML tables as named imports:
+
+```ts app.ts icon="/icons/typescript.svg"
+import { database, redis, features } from "./config.toml";
+
+console.log(database.host); // "localhost"
+console.log(redis.port); // 6379
+console.log(features.auth); // true
+```
+
+Or combine both:
+
+```ts app.ts icon="/icons/typescript.svg"
+import config, { database, features } from "./config.toml";
+
+// Use the full config object
+console.log(config);
+
+// Or use specific parts
+if (features.rateLimit) {
+  setupRateLimiting(database);
+}
+```
+
+#### Import Attributes
+
+You can also use import attributes to load any file as TOML:
+
+```ts app.ts icon="/icons/typescript.svg"
+import myConfig from "./my.config" with { type: "toml" };
+```
+
+### CommonJS
+
+TOML files can also be required in CommonJS:
+
+```ts app.ts icon="/icons/typescript.svg"
+const config = require("./config.toml");
+console.log(config.database.name); // "myapp"
+
+// Destructuring also works
+const { database, redis } = require("./config.toml");
+console.log(database.port); // 5432
+```
+
+---
+
+## Hot Reloading with TOML
+
+When you run your application with `bun --hot`, changes to TOML files are automatically detected and reloaded without restarting:
+
+```toml config.toml
+[server]
+port = 3000
+host = "localhost"
+
+[features]
+debug = true
+verbose = false
+```
+
+```ts server.ts icon="/icons/typescript.svg"
+import { server, features } from "./config.toml";
+
+console.log(`Starting server on ${server.host}:${server.port}`);
+
+Bun.serve({
+  port: server.port,
+  hostname: server.host,
+  fetch(req) {
+    if (features.verbose) {
+      console.log(`${req.method} ${req.url}`);
+    }
+    return new Response("Hello World");
+  },
+});
+```
+
+Run with hot reloading:
+
+```bash terminal icon="terminal"
+bun --hot server.ts
+```
+
+Now when you modify `config.toml`, the changes are immediately reflected in your running application.
+
+---
+
+## Bundler Integration
+
+When you import TOML files and bundle with Bun, the TOML is parsed at build time and included as a JavaScript module:
+
+```bash terminal icon="terminal"
+bun build app.ts --outdir=dist
+```
+
+This means:
+
+- Zero runtime TOML parsing overhead in production
+- Smaller bundle sizes
+- Tree-shaking support for unused properties (named imports)
+
+### Dynamic Imports
+
+TOML files can be dynamically imported:
+
+```ts
+const config = await import("./config.toml");
+```

package/docs/runtime/transpiler.mdx

@@ -0,0 +1,288 @@
+---
+title: Transpiler
+description: Use Bun's transpiler to transpile JavaScript and TypeScript code
+---
+
+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.
+
+<CodeGroup>
+```ts transpile.ts icon="/icons/typescript.svg" 
+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);
+
+````
+
+```ts output
+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,
+);
+````
+
+</CodeGroup>
+
+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");
+```
+
+<Accordion title="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.
+
+</Accordion>
+
+---
+
+## `.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");
+```
+
+<Accordion title="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.
+
+</Accordion>
+
+## `.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.
+
+<CodeGroup>
+
+```ts example.ts icon="/icons/typescript.svg"
+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"
+    }
+  ]
+}
+```
+
+</CodeGroup>
+
+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')`
+
+---
+
+## `.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.
+
+<CodeGroup>
+
+```ts example.ts icon="/icons/typescript.svg"
+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 icon="file-json"
+[
+  {
+    "kind": "import-statement",
+    "path": "react"
+  },
+  {
+    "kind": "require-call",
+    "path": "./cjs.js"
+  },
+  {
+    "kind": "dynamic-import",
+    "path": "./loader"
+  }
+]
+```
+
+</CodeGroup>
+
+---
+
+## Reference
+
+```ts See Typescript Definitions expandable
+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/runtime/typescript.mdx

@@ -0,0 +1,58 @@
+---
+title: "TypeScript"
+description: "Using TypeScript with Bun, including type definitions and compiler options"
+---
+
+To install the TypeScript definitions for Bun's built-in APIs, install `@types/bun`.
+
+```sh
+bun add -d @types/bun # dev dependency
+```
+
+At this point, you should be able to reference the `Bun` global in your TypeScript files without seeing errors in your editor.
+
+```ts
+console.log(Bun.version);
+```
+
+## Suggested `compilerOptions`
+
+Bun supports things like top-level await, JSX, and extensioned `.ts` imports, which TypeScript doesn't allow by default. Below is a set of recommended `compilerOptions` for a Bun project, so you can use these features without seeing compiler warnings from TypeScript.
+
+```jsonc
+{
+  "compilerOptions": {
+    // Environment setup & latest features
+    "lib": ["ESNext"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "allowJs": true,
+
+    // Bundler mode
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+
+    // Best practices
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    // Some stricter flags (disabled by default)
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noPropertyAccessFromIndexSignature": false,
+  },
+}
+```
+
+If you run `bun init` in a new directory, this `tsconfig.json` will be generated for you. (The stricter flags are disabled by default.)
+
+```sh
+bun init
+```