@depup/bun-types 1.3.11-depup.0

package/docs/runtime/cron.mdx

@@ -0,0 +1,358 @@
+---
+title: Cron
+description: Schedule and parse cron jobs with Bun
+---
+
+Bun has built-in support for registering OS-level cron jobs and parsing cron expressions.
+
+## Quickstart
+
+**Parse a cron expression to find the next matching time:**
+
+```ts
+// Next weekday at 9:30 AM UTC
+const next = Bun.cron.parse("30 9 * * MON-FRI");
+console.log(next); // => 2025-01-20T09:30:00.000Z
+```
+
+**Register a cron job that runs a script on a schedule:**
+
+```ts
+await Bun.cron("./worker.ts", "30 2 * * MON", "weekly-report");
+```
+
+---
+
+## `Bun.cron.parse()`
+
+Parse a cron expression and return the next matching UTC `Date`.
+
+```ts
+const next = Bun.cron.parse("*/15 * * * *");
+console.log(next); // => next quarter-hour boundary
+```
+
+### Parameters
+
+| Parameter      | Type             | Description                                              |
+| -------------- | ---------------- | -------------------------------------------------------- |
+| `expression`   | `string`         | A 5-field cron expression or predefined nickname         |
+| `relativeDate` | `Date \| number` | Starting point for the search (defaults to `Date.now()`) |
+
+### Returns
+
+`Date | null` — the next matching UTC time, or `null` if no match exists within ~4 years (e.g. February 30th).
+
+### Chaining calls
+
+Call `parse()` repeatedly to get a sequence of upcoming times:
+
+```ts
+const from = Date.UTC(2025, 0, 15, 10, 0, 0);
+
+const first = Bun.cron.parse("0 * * * *", from);
+console.log(first); // => 2025-01-15T11:00:00.000Z
+
+const second = Bun.cron.parse("0 * * * *", first);
+console.log(second); // => 2025-01-15T12:00:00.000Z
+```
+
+---
+
+## Cron expression syntax
+
+Standard 5-field format: `minute hour day-of-month month day-of-week`
+
+| Field        | Values                  | Special characters |
+| ------------ | ----------------------- | ------------------ |
+| Minute       | `0`–`59`                | `*` `,` `-` `/`    |
+| Hour         | `0`–`23`                | `*` `,` `-` `/`    |
+| Day of month | `1`–`31`                | `*` `,` `-` `/`    |
+| Month        | `1`–`12` or `JAN`–`DEC` | `*` `,` `-` `/`    |
+| Day of week  | `0`–`7` or `SUN`–`SAT`  | `*` `,` `-` `/`    |
+
+### Special characters
+
+| Character | Description | Example                               |
+| --------- | ----------- | ------------------------------------- |
+| `*`       | All values  | `* * * * *` — every minute            |
+| `,`       | List        | `1,15 * * * *` — minute 1 and 15      |
+| `-`       | Range       | `9-17 * * * *` — minutes 9 through 17 |
+| `/`       | Step        | `*/15 * * * *` — every 15 minutes     |
+
+### Named values
+
+Month and weekday fields accept case-insensitive names:
+
+```ts
+// 3-letter abbreviations
+Bun.cron.parse("0 9 * * MON-FRI"); // weekdays
+Bun.cron.parse("0 0 1 JAN,JUN *"); // January and June
+
+// Full names
+Bun.cron.parse("0 9 * * Monday-Friday");
+Bun.cron.parse("0 0 1 January *");
+```
+
+Both `0` and `7` mean Sunday in the weekday field.
+
+### Predefined nicknames
+
+| Nickname                | Equivalent  | Description               |
+| ----------------------- | ----------- | ------------------------- |
+| `@yearly` / `@annually` | `0 0 1 1 *` | Once a year (January 1st) |
+| `@monthly`              | `0 0 1 * *` | Once a month (1st day)    |
+| `@weekly`               | `0 0 * * 0` | Once a week (Sunday)      |
+| `@daily` / `@midnight`  | `0 0 * * *` | Once a day (midnight)     |
+| `@hourly`               | `0 * * * *` | Once an hour              |
+
+```ts
+const next = Bun.cron.parse("@daily");
+console.log(next); // => next midnight UTC
+```
+
+### Day-of-month and day-of-week interaction
+
+When **both** day-of-month and day-of-week are specified (neither is `*`), the expression matches when **either** condition is true. This follows the [POSIX cron](https://pubs.opengroup.org/onlinepubs/9699919799/utilities/crontab.html) standard.
+
+```ts
+// Fires on the 15th of every month OR every Friday
+Bun.cron.parse("0 0 15 * FRI");
+```
+
+When only one is specified (the other is `*`), only that field is used for matching.
+
+---
+
+## `Bun.cron()`
+
+Register an OS-level cron job that runs a JavaScript/TypeScript module on a schedule.
+
+```ts
+await Bun.cron("./worker.ts", "30 2 * * MON", "weekly-report");
+```
+
+### Parameters
+
+| Parameter  | Type     | Description                                                |
+| ---------- | -------- | ---------------------------------------------------------- |
+| `path`     | `string` | Path to the script (resolved relative to caller)           |
+| `schedule` | `string` | Cron expression or nickname                                |
+| `title`    | `string` | Unique job identifier (alphanumeric, hyphens, underscores) |
+
+Re-registering with the same `title` overwrites the existing job in-place — the old schedule is replaced, not duplicated.
+
+```ts
+await Bun.cron("./worker.ts", "0 * * * *", "my-job"); // every hour
+await Bun.cron("./worker.ts", "*/15 * * * *", "my-job"); // replaces: every 15 min
+```
+
+### The `scheduled()` handler
+
+The registered script must export a default object with a `scheduled()` method, following the [Cloudflare Workers Cron Triggers API](https://developers.cloudflare.com/workers/runtime-apis/handlers/scheduled/):
+
+```ts worker.ts
+export default {
+  scheduled(controller: Bun.CronController) {
+    console.log(controller.cron); // "30 2 * * 1"
+    console.log(controller.type); // "scheduled"
+    console.log(controller.scheduledTime); // 1737340201847 (Date.now() at invocation)
+  },
+};
+```
+
+The handler can be `async`. Bun waits for the returned promise to settle before exiting.
+
+---
+
+## How it works per platform
+
+### Linux
+
+Bun uses [crontab](https://man7.org/linux/man-pages/man5/crontab.5.html) to register jobs. Each job is stored as a line in your user's crontab with a `# bun-cron: <title>` marker comment above it.
+
+The crontab entry looks like:
+
+```
+<schedule> '<bun-path>' run --cron-title=<title> --cron-period='<schedule>' '<script-path>'
+```
+
+When the cron daemon fires the job, Bun imports your module and calls the `scheduled()` handler.
+
+**Viewing registered jobs:**
+
+```sh
+crontab -l
+```
+
+**Logs:** On Linux, cron output goes to the system log. Check with:
+
+```sh
+# systemd-based (Ubuntu, Fedora, Arch, etc.)
+journalctl -u cron       # or crond on some distros
+journalctl -u cron --since "1 hour ago"
+
+# syslog-based (older systems)
+grep CRON /var/log/syslog
+```
+
+To capture stdout/stderr to a file, redirect output in the crontab entry directly, or add logging inside your `scheduled()` handler.
+
+**Manually uninstalling without code:**
+
+```sh
+# Edit your crontab and remove the "# bun-cron: <title>" comment
+# and the command line below it
+crontab -e
+
+# Or remove ALL bun cron jobs at once by filtering them out:
+crontab -l | grep -v "# bun-cron:" | grep -v "\-\-cron-title=" | crontab -
+```
+
+### macOS
+
+Bun uses [launchd](https://developer.apple.com/library/archive/documentation/MacOSX/Conceptual/BPSystemStartup/Chapters/CreatingLaunchdJobs.html) to register jobs. Each job is installed as a plist file at:
+
+```
+~/Library/LaunchAgents/bun.cron.<title>.plist
+```
+
+The plist uses `StartCalendarInterval` to define the schedule. Complex patterns with ranges, lists, or steps are supported — Bun expands them into multiple `StartCalendarInterval` dicts via Cartesian product.
+
+**Viewing registered jobs:**
+
+```sh
+launchctl list | grep bun.cron
+```
+
+**Logs:** stdout and stderr are written to:
+
+```
+/tmp/bun.cron.<title>.stdout.log
+/tmp/bun.cron.<title>.stderr.log
+```
+
+For example, a job titled `weekly-report`:
+
+```sh
+cat /tmp/bun.cron.weekly-report.stdout.log
+tail -f /tmp/bun.cron.weekly-report.stderr.log
+```
+
+**Manually uninstalling without code:**
+
+```sh
+# Unload the job from launchd
+launchctl bootout gui/$(id -u)/bun.cron.<title>
+
+# Delete the plist file
+rm ~/Library/LaunchAgents/bun.cron.<title>.plist
+
+# Example for a job titled "weekly-report":
+launchctl bootout gui/$(id -u)/bun.cron.weekly-report
+rm ~/Library/LaunchAgents/bun.cron.weekly-report.plist
+```
+
+### Windows
+
+Bun uses [Windows Task Scheduler](https://learn.microsoft.com/en-us/windows/win32/taskschd/task-scheduler-start-page) with XML-based task definitions. Each job is registered as a scheduled task named `bun-cron-<title>` using [`CalendarTrigger`](https://learn.microsoft.com/en-us/windows/win32/taskschd/taskschedulerschema-calendartrigger-triggergroup-element) elements and [`Repetition`](https://learn.microsoft.com/en-us/windows/win32/taskschd/taskschedulerschema-repetition-triggerbasetype-element) patterns.
+
+Most cron expressions are fully supported, including `@daily`, `@weekly`, `@monthly`, `@yearly`, ranges (`1-5`), lists (`1,15`), named days/months, and day-of-month patterns.
+
+#### User context
+
+Tasks are registered using [`S4U` (Service-for-User)](https://learn.microsoft.com/en-us/windows/win32/taskschd/taskschedulerschema-logontype-simpletype) logon type, which runs jobs as the registering user even when not logged in — matching Linux `crontab` behavior. No password is stored.
+
+TCP/IP networking (`fetch()`, HTTP, WebSocket, database connections) works normally. The only restriction is that S4U tasks cannot access [Windows-authenticated network resources](https://learn.microsoft.com/en-us/windows/win32/taskschd/security-contexts-for-running-tasks) (SMB file shares, mapped drives, Kerberos/NTLM services).
+
+On headless servers and CI environments where the current user's [Security Identifier (SID)](https://learn.microsoft.com/en-us/windows/security/identity-protection/access-control/security-identifiers) cannot be resolved — such as service accounts created by [NSSM](https://nssm.cc/) or similar tools — `Bun.cron()` will fail with an error explaining the issue. To work around this, either run Bun as a regular user account, or create the scheduled task manually with `schtasks /create /xml <file> /tn <name> /ru SYSTEM /f`.
+
+#### Trigger limit
+
+:::caution
+Windows Task Scheduler enforces a limit of [48 triggers per task](https://learn.microsoft.com/en-us/windows/win32/taskschd/taskschedulerschema-triggers-tasktype-element) (the `CalendarTrigger` element has [`maxOccurs="48"`](https://learn.microsoft.com/en-us/windows/win32/taskschd/taskschedulerschema-calendartrigger-triggergroup-element)). Some cron expressions that work on Linux and macOS exceed this limit on Windows.
+
+**Expressions that work on all platforms:**
+
+| Pattern                                    | Trigger strategy                                                                                                                                           | Count |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
+| `*/5 * * * *`                              | Single trigger with [`Repetition`](https://learn.microsoft.com/en-us/windows/win32/taskschd/taskschedulerschema-repetition-triggerbasetype-element) (PT5M) | 1     |
+| `*/15 * * * *`                             | Single trigger with Repetition (PT15M)                                                                                                                     | 1     |
+| `0 9 * * MON-FRI`                          | One `CalendarTrigger` per weekday                                                                                                                          | 5     |
+| `0,30 9-17 * * *`                          | 2 minutes × 9 hours                                                                                                                                        | 18    |
+| `@daily`, `@weekly`, `@monthly`, `@yearly` | Single trigger                                                                                                                                             | 1     |
+
+**Expressions that fail on Windows** (but work on Linux and macOS):
+
+| Pattern           | Why                                           | Trigger count |
+| ----------------- | --------------------------------------------- | ------------- |
+| `*/7 * * * *`     | 9 minute values × 24 hours                    | 216           |
+| `*/8 * * * *`     | 8 minute values × 24 hours                    | 192           |
+| `*/9 * * * *`     | 7 minute values × 24 hours                    | 168           |
+| `*/11 * * * *`    | 6 minute values × 24 hours                    | 144           |
+| `*/13 * * * *`    | 5 minute values × 24 hours                    | 120           |
+| `*/15 * * 6 *`    | Month restriction prevents Repetition: 4 × 24 | 96            |
+| `0,30 * 15 * FRI` | OR-split doubles triggers: 2 × 24 × 2         | 96            |
+
+The key factor is whether the expression can use a [`Repetition`](https://learn.microsoft.com/en-us/windows/win32/taskschd/taskschedulerschema-repetition-triggerbasetype-element) interval (single trigger) or must expand to individual `CalendarTrigger` elements. Minute steps that **evenly divide 60** (`*/1`, `*/2`, `*/3`, `*/4`, `*/5`, `*/6`, `*/10`, `*/12`, `*/15`, `*/20`, `*/30`) use Repetition and work regardless of other fields. Steps that don't divide 60 (`*/7`, `*/8`, `*/9`, `*/11`, `*/13`, etc.) must be expanded, and with 24 hours active, the count quickly exceeds 48.
+
+When a pattern exceeds the limit, `Bun.cron()` rejects it with an error message. To work around it, simplify the expression or restrict the hour range:
+
+```ts
+// ❌ Fails on Windows: */7 with all hours = 216 triggers
+await Bun.cron("./job.ts", "*/7 * * * *", "my-job");
+
+// ✅ Works: restrict to specific hours (9 values × 5 hours = 45 triggers)
+await Bun.cron("./job.ts", "*/7 9-13 * * *", "my-job");
+
+// ✅ Works: use a divisor of 60 instead (Repetition, 1 trigger)
+await Bun.cron("./job.ts", "*/5 * * * *", "my-job");
+```
+
+:::
+
+#### Windows containers
+
+:::caution
+`Bun.cron()` is not supported in Windows Docker containers. The Task Scheduler service is not running in `servercore` or `nanoserver` images. Use an in-process scheduler for containerized workloads.
+:::
+
+**Viewing registered jobs:**
+
+```powershell
+schtasks /query /tn "bun-cron-<title>"
+
+# List all bun cron tasks
+schtasks /query | findstr "bun-cron-"
+```
+
+**Manually uninstalling without code:**
+
+```powershell
+schtasks /delete /tn "bun-cron-<title>" /f
+
+# Example:
+schtasks /delete /tn "bun-cron-weekly-report" /f
+```
+
+Or open **Task Scheduler** (taskschd.msc), find the task named `bun-cron-<title>`, right-click, and delete it.
+
+---
+
+## `Bun.cron.remove()`
+
+Remove a previously registered cron job by its title. Works on all platforms.
+
+```ts
+await Bun.cron.remove("weekly-report");
+```
+
+This reverses what `Bun.cron()` did:
+
+| Platform | What `remove()` does                                     |
+| -------- | -------------------------------------------------------- |
+| Linux    | Edits crontab to remove the entry and its marker comment |
+| macOS    | Runs `launchctl bootout` and deletes the plist file      |
+| Windows  | Runs `schtasks /delete` to remove the scheduled task     |
+
+Removing a job that doesn't exist resolves without error.

package/docs/runtime/csrf.mdx

@@ -0,0 +1,171 @@
+---
+title: CSRF Protection
+description: Generate and verify CSRF tokens with Bun's built-in API
+---
+
+Bun provides a built-in API for generating and verifying [CSRF (Cross-Site Request Forgery)](https://owasp.org/www-community/attacks/csrf) tokens through `Bun.CSRF`. Tokens are signed with HMAC and include expiration timestamps to limit the token validity window.
+
+```ts title="csrf.ts" icon="/icons/typescript.svg"
+// Generate a token
+const token = Bun.CSRF.generate("my-secret");
+
+// Verify it
+const isValid = Bun.CSRF.verify(token, { secret: "my-secret" });
+console.log(isValid); // true
+```
+
+---
+
+## `Bun.CSRF.generate()`
+
+Generate a CSRF token. The token contains a cryptographic nonce, a timestamp, and an HMAC signature, encoded as a string.
+
+```ts title="generate.ts" icon="/icons/typescript.svg"
+const token = Bun.CSRF.generate("my-secret-key");
+```
+
+**Parameters:**
+
+- `secret` (string, optional) — The secret key used to sign the token. If not provided, Bun generates a random in-memory default secret (unique per thread).
+- `options` (object, optional):
+
+| Option      | Type     | Default       | Description                                                                                            |
+| ----------- | -------- | ------------- | ------------------------------------------------------------------------------------------------------ |
+| `expiresIn` | `number` | `86400000`    | Milliseconds until the token expires. Defaults to 24 hours.                                            |
+| `encoding`  | `string` | `"base64url"` | Token encoding format: `"base64"`, `"base64url"`, or `"hex"`.                                          |
+| `algorithm` | `string` | `"sha256"`    | HMAC algorithm: `"sha256"`, `"sha384"`, `"sha512"`, `"sha512-256"`, `"blake2b256"`, or `"blake2b512"`. |
+
+**Returns:** `string` — the encoded token.
+
+```ts title="generate-options.ts" icon="/icons/typescript.svg"
+// Token that expires in 1 hour, encoded as hex
+const token = Bun.CSRF.generate("my-secret", {
+  expiresIn: 60 * 60 * 1000,
+  encoding: "hex",
+});
+
+// Using a different algorithm
+const token2 = Bun.CSRF.generate("my-secret", {
+  algorithm: "sha512",
+});
+```
+
+---
+
+## `Bun.CSRF.verify()`
+
+Verify a CSRF token. Returns `true` if the token is valid and has not expired, `false` otherwise.
+
+```ts title="verify.ts" icon="/icons/typescript.svg"
+const isValid = Bun.CSRF.verify(token, { secret: "my-secret-key" });
+```
+
+**Parameters:**
+
+- `token` (string, required) — The token to verify.
+- `options` (object, optional):
+
+| Option      | Type     | Default       | Description                                                                                          |
+| ----------- | -------- | ------------- | ---------------------------------------------------------------------------------------------------- |
+| `secret`    | `string` | (auto)        | The secret used to sign the token. If not provided, uses the same in-memory default as `generate()`. |
+| `maxAge`    | `number` | `86400000`    | Maximum token age in milliseconds, independent of the token's own `expiresIn`.                       |
+| `encoding`  | `string` | `"base64url"` | Must match the encoding used during `generate()`.                                                    |
+| `algorithm` | `string` | `"sha256"`    | Must match the algorithm used during `generate()`.                                                   |
+
+**Returns:** `boolean`
+
+```ts title="verify-options.ts" icon="/icons/typescript.svg"
+// Verify a hex-encoded token
+const isValid = Bun.CSRF.verify(hexToken, {
+  secret: "my-secret",
+  encoding: "hex",
+});
+
+// Enforce a shorter max age than what the token was generated with
+const isValid2 = Bun.CSRF.verify(token, {
+  secret: "my-secret",
+  maxAge: 60 * 1000, // reject tokens older than 1 minute
+});
+```
+
+---
+
+## Using with `Bun.serve()`
+
+A typical pattern is to generate a token when rendering a form, embed it in a hidden field, and verify it when the form is submitted.
+
+```ts title="server.ts" icon="/icons/typescript.svg"
+const SECRET = process.env.CSRF_SECRET || "my-secret";
+
+const server = Bun.serve({
+  routes: {
+    "/form": () => {
+      const token = Bun.CSRF.generate(SECRET);
+
+      return new Response(
+        `<form method="POST" action="/submit">
+          <input type="hidden" name="_csrf" value="${token}" />
+          <input type="text" name="message" />
+          <button type="submit">Send</button>
+        </form>`,
+        { headers: { "Content-Type": "text/html" } },
+      );
+    },
+
+    "/submit": {
+      POST: async req => {
+        const formData = await req.formData();
+        const csrfToken = formData.get("_csrf");
+
+        if (typeof csrfToken !== "string" || !Bun.CSRF.verify(csrfToken, { secret: SECRET })) {
+          return new Response("Invalid CSRF token", { status: 403 });
+        }
+
+        return new Response("OK");
+      },
+    },
+  },
+});
+
+console.log(`Listening on ${server.url}`);
+```
+
+---
+
+## Default secret
+
+If you omit the `secret` parameter in both `generate()` and `verify()`, Bun uses a random secret generated once per thread. This is convenient for single-thread applications but won't work across multiple servers, workers, or after a restart.
+
+```ts title="default-secret.ts" icon="/icons/typescript.svg"
+// Both calls use the same per-thread default secret within this runtime context.
+const token = Bun.CSRF.generate();
+const isValid = Bun.CSRF.verify(token); // true
+```
+
+For production use, always provide an explicit secret shared across your infrastructure.
+
+---
+
+## TypeScript
+
+```ts title="types.ts" icon="/icons/typescript.svg"
+type CSRFAlgorithm = "blake2b256" | "blake2b512" | "sha256" | "sha384" | "sha512" | "sha512-256";
+
+interface CSRFGenerateOptions {
+  expiresIn?: number;
+  encoding?: "base64" | "base64url" | "hex";
+  algorithm?: CSRFAlgorithm;
+}
+
+interface CSRFVerifyOptions {
+  secret?: string;
+  encoding?: "base64" | "base64url" | "hex";
+  algorithm?: CSRFAlgorithm;
+  maxAge?: number;
+}
+
+namespace Bun.CSRF {
+  function generate(secret?: string, options?: CSRFGenerateOptions): string;
+  function verify(token: string, options?: CSRFVerifyOptions): boolean;
+}
+```