---
url: /plugins/reference/sdks/backend.md
---
# @caido/sdk-backend

This is the reference for the backend SDK used by backend plugins.
[SDK](#events) is the main interface that provides access to various services and functionalities.

## SDK

### SDK

The SDK object available to all scripts.

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `API` | `object` |
| `Events` | `object` |

#### Properties

##### api

> **api**: [`APISDK`](api.md#apisdk)<`API`, `Events`>

The SDK for the API RPC service.

##### console

> **console**: [`Console`](other.md#console)

The console.

This is currently the same as the global `console`.

##### env

> **env**: [`EnvironmentSDK`](environment.md#environmentsdk)

The SDK for the Environment service.

##### events

> **events**: [`EventsSDK`](events.md#eventssdk)<`API`, `Events`>

The SDK for the Events service.

##### findings

> **findings**: [`FindingsSDK`](findings.md#findingssdk)

The SDK for the Findings service.

##### graphql

> **graphql**: [`GraphQLSDK`](graphql.md#graphqlsdk)

The SDK for the GraphQL service.

##### hostedFile

> **hostedFile**: [`HostedFileSDK`](hostedfile.md#hostedfilesdk)

The SDK for the HostedFile service.

##### meta

> **meta**: [`MetaSDK`](meta.md#metasdk)

The SDK for metadata information about the plugin.

##### net

> **net**: [`NetSDK`](net.md#netsdk)

The SDK for the Net service.

##### projects

> **projects**: [`ProjectsSDK`](projects.md#projectssdk)

The SDK for the Projects service.

##### replay

> **replay**: [`ReplaySDK`](replay.md#replaysdk)

The SDK for the Replay service.

##### requests

> **requests**: [`RequestsSDK`](requests.md#requestssdk)

The SDK for the Requests service.

##### runtime

> **runtime**: [`RuntimeSDK`](runtime.md#runtimesdk)

The SDK for the runtime information.

##### scope

> **scope**: [`ScopeSDK`](scope.md#scopesdk)

The SDK for the Scope service.

## API Reference

* [Meta](meta.md)
* [API](api.md)
* [Events](events.md)
* [Requests](requests.md)
* [Findings](findings.md)
* [Replay](replay.md)
* [Projects](projects.md)
* [Shared](shared.md)
* [Environment](environment.md)
* [GraphQL](graphql.md)
* [HostedFile](hostedfile.md)
* [Net](net.md)
* [Other](other.md)
* [Runtime](runtime.md)
* [Scope](scope.md)

---

---
url: /plugins/reference/sdks/frontend.md
---
# @caido/sdk-frontend

This is the reference for the frontend SDK used by frontend plugins.
[Caido](#caido-t-e) is the main interface that provides access to various services and functionalities.

## SDK

### Caido

> **Caido**<`T`, `E`> = `object`

Utilities for frontend plugins.

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `T` *extends* [`BackendEndpoints`](backend.md#backendendpoints) | `Record`<`string`, `never`> |
| `E` *extends* [`BackendEvents`](backend.md#backendevents) | `Record`<`string`, `never`> |

#### Properties

##### ai

> **ai**: [`AiSDK`](ai.md#aisdk)

Utilities to interact with AI.

##### assets

> **assets**: [`AssetsSDK`](files.md#assetssdk)

Utilities to interact with the plugin's static assets.

##### automate

> **automate**: [`AutomateSDK`](automate.md#automatesdk)

Utilities to interact with the Automate page.

##### backend

> **backend**: [`BackendSDK`](backend.md#backendsdk)<`T`, `E`>

Utilities to interact with the backend plugin.

##### commandPalette

> **commandPalette**: [`CommandPaletteSDK`](command-palette.md#commandpalettesdk)

Utilities to interact with the command palette.

##### commands

> **commands**: [`CommandsSDK`](commands.md#commandssdk)

Utilities to interact with commands

##### env

> **env**: [`EnvironmentSDK`](environment.md#environmentsdk)

Utilities to interact with the environment.

##### files

> **files**: [`FilesSDK`](files.md#filessdk)

Utilities to interact with the Files page.

##### filters

> **filters**: [`FiltersSDK`](filters.md#filterssdk)

Utilities to interact with Filters page.

##### findings

> **findings**: [`FindingsSDK`](findings.md#findingssdk)

Utilities to interact with findings

##### footer

> **footer**: [`FooterSDK`](footer.md#footersdk)

Utilities to interact with the footer.

##### graphql

> **graphql**: `GraphqlSDK`

Utilities to interact with the GraphQL API.

##### httpHistory

> **httpHistory**: [`HTTPHistorySDK`](http-history.md#httphistorysdk)

Utilities to interact with the HTTP History page.

##### intercept

> **intercept**: [`InterceptSDK`](intercept.md#interceptsdk)

Utilities to interact with the Intercept page.

##### log

> **log**: [`LogSDK`](log.md#logsdk)

Utilities for logging messages to the console.

##### matchReplace

> **matchReplace**: [`MatchReplaceSDK`](match-and-replace.md#matchreplacesdk)

Utilities to interact with Match and Replace page.

##### menu

> **menu**: [`MenuSDK`](menu.md#menusdk)

Utilities to insert menu items and context-menus throughout the UI.

##### navigation

> **navigation**: [`NavigationSDK`](navigation.md#navigationsdk)

Utilities to interact with navigation.

##### projects

> **projects**: [`ProjectsSDK`](projects.md#projectssdk)

Utilities to interact with projects.

##### replay

> **replay**: [`ReplaySDK`](replay.md#replaysdk)

Utilities to interact with the Replay page.

##### runtime

> **runtime**: [`RuntimeSDK`](runtime.md#runtimesdk)

Utilities to interact with the runtime.

##### scopes

> **scopes**: [`ScopesSDK`](scopes.md#scopessdk)

Utilities to interact with scopes

##### search

> **search**: [`SearchSDK`](search.md#searchsdk)

Utilities to interact with the Search page.

##### settings

> **settings**: [`SettingsSDK`](settings.md#settingssdk)

Utilities to interact with the settings page.

##### shortcuts

> **shortcuts**: [`ShortcutsSDK`](shortcuts.md#shortcutssdk)

Utilities to interact with shortcuts.

##### sidebar

> **sidebar**: [`SidebarSDK`](sidebar.md#sidebarsdk)

Utilities to interact with the sidebar.

##### sitemap

> **sitemap**: [`SitemapSDK`](sitemap.md#sitemapsdk)

Utilities to interact with the Sitemap page.

##### storage

> **storage**: [`StorageSDK`](storage.md#storagesdk)

Utilities to interact with frontend-plugin storage.

##### ui

> **ui**: [`UISDK`](ui.md#uisdk)

Utilities to create UI components.

##### window

> **window**: [`WindowSDK`](window.md#windowsdk)

Utilities to interact with the active page.

##### workflows

> **workflows**: [`WorkflowSDK`](workflows.md#workflowsdk)

Utilities to interact with workflows.

## API Reference

* [Backend](backend.md)
* [UI](ui.md)
* [Scopes](scopes.md)
* [Findings](findings.md)
* [Commands](commands.md)
* [Menu](menu.md)
* [Navigation](navigation.md)
* [Window](window.md)
* [Storage](storage.md)
* [Shortcuts](shortcuts.md)
* [Command Palette](command-palette.md)
* [Sidebar](sidebar.md)
* [Replay](replay.md)
* [HTTP History](http-history.md)
* [Search](search.md)
* [Files](files.md)
* [AI](ai.md)
* [Assistant](assistant.md)
* [Automate](automate.md)
* [Backups](backups.md)
* [Certificate](certificate.md)
* [Editor](editor.md)
* [Environment](environment.md)
* [Exports](exports.md)
* [Filter](filter.md)
* [Filters](filters.md)
* [Footer](footer.md)
* [Intercept](intercept.md)
* [JSON](json.md)
* [Log](log.md)
* [Match and Replace](match-and-replace.md)
* [Other](other.md)
* [Projects](projects.md)
* [Request](request.md)
* [Response](response.md)
* [Runtime](runtime.md)
* [Settings](settings.md)
* [Sitemap](sitemap.md)
* [Slots](slots.md)
* [Utils](utils.md)
* [Websockets](websockets.md)
* [Workflows](workflows.md)

---

---
url: /plugins/reference/sdks/workflow.md
---
# @caido/sdk-workflow

This is the reference for the workflow SDK used by JS Nodes.
[SDK](#sdk) is the main interface that provides access to various services and functionalities.

## SDK

### SDK

> **SDK** = `object`

The SDK object available to all scripts.

#### Properties

##### console

> **console**: [`Console`](other.md#console)

The console for logging.

This is currently the same as the global `console`.

##### env

> **env**: [`EnvironmentSDK`](environment.md#environmentsdk)

The SDK for the Environment service.

##### findings

> **findings**: [`FindingsSDK`](findings.md#findingssdk)

The SDK for the Findings service.

##### graphql

> **graphql**: [`GraphQLSDK`](graphql.md#graphqlsdk)

The SDK for the GraphQL service.

##### hostedFile

> **hostedFile**: [`HostedFileSDK`](hostedfile.md#hostedfilesdk)

The SDK for the HostedFile service.

##### net

> **net**: [`NetSDK`](net.md#netsdk)

The SDK for the Net service.

##### projects

> **projects**: [`ProjectsSDK`](projects.md#projectssdk)

The SDK for the Projects service.

##### replay

> **replay**: [`ReplaySDK`](replay.md#replaysdk)

The SDK for the Replay service.

##### requests

> **requests**: [`RequestsSDK`](requests.md#requestssdk)

The SDK for the Requests service.

##### runtime

> **runtime**: [`RuntimeSDK`](runtime.md#runtimesdk)

The SDK for the runtime information.

##### scope

> **scope**: [`ScopeSDK`](scope.md#scopesdk)

The SDK for the Scope service.

#### Methods

##### asString()

> **asString**(`array`: [`Bytes`](shared.md#bytes)): `string`

Converts bytes to a string.

Unprintable characters will be replaced with `�`.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `array` | [`Bytes`](shared.md#bytes) |

###### Returns

`string`

###### Example

```js
export function run(input, sdk) {
  let parsed = sdk.asString(input);
  sdk.console.log(parsed);
  return parsed;
}
```

## API Reference

* [Data](data.md)
* [Requests](requests.md)
* [Findings](findings.md)
* [Replay](replay.md)
* [Projects](projects.md)
* [Shared](shared.md)
* [Environment](environment.md)
* [GraphQL](graphql.md)
* [HostedFile](hostedfile.md)
* [Net](net.md)
* [Other](other.md)
* [Runtime](runtime.md)
* [Scope](scope.md)

---

---
url: /plugins/guides/assets.md
---
# Access Static Assets

Static assets are files bundled with your plugin that can be accessed at runtime. You can load configuration files, images, templates, data files, and other resources from the assets folder.

## Getting an Asset

To get a file from the assets folder:

```ts
const asset = await sdk.assets.get("path/to/file.txt");
```

The path is relative to your plugin's assets directory.

## Converting Assets to Different Formats

Once you have an asset, you can convert it to different formats:

### Converting to String

```ts
const content = await asset.asString();
```

### Converting to JSON

```ts
const data = await asset.asJson<MyType>();
```

### Converting to ArrayBuffer

```ts
const buffer = await asset.asArrayBuffer();
```

### Converting to ReadableStream

```ts
const stream = asset.asReadableStream();
```

::: tip
Use `asReadableStream()` for large files to process them in chunks and avoid loading the entire file into memory.
:::

## Asset Path Configuration

Assets are configured in your `caido.config.ts`:

```ts
export default defineConfig({
  frontend: {
    assets: ["./assets/**/*"],
  },
});
```

::: warning
Assets are bundled with your plugin, so large files will increase the plugin size. Consider loading external resources at runtime for very large files.
:::

## Examples

### Loading Configuration

This example loads a JSON configuration file from assets and parses it into a typed TypeScript object. It demonstrates error handling and logging for configuration loading operations.

```ts
import type { Caido } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

interface PluginConfig {
  apiKey: string;
  endpoint: string;
  timeout: number;
}

const loadConfig = async (sdk: CaidoSDK): Promise<PluginConfig> => {
  const asset = await sdk.assets.get("config.json");
  const config = await asset.asJson<PluginConfig>();
  return config;
};

export const init = async (sdk: CaidoSDK) => {
  try {
    const config = await loadConfig(sdk);
    sdk.log.info("Loaded config:", config);
    // Use configuration
  } catch (error) {
    sdk.log.error("Failed to load config:", error);
  }
};
```

### Loading Multiple Assets

This example demonstrates loading multiple assets in parallel using Promise.all. It loads a JSON config file, a text template, and a data JSON file simultaneously, converting each to its appropriate format.

```ts
import type { Caido } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

const loadAssets = async (sdk: CaidoSDK) => {
  const [config, template, data] = await Promise.all([
    sdk.assets.get("config.json").then((a) => a.asJson()),
    sdk.assets.get("template.txt").then((a) => a.asString()),
    sdk.assets.get("data.json").then((a) => a.asJson()),
  ]);

  return { config, template, data };
};

export const init = async (sdk: CaidoSDK) => {
  try {
    const assets = await loadAssets(sdk);
    sdk.log.info("Loaded all assets:", assets);
  } catch (error) {
    sdk.log.error("Failed to load assets:", error);
  }
};
```

---

---
url: /plugins/guides/files.md
---
# Add Files

To include additional files in your Caido plugins, you can add the `assets` property key to either the frontend or backend component objects in the `caido.config.ts` file. The key value is an array that stores the locations of any files accessible to the plugin.

In this guide we'll cover how to add a file to a plugin named `myfile.txt`.

## Shared Steps

In the root directory of your plugin package, create a new directory named `assets`. Within this directory, create the `myfile.txt` file, write content to it, and save it. The file can now be referenced with:

```ts
assets : ["./assets/myfile.txt"]
```

::: tip TIPS

Glob syntax (`*`) is supported to reference multiple files:

* `/path/*.txt`: Will include all `.txt` files in the path directory.
* `/**/file.txt`: Will include any `file.txt` within any directory.

Files and directories are included differently:

* For a file, it will copy it at the root of the output assets directory.
* For a directory, it will copy it recursively in the output assets directory.
  :::

::: info
The `assets` key can also be added to a plugin's `manifest.json` file. However, multiple locations can not be defined with this method.
:::

## Adding Files to the Frontend Component

Open the `caido.config.ts` file and add the property to the `frontend` component object:

### /packages/frontend/src/index.ts

To read the file, the `sdk.assets.get()` method can be called.

```ts
const file = await sdk.assets.get("myfile.txt");
```

::: tip
To view the entire frontend script, expand the following:

```ts
import "./styles/index.css";

import type { FrontendSDK } from "./types";

// Note that the init function is async to account for fetching the files.
export const init = async (sdk: FrontendSDK) => {

  const root = document.createElement("div");
  Object.assign(root.style, {
    height: "100%",
    width: "100%",
  });

  root.id = `plugin--frontend-vanilla`;

  const parent = document.createElement("div");
  parent.classList.add("h-full", "flex", "justify-center", "items-center");

  const container = document.createElement("div");
  container.classList.add("flex", "flex-col", "gap-1", "p-4");

  const file = await sdk.assets.get("myfile.txt");
  // For large files or to process in chunks, use file.asReadableStream() instead.
  const content = await file.asString();
  container.textContent = content;

  parent.appendChild(container);

  root.appendChild(parent);

  sdk.navigation.addPage("/view-file-plugin", {
    body: root,
  });

  sdk.sidebar.registerItem("View File Plugin", "/view-file-plugin");
};
```

## Adding Files to the Backend Component

Open the `caido.config.ts` file and add the property to the `backend` component object:

### /packages/backend/src/index.ts

By [creating a custom backend function](./rpc.md) to read the file, we can later call it from the frontend:

```ts
import type { DefineAPI, SDK } from "caido:plugin";
import { readFile } from 'fs/promises';
import path from "path";

const readMyFile = async (sdk: SDK) => {
  try {
    const filePath = path.join(sdk.meta.assetsPath(), "myfile.txt");
    const contents = await readFile(filePath, { encoding: 'utf8' });
    sdk.console.log(contents);
    return contents;
  } catch (err: any) {
    sdk.console.error(err.message);
    throw err;
  }
};

export type API = DefineAPI<{
  readMyFile: typeof readMyFile;
}>;

export function init(sdk: SDK<API>) {
  sdk.api.register("readMyFile", readMyFile);
}
```

::: tip
To view the entire frontend script, expand the following:

```ts
import "./styles/index.css";

import type { FrontendSDK } from "./types";

export const init = async (sdk: FrontendSDK) => {
  const root = document.createElement("div");
  Object.assign(root.style, {
    height: "100%",
    width: "100%",
  });

  root.id = `plugin--frontend-vanilla`;

  const parent = document.createElement("div");
  parent.classList.add("h-full", "flex", "justify-center", "items-center");

  const container = document.createElement("div");
  container.classList.add("flex", "flex-col", "gap-1", "p-4");

  try {
    // Call the backend readMyFile() function to read myfile.txt.
    const content = await sdk.backend.readMyFile();
    container.textContent = content;
  } catch (error: any) {
    container.textContent = `Error reading file: ${error.message}`;
  }

  parent.appendChild(container);

  root.appendChild(parent);

  sdk.navigation.addPage("/view-file-plugin", {
    body: root,
  });

  sdk.sidebar.registerItem("View File Plugin", "/view-file-plugin");
};
```

## The Result

## Listening to File Events

You can listen for events when hosted files are uploaded, updated, or deleted:

### Listening for File Uploads

```ts
const handle = sdk.files.onUploadedHostedFile((file) => {
  sdk.log.info(`File uploaded: ${file.name} (${file.size} bytes)`);
  sdk.window.showToast(`File "${file.name}" uploaded`, { variant: "success" });
});

// Later, stop listening
handle.stop();
```

### Listening for File Updates

```ts
const handle = sdk.files.onUpdatedHostedFile((file) => {
  sdk.log.info(`File updated: ${file.name}`);
  sdk.window.showToast(`File "${file.name}" updated`, { variant: "info" });
});

// Later, stop listening
handle.stop();
```

### Listening for File Deletions

```ts
const handle = sdk.files.onDeletedHostedFile((fileId) => {
  sdk.log.info(`File deleted: ${fileId}`);
  sdk.window.showToast("File deleted", { variant: "info" });
});

// Later, stop listening
handle.stop();
```

## Example: File Monitor Plugin

This example creates a plugin that monitors all file operations and logs them:

```ts
import type { Caido } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  // Monitor file uploads
  sdk.files.onUploadedHostedFile((file) => {
    sdk.log.info(`[File Monitor] Uploaded: ${file.name} (${file.path})`);
  });

  // Monitor file updates
  sdk.files.onUpdatedHostedFile((file) => {
    sdk.log.info(`[File Monitor] Updated: ${file.name} (${file.path})`);
  });

  // Monitor file deletions
  sdk.files.onDeletedHostedFile((fileId) => {
    sdk.log.info(`[File Monitor] Deleted: ${fileId}`);
  });

  sdk.log.info("File monitor plugin initialized");
};
```

---

---
url: /plugins/guides/slots.md
---
# Add to UI Slots

UI slots allow you to extend Caido's interface by adding custom components to specific locations, such as toolbars and footers. You can add buttons, commands, or custom components to these slots.

## Finding Available Slots

### Footer Slots

Footer slots are available via `sdk.footer.addToSlot()`:

* `FooterSlot.FooterSlotPrimary` - Primary footer slot
* `FooterSlot.FooterSlotSecondary` - Secondary footer slot

### Replay Slots

Replay slots are available via `sdk.replay.addToSlot()`:

* `ReplaySlot.SessionToolbarPrimary` - Left side of the session toolbar
* `ReplaySlot.SessionToolbarSecondary` - Right side of the session toolbar
* `ReplaySlot.Topbar` - Topbar area

## Adding Different Types of Content to Slots

You can add three types of content to slots:

### Button

A button with a label, icon, and click handler:

```ts
sdk.footer.addToSlot(FooterSlot.FooterSlotPrimary, {
  kind: "Button",
  label: "My Button",
  icon: "fas fa-rocket",
  onClick: () => {
    console.log("Button clicked");
  },
});
```

### Command

A button that triggers a registered command:

```ts
// First register the command
sdk.commands.register("my-command", {
  name: "My Command",
  run: () => {
    sdk.window.showToast("Command executed", { variant: "info" });
  },
});

// Then add to slot
sdk.footer.addToSlot(FooterSlot.FooterSlotPrimary, {
  kind: "Command",
  commandId: "my-command",
  icon: "fas fa-star",
});
```

### Custom Component

A custom Vue component from a `.vue` file:

```vue
<!-- CustomStatus.vue -->
<script setup lang="ts">
// Component logic here
</script>

<template>
  <div class="p-2">
    Custom content
  </div>
</template>
```

```ts
import CustomStatus from "./CustomStatus.vue";

sdk.footer.addToSlot(FooterSlot.FooterSlotSecondary, {
  kind: "Custom",
  component: {
    component: CustomStatus,
  },
});
```

## Component Props

Custom slot components automatically receive the SDK as an implicit prop. You don't need to pass it explicitly when registering the component.

If your Vue component defines an `sdk` prop, it will automatically receive the SDK instance:

```vue
<script setup lang="ts">
import type { Caido } from "@caido/sdk-frontend";

const props = defineProps<{
  sdk: Caido;
}>();
</script>
```

## Importing Slot Constants

You need to import the slot constants:

```ts
import { FooterSlot } from "@caido/sdk-frontend";
import { ReplaySlot } from "@caido/sdk-frontend";
```

## Best Practices

* Use buttons for simple actions that don't need command registration
* Use commands when you want the action to be available in multiple places (command palette, menus, etc.)
* Use custom components for complex UI or dynamic content
* Keep slot content concise to maintain a clean interface
* Consider the visual hierarchy when adding multiple items to the same slot

::: warning
Be mindful of slot space limitations. Too many items in a slot can clutter the interface. Consider grouping related actions or using custom components to organize multiple controls.
:::

::: tip
Slots are a powerful way to extend Caido's UI without creating custom pages. Use them to add plugin-specific functionality that integrates seamlessly with the existing interface.
:::

::: info
Slot content is rendered when the relevant page is active. For footer slots, content is always visible. For Replay slots, content is only visible on the Replay page.
:::

## Examples

### Footer Actions

This example demonstrates adding multiple types of content to footer slots: a button with a click handler, a command button, and a custom status indicator component.

First, create the status indicator component:

```vue
<!-- StatusIndicator.vue -->
<script setup lang="ts">
// Component logic here
</script>

<template>
  <span class="px-2 py-1 bg-green-500 text-white rounded">
    Plugin Active
  </span>
</template>
```

Then, register all slot content types:

```ts
import type { Caido } from "@caido/sdk-frontend";
import { FooterSlot } from "@caido/sdk-frontend";
import StatusIndicator from "./StatusIndicator.vue";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  // Register a command
  sdk.commands.register("quick-action", {
    name: "Quick Action",
    run: () => {
      sdk.window.showToast("Quick action executed", { variant: "success" });
    },
  });

  // Add button to primary footer slot
  sdk.footer.addToSlot(FooterSlot.FooterSlotPrimary, {
    kind: "Button",
    label: "Custom Action",
    icon: "fas fa-bolt",
    onClick: () => {
      sdk.log.info("Custom action triggered");
    },
  });

  // Add command to primary footer slot
  sdk.footer.addToSlot(FooterSlot.FooterSlotPrimary, {
    kind: "Command",
    commandId: "quick-action",
    icon: "fas fa-star",
  });

  // Add custom component to secondary footer slot
  sdk.footer.addToSlot(FooterSlot.FooterSlotSecondary, {
    kind: "Custom",
    component: {
      component: StatusIndicator,
    },
  });
};
```

### Dynamic Slot Content

This example creates a custom component that tracks and displays a click counter. The button updates its label each time it's clicked and shows a toast notification.

First, create a Vue component with reactive state. The SDK is automatically passed as a prop, so you only need to define it in the component:

```vue
<!-- ClickCounter.vue -->
<script setup lang="ts">
import { ref } from "vue";
import type { Caido } from "@caido/sdk-frontend";

const props = defineProps<{
  sdk: Caido;
}>();

const count = ref(0);

const handleClick = () => {
  count.value++;
  props.sdk.window.showToast(`Clicked ${count.value} times`, { variant: "info" });
};
</script>

<template>
  <button
    @click="handleClick"
    class="px-4 py-2"
  >
    Clicks: {{ count }}
  </button>
</template>
```

Then, register the component in a slot. You don't need to pass the SDK prop explicitly:

```ts
import type { Caido } from "@caido/sdk-frontend";
import { FooterSlot } from "@caido/sdk-frontend";
import ClickCounter from "./ClickCounter.vue";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  sdk.footer.addToSlot(FooterSlot.FooterSlotPrimary, {
    kind: "Custom",
    component: {
      component: ClickCounter,
    },
  });
};
```

---

---
url: /plugins/guides/view_modes.md
---
# Add View Modes

Add custom view modes to display requests in alternative formats, such as custom parsers, formatted views, or visual editors. Custom view modes appear alongside the default view options in the request viewer.

::: tip
Custom view modes are great for domain-specific request formats or when you need specialized visualization of request data.
:::

## Registering a View Mode

### Request View Modes

Call `addRequestViewMode()` on the appropriate SDK method for the page where you want the view mode to appear:

* HTTP History: `sdk.httpHistory.addRequestViewMode()`
* Replay: `sdk.replay.addRequestViewMode()`
* Search: `sdk.search.addRequestViewMode()`
* Sitemap: `sdk.sitemap.addRequestViewMode()`
* Automate: `sdk.automate.addRequestViewMode()`
* Intercept: `sdk.intercept.addRequestViewMode()`
* Findings: `sdk.findings.addRequestViewMode()`

### Response View Modes

Response view modes are also available on pages that display responses. Call `addResponseViewMode()` on the appropriate SDK method:

* HTTP History: `sdk.httpHistory.addResponseViewMode()`
* Replay: `sdk.replay.addResponseViewMode()`
* Search: `sdk.search.addResponseViewMode()`
* Sitemap: `sdk.sitemap.addResponseViewMode()`
* Automate: `sdk.automate.addResponseViewMode()`
* Intercept: `sdk.intercept.addResponseViewMode()`
* Findings: `sdk.findings.addResponseViewMode()`

::: info
View modes are available on all pages that display requests and responses. Consider adding your view mode to multiple pages if it's useful across different contexts.
:::

```ts
sdk.httpHistory.addRequestViewMode({
  label: "My Custom View",
  view: {
    component: MyComponent,
  },
});
```

The `label` is the display name shown in the view mode selector. The `view.component` is your Vue component that renders the custom view.

## Using Component Props

### Request View Mode Props

Request view mode components automatically receive these props—you don't need to pass them when registering:

* `sdk` - The Caido SDK instance
* `request` - The request object of type `RequestFull`
* `requestDraft` - A writable request object of type `RequestDraft` (only in Intercept and Replay contexts)

::: warning
The request object structure may vary between pages. Test your view mode on the pages where you add it to ensure compatibility.
:::

For read-only contexts (HTTP History, Search, etc.):

```vue
<script setup lang="ts">
import type { Caido, RequestFull } from "@caido/sdk-frontend";

defineProps<{
  sdk: Caido;
  request: RequestFull;
}>();
</script>
```

For writable contexts (Intercept, Replay):

```vue
<script setup lang="ts">
import type { Caido, RequestFull, RequestDraft } from "@caido/sdk-frontend";

defineProps<{
  sdk: Caido;
  request: RequestFull;
  requestDraft: RequestDraft;
}>();
</script>
```

### Response View Mode Props

Response view mode components automatically receive these props:

* `sdk` - The Caido SDK instance
* `response` - The response object of type `ResponseFull`
* `request` - The associated request object of type `RequestMeta` or `RequestFull`

```vue
<script setup lang="ts">
import type { Caido, ResponseFull, RequestFull } from "@caido/sdk-frontend";

defineProps<{
  sdk: Caido;
  response: ResponseFull;
  request: RequestFull;
}>();
</script>
```

## Examples

### JSON Formatter View

A view mode that formats request bodies as pretty-printed JSON, displaying an error message if the body isn't valid JSON.

```vue
<script setup lang="ts">
import { computed } from "vue";
import type { Caido, RequestFull } from "@caido/sdk-frontend";

const props = defineProps<{
  sdk: Caido;
  request: RequestFull;
}>();

const formattedJson = computed(() => {
  try {
    const body = props.request.body || "{}";
    const json = JSON.parse(body);
    return JSON.stringify(json, null, 2);
  } catch {
    return "";
  }
});

const error = computed(() => {
  try {
    const body = props.request.body || "{}";
    JSON.parse(body);
    return null;
  } catch {
    return "Invalid JSON";
  }
});
</script>

<template>
  <div v-if="error" class="text-red-500 p-4">
    {{ error }}
  </div>
  <pre v-else class="p-4 bg-gray-100 rounded overflow-auto">
    {{ formattedJson }}
  </pre>
</template>
```

```ts
import type { Caido } from "@caido/sdk-frontend";
import JSONFormatterView from "./JSONFormatterView.vue";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  sdk.httpHistory.addRequestViewMode({
    label: "JSON Formatter",
    view: {
      component: JSONFormatterView,
    },
  });
};
```

### Editable Request View

A view mode for Intercept or Replay that allows editing the request using the `requestDraft` prop.

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { Caido, RequestFull, RequestDraft } from "@caido/sdk-frontend";

const props = defineProps<{
  sdk: Caido;
  request: RequestFull;
  requestDraft: RequestDraft;
}>();

const editedBody = ref(props.request.body || "");

const updateBody = () => {
  props.requestDraft.setBody(editedBody.value);
  props.sdk.window.showToast("Request body updated", { variant: "success" });
};
</script>

<template>
  <div class="p-5">
    <label class="block mb-2">
      Request Body:
      <textarea
        v-model="editedBody"
        class="w-full p-2 mt-1 border rounded"
        rows="10"
      />
    </label>
    <button
      @click="updateBody"
      class="px-4 py-2 bg-blue-500 text-white rounded"
    >
      Update Request
    </button>
  </div>
</template>
```

```ts
import type { Caido } from "@caido/sdk-frontend";
import EditableRequestView from "./EditableRequestView.vue";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  sdk.intercept.addRequestViewMode({
    label: "Editable Body",
    view: {
      component: EditableRequestView,
    },
  });

  sdk.replay.addRequestViewMode({
    label: "Editable Body",
    view: {
      component: EditableRequestView,
    },
  });
};
```

### Response Formatter View

A response view mode that formats response bodies as pretty-printed JSON:

```vue
<script setup lang="ts">
import { computed } from "vue";
import type { Caido, ResponseFull, RequestFull } from "@caido/sdk-frontend";

const props = defineProps<{
  sdk: Caido;
  response: ResponseFull;
  request: RequestFull;
}>();

const formattedJson = computed(() => {
  try {
    const body = props.response.body || "{}";
    const json = JSON.parse(body);
    return JSON.stringify(json, null, 2);
  } catch {
    return "";
  }
});

const error = computed(() => {
  try {
    const body = props.response.body || "{}";
    JSON.parse(body);
    return null;
  } catch {
    return "Invalid JSON";
  }
});
</script>

<template>
  <div v-if="error" class="text-red-500 p-4">
    {{ error }}
  </div>
  <pre v-else class="p-4 bg-gray-100 rounded overflow-auto">
    {{ formattedJson }}
  </pre>
</template>
```

```ts
import type { Caido } from "@caido/sdk-frontend";
import ResponseJSONFormatterView from "./ResponseJSONFormatterView.vue";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  // Add to HTTP History
  sdk.httpHistory.addResponseViewMode({
    label: "JSON Formatter",
    view: {
      component: ResponseJSONFormatterView,
    },
  });

  // Add to Replay
  sdk.replay.addResponseViewMode({
    label: "JSON Formatter",
    view: {
      component: ResponseJSONFormatterView,
    },
  });

  // Add to other pages as needed
  sdk.search.addResponseViewMode({
    label: "JSON Formatter",
    view: {
      component: ResponseJSONFormatterView,
    },
  });
};
```

---

---
url: /plugins/reference/sdks/frontend/ai.md
---
# AI

### AILanguageModelSettings

> **AILanguageModelSettings** = `object`

Settings for AI language model.

#### Properties

##### capabilities?

> `optional` **capabilities**: `object`

###### reasoning

> **reasoning**: `boolean`

###### structured\_output

> **structured\_output**: `boolean`

##### reasoning?

> `optional` **reasoning**: [`AIReasoningSettings`](#aireasoningsettings)

***

### AIProvider

> **AIProvider** = `ProviderV3` & (`modelId`: `string`, `settings?`: [`AILanguageModelSettings`](#ailanguagemodelsettings)) => `LanguageModelV3`

Official AI Provider to be used by the [ai](https://ai-sdk.dev/) library.

***

### AIReasoningSettings

> **AIReasoningSettings** = `object`

Settings for AI reasoning.

#### Properties

##### effort

> **effort**: `"low"` | `"medium"` | `"high"`

***

### AiSDK

> **AiSDK** = `object`

Utilities to interact with AI.

#### Properties

##### createProvider()

> **createProvider**: () => [`AIProvider`](#aiprovider)

Creates a new AI provider instance that can be used with the [ai](https://ai-sdk.dev/) library.

###### Returns

[`AIProvider`](#aiprovider)

A provider instance compatible with the [ai](https://ai-sdk.dev/) library.

##### getUpstreamProviders()

> **getUpstreamProviders**: () => [`AIUpstreamProvider`](#aiupstreamprovider)\[]

Gets the list of upstream AI providers with their configuration status.

###### Returns

[`AIUpstreamProvider`](#aiupstreamprovider)\[]

An array of AI upstream providers with their configuration status.

***

### AIUpstreamProvider

> **AIUpstreamProvider** = `object`

AI upstream provider information.

#### Properties

##### id

> **id**: [`AIUpstreamProviderId`](#aiupstreamproviderid)

##### status

> **status**: [`AIUpstreamProviderStatus`](#aiupstreamproviderstatus)

***

### AIUpstreamProviderId

> **AIUpstreamProviderId** = `"anthropic"` | `"google"` | `"openai"` | `"openrouter"`

AI upstream provider ID.

***

### AIUpstreamProviderStatus

> **AIUpstreamProviderStatus** = `"Ready"` | `"Missing"`

AI upstream provider status.
Ready: The upstream provider is ready to use.
Missing: The upstream provider is not configured.

---

---
url: /plugins/guides/vibe_coding.md
---
# AI Assisted Coding

::: warning DISCLAIMER
While AI assistants can be helpful in development, they may sometimes provide incorrect or incomplete information. Always verify AI-generated code and suggestions against the official documentation and test thoroughly.
:::

## Cursor

If you are using [Cursor](https://www.cursor.com/en) as your IDE, you can load the Caido documentation websites into your workspace so that Cursor becomes aware of the Caido SDK:

1. Open Cursor and click `View` in the menu bar and select `Command Palette` (*or use `CTRL + Shift + P`*) and search for:

```text
Add New Custom Docs
```

2. Select the option and enter the documentation URL:

```text
https://developer.caido.io/
```

3. Provide a reference name and click `Confirm`.

4) Cursor will index the website allowing you to reference the documentation in prompts by using `@<reference name>`.

::: tip TIPS

* Add `https://github.com/caido/sdk-js` to Cursor as well so it has the SDK alongside the developer documentation examples.

* Also add `https://docs.caido.io/` to Cursor so you can reference interfaces for context.

* You can also customize prompt responses by navigating to `Settings`, `Rules`, and writing your preferences in the `User Rules` input field.
  :::

## Custom GPT

[This custom GPT is trained on Caido documentation, SDKs, and additional sources to answer your prompts with higher accuracy.](https://chatgpt.com/g/g-68095eb17eb08191ba19fd85f0a516ec-caido-developer-assistant)

---

---
url: /client-sdk/reference/api.md
---

\<OASpec
:tags='\["api"]'
hide-branding

>

\<template #header="header">



---

---
url: /plugins/reference/sdks/backend/api.md
---
# API

### APISDK

> **APISDK**<`API`, `Events`> = `object`

The SDK for the API RPC service.

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `API` | `object` |
| `Events` | `object` |

#### Methods

##### register()

> **register**(`name`: keyof `API`, `callback`: (`sdk`: [`SDK`](index.md#sdk), ...`args`: `any`\[]) => `any`): `void`

Registers a new backend function for the RPC.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | keyof `API` |
| `callback` | (`sdk`: [`SDK`](index.md#sdk), ...`args`: `any`\[]) => `any` |

###### Returns

`void`

###### Example

```ts
sdk.api.register("multiply", (sdk: SDK, a: number, b: number) => {
   return a * b;
});
```

##### send()

> **send**(`event`: keyof `Events`, ...`args`: `any`\[]): `void`

Sends an event to the frontend plugin.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | keyof `Events` |
| ...`args` | `any`\[] |

###### Returns

`void`

###### Example

```ts
sdk.api.send("myEvent", 5, "hello");
```

---

---
url: /plugins/reference/sdks/frontend/assistant.md
---
# Assistant

### AssistantPageContext

> **AssistantPageContext** = `object`

Assistant page context.

#### Properties

##### kind

> **kind**: `"Assistant"`

---

---
url: /client-sdk/reference/authentication.md
---
# Authentication

To access the public cloud API, you must use Personnal Access Tokens (PAT).
PATs act on your behalf and will have the same set of permissions as you have.
The PATs can be tied to a team to access that team's resources.

## Use to a PAT?

When you send a request to the public cloud API, add the following header:

```http
Authorization: Bearer <PAT>
```

## How to create a PAT?

We currently do not have an interface to create PATs.
For the moment you will have to use our internal GraphQL API.

**Endpoint:** `POST` `https://api.caido.io/dashboard/graphql`
**Authentication:** `CAIDO_SESSION` cookie

```graphql
mutation CreatePat {
  createPat(
    input: {
      name: "<NAME>"
      teamId: "<ENTER TEAM ID>"
      expiresAt: "<OPTIONAL RFC3339 DATETIME>"
    }
  ) {
    pat {
      id
      token
    }
  }
}
```

::: tip

```bash
echo '{ "query":
  "mutation CreatePat($name: String!, $teamId: ID!) {
      createPat(
        input: {
          name: $name
          teamId: $teamId
        }
      ) {
        pat {
          id
          token
        }
      }
    }",
  "variables": {
    "name": "My PAT",
    "teamId": "01JXP5F0C40WYWSPQS9WAHSB9T"
  }
}' | tr -d '\n' | curl --silent \
https://api.caido.io/dashboard/graphql \
--header "Cookie: CAIDO_SESSION=<SESSION>" \
--header "Content-Type: application/json" \
--data @-
```

## How to revoke a PAT?

We currently do not have an interface to revoke PATs.
For the moment you will have to use our internal GraphQL API.

**Endpoint:** `POST` `https://api.caido.io/dashboard/graphql`
**Authentication:** `CAIDO_SESSION` cookie

```graphql
mutation RevokePat {
  revokePat(id: "<PAT ID>") {
    pat {
      id
    }
  }
}
```

::: tip

```bash
echo '{ "query":
  "mutation RevokePat($id: ID!) {
    revokePat(id: $id) {
      pat {
        id
      }
    }
  }",
  "variables": {
    "id": "01JXP5F0C40WYWSPQS9WAHSB9T"
  }
}' | tr -d '\n' | curl --silent \
https://api.caido.io/dashboard/graphql \
--header "Cookie: CAIDO_SESSION=<SESSION>" \
--header "Content-Type: application/json" \
--data @-
```

---

---
url: /client-sdk/concepts/auth_methods.md
---
# Authentication Methods

The Client SDK supports three methods for authenticating a script against a Caido instance: Personal Access Token, Browser Login, and Direct Token. They all produce the same kind of access token, but they differ in how that token is obtained.

Two of them use the same OAuth 2.0 Device Authorization grant that the Caido desktop and web applications use, described in [Instance Authentication](https://docs.caido.io/app/concepts/instance_authentication.html). The third skips the flow entirely.

## Personal Access Token

A Personal Access Token (PAT) is a long-lived credential created in the Caido Dashboard. When the SDK authenticates with a PAT, it starts the device authorization flow on the instance and then automatically approves it by calling the Caido Cloud API with the PAT as a Bearer credential. No human interaction is required.

This is the natural choice for headless environments: scripts, CI/CD pipelines, scheduled jobs, and anything that runs without a person nearby. A PAT is tied to the user that created it and inherits that user's permissions on the resources it targets, whether that's a personal account or a Team.

The PAT itself is not used as the credential for API calls. Once the Cloud approves the device flow, the instance delivers an access token and a refresh token to the script, and those are what subsequent API calls carry as Bearer tokens.

The full mechanics of PATs as a credential, where to create one, and how they relate to accounts and Teams are covered in [Personal Access Token](https://docs.caido.io/app/concepts/pat.html) in the user docs.

## Browser Login

Browser Login uses the same device authorization flow as PAT, but with a person in the loop instead of the Cloud. The SDK starts the flow on the instance, receives a verification URL and a short user code, and surfaces them to the script through an `onRequest` callback. A person opens the URL in a browser, enters the code, and approves the request on the [Caido Dashboard](https://dashboard.caido.io). The SDK waits on a WebSocket subscription until the instance delivers the resulting token pair.

This suits interactive scripts, developer tools, and one-off automations where the person running the script can complete the approval step at the time of authentication. Outside of who approves the request, the resulting token pair is identical to one obtained through a PAT.

## Direct Token

Direct Token skips the device authorization flow entirely. Instead of negotiating with the instance and the Cloud, the script provides an access token, and optionally a refresh token, that it has already obtained through some other channel. The SDK uses the token as-is on every authenticated request.

This pattern fits when the surrounding system already manages tokens for the script. Examples include a parent process that ran the device flow itself and passed the result down, a service that mints tokens out-of-band, or tests that need deterministic credentials.

If only an access token is provided, the SDK has no way to obtain a new one when it expires. The script must rotate the token externally or switch to one of the other two methods. Providing both an access token and a refresh token restores the automatic renewal behavior covered in [Caching of Tokens](./auth_caching.md).

---

---
url: /plugins/reference/sdks/frontend/automate.md
---
# Automate

### AutomateEntry

> **AutomateEntry** = `object`

A automate entry.

#### Properties

##### createdAt

> **createdAt**: `Date`

The date the entry was created.

##### id

> **id**: [`ID`](utils.md#id)

The ID of the entry.

##### name

> **name**: `string`

The name of the entry.

***

### AutomatePageContext

> **AutomatePageContext** = `object`

Automate page context.

#### Properties

##### kind

> **kind**: `"Automate"`

##### requestSelection

> **requestSelection**: [`Selection`](utils.md#selection)<[`ID`](utils.md#id)>

##### selection

> **selection**: [`Selection`](utils.md#selection)<{ `id`: [`ID`](utils.md#id); `kind`: `"AutomateSession"`; } | { `id`: [`ID`](utils.md#id); `kind`: `"AutomateEntry"`; }>

***

### AutomateSDK

> **AutomateSDK** = `object`

Utilities to interact with the Automate page.

#### Properties

##### addEntryIndicator()

> **addEntryIndicator**: (`entryId`: [`ID`](utils.md#id), `indicator`: [`AddIndicatorOptions`](utils.md#addindicatoroptions)) => [`Indicator`](utils.md#indicator)

Add an indicator to an automate entry.
Indicators are displayed next to the entry name in the collections tree.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `entryId` | [`ID`](utils.md#id) | The ID of the entry to add the indicator to. |
| `indicator` | [`AddIndicatorOptions`](utils.md#addindicatoroptions) | The indicator configuration. |

###### Returns

[`Indicator`](utils.md#indicator)

A handle object with a `remove` method to remove the indicator.

###### Example

```ts
const indicator = sdk.automate.addEntryIndicator(entryId, {
  icon: "fas fa-exclamation-triangle",
  description: "Security warning",
});

// Later, remove the indicator
indicator.remove();
```

##### addRequestEditorExtension()

> **addRequestEditorExtension**: (`extension`: `Extension`) => `void`

Add an extension to the request editor.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `extension` | `Extension` | The extension to add. |

###### Returns

`void`

##### addRequestViewMode()

> **addRequestViewMode**: (`options`: [`RequestViewModeOptions`](request.md#requestviewmodeoptions)) => `void`

Add a custom request view mode.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`RequestViewModeOptions`](request.md#requestviewmodeoptions) | The view mode options. |

###### Returns

`void`

##### addResponseViewMode()

> **addResponseViewMode**: (`options`: [`ResponseViewModeOptions`](response.md#responseviewmodeoptions)) => `void`

Add a custom response view mode.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`ResponseViewModeOptions`](response.md#responseviewmodeoptions) | The view mode options. |

###### Returns

`void`

##### getEntries()

> **getEntries**: (`sessionId`: [`ID`](utils.md#id)) => [`AutomateEntry`](#automateentry)\[]

Get the list of all automate entries.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `sessionId` | [`ID`](utils.md#id) | The ID of the session to get the entries of. |

###### Returns

[`AutomateEntry`](#automateentry)\[]

The list of all automate entries.

##### getSessions()

> **getSessions**: () => [`AutomateSession`](#automatesession)\[]

Get the list of all automate sessions.

###### Returns

[`AutomateSession`](#automatesession)\[]

The list of all automate sessions.

***

### AutomateSession

> **AutomateSession** = `object`

A automate session.

#### Properties

##### createdAt

> **createdAt**: `Date`

The date the session was created.

##### entryIds

> **entryIds**: [`ID`](utils.md#id)\[]

The IDs of all entries in this session.

##### id

> **id**: [`ID`](utils.md#id)

The ID of the session.

##### name

> **name**: `string`

The name of the session.

---

---
url: /plugins/reference/sdks/frontend/backend.md
---
# Backend

### BackendEndpoints

> **BackendEndpoints** = `object`

Endpoints provided by the backend plugin.

#### Index Signature

\[`key`: `string`]: (...`args`: `any`\[]) => `any`

***

### BackendEvents

> **BackendEvents** = `object`

Events emitted by the backend plugin.

#### Index Signature

\[`key`: `string`]: (...`args`: `any`\[]) => `void`

***

### BackendSDK

> **BackendSDK**<`T`, `E`> = `{ [K in keyof T]: (args: Parameters<T[K]>) => PromisifiedReturnType<T[K]> }` & `object`

Utilities to interact with the backend plugin.

#### Type Declaration

##### onEvent()

> **onEvent**: <`K`>(`event`: `K`, `callback`: `E`\[`K`]) => `object`

Subscribe to a backend event.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` *extends* keyof `E` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | `K` | The event to subscribe to. |
| `callback` | `E`\[`K`] | The callback to call when the event is emitted. |

###### Returns

`object`

An object with a `stop` method that can be called to stop listening to the event.

###### stop()

> **stop**: () => `void`

###### Returns

`void`

#### Type Parameters

| Type Parameter |
| ------ |
| `T` *extends* [`BackendEndpoints`](#backendendpoints) |
| `E` *extends* [`BackendEvents`](#backendevents) |

---

---
url: /plugins/concepts/workflow.md
---
# Backend Plugins vs Workflows

You might be wondering what the differences between a Workflow and a backend plugin are.
We are aware that the two concepts might be confusing since both give you scripting access to Caido and generally expose the same functionalities.
But they serve different purposes.

## Workflow

Workflows are our low-code/no-code solution. You should generally start with them if you need to extend Caido.
The pre-made Nodes use the [Workflow SDK](/plugins/reference/sdks/workflow/) of Caido under-the-hood.
Workflows run on-demand and they don't persist in-between runs. They are similar in concept to Lambdas or Functions-as-a-Service system.

When using the Javascript Node, you have a full access to the [Workflow SDK](/plugins/reference/sdks/workflow/).
The [runtime](/plugins/concepts/runtime) for that Javascript code is the same as for the backend plugins, but the SDK has access to less functionalities.
This is why it is easier to start with a Workflow using Javascript Nodes and then transition to a backend plugin.

## Backend Plugins

Backend plugins give you a long running thread inside Caido that uses our Javascript [runtime](/plugins/concepts/runtime).
It can use the [Backend SDK](/plugins/reference/sdks/backend/) which is similar to the [Workflow SDK](/plugins/reference/sdks/workflow/), but with more features.
For example, it can expose an API that a `frontend plugin` can use.

Generally if your intent is to create an interface in Caido (via a `frontend plugin`), you will need a `backend plugin` to go with it.

---

---
url: /plugins/reference/sdks/frontend/backups.md
---
# Backups

### BackupsPageContext

> **BackupsPageContext** = `object`

Backups page context.

#### Properties

##### kind

> **kind**: `"Backups"`

---

---
url: /client-sdk/guides/base_setup.md
---
# Base Setup

This guide walks through configuring authentication, caching the resulting tokens, connecting to your Caido instance, and making your first API call to confirm everything works.

## Authenticate

The `Client` supports three authentication methods, exposed through the `auth` option. Pick the one that matches your environment:

1. **Personal Access Token** for headless scripts and CI/CD pipelines.
2. **Browser Login** for interactive scripts where a human can approve the login.
3. **Direct Token** when you already hold an access token from another source.

### 1. Personal Access Token

The SDK uses the PAT to automatically approve a device authorization flow against the Caido Cloud, so no human interaction is required.

[Create a PAT](https://docs.caido.io/dashboard/guides/create_pat.html) from your [Caido Dashboard](https://dashboard.caido.io/developer), then pass the token to the `Client` constructor:

```ts
const client = new Client({
  url: "http://localhost:8080",
  auth: {
    pat: "caido_xxxxx",
  },
});
```

::: warning
Do not commit your PAT to source control. Read it from an environment variable or a secret manager instead:

```ts
const client = new Client({
  url: "http://localhost:8080",
  auth: {
    pat: process.env["CAIDO_PAT"]!,
  },
});
```

:::

### 2. Browser Login

The SDK starts a device authorization flow and surfaces a verification URL that the user opens in their browser to approve the login.

Provide an `onRequest` callback to handle the URL:

```ts
const client = new Client({
  url: "http://localhost:8080",
  auth: {
    onRequest: (request) => {
      console.log(`Open this URL to log in: ${request.verificationUrl}`);
    },
  },
});
```

If `onRequest` is omitted, the SDK logs the URL to the console using its default logger.

### 3. Direct Token

Use this when you already have an access token (and optionally a refresh token), for example from a parent process or an earlier session.

```ts
const client = new Client({
  url: "http://localhost:8080",
  auth: {
    token: "access_token_string",
  },
});
```

To allow the SDK to refresh the access token automatically, pass a token pair:

```ts
const client = new Client({
  url: "http://localhost:8080",
  auth: {
    token: {
      accessToken: "...",
      refreshToken: "...",
    },
  },
});
```

::: info
A bare access token cannot be refreshed. Once it expires, you must provide a new token or switch to the Personal Access Token or Browser Login method.
:::

## Cache the Access Token

Once the SDK exchanges your PAT (or completes the browser flow) for an access token and a refresh token, it can cache them on disk or in `localStorage`. On subsequent runs, the cached tokens are loaded first, so the authentication flow is skipped until the tokens expire.

### File cache

For Node.js scripts. The path is absolute or relative to the current working directory.

```ts
const client = new Client({
  url: "http://localhost:8080",
  auth: {
    pat: process.env["CAIDO_PAT"]!,
    cache: { file: ".caido-token.json" },
  },
});
```

The cache file is written with permissions `0o600` (read and write for the owner only).

### LocalStorage cache

For browser-based tools. The string is the key under which the cache is stored.

```ts
const client = new Client({
  url: "http://localhost:8080",
  auth: {
    pat: "caido_xxxxx",
    cache: { localstorage: "caido-token" },
  },
});
```

::: info
For custom cache implementations (encrypted storage, secret managers, etc.), see the Advanced section.
:::

## Connect to the Instance

Before making any API call, call `connect()` to authenticate and verify the instance is reachable:

```ts
await client.connect();
```

By default, `connect()` waits for the instance to be ready by polling its `/health` endpoint. To skip the ready check or customize the polling:

```ts
// Skip the ready check entirely
await client.connect({ ready: false });

// Custom polling
await client.connect({
  ready: {
    interval: 1000,
    retries: 10,
    timeout: 10000,
  },
});
```

## Get the Viewer

Once connected, call `client.user.viewer()` to retrieve the authenticated user. This is the recommended first call to confirm that authentication and connectivity are wired up correctly.

```ts
const viewer = await client.user.viewer();
console.log(viewer);
```

The result is one of three user kinds:

* `CloudUser`: a cloud-authenticated user with a full profile (email, name, subscription).
* `GuestUser`: a guest user with only an `id`.
* `ScriptUser`: a script-authenticated user with only an `id`.

You can branch on `viewer.kind` to access the profile of a `CloudUser`:

```ts
if (viewer.kind === "CloudUser") {
  console.log(`Logged in as ${viewer.profile.identity.email}`);
}
```

## Examples

The script below combines everything above using PAT authentication and a file cache.

### index.ts

```ts
import { Client } from "@caido/sdk-client";

async function main() {
  const instanceUrl =
    process.env["CAIDO_INSTANCE_URL"] ?? "http://localhost:8080";
  const pat = process.env["CAIDO_PAT"];

  if (!pat) {
    console.error("CAIDO_PAT environment variable is required");
    process.exit(1);
  }

  const client = new Client({
    url: instanceUrl,
    auth: {
      pat: pat,
      cache: { file: ".caido-token.json" },
    },
  });

  await client.connect();

  const viewer = await client.user.viewer();
  console.log("Viewer:", JSON.stringify(viewer, null, 2));
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});
```

Run it with:

```bash
export CAIDO_PAT=caido_xxxxx
npx tsx ./index.ts
```

A successful run logs the authentication flow followed by the authenticated user, for example:

```txt
[caido] Attempting to load cached token
[caido] Failed to load cached token from file
[caido] Starting authentication flow
[caido] Authentication flow completed
[caido] Saving token to cache
Viewer: {
  "kind": "CloudUser",
  "id": "<your-user-id>",
  "profile": {
    "identity": {
      "email": "you@example.com",
      "name": "Your Name"
    },
    "subscription": {
      "plan": {
        "name": "<plan-name>"
      },
      "entitlements": [
        {
          "name": "feature:..."
        }
      ]
    }
  }
}
```

On subsequent runs, the cached token is reused and the `Starting authentication flow` lines are replaced with `Loaded token from cache`.

---

---
url: /client-sdk/concepts/auth_caching.md
---
# Caching of Tokens

After a script authenticates against a Caido instance, the SDK keeps the resulting access token in memory for the rest of the process. To preserve that state across script runs without repeating the [authentication flow](./auth_methods.md) every time, the SDK can serialize it to a cache and reload it on the next connection.

The SDK ships with two built-in caches (file-based for Node and localStorage-based for browsers) and accepts a custom implementation for everything else.

## File

The file cache writes the token state to a JSON file on disk. It is the natural choice for Node.js scripts and CI/CD environments where local disk is available and acceptable.

The file is written with `0o600` permissions (read and write for the owner only) to limit accidental exposure to other users on the same machine. Beyond that, the file content is plain JSON: anyone with file system access can read the tokens.

The file cache is not suitable for shared, networked, or untrusted storage. For those scenarios, see [Custom Implementation](#custom-implementation).

## Local Storage

The localStorage cache writes the token state to the browser's `localStorage` under a key. It is the built-in choice for SDK use inside a browser environment.

Like the file cache, the stored value is plain JSON. Browser sandboxing scopes the storage to the origin, but anything running in the same origin (including third-party scripts loaded into the page) can read it.

## Custom Implementation

For everything that does not fit the file or localStorage models, scripts can implement the `TokenCache` interface (`load`, `save`, `clear`) and pass an instance to the `Client` constructor. Common motivations include:

* Encrypted storage on disk
* Tokens stored in a remote secret manager (Vault, AWS Secrets Manager, etc.)
* Shared cache across multiple workers (Redis, database)
* In-memory cache for tests

A custom cache is opaque to the SDK: it only calls the three interface methods, and the implementation owns where and how the tokens are stored.

## Refresh

Access tokens have a limited lifetime. When an authenticated request fails because the access token has expired or been revoked, the SDK uses the cached refresh token to mint a new access token through the instance's `refreshAuthenticationToken` mutation. The new tokens replace the old ones in memory and are written back to the cache.

The renewal happens reactively rather than on a timer: the SDK does not consult the cached `expiresAt` to refresh proactively. It waits until the server rejects a request, then refreshes and retries. From the script's point of view, the failure is invisible.

A cache holding only an access token (no refresh token) can serve a single short run but cannot recover when the access token expires. Pairing access tokens with refresh tokens is what keeps cached state usable over time.

---

---
url: /plugins/reference/config.md
---
# caido.config.ts

The `caido.config.ts` file is used to configure your package.
It will used to generate the [`manifest.json`](./manifest.md) automatically.

```ts
import { defineConfig } from "@caido-community/dev";

export default defineConfig({
  id: "my-plugin",
  name: "My Plugin",
  description: "A plugin for Caido",
  version: "0.0.0",
  author: {
    name: "Caido Labs Inc.",
    email: "dev@caido.io",
    url: "https://caido.io",
  },
  plugins: [
    {
      kind: "frontend",
      id: "my-frontend",
      name: "My Frontend",
      root: "packages/my-frontend",
      backend: {
        id: "my-backend",
      },
      assets: ["my-assets/*.png"],
    },
    {
      kind: "backend",
      id: "my-backend",
      name: "My Backend",
      root: "packages/my-backend",
    },
  ],
});
```

## Global Options

| Option      | Type     | Required | Description                                                                                                                                                            |
| ----------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id          | `string` | Yes      | Must be unique and must only consist of lowercase letters, numbers, hyphens and underscores (the order of which must satisfy the regex: `^[a-z]+(?:[_-][a-z0-9]+)*$`). |
| name        | `string` | Yes      | The name of your plugin. This is the name that will be displayed when a user installs your plugin.                                                                     |
| description | `string` | Yes      | The description of your plugin. This is the description that will be displayed when a user installs your plugin.                                                       |
| version     | `string` | Yes      | Represents the version of your plugin using [Semantic Versioning](https://semver.org/).                                                                                |

## Author Options

| Option | Type     | Required | Description                             |
| ------ | -------- | -------- | --------------------------------------- |
| name   | `string` | Yes      | The name of the author of your plugin.  |
| email  | `string` | No       | The email of the author of your plugin. |
| url    | `string` | No       | The URL of the author of your plugin.   |

## Frontend Plugin Options

| Option     | Type                                     | Required | Description                                                                                 |
| ---------- | ---------------------------------------- | -------- | ------------------------------------------------------------------------------------------- |
| kind       | `"frontend"`                             | Yes      | The kind of plugin.                                                                         |
| id         | `string`                                 | Yes      | The id of the plugin.                                                                       |
| name       | `string`                                 | No       | The name of the plugin. Defaults to the id.                                                 |
| root       | `string`                                 | Yes      | The root directory of the frontend plugin. (e.g. `packages/my-frontend`)                    |
| backend.id | `string`                                 | Yes      | The id of the backend plugin that this frontend plugin is associated with.                  |
| vite       | [`ViteConfig`](https://vite.dev/config/) | No       | Additional Vite configuration for the frontend plugin.                                      |
| assets     | `Array<string>`                          | No       | Assets to package with the plugin. Supports glob for files and directories (recursive copy) |

## Backend Plugin Options

| Option | Type            | Required | Description                                                                                 |
| ------ | --------------- | -------- | ------------------------------------------------------------------------------------------- |
| kind   | `"backend"`     | Yes      | The kind of plugin.                                                                         |
| id     | `string`        | Yes      | The id of the plugin.                                                                       |
| name   | `string`        | No       | The name of the plugin. Defaults to the id.                                                 |
| root   | `string`        | Yes      | The root directory of the backend plugin. (e.g. `packages/my-backend`)                      |
| assets | `Array<string>` | No       | Assets to package with the plugin. Supports glob for files and directories (recursive copy) |

---

---
url: /plugins/reference/modules/caido/crypto.md
---
[@caido/quickjs-types](../index.md) / caido/crypto

# caido/crypto

## Classes

### Cipheriv

Instances of the `Cipheriv` class are used to encrypt data. The class can be
used in one way:

* Using the `cipher.update()` and `cipher.final()` methods to produce
  the encrypted data.

The [createCipheriv](#createcipheriv) method is
used to create `Cipheriv` instances. `Cipheriv` objects are not to be created
directly using the `new` keyword.

#### Extended by

* [`CipherCCM`](#cipherccm)
* [`CipherGCM`](#ciphergcm)
* [`CipherOCB`](#cipherocb)
* [`CipherChaCha20Poly1305`](#cipherchacha20poly1305)

#### Methods

##### final()

> **final**(): [`Buffer`](../llrt/buffer.md#buffer)

Once the `cipher.final()` method has been called, the `Cipheriv` object can no
longer be used to encrypt data. Attempts to call `cipher.final()` more than
once will result in an error being thrown.

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

Any remaining enciphered contents.

##### update()

> **update**(`data`: [`BinaryLike`](#binarylike)): [`Buffer`](../llrt/buffer.md#buffer)

Updates the cipher with `data`.

The `cipher.update()` method can be called multiple times with new data until `cipher.final()` is called. Calling `cipher.update()` after `cipher.final()` will result in an error being
thrown.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `data` | [`BinaryLike`](#binarylike) |

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

***

### Decipheriv

Instances of the `Decipheriv` class are used to decrypt data. The class can be
used in one way:

* Using the `decipher.update()` and `decipher.final()` methods to
  produce the unencrypted data.

The [createDecipheriv](#createdecipheriv) method is
used to create `Decipheriv` instances. `Decipheriv` objects are not to be created
directly using the `new` keyword.

#### Extended by

* [`DecipherCCM`](#decipherccm)
* [`DecipherGCM`](#deciphergcm)
* [`DecipherOCB`](#decipherocb)
* [`DecipherChaCha20Poly1305`](#decipherchacha20poly1305)

#### Methods

##### final()

> **final**(): [`Buffer`](../llrt/buffer.md#buffer)

Once the `decipher.final()` method has been called, the `Decipheriv` object can
no longer be used to decrypt data. Attempts to call `decipher.final()` more
than once will result in an error being thrown.

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

##### update()

> **update**(`data`: [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview)): [`Buffer`](../llrt/buffer.md#buffer)

Updates the decipher with `data`.

The `decipher.update()` method can be called multiple times with new data until `decipher.final()` is called. Calling `decipher.update()` after `decipher.final()` will result in an error
being thrown.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `data` | [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview) |

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

***

### Hash

The `Hash` class is a utility for creating hash digests of data.

Using the `hash.update()` and `hash.digest()` methods to produce the
computed hash.

The [createHash](#createhash) method is used to create `Hash` instances.
`Hash`objects are not to be created directly using the `new` keyword.

Example: Using the `hash.update()` and `hash.digest()` methods:

```js
import { createHash } from 'crypto';

const hash = createHash('sha256');

hash.update('some data to hash');
console.log(hash.digest('hex'));
// Prints:
//   6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50
```

#### Methods

##### digest()

###### Call Signature

> **digest**(): [`Buffer`](../llrt/buffer.md#buffer)

Calculates the digest of all of the data passed to be hashed (using the `hash.update()` method).
If `encoding` is provided a string will be returned; otherwise
a `Buffer` is returned.

The `Hash` object can not be used again after `hash.digest()` method has been
called. Multiple calls will cause an error to be thrown.

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

###### Call Signature

> **digest**(`encoding`: [`BinaryToTextEncoding`](#binarytotextencoding)): `string`

Calculates the digest of all of the data passed to be hashed (using the `hash.update()` method).
If `encoding` is provided a string will be returned; otherwise
a `Buffer` is returned.

The `Hash` object can not be used again after `hash.digest()` method has been
called. Multiple calls will cause an error to be thrown.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `encoding` | [`BinaryToTextEncoding`](#binarytotextencoding) | The `encoding` of the return value. |

###### Returns

`string`

##### update()

###### Call Signature

> **update**(`data`: [`BinaryLike`](#binarylike)): [`Hash`](#hash)

Updates the hash content with the given `data`, the encoding of which
is given in `inputEncoding`.
If `encoding` is not provided, and the `data` is a string, an
encoding of `'utf8'` is enforced. If `data` is a `Buffer`, `TypedArray`, or`DataView`,
then `inputEncoding` is ignored.

This can be called many times with new data as it is streamed.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `data` | [`BinaryLike`](#binarylike) |

###### Returns

[`Hash`](#hash)

###### Call Signature

> **update**(`data`: `string`, `inputEncoding`: [`Encoding`](#encoding)): [`Hash`](#hash)

Updates the hash content with the given `data`, the encoding of which
is given in `inputEncoding`.
If `encoding` is not provided, and the `data` is a string, an
encoding of `'utf8'` is enforced. If `data` is a `Buffer`, `TypedArray`, or`DataView`,
then `inputEncoding` is ignored.

This can be called many times with new data as it is streamed.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `data` | `string` | - |
| `inputEncoding` | [`Encoding`](#encoding) | The `encoding` of the `data` string. |

###### Returns

[`Hash`](#hash)

***

### Hmac

The `Hmac` class is a utility for creating cryptographic HMAC digests.

Using the `hmac.update()` and `hmac.digest()` methods to produce the
computed HMAC digest.

The [createHmac](#createhmac) method is used to create `Hmac` instances.
`Hmac`objects are not to be created directly using the `new` keyword.

Example: Using the `hmac.update()` and `hmac.digest()` methods:

```js
import { createHmac } from 'crypto';

const hmac = createHmac('sha256', 'a secret');

hmac.update('some data to hash');
console.log(hmac.digest('hex'));
// Prints:
//   7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e
```

#### Methods

##### digest()

###### Call Signature

> **digest**(): [`Buffer`](../llrt/buffer.md#buffer)

Calculates the HMAC digest of all of the data passed using `hmac.update()`.
If `encoding` is
provided a string is returned; otherwise a `Buffer` is returned;

The `Hmac` object can not be used again after `hmac.digest()` has been
called. Multiple calls to `hmac.digest()` will result in an error being thrown.

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

###### Call Signature

> **digest**(`encoding`: [`BinaryToTextEncoding`](#binarytotextencoding)): `string`

Calculates the HMAC digest of all of the data passed using `hmac.update()`.
If `encoding` is
provided a string is returned; otherwise a `Buffer` is returned;

The `Hmac` object can not be used again after `hmac.digest()` has been
called. Multiple calls to `hmac.digest()` will result in an error being thrown.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `encoding` | [`BinaryToTextEncoding`](#binarytotextencoding) | The `encoding` of the return value. |

###### Returns

`string`

##### update()

###### Call Signature

> **update**(`data`: [`BinaryLike`](#binarylike)): [`Hmac`](#hmac)

Updates the `Hmac` content with the given `data`, the encoding of which
is given in `inputEncoding`.
If `encoding` is not provided, and the `data` is a string, an
encoding of `'utf8'` is enforced. If `data` is a `Buffer`, `TypedArray`, or`DataView`,
then `inputEncoding` is ignored.

This can be called many times with new data as it is streamed.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `data` | [`BinaryLike`](#binarylike) |

###### Returns

[`Hmac`](#hmac)

###### Call Signature

> **update**(`data`: `string`, `inputEncoding`: [`Encoding`](#encoding)): [`Hmac`](#hmac)

Updates the `Hmac` content with the given `data`, the encoding of which
is given in `inputEncoding`.
If `encoding` is not provided, and the `data` is a string, an
encoding of `'utf8'` is enforced. If `data` is a `Buffer`, `TypedArray`, or`DataView`,
then `inputEncoding` is ignored.

This can be called many times with new data as it is streamed.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `data` | `string` | - |
| `inputEncoding` | [`Encoding`](#encoding) | The `encoding` of the `data` string. |

###### Returns

[`Hmac`](#hmac)

## Interfaces

### CipherCCM

Instances of the `Cipheriv` class are used to encrypt data. The class can be
used in one way:

* Using the `cipher.update()` and `cipher.final()` methods to produce
  the encrypted data.

The [createCipheriv](#createcipheriv) method is
used to create `Cipheriv` instances. `Cipheriv` objects are not to be created
directly using the `new` keyword.

#### Extends

* [`Cipheriv`](#cipheriv)

#### Methods

##### final()

> **final**(): [`Buffer`](../llrt/buffer.md#buffer)

Once the `cipher.final()` method has been called, the `Cipheriv` object can no
longer be used to encrypt data. Attempts to call `cipher.final()` more than
once will result in an error being thrown.

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

Any remaining enciphered contents.

###### Inherited from

[`Cipheriv`](#cipheriv).[`final`](#final)

##### getAuthTag()

> **getAuthTag**(): [`Buffer`](../llrt/buffer.md#buffer)

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

##### setAAD()

> **setAAD**(`buffer`: [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview)): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `buffer` | [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview) |

###### Returns

`this`

##### update()

> **update**(`data`: [`BinaryLike`](#binarylike)): [`Buffer`](../llrt/buffer.md#buffer)

Updates the cipher with `data`.

The `cipher.update()` method can be called multiple times with new data until `cipher.final()` is called. Calling `cipher.update()` after `cipher.final()` will result in an error being
thrown.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `data` | [`BinaryLike`](#binarylike) |

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

###### Inherited from

[`Cipheriv`](#cipheriv).[`update`](#update)

***

### CipherCCMOptions

#### Properties

##### authTagLength

> **authTagLength**: `number`

***

### CipherChaCha20Poly1305

Instances of the `Cipheriv` class are used to encrypt data. The class can be
used in one way:

* Using the `cipher.update()` and `cipher.final()` methods to produce
  the encrypted data.

The [createCipheriv](#createcipheriv) method is
used to create `Cipheriv` instances. `Cipheriv` objects are not to be created
directly using the `new` keyword.

#### Extends

* [`Cipheriv`](#cipheriv)

#### Methods

##### final()

> **final**(): [`Buffer`](../llrt/buffer.md#buffer)

Once the `cipher.final()` method has been called, the `Cipheriv` object can no
longer be used to encrypt data. Attempts to call `cipher.final()` more than
once will result in an error being thrown.

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

Any remaining enciphered contents.

###### Inherited from

[`Cipheriv`](#cipheriv).[`final`](#final)

##### getAuthTag()

> **getAuthTag**(): [`Buffer`](../llrt/buffer.md#buffer)

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

##### setAAD()

> **setAAD**(`buffer`: [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview)): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `buffer` | [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview) |

###### Returns

`this`

##### update()

> **update**(`data`: [`BinaryLike`](#binarylike)): [`Buffer`](../llrt/buffer.md#buffer)

Updates the cipher with `data`.

The `cipher.update()` method can be called multiple times with new data until `cipher.final()` is called. Calling `cipher.update()` after `cipher.final()` will result in an error being
thrown.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `data` | [`BinaryLike`](#binarylike) |

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

###### Inherited from

[`Cipheriv`](#cipheriv).[`update`](#update)

***

### CipherChaCha20Poly1305Options

#### Properties

##### authTagLength?

> `optional` **authTagLength**: `number`

###### Default

```ts
16
```

***

### CipherGCM

Instances of the `Cipheriv` class are used to encrypt data. The class can be
used in one way:

* Using the `cipher.update()` and `cipher.final()` methods to produce
  the encrypted data.

The [createCipheriv](#createcipheriv) method is
used to create `Cipheriv` instances. `Cipheriv` objects are not to be created
directly using the `new` keyword.

#### Extends

* [`Cipheriv`](#cipheriv)

#### Methods

##### final()

> **final**(): [`Buffer`](../llrt/buffer.md#buffer)

Once the `cipher.final()` method has been called, the `Cipheriv` object can no
longer be used to encrypt data. Attempts to call `cipher.final()` more than
once will result in an error being thrown.

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

Any remaining enciphered contents.

###### Inherited from

[`Cipheriv`](#cipheriv).[`final`](#final)

##### getAuthTag()

> **getAuthTag**(): [`Buffer`](../llrt/buffer.md#buffer)

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

##### setAAD()

> **setAAD**(`buffer`: [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview)): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `buffer` | [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview) |

###### Returns

`this`

##### update()

> **update**(`data`: [`BinaryLike`](#binarylike)): [`Buffer`](../llrt/buffer.md#buffer)

Updates the cipher with `data`.

The `cipher.update()` method can be called multiple times with new data until `cipher.final()` is called. Calling `cipher.update()` after `cipher.final()` will result in an error being
thrown.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `data` | [`BinaryLike`](#binarylike) |

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

###### Inherited from

[`Cipheriv`](#cipheriv).[`update`](#update)

***

### CipherGCMOptions

#### Properties

##### authTagLength?

> `optional` **authTagLength**: `number`

***

### CipherOCB

Instances of the `Cipheriv` class are used to encrypt data. The class can be
used in one way:

* Using the `cipher.update()` and `cipher.final()` methods to produce
  the encrypted data.

The [createCipheriv](#createcipheriv) method is
used to create `Cipheriv` instances. `Cipheriv` objects are not to be created
directly using the `new` keyword.

#### Extends

* [`Cipheriv`](#cipheriv)

#### Methods

##### final()

> **final**(): [`Buffer`](../llrt/buffer.md#buffer)

Once the `cipher.final()` method has been called, the `Cipheriv` object can no
longer be used to encrypt data. Attempts to call `cipher.final()` more than
once will result in an error being thrown.

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

Any remaining enciphered contents.

###### Inherited from

[`Cipheriv`](#cipheriv).[`final`](#final)

##### getAuthTag()

> **getAuthTag**(): [`Buffer`](../llrt/buffer.md#buffer)

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

##### setAAD()

> **setAAD**(`buffer`: [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview)): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `buffer` | [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview) |

###### Returns

`this`

##### update()

> **update**(`data`: [`BinaryLike`](#binarylike)): [`Buffer`](../llrt/buffer.md#buffer)

Updates the cipher with `data`.

The `cipher.update()` method can be called multiple times with new data until `cipher.final()` is called. Calling `cipher.update()` after `cipher.final()` will result in an error being
thrown.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `data` | [`BinaryLike`](#binarylike) |

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

###### Inherited from

[`Cipheriv`](#cipheriv).[`update`](#update)

***

### CipherOCBOptions

#### Properties

##### authTagLength

> **authTagLength**: `number`

***

### DecipherCCM

Instances of the `Decipheriv` class are used to decrypt data. The class can be
used in one way:

* Using the `decipher.update()` and `decipher.final()` methods to
  produce the unencrypted data.

The [createDecipheriv](#createdecipheriv) method is
used to create `Decipheriv` instances. `Decipheriv` objects are not to be created
directly using the `new` keyword.

#### Extends

* [`Decipheriv`](#decipheriv)

#### Methods

##### final()

> **final**(): [`Buffer`](../llrt/buffer.md#buffer)

Once the `decipher.final()` method has been called, the `Decipheriv` object can
no longer be used to decrypt data. Attempts to call `decipher.final()` more
than once will result in an error being thrown.

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

###### Inherited from

[`Decipheriv`](#decipheriv).[`final`](#final-2)

##### setAAD()

> **setAAD**(`buffer`: [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview)): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `buffer` | [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview) |

###### Returns

`this`

##### setAuthTag()

> **setAuthTag**(`buffer`: [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview)): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `buffer` | [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview) |

###### Returns

`this`

##### update()

> **update**(`data`: [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview)): [`Buffer`](../llrt/buffer.md#buffer)

Updates the decipher with `data`.

The `decipher.update()` method can be called multiple times with new data until `decipher.final()` is called. Calling `decipher.update()` after `decipher.final()` will result in an error
being thrown.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `data` | [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview) |

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

###### Inherited from

[`Decipheriv`](#decipheriv).[`update`](#update-2)

***

### DecipherChaCha20Poly1305

Instances of the `Decipheriv` class are used to decrypt data. The class can be
used in one way:

* Using the `decipher.update()` and `decipher.final()` methods to
  produce the unencrypted data.

The [createDecipheriv](#createdecipheriv) method is
used to create `Decipheriv` instances. `Decipheriv` objects are not to be created
directly using the `new` keyword.

#### Extends

* [`Decipheriv`](#decipheriv)

#### Methods

##### final()

> **final**(): [`Buffer`](../llrt/buffer.md#buffer)

Once the `decipher.final()` method has been called, the `Decipheriv` object can
no longer be used to decrypt data. Attempts to call `decipher.final()` more
than once will result in an error being thrown.

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

###### Inherited from

[`Decipheriv`](#decipheriv).[`final`](#final-2)

##### setAAD()

> **setAAD**(`buffer`: [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview)): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `buffer` | [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview) |

###### Returns

`this`

##### setAuthTag()

> **setAuthTag**(`buffer`: [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview)): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `buffer` | [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview) |

###### Returns

`this`

##### update()

> **update**(`data`: [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview)): [`Buffer`](../llrt/buffer.md#buffer)

Updates the decipher with `data`.

The `decipher.update()` method can be called multiple times with new data until `decipher.final()` is called. Calling `decipher.update()` after `decipher.final()` will result in an error
being thrown.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `data` | [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview) |

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

###### Inherited from

[`Decipheriv`](#decipheriv).[`update`](#update-2)

***

### DecipherGCM

Instances of the `Decipheriv` class are used to decrypt data. The class can be
used in one way:

* Using the `decipher.update()` and `decipher.final()` methods to
  produce the unencrypted data.

The [createDecipheriv](#createdecipheriv) method is
used to create `Decipheriv` instances. `Decipheriv` objects are not to be created
directly using the `new` keyword.

#### Extends

* [`Decipheriv`](#decipheriv)

#### Methods

##### final()

> **final**(): [`Buffer`](../llrt/buffer.md#buffer)

Once the `decipher.final()` method has been called, the `Decipheriv` object can
no longer be used to decrypt data. Attempts to call `decipher.final()` more
than once will result in an error being thrown.

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

###### Inherited from

[`Decipheriv`](#decipheriv).[`final`](#final-2)

##### setAAD()

> **setAAD**(`buffer`: [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview)): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `buffer` | [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview) |

###### Returns

`this`

##### setAuthTag()

> **setAuthTag**(`buffer`: [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview)): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `buffer` | [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview) |

###### Returns

`this`

##### update()

> **update**(`data`: [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview)): [`Buffer`](../llrt/buffer.md#buffer)

Updates the decipher with `data`.

The `decipher.update()` method can be called multiple times with new data until `decipher.final()` is called. Calling `decipher.update()` after `decipher.final()` will result in an error
being thrown.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `data` | [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview) |

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

###### Inherited from

[`Decipheriv`](#decipheriv).[`update`](#update-2)

***

### DecipherOCB

Instances of the `Decipheriv` class are used to decrypt data. The class can be
used in one way:

* Using the `decipher.update()` and `decipher.final()` methods to
  produce the unencrypted data.

The [createDecipheriv](#createdecipheriv) method is
used to create `Decipheriv` instances. `Decipheriv` objects are not to be created
directly using the `new` keyword.

#### Extends

* [`Decipheriv`](#decipheriv)

#### Methods

##### final()

> **final**(): [`Buffer`](../llrt/buffer.md#buffer)

Once the `decipher.final()` method has been called, the `Decipheriv` object can
no longer be used to decrypt data. Attempts to call `decipher.final()` more
than once will result in an error being thrown.

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

###### Inherited from

[`Decipheriv`](#decipheriv).[`final`](#final-2)

##### setAAD()

> **setAAD**(`buffer`: [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview)): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `buffer` | [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview) |

###### Returns

`this`

##### setAuthTag()

> **setAuthTag**(`buffer`: [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview)): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `buffer` | [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview) |

###### Returns

`this`

##### update()

> **update**(`data`: [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview)): [`Buffer`](../llrt/buffer.md#buffer)

Updates the decipher with `data`.

The `decipher.update()` method can be called multiple times with new data until `decipher.final()` is called. Calling `decipher.update()` after `decipher.final()` will result in an error
being thrown.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `data` | [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview) |

###### Returns

[`Buffer`](../llrt/buffer.md#buffer)

###### Inherited from

[`Decipheriv`](#decipheriv).[`update`](#update-2)

## Type Aliases

### BinaryLike

> **BinaryLike** = `string` | [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview)

***

### BinaryToTextEncoding

> **BinaryToTextEncoding** = `"base64"` | `"hex"`

***

### CharacterEncoding

> **CharacterEncoding** = `"utf8"` | `"utf-8"` | `"utf16le"` | `"utf-16le"` | `"latin1"`

***

### CipherCCMTypes

> **CipherCCMTypes** = `"aes-128-ccm"` | `"aes-192-ccm"` | `"aes-256-ccm"`

***

### CipherChaCha20Poly1305Types

> **CipherChaCha20Poly1305Types** = `"chacha20-poly1305"`

***

### CipherGCMTypes

> **CipherGCMTypes** = `"aes-128-gcm"` | `"aes-192-gcm"` | `"aes-256-gcm"`

***

### CipherKey

> **CipherKey** = [`BinaryLike`](#binarylike)

***

### CipherOCBTypes

> **CipherOCBTypes** = `"aes-128-ocb"` | `"aes-192-ocb"` | `"aes-256-ocb"`

***

### Encoding

> **Encoding** = [`BinaryToTextEncoding`](#binarytotextencoding) | [`CharacterEncoding`](#characterencoding) | [`LegacyCharacterEncoding`](#legacycharacterencoding)

***

### LegacyCharacterEncoding

> **LegacyCharacterEncoding** = `"ascii"`

***

### UUID

> **UUID** = `` `${string}-${string}-${string}-${string}-${string}` ``

## Functions

### createCipheriv()

#### Call Signature

> **createCipheriv**(`algorithm`: [`CipherCCMTypes`](#cipherccmtypes), `key`: [`BinaryLike`](#binarylike), `iv`: [`BinaryLike`](#binarylike), `options`: [`CipherCCMOptions`](#cipherccmoptions)): [`Cipheriv`](#cipheriv)

Creates and returns a `Cipher` object, with the given `algorithm`, `key` and
initialization vector (`iv`).

The `options` argument controls stream behavior and is optional except when a
cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) is used. In that case, the`authTagLength` option is required and specifies the length of the
authentication tag in bytes, see `CCM mode`. In GCM mode, the `authTagLength`option is not required but can be used to set the length of the authentication
tag and defaults to 16 bytes.
For `chacha20-poly1305`, the `authTagLength` option defaults to 16 bytes.

The `key` is the raw key used by the `algorithm` and `iv` is an [initialization vector](https://en.wikipedia.org/wiki/Initialization_vector). Both arguments must be `'utf8'` encoded
strings,`Buffers`, `TypedArray`, or `DataView`s. The `key` may optionally be
a `KeyObject` of type `secret`. If the cipher does not need
an initialization vector, `iv` may be `null`.

When passing strings for `key` or `iv`, please consider `caveats when using strings as inputs to cryptographic APIs`.

Initialization vectors should be unpredictable and unique; ideally, they will be
cryptographically random. They do not have to be secret: IVs are typically just
added to ciphertext messages unencrypted. It may sound contradictory that
something has to be unpredictable and unique, but does not have to be secret;
remember that an attacker must not be able to predict ahead of time what a
given IV will be.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `algorithm` | [`CipherCCMTypes`](#cipherccmtypes) |
| `key` | [`BinaryLike`](#binarylike) |
| `iv` | [`BinaryLike`](#binarylike) |
| `options` | [`CipherCCMOptions`](#cipherccmoptions) |

##### Returns

[`Cipheriv`](#cipheriv)

#### Call Signature

> **createCipheriv**(`algorithm`: [`CipherOCBTypes`](#cipherocbtypes), `key`: [`BinaryLike`](#binarylike), `iv`: [`BinaryLike`](#binarylike), `options`: [`CipherOCBOptions`](#cipherocboptions)): [`CipherOCB`](#cipherocb)

Creates and returns a `Cipher` object, with the given `algorithm`, `key` and
initialization vector (`iv`).

The `options` argument controls stream behavior and is optional except when a
cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) is used. In that case, the`authTagLength` option is required and specifies the length of the
authentication tag in bytes, see `CCM mode`. In GCM mode, the `authTagLength`option is not required but can be used to set the length of the authentication
tag and defaults to 16 bytes.
For `chacha20-poly1305`, the `authTagLength` option defaults to 16 bytes.

The `key` is the raw key used by the `algorithm` and `iv` is an [initialization vector](https://en.wikipedia.org/wiki/Initialization_vector). Both arguments must be `'utf8'` encoded
strings,`Buffers`, `TypedArray`, or `DataView`s. The `key` may optionally be
a `KeyObject` of type `secret`. If the cipher does not need
an initialization vector, `iv` may be `null`.

When passing strings for `key` or `iv`, please consider `caveats when using strings as inputs to cryptographic APIs`.

Initialization vectors should be unpredictable and unique; ideally, they will be
cryptographically random. They do not have to be secret: IVs are typically just
added to ciphertext messages unencrypted. It may sound contradictory that
something has to be unpredictable and unique, but does not have to be secret;
remember that an attacker must not be able to predict ahead of time what a
given IV will be.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `algorithm` | [`CipherOCBTypes`](#cipherocbtypes) |
| `key` | [`BinaryLike`](#binarylike) |
| `iv` | [`BinaryLike`](#binarylike) |
| `options` | [`CipherOCBOptions`](#cipherocboptions) |

##### Returns

[`CipherOCB`](#cipherocb)

#### Call Signature

> **createCipheriv**(`algorithm`: [`CipherGCMTypes`](#ciphergcmtypes), `key`: [`BinaryLike`](#binarylike), `iv`: [`BinaryLike`](#binarylike), `options?`: [`CipherGCMOptions`](#ciphergcmoptions)): [`CipherGCM`](#ciphergcm)

Creates and returns a `Cipher` object, with the given `algorithm`, `key` and
initialization vector (`iv`).

The `options` argument controls stream behavior and is optional except when a
cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) is used. In that case, the`authTagLength` option is required and specifies the length of the
authentication tag in bytes, see `CCM mode`. In GCM mode, the `authTagLength`option is not required but can be used to set the length of the authentication
tag and defaults to 16 bytes.
For `chacha20-poly1305`, the `authTagLength` option defaults to 16 bytes.

The `key` is the raw key used by the `algorithm` and `iv` is an [initialization vector](https://en.wikipedia.org/wiki/Initialization_vector). Both arguments must be `'utf8'` encoded
strings,`Buffers`, `TypedArray`, or `DataView`s. The `key` may optionally be
a `KeyObject` of type `secret`. If the cipher does not need
an initialization vector, `iv` may be `null`.

When passing strings for `key` or `iv`, please consider `caveats when using strings as inputs to cryptographic APIs`.

Initialization vectors should be unpredictable and unique; ideally, they will be
cryptographically random. They do not have to be secret: IVs are typically just
added to ciphertext messages unencrypted. It may sound contradictory that
something has to be unpredictable and unique, but does not have to be secret;
remember that an attacker must not be able to predict ahead of time what a
given IV will be.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `algorithm` | [`CipherGCMTypes`](#ciphergcmtypes) |
| `key` | [`BinaryLike`](#binarylike) |
| `iv` | [`BinaryLike`](#binarylike) |
| `options?` | [`CipherGCMOptions`](#ciphergcmoptions) |

##### Returns

[`CipherGCM`](#ciphergcm)

#### Call Signature

> **createCipheriv**(`algorithm`: `"chacha20-poly1305"`, `key`: [`BinaryLike`](#binarylike), `iv`: [`BinaryLike`](#binarylike), `options?`: [`CipherChaCha20Poly1305Options`](#cipherchacha20poly1305options)): [`CipherChaCha20Poly1305`](#cipherchacha20poly1305)

Creates and returns a `Cipher` object, with the given `algorithm`, `key` and
initialization vector (`iv`).

The `options` argument controls stream behavior and is optional except when a
cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) is used. In that case, the`authTagLength` option is required and specifies the length of the
authentication tag in bytes, see `CCM mode`. In GCM mode, the `authTagLength`option is not required but can be used to set the length of the authentication
tag and defaults to 16 bytes.
For `chacha20-poly1305`, the `authTagLength` option defaults to 16 bytes.

The `key` is the raw key used by the `algorithm` and `iv` is an [initialization vector](https://en.wikipedia.org/wiki/Initialization_vector). Both arguments must be `'utf8'` encoded
strings,`Buffers`, `TypedArray`, or `DataView`s. The `key` may optionally be
a `KeyObject` of type `secret`. If the cipher does not need
an initialization vector, `iv` may be `null`.

When passing strings for `key` or `iv`, please consider `caveats when using strings as inputs to cryptographic APIs`.

Initialization vectors should be unpredictable and unique; ideally, they will be
cryptographically random. They do not have to be secret: IVs are typically just
added to ciphertext messages unencrypted. It may sound contradictory that
something has to be unpredictable and unique, but does not have to be secret;
remember that an attacker must not be able to predict ahead of time what a
given IV will be.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `algorithm` | `"chacha20-poly1305"` |
| `key` | [`BinaryLike`](#binarylike) |
| `iv` | [`BinaryLike`](#binarylike) |
| `options?` | [`CipherChaCha20Poly1305Options`](#cipherchacha20poly1305options) |

##### Returns

[`CipherChaCha20Poly1305`](#cipherchacha20poly1305)

#### Call Signature

> **createCipheriv**(`algorithm`: `string`, `key`: [`BinaryLike`](#binarylike), `iv`: [`BinaryLike`](#binarylike) | `null`): [`Cipheriv`](#cipheriv)

Creates and returns a `Cipher` object, with the given `algorithm`, `key` and
initialization vector (`iv`).

The `options` argument controls stream behavior and is optional except when a
cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) is used. In that case, the`authTagLength` option is required and specifies the length of the
authentication tag in bytes, see `CCM mode`. In GCM mode, the `authTagLength`option is not required but can be used to set the length of the authentication
tag and defaults to 16 bytes.
For `chacha20-poly1305`, the `authTagLength` option defaults to 16 bytes.

The `key` is the raw key used by the `algorithm` and `iv` is an [initialization vector](https://en.wikipedia.org/wiki/Initialization_vector). Both arguments must be `'utf8'` encoded
strings,`Buffers`, `TypedArray`, or `DataView`s. The `key` may optionally be
a `KeyObject` of type `secret`. If the cipher does not need
an initialization vector, `iv` may be `null`.

When passing strings for `key` or `iv`, please consider `caveats when using strings as inputs to cryptographic APIs`.

Initialization vectors should be unpredictable and unique; ideally, they will be
cryptographically random. They do not have to be secret: IVs are typically just
added to ciphertext messages unencrypted. It may sound contradictory that
something has to be unpredictable and unique, but does not have to be secret;
remember that an attacker must not be able to predict ahead of time what a
given IV will be.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `algorithm` | `string` |
| `key` | [`BinaryLike`](#binarylike) |
| `iv` | [`BinaryLike`](#binarylike) | `null` |

##### Returns

[`Cipheriv`](#cipheriv)

***

### createDecipheriv()

#### Call Signature

> **createDecipheriv**(`algorithm`: [`CipherCCMTypes`](#cipherccmtypes), `key`: [`BinaryLike`](#binarylike), `iv`: [`BinaryLike`](#binarylike), `options`: [`CipherCCMOptions`](#cipherccmoptions)): [`DecipherCCM`](#decipherccm)

Creates and returns a `Decipheriv` object that uses the given `algorithm`, `key` and initialization vector (`iv`).

The `options` argument controls stream behavior and is optional except when a
cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) is used. In that case, the `authTagLength` option is required and specifies the length of the
authentication tag in bytes, see `CCM mode`. In GCM mode, the `authTagLength` option is not required but can be used to restrict accepted authentication tags
to those with the specified length.
For `chacha20-poly1305`, the `authTagLength` option defaults to 16 bytes.

The `key` is the raw key used by the `algorithm` and `iv` is an [initialization vector](https://en.wikipedia.org/wiki/Initialization_vector). Both arguments must be `'utf8'` encoded
strings,`Buffers`, `TypedArray`, or `DataView`s. The `key` may optionally be
a `KeyObject` of type `secret`. If the cipher does not need
an initialization vector, `iv` may be `null`.

When passing strings for `key` or `iv`, please consider `caveats when using strings as inputs to cryptographic APIs`.

Initialization vectors should be unpredictable and unique; ideally, they will be
cryptographically random. They do not have to be secret: IVs are typically just
added to ciphertext messages unencrypted. It may sound contradictory that
something has to be unpredictable and unique, but does not have to be secret;
remember that an attacker must not be able to predict ahead of time what a given
IV will be.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `algorithm` | [`CipherCCMTypes`](#cipherccmtypes) |
| `key` | [`BinaryLike`](#binarylike) |
| `iv` | [`BinaryLike`](#binarylike) |
| `options` | [`CipherCCMOptions`](#cipherccmoptions) |

##### Returns

[`DecipherCCM`](#decipherccm)

#### Call Signature

> **createDecipheriv**(`algorithm`: [`CipherOCBTypes`](#cipherocbtypes), `key`: [`BinaryLike`](#binarylike), `iv`: [`BinaryLike`](#binarylike), `options`: [`CipherOCBOptions`](#cipherocboptions)): [`DecipherOCB`](#decipherocb)

Creates and returns a `Decipheriv` object that uses the given `algorithm`, `key` and initialization vector (`iv`).

The `options` argument controls stream behavior and is optional except when a
cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) is used. In that case, the `authTagLength` option is required and specifies the length of the
authentication tag in bytes, see `CCM mode`. In GCM mode, the `authTagLength` option is not required but can be used to restrict accepted authentication tags
to those with the specified length.
For `chacha20-poly1305`, the `authTagLength` option defaults to 16 bytes.

The `key` is the raw key used by the `algorithm` and `iv` is an [initialization vector](https://en.wikipedia.org/wiki/Initialization_vector). Both arguments must be `'utf8'` encoded
strings,`Buffers`, `TypedArray`, or `DataView`s. The `key` may optionally be
a `KeyObject` of type `secret`. If the cipher does not need
an initialization vector, `iv` may be `null`.

When passing strings for `key` or `iv`, please consider `caveats when using strings as inputs to cryptographic APIs`.

Initialization vectors should be unpredictable and unique; ideally, they will be
cryptographically random. They do not have to be secret: IVs are typically just
added to ciphertext messages unencrypted. It may sound contradictory that
something has to be unpredictable and unique, but does not have to be secret;
remember that an attacker must not be able to predict ahead of time what a given
IV will be.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `algorithm` | [`CipherOCBTypes`](#cipherocbtypes) |
| `key` | [`BinaryLike`](#binarylike) |
| `iv` | [`BinaryLike`](#binarylike) |
| `options` | [`CipherOCBOptions`](#cipherocboptions) |

##### Returns

[`DecipherOCB`](#decipherocb)

#### Call Signature

> **createDecipheriv**(`algorithm`: [`CipherGCMTypes`](#ciphergcmtypes), `key`: [`BinaryLike`](#binarylike), `iv`: [`BinaryLike`](#binarylike), `options?`: [`CipherGCMOptions`](#ciphergcmoptions)): [`DecipherGCM`](#deciphergcm)

Creates and returns a `Decipheriv` object that uses the given `algorithm`, `key` and initialization vector (`iv`).

The `options` argument controls stream behavior and is optional except when a
cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) is used. In that case, the `authTagLength` option is required and specifies the length of the
authentication tag in bytes, see `CCM mode`. In GCM mode, the `authTagLength` option is not required but can be used to restrict accepted authentication tags
to those with the specified length.
For `chacha20-poly1305`, the `authTagLength` option defaults to 16 bytes.

The `key` is the raw key used by the `algorithm` and `iv` is an [initialization vector](https://en.wikipedia.org/wiki/Initialization_vector). Both arguments must be `'utf8'` encoded
strings,`Buffers`, `TypedArray`, or `DataView`s. The `key` may optionally be
a `KeyObject` of type `secret`. If the cipher does not need
an initialization vector, `iv` may be `null`.

When passing strings for `key` or `iv`, please consider `caveats when using strings as inputs to cryptographic APIs`.

Initialization vectors should be unpredictable and unique; ideally, they will be
cryptographically random. They do not have to be secret: IVs are typically just
added to ciphertext messages unencrypted. It may sound contradictory that
something has to be unpredictable and unique, but does not have to be secret;
remember that an attacker must not be able to predict ahead of time what a given
IV will be.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `algorithm` | [`CipherGCMTypes`](#ciphergcmtypes) |
| `key` | [`BinaryLike`](#binarylike) |
| `iv` | [`BinaryLike`](#binarylike) |
| `options?` | [`CipherGCMOptions`](#ciphergcmoptions) |

##### Returns

[`DecipherGCM`](#deciphergcm)

#### Call Signature

> **createDecipheriv**(`algorithm`: `"chacha20-poly1305"`, `key`: [`BinaryLike`](#binarylike), `iv`: [`BinaryLike`](#binarylike), `options?`: [`CipherChaCha20Poly1305Options`](#cipherchacha20poly1305options)): [`DecipherChaCha20Poly1305`](#decipherchacha20poly1305)

Creates and returns a `Decipheriv` object that uses the given `algorithm`, `key` and initialization vector (`iv`).

The `options` argument controls stream behavior and is optional except when a
cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) is used. In that case, the `authTagLength` option is required and specifies the length of the
authentication tag in bytes, see `CCM mode`. In GCM mode, the `authTagLength` option is not required but can be used to restrict accepted authentication tags
to those with the specified length.
For `chacha20-poly1305`, the `authTagLength` option defaults to 16 bytes.

The `key` is the raw key used by the `algorithm` and `iv` is an [initialization vector](https://en.wikipedia.org/wiki/Initialization_vector). Both arguments must be `'utf8'` encoded
strings,`Buffers`, `TypedArray`, or `DataView`s. The `key` may optionally be
a `KeyObject` of type `secret`. If the cipher does not need
an initialization vector, `iv` may be `null`.

When passing strings for `key` or `iv`, please consider `caveats when using strings as inputs to cryptographic APIs`.

Initialization vectors should be unpredictable and unique; ideally, they will be
cryptographically random. They do not have to be secret: IVs are typically just
added to ciphertext messages unencrypted. It may sound contradictory that
something has to be unpredictable and unique, but does not have to be secret;
remember that an attacker must not be able to predict ahead of time what a given
IV will be.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `algorithm` | `"chacha20-poly1305"` |
| `key` | [`BinaryLike`](#binarylike) |
| `iv` | [`BinaryLike`](#binarylike) |
| `options?` | [`CipherChaCha20Poly1305Options`](#cipherchacha20poly1305options) |

##### Returns

[`DecipherChaCha20Poly1305`](#decipherchacha20poly1305)

#### Call Signature

> **createDecipheriv**(`algorithm`: `string`, `key`: [`BinaryLike`](#binarylike), `iv`: [`BinaryLike`](#binarylike) | `null`): [`Decipheriv`](#decipheriv)

Creates and returns a `Decipheriv` object that uses the given `algorithm`, `key` and initialization vector (`iv`).

The `options` argument controls stream behavior and is optional except when a
cipher in CCM or OCB mode (e.g. `'aes-128-ccm'`) is used. In that case, the `authTagLength` option is required and specifies the length of the
authentication tag in bytes, see `CCM mode`. In GCM mode, the `authTagLength` option is not required but can be used to restrict accepted authentication tags
to those with the specified length.
For `chacha20-poly1305`, the `authTagLength` option defaults to 16 bytes.

The `key` is the raw key used by the `algorithm` and `iv` is an [initialization vector](https://en.wikipedia.org/wiki/Initialization_vector). Both arguments must be `'utf8'` encoded
strings,`Buffers`, `TypedArray`, or `DataView`s. The `key` may optionally be
a `KeyObject` of type `secret`. If the cipher does not need
an initialization vector, `iv` may be `null`.

When passing strings for `key` or `iv`, please consider `caveats when using strings as inputs to cryptographic APIs`.

Initialization vectors should be unpredictable and unique; ideally, they will be
cryptographically random. They do not have to be secret: IVs are typically just
added to ciphertext messages unencrypted. It may sound contradictory that
something has to be unpredictable and unique, but does not have to be secret;
remember that an attacker must not be able to predict ahead of time what a given
IV will be.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `algorithm` | `string` |
| `key` | [`BinaryLike`](#binarylike) |
| `iv` | [`BinaryLike`](#binarylike) | `null` |

##### Returns

[`Decipheriv`](#decipheriv)

***

### createHash()

> **createHash**(`algorithm`: `string`): [`Hash`](#hash)

Creates and returns a `Hash` object that can be used to generate hash digests
using the given `algorithm`.

The `algorithm` is supported by `'md4'`, `'md5'`, `'sha1'`, `'sha256'`,`'sha384'` and `'sha512'`.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `algorithm` | `string` |

#### Returns

[`Hash`](#hash)

***

### createHmac()

> **createHmac**(`algorithm`: `string`, `key`: [`BinaryLike`](#binarylike)): [`Hmac`](#hmac)

Creates and returns an `Hmac` object that uses the given `algorithm` and `key`.

The `algorithm` is supported by `'md4'`, `'md5'`, `'sha1'`, `'sha256'`,`'sha384'` and `'sha512'`.

The `key` is the HMAC key used to generate the cryptographic HMAC hash.
If it is a string, please consider `caveats when using strings as inputs to cryptographic APIs`.
If it was obtained from a cryptographically secure source of entropy, such as [randomBytes](#randombytes)
or generateKey, its length should not exceed the block size of `algorithm`
(e.g., 512 bits for SHA-256).

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `algorithm` | `string` |
| `key` | [`BinaryLike`](#binarylike) |

#### Returns

[`Hmac`](#hmac)

***

### getRandomValues()

> **getRandomValues**<`T`>(`typedArray`: `T`): `T`

A convenient alias for webcrypto.getRandomValues. This
implementation is not compliant with the Web Crypto spec, to write
web-compatible code use webcrypto.getRandomValues instead.

#### Type Parameters

| Type Parameter |
| ------ |
| `T` *extends* [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview) |

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `typedArray` | `T` |

#### Returns

`T`

Returns `typedArray`.

***

### randomBytes()

> **randomBytes**(`size`: `number`): [`Buffer`](../llrt/buffer.md#buffer)

Generates cryptographically strong pseudorandom data. The `size` argument
is a number indicating the number of bytes to generate.

the random bytes are generated synchronously and returned as a `Buffer`.
An error will be thrown if there is a problem generating the bytes.

```js
// Synchronous
import { randomBytes } from 'crypto';

const buf = randomBytes(256);
console.log(
  `${buf.length} bytes of random data: ${buf.toString('hex')}`);
```

The `crypto.randomBytes()` method will not complete until there is
sufficient entropy available.
This should normally never take longer than a few milliseconds. The only time
when generating the random bytes may conceivably block for a longer period of
time is right after boot, when the whole system is still low on entropy.

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `size` | `number` | The number of bytes to generate. The `size` must not be larger than `2**31 - 1`. |

#### Returns

[`Buffer`](../llrt/buffer.md#buffer)

***

### randomFill()

#### Call Signature

> **randomFill**<`T`>(`buffer`: `T`, `callback`: (`err`: `Error` | `null`, `buf`: `T`) => `void`): `void`

This function is similar to [randomBytes](#randombytes) but requires the first
argument to be a `Buffer` that will be filled. It also
requires that a callback is passed in.

If the `callback` function is not provided, an error will be thrown.

```js
import { Buffer } from 'buffer';
import { randomFill } from 'crypto';

const buf = Buffer.alloc(10);
randomFill(buf, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});

randomFill(buf, 5, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});

// The above is equivalent to the following:
randomFill(buf, 5, 5, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});
```

Any `ArrayBuffer`, `TypedArray`, or `DataView` instance may be passed as `buffer`.

While this includes instances of `Float32Array` and `Float64Array`, this
function should not be used to generate random floating-point numbers. The
result may contain `+Infinity`, `-Infinity`, and `NaN`, and even if the array
contains finite numbers only, they are not drawn from a uniform random
distribution and have no meaningful lower or upper bounds.

```js
import { Buffer } from 'buffer';
import { randomFill } from 'crypto';

const a = new Uint32Array(10);
randomFill(a, (err, buf) => {
  if (err) throw err;
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength)
    .toString('hex'));
});

const b = new DataView(new ArrayBuffer(10));
randomFill(b, (err, buf) => {
  if (err) throw err;
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength)
    .toString('hex'));
});

const c = new ArrayBuffer(10);
randomFill(c, (err, buf) => {
  if (err) throw err;
  console.log(Buffer.from(buf).toString('hex'));
});
```

##### Type Parameters

| Type Parameter |
| ------ |
| `T` *extends* [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview) |

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `buffer` | `T` | Must be supplied. The size of the provided `buffer` must not be larger than `2**31 - 1`. |
| `callback` | (`err`: `Error` | `null`, `buf`: `T`) => `void` | `function(err, buf) {}`. |

##### Returns

`void`

#### Call Signature

> **randomFill**<`T`>(`buffer`: `T`, `offset`: `number`, `callback`: (`err`: `Error` | `null`, `buf`: `T`) => `void`): `void`

This function is similar to [randomBytes](#randombytes) but requires the first
argument to be a `Buffer` that will be filled. It also
requires that a callback is passed in.

If the `callback` function is not provided, an error will be thrown.

```js
import { Buffer } from 'buffer';
import { randomFill } from 'crypto';

const buf = Buffer.alloc(10);
randomFill(buf, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});

randomFill(buf, 5, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});

// The above is equivalent to the following:
randomFill(buf, 5, 5, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});
```

Any `ArrayBuffer`, `TypedArray`, or `DataView` instance may be passed as `buffer`.

While this includes instances of `Float32Array` and `Float64Array`, this
function should not be used to generate random floating-point numbers. The
result may contain `+Infinity`, `-Infinity`, and `NaN`, and even if the array
contains finite numbers only, they are not drawn from a uniform random
distribution and have no meaningful lower or upper bounds.

```js
import { Buffer } from 'buffer';
import { randomFill } from 'crypto';

const a = new Uint32Array(10);
randomFill(a, (err, buf) => {
  if (err) throw err;
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength)
    .toString('hex'));
});

const b = new DataView(new ArrayBuffer(10));
randomFill(b, (err, buf) => {
  if (err) throw err;
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength)
    .toString('hex'));
});

const c = new ArrayBuffer(10);
randomFill(c, (err, buf) => {
  if (err) throw err;
  console.log(Buffer.from(buf).toString('hex'));
});
```

##### Type Parameters

| Type Parameter |
| ------ |
| `T` *extends* [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview) |

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `buffer` | `T` | Must be supplied. The size of the provided `buffer` must not be larger than `2**31 - 1`. |
| `offset` | `number` |  |
| `callback` | (`err`: `Error` | `null`, `buf`: `T`) => `void` | `function(err, buf) {}`. |

##### Returns

`void`

#### Call Signature

> **randomFill**<`T`>(`buffer`: `T`, `offset`: `number`, `size`: `number`, `callback`: (`err`: `Error` | `null`, `buf`: `T`) => `void`): `void`

This function is similar to [randomBytes](#randombytes) but requires the first
argument to be a `Buffer` that will be filled. It also
requires that a callback is passed in.

If the `callback` function is not provided, an error will be thrown.

```js
import { Buffer } from 'buffer';
import { randomFill } from 'crypto';

const buf = Buffer.alloc(10);
randomFill(buf, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});

randomFill(buf, 5, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});

// The above is equivalent to the following:
randomFill(buf, 5, 5, (err, buf) => {
  if (err) throw err;
  console.log(buf.toString('hex'));
});
```

Any `ArrayBuffer`, `TypedArray`, or `DataView` instance may be passed as `buffer`.

While this includes instances of `Float32Array` and `Float64Array`, this
function should not be used to generate random floating-point numbers. The
result may contain `+Infinity`, `-Infinity`, and `NaN`, and even if the array
contains finite numbers only, they are not drawn from a uniform random
distribution and have no meaningful lower or upper bounds.

```js
import { Buffer } from 'buffer';
import { randomFill } from 'crypto';

const a = new Uint32Array(10);
randomFill(a, (err, buf) => {
  if (err) throw err;
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength)
    .toString('hex'));
});

const b = new DataView(new ArrayBuffer(10));
randomFill(b, (err, buf) => {
  if (err) throw err;
  console.log(Buffer.from(buf.buffer, buf.byteOffset, buf.byteLength)
    .toString('hex'));
});

const c = new ArrayBuffer(10);
randomFill(c, (err, buf) => {
  if (err) throw err;
  console.log(Buffer.from(buf).toString('hex'));
});
```

##### Type Parameters

| Type Parameter |
| ------ |
| `T` *extends* [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview) |

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `buffer` | `T` | Must be supplied. The size of the provided `buffer` must not be larger than `2**31 - 1`. |
| `offset` | `number` |  |
| `size` | `number` |  |
| `callback` | (`err`: `Error` | `null`, `buf`: `T`) => `void` | `function(err, buf) {}`. |

##### Returns

`void`

***

### randomFillSync()

> **randomFillSync**<`T`>(`buffer`: `T`, `offset?`: `number`, `size?`: `number`): `T`

Synchronous version of [randomFill](#randomfill).

```js
import { Buffer } from 'buffer';
import { randomFillSync } from 'crypto';

const buf = Buffer.alloc(10);
console.log(randomFillSync(buf).toString('hex'));

randomFillSync(buf, 5);
console.log(buf.toString('hex'));

// The above is equivalent to the following:
randomFillSync(buf, 5, 5);
console.log(buf.toString('hex'));
```

Any `ArrayBuffer`, `TypedArray` or `DataView` instance may be passed as`buffer`.

```js
import { Buffer } from 'buffer';
import { randomFillSync } from 'crypto';

const a = new Uint32Array(10);
console.log(Buffer.from(randomFillSync(a).buffer,
                        a.byteOffset, a.byteLength).toString('hex'));

const b = new DataView(new ArrayBuffer(10));
console.log(Buffer.from(randomFillSync(b).buffer,
                        b.byteOffset, b.byteLength).toString('hex'));

const c = new ArrayBuffer(10);
console.log(Buffer.from(randomFillSync(c)).toString('hex'));
```

#### Type Parameters

| Type Parameter |
| ------ |
| `T` *extends* [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview) |

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `buffer` | `T` | Must be supplied. The size of the provided `buffer` must not be larger than `2**31 - 1`. |
| `offset?` | `number` |  |
| `size?` | `number` |  |

#### Returns

`T`

The object passed as `buffer` argument.

***

### randomInt()

#### Call Signature

> **randomInt**(`max`: `number`): `number`

Return a random integer `n` such that `min <= n < max`.  This
implementation avoids [modulo bias](https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle#Modulo_bias).

The range (`max - min`) must be less than 2\*\*48. `min` and `max` must
be [safe integers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger).

```js
// Synchronous
import { randomInt } from 'crypto';

const n = randomInt(3);
console.log(`Random number chosen from (0, 1, 2): ${n}`);
```

```js
// With `min` argument
import { randomInt } from 'crypto';

const n = randomInt(1, 7);
console.log(`The dice rolled: ${n}`);
```

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `max` | `number` | End of random range (exclusive). |

##### Returns

`number`

#### Call Signature

> **randomInt**(`min`: `number`, `max`: `number`): `number`

Return a random integer `n` such that `min <= n < max`.  This
implementation avoids [modulo bias](https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle#Modulo_bias).

The range (`max - min`) must be less than 2\*\*48. `min` and `max` must
be [safe integers](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger).

```js
// Synchronous
import { randomInt } from 'crypto';

const n = randomInt(3);
console.log(`Random number chosen from (0, 1, 2): ${n}`);
```

```js
// With `min` argument
import { randomInt } from 'crypto';

const n = randomInt(1, 7);
console.log(`The dice rolled: ${n}`);
```

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `min` | `number` | Start of random range (inclusive). |
| `max` | `number` | End of random range (exclusive). |

##### Returns

`number`

***

### randomUUID()

> **randomUUID**(): `` `${string}-${string}-${string}-${string}-${string}` ``

Generates a random [RFC 4122](https://www.rfc-editor.org/rfc/rfc4122.txt) version 4 UUID.
The UUID is generated using a cryptographic pseudorandom number generator.

#### Returns

`` `${string}-${string}-${string}-${string}-${string}` ``

---

---
url: /plugins/reference/modules/caido/http.md
---
[@caido/quickjs-types](../index.md) / caido/http

# caido/http

## Classes

### Blob

A [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) encapsulates immutable, raw data.

#### Extended by

* [`File`](#file)

#### Constructors

##### Constructor

> **new Blob**(`parts`: (`string` | [`Blob`](#blob) | `ArrayBuffer`)\[], `opts?`: [`BlobOpts`](#blobopts)): [`Blob`](#blob)

Creates a new `Blob` object containing a concatenation of the given sources.

{ArrayBuffer}, and {Blob} sources are copied into the 'Blob' and can therefore be
safely modified after the 'Blob' is created.

String sources are also copied into the `Blob`.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `parts` | (`string` | [`Blob`](#blob) | `ArrayBuffer`)\[] |
| `opts?` | [`BlobOpts`](#blobopts) |

###### Returns

[`Blob`](#blob)

#### Properties

##### size

> `readonly` **size**: `number`

The total size of the `Blob` in bytes.

##### type

> `readonly` **type**: `string`

The content-type of the `Blob`.

#### Methods

##### arrayBuffer()

> **arrayBuffer**(): `Promise`<`ArrayBuffer`>

Returns a promise that fulfills with an [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) containing a copy of
the `Blob` data.

###### Returns

`Promise`<`ArrayBuffer`>

##### bytes()

> **bytes**(): `Promise`<`Uint8Array`>

Returns a promise that resolves with an Uint8Array containing the contents of the Blob.

###### Returns

`Promise`<`Uint8Array`>

##### slice()

> **slice**(`start?`: `number`, `end?`: `number`, `type?`: `string`): [`Blob`](#blob)

Creates and returns a new `Blob` containing a subset of this `Blob` objects
data. The original `Blob` is not altered.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `start?` | `number` | The starting index. |
| `end?` | `number` | The ending index. |
| `type?` | `string` | The content-type for the new `Blob` |

###### Returns

[`Blob`](#blob)

##### text()

> **text**(): `Promise`<`string`>

Returns a promise that fulfills with the contents of the `Blob` decoded as a UTF-8 string.

###### Returns

`Promise`<`string`>

***

### File

A [`Blob`](https://developer.mozilla.org/en-US/docs/Web/API/Blob) encapsulates immutable, raw data.

#### Extends

* [`Blob`](#blob)

#### Constructors

##### Constructor

> **new File**(`data`: (`string` | [`Blob`](#blob) | `ArrayBuffer`)\[], `fileName`: `string`, `opts?`: [`FileOpts`](#fileopts)): [`File`](#file)

Returns a newly constructed File.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `data` | (`string` | [`Blob`](#blob) | `ArrayBuffer`)\[] |
| `fileName` | `string` |
| `opts?` | [`FileOpts`](#fileopts) |

###### Returns

[`File`](#file)

###### Overrides

[`Blob`](#blob).[`constructor`](#constructor)

#### Properties

##### lastModified

> `readonly` **lastModified**: `number`

The last modified date of the file as the number of milliseconds since the Unix epoch (January 1, 1970 at midnight).
Files without a known last modified date return the current date.

##### name

> `readonly` **name**: `string`

Name of the file referenced by the File object.

##### size

> `readonly` **size**: `number`

The total size of the `Blob` in bytes.

###### Inherited from

[`Blob`](#blob).[`size`](#size)

##### type

> `readonly` **type**: `string`

The content-type of the `Blob`.

###### Inherited from

[`Blob`](#blob).[`type`](#type)

#### Methods

##### arrayBuffer()

> **arrayBuffer**(): `Promise`<`ArrayBuffer`>

Returns a promise that fulfills with an [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) containing a copy of
the `Blob` data.

###### Returns

`Promise`<`ArrayBuffer`>

###### Inherited from

[`Blob`](#blob).[`arrayBuffer`](#arraybuffer)

##### bytes()

> **bytes**(): `Promise`<`Uint8Array`>

Returns a promise that resolves with an Uint8Array containing the contents of the Blob.

###### Returns

`Promise`<`Uint8Array`>

###### Inherited from

[`Blob`](#blob).[`bytes`](#bytes)

##### slice()

> **slice**(`start?`: `number`, `end?`: `number`, `type?`: `string`): [`Blob`](#blob)

Creates and returns a new `Blob` containing a subset of this `Blob` objects
data. The original `Blob` is not altered.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `start?` | `number` | The starting index. |
| `end?` | `number` | The ending index. |
| `type?` | `string` | The content-type for the new `Blob` |

###### Returns

[`Blob`](#blob)

###### Inherited from

[`Blob`](#blob).[`slice`](#slice)

##### text()

> **text**(): `Promise`<`string`>

Returns a promise that fulfills with the contents of the `Blob` decoded as a UTF-8 string.

###### Returns

`Promise`<`string`>

###### Inherited from

[`Blob`](#blob).[`text`](#text)

***

### Headers

#### Implements

* `Iterable`<\[`string`, `string`]>

#### Constructors

##### Constructor

> **new Headers**(`opts?`: [`HeadersOpts`](#headersopts)): [`Headers`](#headers)

Creates a new Headers object.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `opts?` | [`HeadersOpts`](#headersopts) |

###### Returns

[`Headers`](#headers)

#### Properties

##### \[iterator]\()

> `readonly` **\[iterator]**: () => `Iterator`<\[`string`, `string`]>

###### Returns

`Iterator`<\[`string`, `string`]>

###### Implementation of

`Iterable.[iterator]`

##### append()

> `readonly` **append**: (`name`: `string`, `value`: `string`) => `void`

Appends a new value onto an existing header inside a Headers object, or adds the header if it does not already exist.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |
| `value` | `string` |

###### Returns

`void`

##### delete()

> `readonly` **delete**: (`name`: `string`) => `void`

Deletes a header from a Headers object.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |

###### Returns

`void`

##### entries()

> `readonly` **entries**: () => `IterableIterator`<\[`string`, `string`]>

Returns an iterator allowing to go through all key/value pairs contained in this object.

###### Returns

`IterableIterator`<\[`string`, `string`]>

##### forEach()

> `readonly` **forEach**: (`callbackfn`: (`value`: `string`, `key`: `string`) => `void`) => `void`

Executes a provided function once for each key/value pair in this Headers object.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `callbackfn` | (`value`: `string`, `key`: `string`) => `void` |

###### Returns

`void`

##### get()

> `readonly` **get**: (`name`: `string`) => `string` | `null`

A String sequence representing the values of the retrieved header or null if this header is not set.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |

###### Returns

`string` | `null`

##### getSetCookie()

> `readonly` **getSetCookie**: () => `string`\[]

Returns an array containing the values of all Set-Cookie headers associated with a response.

###### Returns

`string`\[]

##### has()

> `readonly` **has**: (`name`: `string`) => `boolean`

Returns a boolean stating whether a Headers object contains a certain header.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |

###### Returns

`boolean`

##### keys()

> `readonly` **keys**: () => `IterableIterator`<`string`>

Returns an iterator allowing you to go through all keys of the key/value pairs contained in this object.

###### Returns

`IterableIterator`<`string`>

##### set()

> `readonly` **set**: (`name`: `string`, `value`: `string`) => `void`

Sets a new value for an existing header inside a Headers object, or adds the header if it does not already exist.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |
| `value` | `string` |

###### Returns

`void`

##### values()

> `readonly` **values**: () => `IterableIterator`<`string`>

Returns an iterator allowing you to go through all values of the key/value pairs contained in this object.

###### Returns

`IterableIterator`<`string`>

***

### Request

The Request interface of the Fetch API represents a resource request.

#### Constructors

##### Constructor

> **new Request**(`input`: `string` | [`Request`](#request), `init?`: [`RequestOpts`](#requestopts)): [`Request`](#request)

Creates a new Request object.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | `string` | [`Request`](#request) |
| `init?` | [`RequestOpts`](#requestopts) |

###### Returns

[`Request`](#request)

#### Properties

##### arrayBuffer()

> `readonly` **arrayBuffer**: () => `Promise`<`ArrayBuffer`>

Returns a promise that resolves with an ArrayBuffer representation of the request body.

###### Returns

`Promise`<`ArrayBuffer`>

##### blob()

> `readonly` **blob**: () => `Promise`<[`Blob`](#blob)>

Returns a promise that resolves with a [Blob](#blob) representation of the request body.

###### Returns

`Promise`<[`Blob`](#blob)>

##### body

> `readonly` **body**: [`Body`](#body-3)

The body content.

##### bodyUsed

> `readonly` **bodyUsed**: `boolean`

Stores true or false to indicate whether or not the body has been used in a request yet.

##### bytes()

> `readonly` **bytes**: () => `Promise`<`Uint8Array`>

Returns a promise that resolves with a Uint8Array representation of the request body.

###### Returns

`Promise`<`Uint8Array`>

##### cache

> `readonly` **cache**: `"no-cache"`

Contains the cache mode of the request

##### clone()

> `readonly` **clone**: () => [`Request`](#request)

Creates a copy of the current [Request](#request) object.

###### Returns

[`Request`](#request)

##### headers

> `readonly` **headers**: [`Headers`](#headers)

Contains the associated Headers object of the request.

##### json()

> `readonly` **json**: () => `Promise`<`unknown`>

Returns a promise that resolves with the result of parsing the request body as JSON.

###### Returns

`Promise`<`unknown`>

##### keepalive

> `readonly` **keepalive**: `boolean`

Contains the request's keepalive setting (true or false), which indicates whether llrt will
keep the associated connection alive.

##### method

> `readonly` **method**: `string`

Contains the request's method (GET, POST, etc.)

##### mode

> `readonly` **mode**: `"navigate"`

Contains the mode of the request

##### signal

> `readonly` **signal**: [`AbortSignal`](../llrt/abort.md#abortsignal)

Returns the [AbortSignal](../llrt/abort.md#abortsignal) associated with the request

##### text()

> `readonly` **text**: () => `Promise`<`string`>

Returns a promise that resolves with a text representation of the request body.

###### Returns

`Promise`<`string`>

##### url

> `readonly` **url**: `string`

Contains the URL of the request.

***

### Response

The Response interface of the Fetch API represents the response to a request.

#### Constructors

##### Constructor

> **new Response**(`body?`: [`Body`](#body-3), `opts?`: [`ResponseOpts`](#responseopts)): [`Response`](#response)

Creates a new Response object.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `body?` | [`Body`](#body-3) |
| `opts?` | [`ResponseOpts`](#responseopts) |

###### Returns

[`Response`](#response)

#### Properties

##### arrayBuffer()

> `readonly` **arrayBuffer**: () => `Promise`<`ArrayBuffer`>

Returns a promise that resolves with an ArrayBuffer representation of the response body.

###### Returns

`Promise`<`ArrayBuffer`>

##### blob()

> `readonly` **blob**: () => `Promise`<[`Blob`](#blob)>

Returns a promise that resolves with a [Blob](#blob) representation of the response body.

###### Returns

`Promise`<[`Blob`](#blob)>

##### body

> `readonly` **body**: `null`

The body content (NOT IMPLEMENTED YET).

##### bodyUsed

> `readonly` **bodyUsed**: `boolean`

Stores a boolean value that declares whether the body has been used in a response yet.

##### clone()

> `readonly` **clone**: () => [`Response`](#response)

Creates a clone of a [Response](#response) object.

###### Returns

[`Response`](#response)

##### headers

> `readonly` **headers**: [`Headers`](#headers)

The [Headers](#headers) object associated with the response.

##### json()

> `readonly` **json**: () => `Promise`<`unknown`>

Returns a promise that resolves with the result of parsing the response body text as JSON.

###### Returns

`Promise`<`unknown`>

##### ok

> `readonly` **ok**: `boolean`

A boolean indicating whether the response was successful (status in the range 200 – 299) or not.

##### redirected

> `readonly` **redirected**: `boolean`

Indicates whether or not the response is the result of a redirect (that is, its URL list has more than one entry).

##### status

> `readonly` **status**: `number`

The status code of the response. (This will be 200 for a success).

##### statusText

> `readonly` **statusText**: `string`

The status message corresponding to the status code. (e.g., OK for 200).

##### text()

> `readonly` **text**: () => `Promise`<`string`>

Returns a promise that resolves with a text representation of the response body.

###### Returns

`Promise`<`string`>

##### type

> `readonly` **type**: [`ResponseType`](#responsetype-1)

The type of the response.

##### url

> `readonly` **url**: `string`

#### Methods

##### error()

> `static` **error**(): [`Response`](#response)

Returns a new [Response](#response) object associated with a network error.

###### Returns

[`Response`](#response)

##### json()

> `static` **json**(`data`: `any`, `init?`: [`ResponseInit`](#responseinit)): [`Response`](#response)

Returns a new [Response](#response) object for returning the provided JSON encoded data.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `data` | `any` |
| `init?` | [`ResponseInit`](#responseinit) |

###### Returns

[`Response`](#response)

##### redirect()

> `static` **redirect**(`url`: `string`, `status?`: `number`): [`Response`](#response)

Returns a new [Response](#response) with a different URL.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `url` | `string` |
| `status?` | `number` |

###### Returns

[`Response`](#response)

## Interfaces

### BlobOpts

#### Extended by

* [`FileOpts`](#fileopts)

#### Properties

##### endings?

> `optional` **endings**: `"transparent"` | `"native"`

One of either `'transparent'` or `'native'`. When set to `'native'`, line endings in string source parts
will be converted to the platform native line-ending as specified by `import { EOL } from 'os'`.

##### type?

> `optional` **type**: `string`

The Blob content-type. The intent is for `type` to convey the MIME media type of the data,
however no validation of the type format is performed.

***

### FileOpts

#### Extends

* [`BlobOpts`](#blobopts)

#### Properties

##### endings?

> `optional` **endings**: `"transparent"` | `"native"`

One of either `'transparent'` or `'native'`. When set to `'native'`, line endings in string source parts
will be converted to the platform native line-ending as specified by `import { EOL } from 'os'`.

###### Inherited from

[`BlobOpts`](#blobopts).[`endings`](#endings)

##### lastModified?

> `optional` **lastModified**: `number`

The last modified date of the file as the number of milliseconds since the Unix epoch (January 1, 1970 at midnight).
Files without a known last modified date return the current date.

##### type?

> `optional` **type**: `string`

The Blob content-type. The intent is for `type` to convey the MIME media type of the data,
however no validation of the type format is performed.

###### Inherited from

[`BlobOpts`](#blobopts).[`type`](#type-3)

***

### RequestOpts

#### Properties

##### body?

> `optional` **body**: [`Blob`](#blob)

##### headers?

> `optional` **headers**: [`HeadersLike`](#headerslike)

##### method?

> `optional` **method**: `string`

##### signal?

> `optional` **signal**: [`AbortSignal`](../llrt/abort.md#abortsignal)

##### url?

> `optional` **url**: `string`

***

### ResponseInit

#### Extended by

* [`ResponseOpts`](#responseopts)

#### Properties

##### headers?

> `readonly` `optional` **headers**: [`HeadersLike`](#headerslike)

##### status?

> `readonly` `optional` **status**: `number`

##### statusText?

> `readonly` `optional` **statusText**: `string`

***

### ResponseOpts

#### Extends

* [`ResponseInit`](#responseinit)

#### Properties

##### headers?

> `readonly` `optional` **headers**: [`HeadersLike`](#headerslike)

###### Inherited from

[`ResponseInit`](#responseinit).[`headers`](#headers-4)

##### signal?

> `readonly` `optional` **signal**: [`AbortSignal`](../llrt/abort.md#abortsignal)

##### status?

> `readonly` `optional` **status**: `number`

###### Inherited from

[`ResponseInit`](#responseinit).[`status`](#status-1)

##### statusText?

> `readonly` `optional` **statusText**: `string`

###### Inherited from

[`ResponseInit`](#responseinit).[`statusText`](#statustext-1)

##### url?

> `readonly` `optional` **url**: `string`

## Type Aliases

### Body

> **Body** = [`ArrayBufferView`](../llrt/globals/namespaces/QuickJS.md#arraybufferview) | [`Blob`](#blob) | `null`

The `Body` of a [Response](#response) or [Request](#request).
Currently NOT a `ReadableStream`.

***

### HeadersLike

> **HeadersLike** = `Record`<`string`, `string`> | [`Headers`](#headers)

***

### HeadersOpts

> **HeadersOpts** = `string`\[]\[] | [`HeadersLike`](#headerslike)

***

### RequestCache

> **RequestCache** = `"no-cache"`

***

### RequestMode

> **RequestMode** = `"navigate"`

***

### ResponseType

> **ResponseType** = `"basic"` | `"error"`

## Functions

### fetch()

> **fetch**(`input`: `string` | [`Request`](#request), `init?`: [`RequestOpts`](#requestopts)): `Promise`<[`Response`](#response)>

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | `string` | [`Request`](#request) |
| `init?` | [`RequestOpts`](#requestopts) |

#### Returns

`Promise`<[`Response`](#response)>

---

---
url: /client-sdk/guides/call_function.md
---
# Call a Plugin Function

Once a plugin is installed, the Client SDK lets you invoke functions exposed by its backend over the network. This is useful for driving a plugin from a script, integrating it into a wider automation, or testing its behavior end-to-end.

This guide covers the explicit `callFunction()` form, which works for any installed plugin without extra setup. For fully typed direct calls (e.g. `pkg.getProviders()` instead of `pkg.callFunction({ name: "getProviders" })`), see the next guide on the npm spec packages.

::: info
A runnable version of this guide lives in the SDK repository at [`examples/functionCall`](https://github.com/caido/sdk-js/tree/main/packages/sdk-client/examples/functionCall). Function names exposed by a plugin (like `getProviders`, `createSession` for `quickssrf`) come from the plugin's own source. Look for `sdk.api.register("name", ...)` calls in the plugin's backend code or check its repository under [caido-community](https://github.com/caido-community).
:::

## Get the Plugin Handle

To call a function on an installed plugin, you first need its **package handle**. Use `client.plugin.pluginPackage()` to look up the installed plugin by its [manifest ID](./install_plugin.md#1-from-the-caido-store):

```ts
const pkg = await client.plugin.pluginPackage("quickssrf");
if (pkg === undefined) {
  throw new Error("quickssrf is not installed");
}
```

`pluginPackage()` returns `undefined` when no installed plugin matches the manifest ID, so always check the result before calling functions on it.

::: info
If you are installing the plugin in the same script, you can skip the lookup since `client.plugin.install()` returns the same handle directly.
:::

## Call a Function

Use `pkg.callFunction()` with a generic type for the return value. The function name is a string (the same name the backend used in `sdk.api.register()`), and arguments are passed as an array.

### Without Arguments

```ts
type Result<T> =
  | { kind: "Ok"; value: T }
  | { kind: "Error"; error: string };

type Provider = {
  id: string;
  name: string;
  kind: string;
  url: string;
  enabled: boolean;
};

const providers = await pkg.callFunction<Result<Provider[]>>({
  name: "getProviders",
});
```

### With Arguments

Pass positional arguments through the `arguments` array. They are JSON-serialized before being sent to the backend, so any JSON-compatible value is accepted.

```ts
type Session = {
  id: string;
  providerId: string;
  url: string;
  status: string;
};

const providerId = providers.value[0].id;

const session = await pkg.callFunction<Result<Session>>({
  name: "createSession",
  arguments: [providerId],
});
```

::: info
The return shape is defined entirely by the plugin. The `Result<T>` wrapper used above is a `quickssrf` convention, not a Caido SDK one. Other plugins return whatever shape they want, and you supply the matching TypeScript type as the generic parameter.
:::

## Multi-Backend Plugins

A package can ship more than one backend plugin. When that is the case, `callFunction()` needs to know which backend owns the function. Pass the `manifestId` of the target backend:

```ts
await pkg.callFunction({
  name: "myFunction",
  manifestId: "specific-backend",
  arguments: [],
});
```

If the package has only one backend, the `manifestId` field is optional and the SDK picks it automatically.

## Errors

`callFunction()` throws a `PluginFunctionCallError` when the backend returns an error response (for example, when the function name is not registered or the backend itself throws):

```ts
import { PluginFunctionCallError } from "@caido/sdk-client";

try {
  await pkg.callFunction({ name: "doesNotExist" });
} catch (error) {
  if (error instanceof PluginFunctionCallError) {
    console.error("Function call failed:", error.message);
  } else {
    throw error;
  }
}
```

Plugins that use a `Result`-style return value (like `quickssrf`) signal *functional* failures through the return shape rather than throwing, so the `try/catch` above only covers transport- and runtime-level errors.

## Examples

The script below looks up the installed `quickssrf` plugin, fetches its available providers, and creates a session against the first one.

### index.ts

```ts
import { Client } from "@caido/sdk-client";

type Result<T> =
  | { kind: "Ok"; value: T }
  | { kind: "Error"; error: string };

type Provider = {
  id: string;
  name: string;
  kind: string;
  url: string;
  enabled: boolean;
};

type Session = {
  id: string;
  providerId: string;
  url: string;
  status: string;
};

async function main() {
  const client = new Client({
    url: process.env["CAIDO_INSTANCE_URL"] ?? "http://localhost:8080",
    auth: {
      pat: process.env["CAIDO_PAT"]!,
      cache: { file: ".caido-token.json" },
    },
  });

  await client.connect();

  const pkg = await client.plugin.pluginPackage("quickssrf");
  if (pkg === undefined) {
    throw new Error("quickssrf is not installed");
  }

  const providers = await pkg.callFunction<Result<Provider[]>>({
    name: "getProviders",
  });
  if (providers.kind === "Error") {
    throw new Error(`getProviders failed: ${providers.error}`);
  }

  const firstProvider = providers.value[0];
  if (firstProvider === undefined) {
    throw new Error("No providers available");
  }

  const session = await pkg.callFunction<Result<Session>>({
    name: "createSession",
    arguments: [firstProvider.id],
  });
  if (session.kind === "Error") {
    throw new Error(`createSession failed: ${session.error}`);
  }

  console.log("Session URL:", session.value.url);
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});
```

Run it with:

```bash
export CAIDO_PAT=caido_xxxxx
npx tsx ./index.ts
```

A successful run prints:

```txt
[caido] Loaded token from cache
Session URL: https://oast.site/abcdef1234567890
```

---

---
url: /plugins/guides/rpc.md
---
# Call Custom Functions

When developing a plugin, there are two components to consider: the **frontend** and the **backend**.

In this guide, we'll cover how to create a custom endpoint in a backend plugin, and call it from a frontend plugin.

::: info
For additional documentation on the differences between a frontend and backend plugin - click [here](/plugins/concepts/package.md).
:::

## Registering an Endpoint

Let's start by creating an endpoint called `multiply` in our backend plugin.

`multiply` will take two numbers, output the result in the backend logs, as well as return the result. This endpoint will used by the frontend later on.

### /packages/backend/src/index.ts

```ts
import { SDK, DefineAPI } from "caido:plugin";

function multiply(sdk: SDK, a: number, b: number) {
    const result = a * b;
    sdk.console.log(`The product of the multiply call is: ${result}`);
    return result;
}

export type API = DefineAPI<{
    multiply: typeof multiply;
}>;

export function init(sdk: SDK<API>) {
    sdk.api.register("multiply", multiply);
}
```

### Script Breakdown

First, the necessary type aliases are imported. `SDK` is the interface used to interact with Caido. `DefineAPI` is used to structure the API: definining what methods or endpoints are available, the parameters those methods accept and what types of values they return.

```ts
import { SDK, DefineAPI } from "caido:plugin";
```

Next, the function is defined. The function takes three parameters: `sdk`, `a` and `b`. The `sdk` parameter is typed using the `SDK` alias to give the function access to its utilities. The `a` and `b` parameters are expected to be numbers as this function multiplies the two together.

```ts
function multiply(sdk: SDK, a: number, b: number) {
    const result = a * b;
    sdk.console.log(`The product of the multiply call is: ${result}`);
    return result;
}
```

Using the `DefineAPI` utility, we are stating what our API offers. In this case, the `multiply` function is available to be called. To ensure the function receives the expected parameter data types, `typeof` is used to link the `multiply` API call to the `multiply` function definition. This definition is stored in the type alias `API` and exported so it can be used in other files.

```ts
export type API = DefineAPI<{
    multiply: typeof multiply;
}>;
```

Next, we define a function that will run as soon as Caido loads the plugin. It extends upon the base `SDK` by adding the `<API>`. In order to register the function, we use the `sdk.api.register()` method which takes two parameters: a string name for the function and the function it refers to. We give the name `"multiply"` to the `multiply` function.

```ts
export function init(sdk: SDK<API>) {
    sdk.api.register("multiply", multiply);
}
```

## Calling the Endpoint

Now that we've created our endpoint in the backend plugin, we can call `multiply` from our frontend plugin.

### /packages/frontend/src/index.ts

```ts
import { Classic } from "@caido/primevue";
import PrimeVue from "primevue/config";
import { createApp } from "vue";

import type { Caido } from "@caido/sdk-frontend";
import type { API } from "../../backend/src/index.ts";

import App from "./views/App.vue";

export type CaidoSDK = Caido<API>;

export const init = (sdk: CaidoSDK) => {
  const app = createApp(App);
  
  app.provide("sdk", sdk);
  
  app.use(PrimeVue, {
    unstyled: true,
    pt: Classic,
  });

  const root = document.createElement("div");
  Object.assign(root.style, {
    height: "100%",
    width: "100%",
  });

  app.mount(root);

  sdk.navigation.addPage("/multiply-page", {
    body: root,
  });

  sdk.sidebar.registerItem("Multiply", "/multiply-page", {
    icon: "fas fa-calculator",
  });
};
```

### /packages/frontend/src/views/App.vue

```vue
<script setup lang="ts">
import Button from "primevue/button";
import InputNumber from "primevue/inputnumber";
import { inject, ref } from "vue";

import type { CaidoSDK } from "../index";

const sdk = inject<CaidoSDK>("sdk");

const inputA = ref(0);
const inputB = ref(0);
const result = ref<string>("Result will appear here.");

const calculate = async () => {
  if (!sdk) return;
  const value = await sdk.backend.multiply(inputA.value, inputB.value);
  result.value = `Result: ${value}`;
};
</script>

<template>
  <div class="h-full flex flex-col p-4 gap-4">
    <div class="flex flex-col gap-2">
      <label class="text-sm font-medium">First Number</label>
      <InputNumber v-model="inputA" inputClass="w-full" />
    </div>
    <div class="flex flex-col gap-2">
      <label class="text-sm font-medium">Second Number</label>
      <InputNumber v-model="inputB" inputClass="w-full" />
    </div>
    <Button label="Calculate" @click="calculate" />
    <p class="text-gray-400">{{ result }}</p>
  </div>
</template>
```

### Script Breakdown

The frontend setup imports the necessary type aliases and creates a Vue application. The `CaidoSDK` type alias extends the base `Caido` type with the `API` we defined in the backend.

```ts
import type { Caido } from "@caido/sdk-frontend";
import type { API } from "../../backend/src/index.ts";

export type CaidoSDK = Caido<API>;
```

The Vue app is created with PrimeVue configured using the Classic preset. The SDK is provided to all components using Vue's dependency injection system.

```ts
const app = createApp(App);
app.provide("sdk", sdk);
app.use(PrimeVue, { unstyled: true, pt: Classic });
```

The Vue component uses reactive refs for the input values and result. When the button is clicked, it calls `sdk.backend.multiply()` with the input values and updates the result display.

::: tip
For additional documentation on creating a page - click [here](/plugins/guides/page.md).
:::

## The Result

The entry to your Caido log file should resemble:

```txt
2024-11-05T13:26:13.528023Z  INFO plugin:5a758b74-e176-473f-a545-bdb452015b9a js|sdk: The product of the multiply call is: 15
```

---

---
url: /client-sdk/guides/graphql_direct.md
---
# Call GraphQL Directly

The high-level SDKs on `Client` (`client.request`, `client.finding`, `client.environment`, etc.) cover the most common operations against a Caido instance. When you need something the high-level SDKs do not expose, drop down to `client.graphql` and run your own queries, mutations, or subscriptions against Caido's GraphQL API directly.

:::: info
The `gql` template tag is not re-exported by the SDK. Install [`@urql/core`](https://www.npmjs.com/package/@urql/core) (the GraphQL client the SDK is built on) to get it:

::: code-group

```bash [pnpm]
pnpm add @urql/core
```

```bash [npm]
npm install @urql/core
```

```bash [yarn]
yarn add @urql/core
```

:::

Any tag that returns a `TypedDocumentNode` also works, such as `graphql-tag`.
::::

## Run a Query

To run a query, build a document with `gql` and pass it to `client.graphql.query()`. The first generic parameter types the response data:

```ts
import { gql } from "@urql/core";

const ViewerQuery = gql<{ viewer: { __typename: string; id: string } }>`
  query CustomViewer {
    viewer {
      __typename
      ... on CloudUser { id }
      ... on GuestUser { id }
      ... on ScriptUser { id }
    }
  }
`;

const result = await client.graphql.query(ViewerQuery);
console.log(result.viewer);
```

## Pass Variables

To parameterize a query, declare its variables with `$` syntax inside the document and pass them as the second argument to `query()`. The second generic parameter types the variable map:

```ts
const RequestQuery = gql<
  { request: { id: string; host: string; method: string; path: string } | null },
  { id: string }
>`
  query CustomRequest($id: ID!) {
    request(id: $id) {
      id
      host
      method
      path
    }
  }
`;

const result = await client.graphql.query(RequestQuery, { id: "1" });
console.log(result.request);
```

## Run a Mutation

Mutations use the same shape with `client.graphql.mutation()`:

```ts
const RenameMutation = gql<
  {
    renameReplaySessionCollection: {
      collection: { id: string; name: string } | null;
    };
  },
  { id: string; name: string }
>`
  mutation RenameCollection($id: ID!, $name: String!) {
    renameReplaySessionCollection(id: $id, name: $name) {
      collection { id name }
    }
  }
`;

const result = await client.graphql.mutation(RenameMutation, {
  id: "1",
  name: "Renamed via raw GraphQL",
});

console.log(result.renameReplaySessionCollection.collection);
```

## Subscribe to a Subscription

Subscriptions are exposed through `client.graphql.subscribe()` and return an `AsyncIterable` that yields each event as it arrives. Iterate with `for await` and `break` out of the loop to disconnect:

```ts
const NewRequests = gql<{
  createdRequest: {
    requestEdge: {
      cursor: string;
      node: { id: string; host: string; method: string; path: string };
    };
  };
}>`
  subscription NewRequests {
    createdRequest {
      requestEdge {
        cursor
        node { id host method path }
      }
    }
  }
`;

for await (const event of client.graphql.subscribe(NewRequests)) {
  const req = event.createdRequest.requestEdge.node;
  console.log(`New request: ${req.method} ${req.host}${req.path}`);
}
```

## Find Available Operations

Caido's GraphQL endpoint lives at `<instanceUrl>/graphql` and supports standard introspection. Point any GraphQL explorer (Apollo Studio, Insomnia, GraphiQL, etc.) at that URL with your access token in the `Authorization` header to browse the full schema, including every type, field, and input.

For TypeScript signatures, the SDK's source repository also ships generated bindings under [`packages/sdk-client/src/graphql/__generated__/`](https://github.com/caido/sdk-js/tree/main/packages/sdk-client/src/graphql) that mirror every operation the high-level SDKs use. They are useful as a reference for fragment shapes and required arguments.

## Errors

Raw GraphQL calls throw the same error types the high-level SDKs use:

* `NetworkUserError`: the request did not reach the server
* `OperationUserError`: the server rejected the query (invalid fields, type errors, missing arguments)
* `NoDataUserError`: the server accepted the query but returned no data

```ts
import { OperationUserError } from "@caido/sdk-client";

try {
  await client.graphql.query(RequestQuery, { id: "doesNotExist" });
} catch (error) {
  if (error instanceof OperationUserError) {
    console.error("GraphQL rejected the query:", error.message);
  } else {
    throw error;
  }
}
```

## Examples

The script below uses a raw query to fetch the authenticated user, replicating what `client.user.viewer()` does internally:

### index.ts

```ts
import { Client } from "@caido/sdk-client";
import { gql } from "@urql/core";

async function main() {
  const client = new Client({
    url: process.env["CAIDO_INSTANCE_URL"] ?? "http://localhost:8080",
    auth: {
      pat: process.env["CAIDO_PAT"]!,
      cache: { file: ".caido-token.json" },
    },
  });

  await client.connect();

  const ViewerQuery = gql<{ viewer: { __typename: string; id: string } }>`
    query CustomViewer {
      viewer {
        __typename
        ... on CloudUser { id }
        ... on GuestUser { id }
        ... on ScriptUser { id }
      }
    }
  `;

  const result = await client.graphql.query(ViewerQuery);
  console.log(
    `Authenticated as ${result.viewer.__typename} ${result.viewer.id}`,
  );
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});
```

Run it with:

```bash
export CAIDO_PAT=caido_xxxxx
npx tsx ./index.ts
```

A successful run prints:

```txt
[caido] Loaded token from cache
Authenticated as CloudUser 01JX49W2EBZBSVT8HBRXCDD8XB
```

---

---
url: /plugins/reference/sdks/frontend/certificate.md
---
# Certificate

### CertificatePageContext

> **CertificatePageContext** = `object`

Certificate page context.

#### Properties

##### kind

> **kind**: `"Certificate"`

---

---
url: /plugins/concepts/child_process.md
---
# Child Process

Caido plugins offer a `child_process` module similiar to NodeJS's `child_process` module. This allows you to spawn child processes from your code, with some limitations.

This page will cover the differences between NodeJS's `child_process` module and Caido's implementation.

::: info
For an exhaustive list of implemented features, refer to the [child\_process.d.ts](https://github.com/caido/dependency-llrt/blob/main/types/child_process.d.ts) file.
:::

## Differences

* The function `exec` is not implemented, use `spawn` with the `shell` option instead.
* The method `pipe` is not available to streams (like `stdout` and `stderr`).

---

---
url: /client-sdk/concepts.md
---
# Client SDK Concepts

Explanations of authentication, caching, and community SDK implementations for `@caido/sdk-client`.

## Authentication

* [Methods](./auth_methods.md)
* [Caching of Tokens](./auth_caching.md)

## Community implementations

* [Golang SDK](./community_golang.md)
* [Python SDK](./community_python.md)

---

---
url: /client-sdk/guides.md
---
# Client SDK Guides

Guides for using `@caido/sdk-client` to programmatically access a running Caido instance from external scripts and tools.

## Getting Started

* [Install the SDK](./install.md)
* [Base Setup](./base_setup.md)

## Core Features

* [Extract Requests](./extract_requests.md)
* [Manage Findings](./manage_findings.md)
* [Environments and Variables](./environments.md)

## Plugins

* [Install a Plugin](./install_plugin.md)
* [Call a Plugin Function](./call_function.md)
* [Receive Plugin Events](./receive_events.md)
* [Use a Plugin's NPM Spec Package](./spec_typing.md)

## Advanced

* [Call GraphQL Directly](./graphql_direct.md)
* [Custom Cache Implementation](./custom_cache.md)

---

---
url: /client-sdk/reference.md
---
# Client SDK Reference

Reference documentation for programmatic access to Caido from external tools.

## Cloud

* [Authentication](./authentication.md)
* [API](./api.md)

---

---
url: /client-sdk/tutorials.md
---
# Client SDK Tutorials

Step-by-step tutorials for building tools and automations with `@caido/sdk-client`.

* [Using the Scanner API](./scanner.md)
* [Using the Autorize API](./autorize.md)

---

---
url: /plugins/reference/sdks/frontend/command-palette.md
---
# Command Palette

### CommandPaletteSDK

> **CommandPaletteSDK** = `object`

Utilities to interact with the command palette.

#### Properties

##### pushView()

> **pushView**: (`view`: [`CommandPaletteView`](#commandpaletteview)) => `void`

Push a new view onto the command palette view stack.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `view` | [`CommandPaletteView`](#commandpaletteview) | The view to push onto the stack. |

###### Returns

`void`

##### register()

> **register**: (`commandId`: [`CommandID`](other.md#commandid)) => `void`

Register a command.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `commandId` | [`CommandID`](other.md#commandid) | The id of the command to register. |

###### Returns

`void`

***

### CommandPaletteView

> **CommandPaletteView** = `object`

Command palette view definition for custom UI content.

#### Properties

##### definition

> **definition**: [`ComponentDefinition`](utils.md#componentdefinition)

##### type

> **type**: `"Custom"`

---

---
url: /plugins/reference/sdks/frontend/commands.md
---
# Commands

### CommandContext

> **CommandContext** = [`CommandContextBase`](#commandcontextbase) | [`CommandContextRequestRow`](#commandcontextrequestrow) | [`CommandContextRequest`](#commandcontextrequest) | [`CommandContextResponse`](#commandcontextresponse)

Represents the context in which a command is executed.

***

### CommandContextBase

> **CommandContextBase** = `object`

The base context for a command.
This context is used for commands that are not executed in a specific context, such as via shortcuts and the command palette.

#### Properties

##### type

> **type**: `"BaseContext"`

***

### CommandContextRequest

> **CommandContextRequest** = `object`

The context for a command that is executed on a request pane.

#### Properties

##### request

> **request**: [`RequestDraft`](request.md#requestdraft) | [`RequestFull`](request.md#requestfull)

The request that is currently open in the request pane.
If the request has not yet been saved in the database, the id will be undefined.

##### selection

> **selection**: `string`

The currently selected text in the request pane.

##### type

> **type**: `"RequestContext"`

***

### CommandContextRequestRow

> **CommandContextRequestRow** = `object`

The context for a command that is executed on a row in the request table.

#### Properties

##### requests

> **requests**: [`RequestMeta`](request.md#requestmeta)\[]

The requests that are selected in the request table.

##### type

> **type**: `"RequestRowContext"`

***

### CommandContextResponse

> **CommandContextResponse** = `object`

The context for a command that is executed on a response pane.

#### Properties

##### request

> **request**: [`RequestMeta`](request.md#requestmeta)

The request that is associated with the response.

##### response

> **response**: `object`

The response that is currently open in the response pane.

###### id

> **id**: [`ID`](utils.md#id)

###### raw

> **raw**: `string`

###### roundtripTime

> **roundtripTime**: `number`

###### statusCode

> **statusCode**: `number`

##### selection

> **selection**: `string`

The currently selected text in the response pane.

##### type

> **type**: `"ResponseContext"`

***

### CommandsSDK

> **CommandsSDK** = `object`

Utilities to interact with commands

#### Properties

##### register()

> **register**: (`id`: [`CommandID`](other.md#commandid), `options`: `object`) => `void`

Register a command.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`CommandID`](other.md#commandid) | The id of the command. |
| `options` | { `group?`: `string`; `name`: `string`; `run`: (`context`: [`CommandContext`](#commandcontext)) => `Promise`<`void`> | `void`; `when?`: (`context`: [`CommandContext`](#commandcontext)) => `Promise`<`boolean`> | `boolean`; } | Options for the command. |
| `options.group?` | `string` | The group this command belongs to. |
| `options.name` | `string` | The name of the command. |
| `options.run` | (`context`: [`CommandContext`](#commandcontext)) => `Promise`<`void`> | `void` | The function to run when the command is executed. |
| `options.when?` | (`context`: [`CommandContext`](#commandcontext)) => `Promise`<`boolean`> | `boolean` | A function to determine if the command is available. |

###### Returns

`void`

###### Example

```ts
sdk.commands.register("hello", {
  name: "Print to console.",
  run: () => console.log("Hello world!"),
  group: "Custom Commands",
});
```

---

---
url: /plugins/concepts.md
---
# Concepts

Here you will find explanations of the core concepts that underpin Caido plugins.

## Frontend

* [UI Styling](./ui.md) - The Caido user-interface.

## Backend

* [Dealing with Binary Data](./binary.md) - Using invalid UTF-8 in Caido.
* [Plugins vs Workflows](./workflow.md) - How they differ.

## Essentials

* [Plugin Architecture](./package.md) - The structure of a plugin package.
* [Tooling](./tooling.md) - Tools for the ease of plugin development.
* [Runtime](./runtime.md) - Javascript runtimes used by plugins.
* [Signing](./signing.md) - Plugin signing.

## Modules

* [Child Process](./child_process.md) - Caido's implementation of NodeJS's `child_process` module.

---

---
url: /plugins/guides/config.md
---
# Configure Package

Caido packages are configured using the `caido.config.ts` file. This file is located in the root of your plugin's directory.
This file is used by the `caido-dev` CLI to build your plugin into a `plugin_package.zip` file.

If you've created a new package with `pnpm create @caido-community/plugin`, the `caido.config.ts` file will be created for you.

Here's what a typical `caido.config.ts` file looks like:

```ts
import { defineConfig } from "@caido-community/dev";

export default defineConfig({
  id: "my-plugin",
  name: "My Plugin",
  description: "A plugin for Caido",
  version: "0.0.0",
  author: {
    name: "Caido Labs Inc.",
    email: "dev@caido.io",
    url: "https://caido.io"
  },
  plugins: [
    {
      kind: "frontend",
      id: "my-frontend",
      name: "My Frontend",
      root: "packages/my-frontend",
      backend: {
        id: "my-backend"
      }
    },
    {
      kind: "backend",
      id: "my-backend",
      name: "My Backend",
      root: "packages/my-backend",
    }
  ]
});
```

You can find more information about the `caido.config.ts` file in the [Config Reference](/plugins/reference/config) page.

## Updating Package Details

Most plugins will only need to update the `id`, `name`, `description`, `author`, and `version` fields.

### ID

The `id` field is a unique identifier used to identify your plugin in Caido. This must be a string that is unique across all plugins.

### Name

The `name` field is the name of your plugin. This is the name that will be displayed when a user installs your plugin.

Keep your names concise, and avoid using the term "Caido" in the name. (e.g. "Auth Tester" instead of "Caido Auth Tester")

### Description

The `description` field is a short description of your plugin. This will be displayed when a user installs your plugin.

### Author

The `author` field is an object comprised of a `name`, `email`, and `url`.

* `name` is the name of the author.
* `email` is a contact email address for the author.
* `url` is a URL that links to the author's website.

### Version

The `version` field is a string that represents the version of your plugin using [Semantic Versioning](https://semver.org/).

When creating a new release of your plugin, you should increment this version number.

## Updating Plugin Details

Packages are comprised of one or more plugins that may need to be configured differently. You can find more information about plugins in the [Plugin Architecture](/plugins/concepts/package) page.

These options usually don't need to be updated, but you can if needed.

### Frontend Plugins

For frontend plugins, `caido-dev` uses [Vite](https://vitejs.dev/) to build your plugin. This means you can specify additional Vite options in your `caido.config.ts` file.

If you created your package with `pnpm create @caido-community/plugin`, the `caido.config.ts` file will be created with a default set of Vite options. We suggest you start with these options, and then update them if needed.

### Backend Plugins

For backend plugins, `caido-dev` uses [tsup](https://tsup.egoist.dev/) to build your plugin. The `tsup` options are not currently configurable.

---

---
url: /plugins/reference/modules/llrt/fs/namespaces/constants.md
---
[@caido/quickjs-types](../../../index.md) / [llrt/fs](../index.md) / constants

# constants

## Variables

### F\_OK

> `const` **F\_OK**: `number`

Constant for fs.access(). File is visible to the calling process.

***

### R\_OK

> `const` **R\_OK**: `number`

Constant for fs.access(). File can be read by the calling process.

***

### W\_OK

> `const` **W\_OK**: `number`

Constant for fs.access(). File can be written by the calling process.

***

### X\_OK

> `const` **X\_OK**: `number`

Constant for fs.access(). File can be executed by the calling process.

---

---
url: /plugins/guides/documentation.md
---
# Contributing

Our documentation is totally [open source](https://github.com/caido/doc-developer) and is there to help the community.
We are doing our best to improve it, but we would gladly welcome your contributions.
Don't hesitate to join our [Discord](https://links.caido.io/www-discord) if you need help.

## Requirements

* [Git](https://git-scm.com/)
* [NodeJS](https://nodejs.org/)
* [Pnpm](https://pnpm.io/)
* [Github Account](https://github.com)

## Steps

### Prepare

1. (Optional) Open an issue on the [repository](https://github.com/caido/doc-developer) to let us know you are working on something.
2. [Fork the repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo).
3. Clone your fork: `git clone https://github.com/[USERNAME]/doc-developer`.
4. Move into the directory: `cd doc-developer`.
5. Install dependencies: `pnpm i`
6. Create a new branch: `git branch -b [BRANCH NAME]`.

You are now ready to edit files. 🚀

### Edits

* Pages are primarily markdown files, but HTML can be used too.
* **Always** link pages in the `index.md` file otherwise they won't show up.
* To render the website we suggest using: `pnpm dev`.

### Publish

1. Commit changes: `git add . && git commit -m "[WHAT IS MY COMMIT ABOUT]"`.
2. Push changes to your fork: `git push`.
3. Open a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) on the [Caido repository](https://github.com/caido/doc-developer).
4. A preview link will appear in a comment.
5. Sign the CLA using the link that will also appear in a comment.

We will then check your pull request, make changes if necessary and merge it. It will then appear on the official documentation. 🎉

---

---
url: /plugins/guides/command.md
---
# Create a Command

Commands are used to register actions to expose functionality, bind actions to the user-interface and implement business logic.

## Registering a Command

```ts
sdk.commands.register("hello", {
  name: "Print to console.",
  run: () => console.log("Hello world!"),
  group: "Custom Commands",
});
```

This creates a command.

* "hello" is the `id` that is used to reference the command.
* "Print to console." is the command `name` that will be displayed in context menus and within the command palette.
* "Custom Commands" is the category `group` within the command palette that the command will be listed under.

::: info
The optional `when` property defines a conditional that must be met for the command to be available.

*For example, to explicity set the command to be available at all times, `when: () => true` can be used.*
:::

### Adding a Command to the Command Palette

```ts
sdk.commandPalette.register("hello");
```

This registers the previously created command to the command palette.

---

---
url: /plugins/guides/page.md
---
# Create a Page

Plugin pages provide a graphical user interface in the Caido application. Pages are created using Vue.js components with PrimeVue and Tailwind CSS for styling.

::: info
Vue.js is the standard approach for creating plugin pages in Caido. When you initialize a plugin using `pnpm create @caido-community/plugin`, you can choose the Vue.js template option. This guide shows how to create pages using Vue components. For more information about using PrimeVue components and styling, see [Using the Component Library](/plugins/guides/styling.md).
:::

## Creating Pages and Navigating

Used to create pages in the application and navigate to them.

### Adding a Page

Pages are created by setting up a Vue application and mounting it to a root element, which is then passed to `sdk.navigation.addPage()`. The Vue app handles the page's layout, state, and user interactions.

```ts
import { Classic } from "@caido/primevue";
import PrimeVue from "primevue/config";
import { createApp } from "vue";

import App from "./views/App.vue";

export const init = (sdk: CaidoSDK) => {
  const app = createApp(App);
  
  app.use(PrimeVue, {
    unstyled: true,
    pt: Classic,
  });

  const root = document.createElement("div");
  Object.assign(root.style, {
    height: "100%",
    width: "100%",
  });

  app.mount(root);

  sdk.navigation.addPage("/my-plugin-page", {
    body: root,
  });
};
```

This creates a page where the contents are defined in your `App.vue` component. The Vue app is mounted to a root `div` element, which is then passed as the `body` property to `addPage`.

The `topbar` property is optional and appears to the right of the Caido logo in the top-left corner.

### Navigating to a Page

```ts
sdk.navigation.goTo("/my-plugin-page");
```

## Adding Sidebar Items

Used to add an entry to the left-hand navigation menu in the Caido user-interface to navigate between pages.

```ts
sdk.sidebar.registerItem("My Plugin", "/my-plugin-page", {
  icon: "fas fa-rocket",
});
```

The `icon` property is optional and adds a [FontAwesome](https://fontawesome.com/icons) icon at the leading side of the button.

::: info

* The `group` property is optional and dictates which category the entry will be under in the left-hand side menu.
* The `isExternal` property is optional and takes a boolean value of *true* if the path points to an external URL.
  :::

## Building UI Components with PrimeVue

UI components are built using PrimeVue components styled with Tailwind CSS. PrimeVue provides a comprehensive set of components that match Caido's design system.

### Using PrimeVue Components

Import and use PrimeVue components directly in your Vue components. For example, to create a button:

```vue
<script setup lang="ts">
import Button from "primevue/button";
</script>

<template>
  <Button label="Delete" icon="fas fa-trash-can" severity="danger" size="small" />
</template>
```

PrimeVue components support various props for customization:

* `label` - The button text
* `icon` - FontAwesome icon class
* `severity` - Button style (`primary`, `secondary`, `success`, `info`, `warning`, `danger`)
* `size` - Button size (`small`, `medium`, `large`)

### Creating Layouts with Tailwind CSS

Use Tailwind CSS utility classes to create layouts. For example, to create a card-like layout:

```vue
<script setup lang="ts">
import { ref } from "vue";
</script>

<template>
  <div class="h-full flex flex-col">
    <div class="p-4 border-b border-gray-700">
      <h1 class="text-xl font-bold">Hello world!</h1>
      <p class="text-gray-400">Lorem ipsum.</p>
    </div>
    <div class="flex-1 p-4">
      <p>Paragraph.</p>
    </div>
    <div class="p-4 border-t border-gray-700">
      <p>Footer text.</p>
    </div>
  </div>
</template>
```

::: tip
For a complete example of creating a page with Vue components, see the example below. This shows how to set up a Vue app in `index.ts` and create the page layout in `App.vue`:

```ts
import { Classic } from "@caido/primevue";
import PrimeVue from "primevue/config";
import { createApp } from "vue";

import type { Caido } from "@caido/sdk-frontend";
import type { API } from "starterkit-plugin-backend";

import App from "./views/App.vue";

export type CaidoSDK = Caido<API>;

export const init = (sdk: CaidoSDK) => {
  const app = createApp(App);
  
  app.use(PrimeVue, {
    unstyled: true,
    pt: Classic,
  });

  const root = document.createElement("div");
  Object.assign(root.style, {
    height: "100%",
    width: "100%",
  });

  app.mount(root);

  sdk.navigation.addPage("/my-plugin-page", {
    body: root,
  });

  sdk.sidebar.registerItem("My Plugin", "/my-plugin-page", {
    icon: "fas fa-rocket",
  });
};
```

The `App.vue` component defines the page layout:

```vue
<script setup lang="ts">
import Button from "primevue/button";
</script>

<template>
  <div class="h-full flex flex-col">
    <div class="p-4 border-b border-gray-700">
      <h1 class="text-xl font-bold">Hello world!</h1>
      <p class="text-gray-400">Lorem ipsum.</p>
    </div>
    <div class="flex-1 p-4">
      <p>Paragraph.</p>
    </div>
    <div class="p-4 border-t border-gray-700">
      <p>Footer text.</p>
    </div>
  </div>
</template>
```

The `init` function creates the Vue app, mounts it to a root element, and registers the page with `addPage`. The sidebar item is registered to make the page accessible from the navigation menu.
:::

## Getting and Monitoring Context

The Window SDK provides methods to get and monitor the global application context, including the current page context.

### Getting Current Context

To get the current global context:

```ts
const context = sdk.window.getContext();
```

The context includes:

* `page` - The current page context (if on a specific page), which varies by page type

### Monitoring Context Changes

To listen for changes to the global context:

```ts
const handle = sdk.window.onContextChange((context) => {
  if (context.page) {
    console.log("Current page:", context.page.kind);

    // Access page-specific context
    if (context.page.kind === "Intercept") {
      const interceptContext = context.page;
      console.log("Request selection:", interceptContext.requestSelection);
    }
  }
});

// Later, stop listening
handle.stop();
```

### Example: Context-Aware Plugin

This example creates a plugin that reacts to context changes:

```ts
import type { Caido } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  sdk.window.onContextChange((context) => {
    if (context.page) {
      switch (context.page.kind) {
        case "Intercept":
          sdk.log.info("User is on the Intercept page");
          break;
        case "HTTPHistory":
          sdk.log.info("User is on the HTTP History page");
          break;
        case "Sitemap":
          sdk.log.info("User is on the Sitemap page");
          break;
        default:
          sdk.log.info(`User is on the ${context.page.kind} page`);
      }
    } else {
      sdk.log.info("User is not on a specific page");
    }
  });
};
```

## Page Context Types

Caido provides different page context types that are available depending on which page the user is viewing. Each context type offers different properties and capabilities. When creating pages for specific sections of Caido, understanding these context types allows you to build context-aware pages that react to user selections and application state.

### Available Page Context Types

The following page context types are available in Caido:

* **Assistant** - Context when viewing the AI Assistant page
* **Backups** - Context when viewing the Backups page
* **Certificate** - Context when viewing the Certificate page
* **Exports** - Context when viewing the Exports page
* **Intercept** - Context when viewing the Intercept page with access to request and response selections
* **WebSocket** - Context when viewing the WebSocket page

### Assistant Page Context

The Assistant page context is available when the user is on the AI Assistant page. This context has minimal state, primarily serving as an indicator of the current page.

**What this context provides:**

* A signal that the user is on the Assistant page

**Accessing Assistant context:**

```ts
sdk.window.onContextChange((context) => {
  if (context.page?.kind === "Assistant") {
    sdk.log.info("User navigated to Assistant page");
  }
});
```

**Example: Page for Assistant section:**

```ts
import { Classic } from "@caido/primevue";
import PrimeVue from "primevue/config";
import { createApp } from "vue";

import type { Caido } from "@caido/sdk-frontend";
import App from "./views/AssistantApp.vue";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  const app = createApp(App);

  app.use(PrimeVue, {
    unstyled: true,
    pt: Classic,
  });

  const root = document.createElement("div");
  Object.assign(root.style, {
    height: "100%",
    width: "100%",
  });

  app.mount(root);

  sdk.navigation.addPage("/ai-assistant-tools", {
    body: root,
  });

  // React to Assistant page context
  sdk.window.onContextChange((context) => {
    if (context.page?.kind === "Assistant") {
      sdk.log.info("Assistant tools page is now relevant");
    }
  });
};
```

### Backups Page Context

The Backups page context is available when the user is on the Backups page. This context provides access to backup-related state and operations.

**What this context provides:**

* A signal that the user is on the Backups page

**Accessing Backups context:**

```ts
sdk.window.onContextChange((context) => {
  if (context.page?.kind === "Backups") {
    sdk.log.info("User is on the Backups page");
  }
});
```

**Example: Page for Backups management:**

```ts
import { Classic } from "@caido/primevue";
import PrimeVue from "primevue/config";
import { createApp } from "vue";

import type { Caido } from "@caido/sdk-frontend";
import App from "./views/BackupsApp.vue";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  const app = createApp(App);

  app.use(PrimeVue, {
    unstyled: true,
    pt: Classic,
  });

  const root = document.createElement("div");
  Object.assign(root.style, {
    height: "100%",
    width: "100%",
  });

  app.mount(root);

  sdk.navigation.addPage("/backup-analytics", {
    body: root,
  });

  // Monitor Backups page changes
  sdk.window.onContextChange((context) => {
    if (context.page?.kind === "Backups") {
      sdk.log.info("Now on Backups page");
    }
  });
};
```

### Certificate Page Context

The Certificate page context is available when the user is on the Certificate management page. This context allows your plugin to respond to certificate-related operations.

**What this context provides:**

* A signal that the user is on the Certificate page

**Accessing Certificate context:**

```ts
sdk.window.onContextChange((context) => {
  if (context.page?.kind === "Certificate") {
    sdk.log.info("User is on the Certificate page");
  }
});
```

**Example: Certificate management plugin:**

```ts
import { Classic } from "@caido/primevue";
import PrimeVue from "primevue/config";
import { createApp } from "vue";

import type { Caido } from "@caido/sdk-frontend";
import App from "./views/CertificateApp.vue";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  const app = createApp(App);

  app.use(PrimeVue, {
    unstyled: true,
    pt: Classic,
  });

  const root = document.createElement("div");
  Object.assign(root.style, {
    height: "100%",
    width: "100%",
  });

  app.mount(root);

  sdk.navigation.addPage("/certificate-tools", {
    body: root,
  });

  // React to Certificate page context
  sdk.window.onContextChange((context) => {
    if (context.page?.kind === "Certificate") {
      sdk.log.info("Certificate management tools available");
    }
  });
};
```

### Exports Page Context

The Exports page context is available when the user is on the Exports page. This context allows you to build tools that work with exported data.

**What this context provides:**

* A signal that the user is on the Exports page

**Accessing Exports context:**

```ts
sdk.window.onContextChange((context) => {
  if (context.page?.kind === "Exports") {
    sdk.log.info("User is on the Exports page");
  }
});
```

**Example: Export analytics page:**

```ts
import { Classic } from "@caido/primevue";
import PrimeVue from "primevue/config";
import { createApp } from "vue";

import type { Caido } from "@caido/sdk-frontend";
import App from "./views/ExportAnalyticsApp.vue";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  const app = createApp(App);

  app.use(PrimeVue, {
    unstyled: true,
    pt: Classic,
  });

  const root = document.createElement("div");
  Object.assign(root.style, {
    height: "100%",
    width: "100%",
  });

  app.mount(root);

  sdk.navigation.addPage("/export-analytics", {
    body: root,
  });

  // React to Exports page context
  sdk.window.onContextChange((context) => {
    if (context.page?.kind === "Exports") {
      sdk.log.info("Export analytics tools available");
    }
  });
};
```

### Intercept Page Context

The Intercept page context is the most feature-rich context. It provides access to request, response, and WebSocket message selections, allowing you to build tools that work directly with intercepted traffic.

**What this context provides:**

* `requestSelection` - A selection object tracking the currently selected intercepted request
* `responseSelection` - A selection object tracking the currently selected intercepted response
* `websocketSelection` - A selection object tracking the currently selected WebSocket message

**Accessing Intercept context:**

```ts
sdk.window.onContextChange((context) => {
  if (context.page?.kind === "Intercept") {
    const intercept = context.page;

    // Check what is currently selected
    if (intercept.requestSelection.isSelected) {
      const selectedId = intercept.requestSelection.value;
      sdk.log.info(`Selected request: ${selectedId}`);
    }

    if (intercept.responseSelection.isSelected) {
      const selectedId = intercept.responseSelection.value;
      sdk.log.info(`Selected response: ${selectedId}`);
    }

    if (intercept.websocketSelection.isSelected) {
      const selectedId = intercept.websocketSelection.value;
      sdk.log.info(`Selected WebSocket message: ${selectedId}`);
    }
  }
});
```

**Example: Request analyzer plugin:**

This example creates a page that analyzes the currently selected intercepted request:

```ts
import { Classic } from "@caido/primevue";
import PrimeVue from "primevue/config";
import { createApp } from "vue";
import { ref } from "vue";

import type { Caido } from "@caido/sdk-frontend";
import App from "./views/InterceptAnalyzerApp.vue";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  const selectedRequest = ref<string | null>(null);
  const selectedResponse = ref<string | null>(null);

  const app = createApp(App, {
    selectedRequest,
    selectedResponse,
  });

  app.use(PrimeVue, {
    unstyled: true,
    pt: Classic,
  });

  const root = document.createElement("div");
  Object.assign(root.style, {
    height: "100%",
    width: "100%",
  });

  app.mount(root);

  sdk.navigation.addPage("/intercept-analyzer", {
    body: root,
  });

  // Monitor Intercept page selections
  sdk.window.onContextChange((context) => {
    if (context.page?.kind === "Intercept") {
      const intercept = context.page;

      // Update selected request
      if (intercept.requestSelection.isSelected) {
        selectedRequest.value = intercept.requestSelection.value;
      } else {
        selectedRequest.value = null;
      }

      // Update selected response
      if (intercept.responseSelection.isSelected) {
        selectedResponse.value = intercept.responseSelection.value;
      } else {
        selectedResponse.value = null;
      }
    }
  });
};
```

And in your `InterceptAnalyzerApp.vue` component:

```vue
<script setup lang="ts">
import { ref, computed } from "vue";

const props = defineProps<{
  selectedRequest: string | null;
  selectedResponse: string | null;
}>();

const noSelection = computed(() => !props.selectedRequest && !props.selectedResponse);
</script>

<template>
  <div class="h-full flex flex-col p-4">
    <div v-if="noSelection" class="text-gray-400">
      <p>Select a request or response in the Intercept tab to view analysis</p>
    </div>
    <div v-else>
      <div v-if="selectedRequest" class="mb-4 p-3 bg-blue-900/20 border border-blue-700 rounded">
        <h3 class="font-bold text-blue-400">Selected Request</h3>
        <p class="text-sm text-gray-300">{{ selectedRequest }}</p>
      </div>
      <div v-if="selectedResponse" class="p-3 bg-green-900/20 border border-green-700 rounded">
        <h3 class="font-bold text-green-400">Selected Response</h3>
        <p class="text-sm text-gray-300">{{ selectedResponse }}</p>
      </div>
    </div>
  </div>
</template>
```

### WebSocket Page Context

The WebSocket page context is available when the user is on the WebSocket page. This context allows you to build tools that interact with WebSocket connections.

**What this context provides:**

* A signal that the user is on the WebSocket page

**Accessing WebSocket context:**

```ts
sdk.window.onContextChange((context) => {
  if (context.page?.kind === "Websocket") {
    sdk.log.info("User is on the WebSocket page");
  }
});
```

**Example: WebSocket message analyzer:**

```ts
import { Classic } from "@caido/primevue";
import PrimeVue from "primevue/config";
import { createApp } from "vue";

import type { Caido } from "@caido/sdk-frontend";
import App from "./views/WebSocketAnalyzerApp.vue";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  const app = createApp(App);

  app.use(PrimeVue, {
    unstyled: true,
    pt: Classic,
  });

  const root = document.createElement("div");
  Object.assign(root.style, {
    height: "100%",
    width: "100%",
  });

  app.mount(root);

  sdk.navigation.addPage("/websocket-analyzer", {
    body: root,
  });

  // React to WebSocket page context
  sdk.window.onContextChange((context) => {
    if (context.page?.kind === "Websocket") {
      sdk.log.info("WebSocket analyzer tools available");
    }
  });
};
```

### Working with Page Context and State

When building context-aware pages, consider these best practices:

1. **Check context availability** - Always verify that `context.page` exists before accessing its properties, as the user may be on a plugin page that does not provide page context.

2. **Handle selection changes** - For pages with selections (like Intercept), use the `isSelected` property to determine if a selection is active before accessing the `value` property.

3. **Update UI reactively** - Use Vue's reactivity system (refs, computed properties) to update your UI when context changes.

4. **Provide fallback UI** - When no context is available or no selection is made, display helpful UI that guides the user about how to interact with your page.

5. **Clean up listeners** - When your plugin or page is destroyed, call the `stop()` method on listener handles to prevent memory leaks:

```ts
const handle = sdk.window.onContextChange((context) => {
  // Handle context changes
});

// When the page is destroyed
handle.stop();
```

## Interacting with Windows and Editors

Used to interact with text within the application environment, allowing text selection, replacement, read permission designations, focusing and editor related messaging.

### Interacting with Text Within Editors

```ts
let currentSelection = sdk.window.getActiveEditor()?.getSelectedText();
```

This takes the value of the current highlight-selected text and stores it in a variable.

```ts
sdk.window
  .getActiveEditor()
  ?.replaceSelectedText("Text that will replace the selection.");
```

This takes the value of the current highlight-selected text and replaces it with the arguement value.

### Displaying a Toast Message

```ts
sdk.window.showToast("Message to display.", {
  variant: "info",
  duration: 3000,
});
```

This displays a banner containing the specified message.

All message properties are optional and include:

* `variant` - Specifies the message type and can have a value of `"success"`, `"error"`, `"warning"` or `"info"`.
* `duration` - Specifies the amount of time a message will be displayed in milliseconds.

## Examples

### Basic Page with Button

This example creates a simple page with a button that displays a toast message when clicked.

```vue
<script setup lang="ts">
import Button from "primevue/button";
import { inject } from "vue";

const sdk = inject<CaidoSDK>("sdk");

const handleClick = () => {
  sdk?.window.showToast("Message to display.", {
    variant: "info",
    duration: 3000,
  });
};
</script>

<template>
  <div class="h-full flex flex-col p-4">
    <div class="mb-4">
      <h1 class="text-xl font-bold mb-2">Hello world!</h1>
      <p class="text-gray-400">Lorem ipsum.</p>
    </div>
    <div class="flex-1">
      <p>Paragraph.</p>
    </div>
    <div class="mt-4">
      <Button label="Message Button" @click="handleClick" />
    </div>
  </div>
</template>
```

The corresponding `index.ts` file:

```ts
import { Classic } from "@caido/primevue";
import PrimeVue from "primevue/config";
import { createApp } from "vue";

import type { Caido } from "@caido/sdk-frontend";
import type { API } from "starterkit-plugin-backend";

import App from "./views/App.vue";

export type CaidoSDK = Caido<API>;

export const init = (sdk: CaidoSDK) => {
  const app = createApp(App);
  
  app.provide("sdk", sdk);
  
  app.use(PrimeVue, {
    unstyled: true,
    pt: Classic,
  });

  const root = document.createElement("div");
  Object.assign(root.style, {
    height: "100%",
    width: "100%",
  });

  app.mount(root);

  sdk.navigation.addPage("/my-plugin-page", {
    body: root,
  });

  sdk.sidebar.registerItem("My Plugin", "/my-plugin-page", {
    icon: "fas fa-rocket",
  });
};
```

**What this context provides:**

* A signal that the user is on the WebSocket page

**Accessing WebSocket context:**

```ts
sdk.window.onContextChange((context) => {
  if (context.page?.kind === "Websocket") {
    sdk.log.info("User is on the WebSocket page");
  }
});
```

**Example: WebSocket message analyzer:**

```ts
import { Classic } from "@caido/primevue";
import PrimeVue from "primevue/config";
import { createApp } from "vue";

import type { Caido } from "@caido/sdk-frontend";
import App from "./views/WebSocketAnalyzerApp.vue";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  const app = createApp(App);

  app.use(PrimeVue, {
    unstyled: true,
    pt: Classic,
  });

  const root = document.createElement("div");
  Object.assign(root.style, {
    height: "100%",
    width: "100%",
  });

  app.mount(root);

  sdk.navigation.addPage("/websocket-analyzer", {
    body: root,
  });

  // React to WebSocket page context
  sdk.window.onContextChange((context) => {
    if (context.page?.kind === "Websocket") {
      sdk.log.info("WebSocket analyzer tools available");
    }
  });
};
```

---

---
url: /client-sdk/guides/custom_cache.md
---
# Custom Cache Implementation

The SDK ships with two built-in token caches: a file-based one for Node.js scripts and a `localStorage`-based one for browser tools. For everything else (encrypted storage, secret managers, shared state across workers, test mocks), implement the `TokenCache` interface yourself and pass an instance to the `Client` constructor.

::: info
If you only need a basic file or `localStorage` cache, use the `{ file }` or `{ localstorage }` options described in [Base Setup](./base_setup.md#cache-the-access-token). A custom implementation is only worth the extra code when you need behavior the built-in caches do not provide.
:::

## The TokenCache Interface

To plug in your own cache, implement three methods. The SDK exports the interface and the payload type:

```ts
import type { TokenCache, CachedToken } from "@caido/sdk-client";

// For reference, this is the shape you implement:
interface TokenCache {
  load(): Promise<CachedToken | undefined>;
  save(token: CachedToken): Promise<void>;
  clear(): Promise<void>;
}

interface CachedToken {
  accessToken: string;
  refreshToken?: string;
  expiresAt?: string;
}
```

When the SDK calls each method:

* **`load()`** runs once at the start of `client.connect()`. Return the cached token, or `undefined` to trigger a fresh authentication flow.
* **`save()`** runs after the SDK obtains a new token: after a PAT exchange, a browser login, a direct token (`auth.token`) being set, or a refresh.
* **`clear()`** is never called automatically by the SDK. It exists for your own code to invalidate the cache when needed (for example, on logout or after detecting a revoked token).

## Build an In-Memory Cache

The simplest custom cache holds the token in memory for the lifetime of the process. This is useful for short-lived scripts that make several authenticated calls but should not write to disk:

```ts
import type { TokenCache, CachedToken } from "@caido/sdk-client";

class InMemoryCache implements TokenCache {
  private stored: CachedToken | undefined;

  async load(): Promise<CachedToken | undefined> {
    return this.stored;
  }

  async save(token: CachedToken): Promise<void> {
    this.stored = token;
  }

  async clear(): Promise<void> {
    this.stored = undefined;
  }
}
```

Wire it in via the `auth.cache` option:

```ts
const client = new Client({
  url: "http://localhost:8080",
  auth: {
    pat: process.env["CAIDO_PAT"]!,
    cache: new InMemoryCache(),
  },
});

await client.connect();
```

The first `connect()` will run the full PAT exchange (since `load()` returns `undefined`) and then call `save()` with the resulting tokens. Subsequent `connect()` calls in the same process (for example, after recreating the `Client`) reuse the cached token without re-authenticating.

## Encrypted Storage

To store tokens encrypted at rest (when writing to a shared filesystem, a synced drive, or a CI cache), wrap a persistence layer with your encryption primitive:

```ts
import { readFile, writeFile, unlink } from "node:fs/promises";
import type { TokenCache, CachedToken } from "@caido/sdk-client";

class EncryptedFileCache implements TokenCache {
  private readonly path: string;
  private readonly key: Buffer;

  constructor(path: string, key: Buffer) {
    this.path = path;
    this.key = key;
  }

  async load(): Promise<CachedToken | undefined> {
    const ciphertext = await readFile(this.path).catch(() => undefined);
    if (!ciphertext) return undefined;
    const plaintext = decrypt(ciphertext, this.key); // your encryption primitive
    return JSON.parse(plaintext) as CachedToken;
  }

  async save(token: CachedToken): Promise<void> {
    const plaintext = JSON.stringify(token);
    const ciphertext = encrypt(plaintext, this.key); // your encryption primitive
    await writeFile(this.path, ciphertext, { mode: 0o600 });
  }

  async clear(): Promise<void> {
    await unlink(this.path).catch(() => {});
  }
}
```

Use a key from your OS keychain, a secret manager, or a derived key from a passphrase. Avoid hard-coding it in source.

## Secret Manager

To store tokens in a remote secret manager (AWS Secrets Manager, HashiCorp Vault, GCP Secret Manager, etc.), delegate to that service's SDK from your implementation. Sketch using AWS Secrets Manager:

```ts
import type { TokenCache, CachedToken } from "@caido/sdk-client";
import type { SecretsManager } from "@aws-sdk/client-secrets-manager";

class SecretsManagerCache implements TokenCache {
  private readonly client: SecretsManager;
  private readonly secretId: string;

  constructor(client: SecretsManager, secretId: string) {
    this.client = client;
    this.secretId = secretId;
  }

  async load(): Promise<CachedToken | undefined> {
    try {
      const result = await this.client.getSecretValue({ SecretId: this.secretId });
      return result.SecretString
        ? (JSON.parse(result.SecretString) as CachedToken)
        : undefined;
    } catch {
      return undefined;
    }
  }

  async save(token: CachedToken): Promise<void> {
    await this.client.putSecretValue({
      SecretId: this.secretId,
      SecretString: JSON.stringify(token),
    });
  }

  async clear(): Promise<void> {
    await this.client.deleteSecret({
      SecretId: this.secretId,
      ForceDeleteWithoutRecovery: true,
    });
  }
}
```

The same pattern applies to any backing store: implement the three methods against its API.

## Manually Clearing the Cache

The SDK never calls `clear()` on its own. Invoke it from your code when you want to invalidate the cached token, for example after detecting an authentication error or when explicitly signing out:

```ts
const cache = new InMemoryCache();
// ... use the client ...
await cache.clear();
```

On the next `connect()`, `load()` will return `undefined` and the SDK will run a fresh authentication flow.

## Examples

A complete script that uses an in-memory cache, connects, fetches the viewer, and clears the cache on exit:

### index.ts

```ts
import {
  Client,
  type TokenCache,
  type CachedToken,
} from "@caido/sdk-client";

class InMemoryCache implements TokenCache {
  private stored: CachedToken | undefined;

  async load(): Promise<CachedToken | undefined> {
    return this.stored;
  }

  async save(token: CachedToken): Promise<void> {
    this.stored = token;
  }

  async clear(): Promise<void> {
    this.stored = undefined;
  }
}

async function main() {
  const cache = new InMemoryCache();

  const client = new Client({
    url: process.env["CAIDO_INSTANCE_URL"] ?? "http://localhost:8080",
    auth: {
      pat: process.env["CAIDO_PAT"]!,
      cache,
    },
  });

  await client.connect();

  const viewer = await client.user.viewer();
  console.log("Authenticated as", viewer.kind);

  await cache.clear();
  console.log("Cache cleared");
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});
```

Run it with:

```bash
export CAIDO_PAT=caido_xxxxx
npx tsx ./index.ts
```

A successful run prints the auth flow followed by the viewer kind and the clear confirmation:

```txt
[caido] Attempting to load cached token
[caido] Starting authentication flow
[caido] Authentication flow completed
[caido] Saving token to cache
Authenticated as CloudUser
Cache cleared
```

---

---
url: /plugins/guides/settings.md
---
# Custom Settings Pages

The Settings SDK allows you to add custom settings pages to Caido's settings interface. This is useful for providing plugin-specific configuration options that users can access through the main settings menu.

## Adding a Settings Page

To add a custom settings page, use the `addToSlot` method with the `SettingsSlot.PluginsSection` slot:

```ts
import { SettingsSlot } from "@caido/sdk-frontend";

sdk.settings.addToSlot(SettingsSlot.PluginsSection, {
  type: "Custom",
  name: "My Plugin Settings",
  definition: MySettingsComponent,
});
```

### Settings Slot Content

The settings slot content requires:

* `type` - Must be `"Custom"`
* `name` - The display name shown in the settings sidebar
* `definition` - Your Vue component definition

## Settings Component

Your settings component is a standard Vue component that will be rendered in the settings page. You can use any Vue features and Caido SDK methods:

```vue
<script setup lang="ts">
import { ref } from "vue";
import type { Caido } from "@caido/sdk-frontend";

const props = defineProps<{
  sdk: Caido;
}>();

const settingValue = ref("default");

const saveSettings = () => {
  // Save settings using storage SDK
  props.sdk.storage.set({ mySetting: settingValue.value });
  props.sdk.window.showToast("Settings saved", { variant: "success" });
};
</script>

<template>
  <div class="p-4">
    <h2 class="text-lg font-bold mb-4">My Plugin Settings</h2>
    
    <div class="mb-4">
      <label class="block mb-2">
        Setting Value:
        <input
          v-model="settingValue"
          type="text"
          class="w-full p-2 border rounded mt-1"
        />
      </label>
    </div>
    
    <button
      @click="saveSettings"
      class="px-4 py-2 bg-blue-500 text-white rounded"
    >
      Save Settings
    </button>
  </div>
</template>
```

## Available Slots

Currently, the Settings SDK provides one slot:

* `SettingsSlot.PluginsSection` - The plugins section in the settings sidebar

## Examples

### Simple Settings Page

This example creates a basic settings page with a text input and save button:

```vue
<!-- MySettings.vue -->
<script setup lang="ts">
import { ref, onMounted } from "vue";
import type { Caido } from "@caido/sdk-frontend";

const props = defineProps<{
  sdk: Caido;
}>();

const apiKey = ref("");

onMounted(() => {
  // Load saved settings
  const saved = props.sdk.storage.get() as { apiKey?: string } | null;
  if (saved?.apiKey) {
    apiKey.value = saved.apiKey;
  }
});

const save = () => {
  props.sdk.storage.set({ apiKey: apiKey.value });
  props.sdk.window.showToast("API key saved", { variant: "success" });
};
</script>

<template>
  <div class="p-6 space-y-4">
    <h2 class="text-xl font-bold">My Plugin Configuration</h2>
    
    <div>
      <label class="block mb-2 font-medium">
        API Key:
        <input
          v-model="apiKey"
          type="password"
          placeholder="Enter your API key"
          class="w-full p-2 mt-1 border border-gray-600 rounded bg-gray-800 text-white"
        />
      </label>
    </div>
    
    <button
      @click="save"
      class="px-4 py-2 bg-blue-600 hover:bg-blue-700 text-white rounded"
    >
      Save
    </button>
  </div>
</template>
```

```ts
import type { Caido } from "@caido/sdk-frontend";
import { SettingsSlot } from "@caido/sdk-frontend";
import MySettings from "./MySettings.vue";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  sdk.settings.addToSlot(SettingsSlot.PluginsSection, {
    type: "Custom",
    name: "My Plugin",
    definition: MySettings,
  });
};
```

### Advanced Settings with Multiple Options

This example creates a more complex settings page with multiple configuration options:

```vue
<!-- AdvancedSettings.vue -->
<script setup lang="ts">
import { ref, onMounted } from "vue";
import type { Caido } from "@caido/sdk-frontend";

const props = defineProps<{
  sdk: Caido;
}>();

interface Settings {
  enabled: boolean;
  theme: "light" | "dark" | "auto";
  timeout: number;
  notifications: boolean;
}

const settings = ref<Settings>({
  enabled: true,
  theme: "auto",
  timeout: 5000,
  notifications: true,
});

onMounted(() => {
  const saved = props.sdk.storage.get() as Settings | null;
  if (saved) {
    settings.value = { ...settings.value, ...saved };
  }
});

const save = () => {
  props.sdk.storage.set(settings.value);
  props.sdk.window.showToast("Settings saved", { variant: "success" });
};

const reset = () => {
  settings.value = {
    enabled: true,
    theme: "auto",
    timeout: 5000,
    notifications: true,
  };
  save();
};
</script>

<template>
  <div class="p-6 space-y-6">
    <h2 class="text-xl font-bold">Advanced Plugin Settings</h2>
    
    <div class="space-y-4">
      <div class="flex items-center justify-between">
        <label class="font-medium">Enable Plugin</label>
        <input
          v-model="settings.enabled"
          type="checkbox"
          class="w-4 h-4"
        />
      </div>
      
      <div>
        <label class="block mb-2 font-medium">Theme</label>
        <select
          v-model="settings.theme"
          class="w-full p-2 border border-gray-600 rounded bg-gray-800 text-white"
        >
          <option value="light">Light</option>
          <option value="dark">Dark</option>
          <option value="auto">Auto</option>
        </select>
      </div>
      
      <div>
        <label class="block mb-2 font-medium">
          Timeout (ms): {{ settings.timeout }}
        </label>
        <input
          v-model.number="settings.timeout"
          type="range"
          min="1000"
          max="30000"
          step="1000"
          class="w-full"
        />
      </div>
      
      <div class="flex items-center justify-between">
        <label class="font-medium">Enable Notifications</label>
        <input
          v-model="settings.notifications"
          type="checkbox"
          class="w-4 h-4"
        />
      </div>
    </div>
    
    <div class="flex gap-2">
      <button
        @click="save"
        class="px-4 py-2 bg-blue-600 hover:bg-blue-700 text-white rounded"
      >
        Save
      </button>
      <button
        @click="reset"
        class="px-4 py-2 bg-gray-600 hover:bg-gray-700 text-white rounded"
      >
        Reset to Defaults
      </button>
    </div>
  </div>
</template>
```

```ts
import type { Caido } from "@caido/sdk-frontend";
import { SettingsSlot } from "@caido/sdk-frontend";
import AdvancedSettings from "./AdvancedSettings.vue";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  sdk.settings.addToSlot(SettingsSlot.PluginsSection, {
    type: "Custom",
    name: "Advanced Plugin",
    definition: AdvancedSettings,
  });
};
```

::: tip
Settings pages are a great way to provide configuration options for your plugin. Use the Storage SDK to persist settings across sessions. See the [Frontend Storage](/plugins/guides/frontend_storage.md) guide for more information.
:::

---

---
url: /plugins/guides/command_palette_advanced.md
---
# Customize Command Palette

Beyond registering commands, you can push custom views onto the command palette stack to create interactive command palette experiences, custom search interfaces, and multi-step commands.

::: tip
Custom command palette views enable rich, interactive experiences beyond simple command execution. Use them for complex workflows that benefit from user interaction.
:::

## Pushing a Custom View

To push a custom view onto the command palette, create a Vue component and pass it using the `ComponentDefinition` format:

```ts
import CustomView from "./CustomView.vue";

sdk.commandPalette.pushView({
  type: "Custom",
  definition: {
    component: CustomView,
  },
});
```

Command palette components automatically receive the SDK as a prop. You can also pass additional props and events:

```ts
sdk.commandPalette.pushView({
  type: "Custom",
  definition: {
    component: CustomView,
    props: {
      initialValue: "Hello",
    },
    events: {
      onComplete: () => {
        console.log("Completed");
      },
    },
  },
});
```

::: info
Pushed views are added to a stack. Users can navigate back through the stack using standard command palette navigation.
:::

## Using Component Props

Command palette components automatically receive the SDK as an implicit prop. If your Vue component defines an `sdk` prop, it will automatically receive the SDK instance:

```vue
<script setup lang="ts">
import type { Caido } from "@caido/sdk-frontend";

const props = defineProps<{
  sdk: Caido;
}>();
</script>
```

## Examples

### Custom Search Interface

This example creates a custom search interface within the command palette. It provides a text input that filters available commands in real-time as you type, displaying matching commands as clickable items.

```vue
<!-- CustomSearchView.vue -->
<script setup lang="ts">
import { ref, computed } from "vue";
import type { Caido } from "@caido/sdk-frontend";

const props = defineProps<{
  sdk: Caido;
}>();

const query = ref("");

const filteredCommands = computed(() => {
  if (!query.value) return [];
  
  const commands = props.sdk.commands.getAll?.() || [];
  return commands.filter((cmd) =>
    cmd.name.toLowerCase().includes(query.value.toLowerCase())
  );
});

const runCommand = (command: { run: () => void }) => {
  command.run();
};
</script>

<template>
  <div class="p-4">
    <input
      v-model="query"
      type="text"
      placeholder="Search..."
      class="w-full p-2 mb-4 border rounded"
      autofocus
    />
    
    <div v-if="filteredCommands.length > 0" class="space-y-1">
      <div
        v-for="cmd in filteredCommands"
        :key="cmd.id"
        @click="runCommand(cmd)"
        class="p-2 cursor-pointer hover:bg-gray-100 rounded"
      >
        {{ cmd.name }}
      </div>
    </div>
    
    <div v-else-if="query" class="text-gray-500 p-2">
      No commands found
    </div>
  </div>
</template>
```

```ts
import type { Caido } from "@caido/sdk-frontend";
import CustomSearchView from "./CustomSearchView.vue";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  sdk.commands.register("custom-search", {
    name: "Custom Search",
    run: () => {
      sdk.commandPalette.pushView({
        type: "Custom",
        definition: {
          component: CustomSearchView,
        },
      });
    },
  });

  sdk.commandPalette.register("custom-search");
};
```

### Multi-Step Command

This example implements a multi-step wizard interface in the command palette. It displays a step indicator, shows the current step content, and provides Next/Back navigation buttons to move through the steps.

```vue
<!-- MultiStepView.vue -->
<script setup lang="ts">
import { ref } from "vue";
import type { Caido } from "@caido/sdk-frontend";

const props = defineProps<{
  sdk: Caido;
  steps: string[];
}>();

const currentStep = ref(0);

const next = () => {
  if (currentStep.value < props.steps.length - 1) {
    currentStep.value++;
  } else {
    props.sdk.window.showToast("Process completed!", { variant: "success" });
  }
};

const back = () => {
  if (currentStep.value > 0) {
    currentStep.value--;
  }
};
</script>

<template>
  <div class="p-4">
    <div class="mb-4 font-bold">
      Step {{ currentStep + 1 }} of {{ steps.length }}
    </div>
    
    <div class="mb-4">
      {{ steps[currentStep] }}
    </div>
    
    <div class="flex gap-2 justify-end mt-4">
      <button
        @click="back"
        :disabled="currentStep === 0"
        class="px-4 py-2 border rounded disabled:opacity-50"
      >
        Back
      </button>
      <button
        @click="next"
        class="px-4 py-2 bg-blue-500 text-white rounded"
      >
        {{ currentStep < steps.length - 1 ? "Next" : "Finish" }}
      </button>
    </div>
  </div>
</template>
```

```ts
import type { Caido } from "@caido/sdk-frontend";
import MultiStepView from "./MultiStepView.vue";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  sdk.commands.register("multi-step", {
    name: "Multi-Step Process",
    run: () => {
      const steps = ["Step 1: Configure", "Step 2: Review", "Step 3: Execute"];
      sdk.commandPalette.pushView({
        type: "Custom",
        definition: {
          component: MultiStepView,
          props: {
            steps,
          },
        },
      });
    },
  });

  sdk.commandPalette.register("multi-step");
};
```

---

---
url: /plugins/guides/menu.md
---
# Customize Context Menus

The context menu is the list of actions/options that appears when right-clicking within an application.

## Registering Context Menu Items

Used to register right-click context menu actions/options and create a plugin specific settings page, allowing quick access to your plugin functionality.

### Registering an Entry to the Context Menu

```ts
sdk.menu.registerItem({
  type: "Request",
  commandId: "hello",
  leadingIcon: "fas fa-hand",
});
```

This registers the previously created [command](./command.md) to the context menu.

The `type` property specifies which context menu to add the action/option to:

* `Request` makes it available when right-clicking in a request pane.
* `RequestRow` makes it available when right-clicking on a request in a table.
* `Response` makes it available when right-clicking in a response pane.
* `Settings` makes it available when right-clicking in the settings menu.

The `commandId` value is the name of the registered command to execute.

The `leadingIcon` property is optional and adds an icon on the leading side of the entry.

::: info
When using the `Settings` value - an additional property of `path` exists which takes a string value of the path to be navigated to.
:::

---

---
url: /plugins/reference/sdks/workflow/data.md
---
# Data

### BytesInput

> **BytesInput** = `number`\[]

The input for the Javascript Nodes.

***

### ~~ConvertInput~~

> **ConvertInput** = [`BytesInput`](#bytesinput)

#### Deprecated

Use BytesInput instead.

***

### Data

> **Data** = [`Bytes`](shared.md#bytes)

The output for the Javascript Nodes.

***

### Decision

> **Decision** = `boolean`

The output for the If/Else Javascript Nodes.

***

### HttpInput

> **HttpInput** = `object`

The input for the HTTP Javascript Nodes

#### Properties

##### request

> **request**: [`Request`](requests.md#request) | `undefined`

##### response

> **response**: [`Response`](requests.md#response) | `undefined`

***

### NodeInput

> **NodeInput** = `object`

The input for the JavaScript V2+ Nodes.

#### Properties

##### data?

> `optional` **data**: [`Bytes`](shared.md#bytes)

##### extra?

> `optional` **extra**: `Record`<`string`, `any`>

***

### NodeInputHTTP

> **NodeInputHTTP** = `object`

The input for HTTP JavaScript Nodes.

#### Properties

##### extra?

> `optional` **extra**: `Record`<`string`, `any`>

##### request?

> `optional` **request**: [`Request`](requests.md#request)

##### response?

> `optional` **response**: [`Response`](requests.md#response)

***

### NodeResult

> **NodeResult** = `object`

The result for the JavaScript V2+ Nodes.

#### Properties

##### data?

> `optional` **data**: [`Bytes`](shared.md#bytes)

##### extra?

> `optional` **extra**: `Record`<`string`, `any`>

***

### ~~PassiveInput~~

> **PassiveInput** = [`HttpInput`](#httpinput)

#### Deprecated

Use HttpInput instead.

---

---
url: /plugins/concepts/binary.md
---
# Dealing with Binary Data

Caido plugins are written in JavaScript. When creating a plugin that must handle raw bytes, there are some caveats to be aware of as the backend language used by Caido is Rust.

## UTF-8 Encoding

For Unicode code points outside of the ASCII range (U+0000 to U+007F) multiple bytes are used.

When encoding code points into multibyte UTF-8 characters, the bytes are prefixed with specific bit patterns. The first byte prefix indicates how many bytes are used based on the number of leading '1's, and any subsequent (continuation) bytes begin with '10'.

This can be an issue if you want to create a Caido plugin that sends invalid UTF-8 to a target server to see how it is processed.

For example, if your intention is to append the byte `\x85` (`[1000 0101]`) to a path:

1. JavaScript strings are encoded using UTF-16 (`[0000 0000 1000 0101]`).
2. When passed to Rust, it is encoded as UTF-8. To produce valid UTF-8, the prefix is added to satisfy the multibyte pattern rules:
   * First byte `C2`: `[1100 0010]` (prefix marks start of 2-byte sequence)
   * Second byte `85`: `[1000 0101]` (continuation byte)
3. Now, `[1100 0010 1000 0101]` is sent instead of the intended `[1000 0101]`.

::: tip
You can view this visually by listening for the request with Netcat:

`ncat -lvnp 5555`

You can view the bytes by piping `xxd` to display the hex dump:

`ncat -lvnp 5555 | xxd -g1`

## Preserving the Raw Byte

To avoid the conversion, the raw byte must be used instead. This can be accomplished by:

1. Taking a request and returning a UInt8Array byte stream:

`.getPath({raw: true})`

2. Creating a new array that includes the existing bytes and the added byte:

`let path = [...spec.getPath({raw: true}), 0x85]`

3. Setting the path to use this new array:

`spec.setPath(path)`

::: tip
Now, `C2` will not be prefixed:

`ncat -lvnp 5555 | xxd -g1`

## What's next?

To view the full script and an additional technique that can be used to set raw bytes in Caido plugins, click [here](/plugins/guides/utf.md).

---

---
url: /policy.md
---
# Developer Policy

Last Update: 02/09/2024

The goal of Caido plugins is to make it easy for users to safely modify and expand the capabilities of Caido.

All plugin packages added to the Caido store must respect the following policy. Every plugin package is individually vetted before being included in the store. Plugin packages that don't follow these policies will be removed from the store.

This policy only apply to plugin listed in the Caido store. We may update this policy at any point in the future without notification.
This policy does not apply to plugin packages installed outside of the Caido store, but it is nonetheless good practice to follow.

::: warning
Plugin Packages are community driven by Caido users. Since development and distribution are done in this 3rd-party sense - Caido makes no warranty on the safety, functionality or quality of any plugin installed.
:::

## Policy

This policy complements our [Terms & Conditions](https://caido.io/terms). In case of conflict between this policy and our `Terms & Conditions`, the `Terms & Conditions` prevail.

### Not Allowed

Plugin packages must not:

* Obfuscate code to hide its purpose.
* Contain malware or any code that could be considered as such.
* Contain illegal or objectionable material (as determined by us).
* Insert static or dynamic ads.
* Include client-side telemetry.
* Include a mechanism that updates the plugin.
* Load assets from the internet (except if disclosed in README).

### Disclosures

The following are only allowed if clearly indicated in your README:

* Payment is required for full access.
* An account is required for full access.
* External services. Clearly explain which are used and why they are required.
* Server-side telemetry. Link to a privacy policy that explains how the data is handled must be included.
* Closed source code. Please contact us to include closed source plugin packages.

### Copyright and Licensing

All community plugins and themes must follow these requirements:

* Include a `LICENSE` file and clearly indicate the license of your plugin or theme.
* Comply with the original licenses of any code your plugin or theme makes use of, including attribution in the README if required.
* Respect Caido Copyright. Don't use Caido Copyright in a way that could confuse users into thinking your plugin package is a first-party creation.

## Reporting Violations

If you encounter a plugin package that violates the policy, please let the developer know by opening a GitHub issue on their repository.

If the developer doesn’t respond after 7 days, [contact the Caido team](mailto:info@caido.io). For serious violations, please contact us immediately!

## Removing Plugin Packages

In case of a policy violation, we may attempt to contact the developer and provide a reasonable timeframe for them to resolve the problem.

If the problem is not resolved by the agreed date, we will remove the plugin package from the store.

We may immediately remove a plugin package if:

* The plugin package appears to be malicious.
* The developer is uncooperative.
* This is a repeated violation.
* It is unmaintained or severely broken.
* Any other reason that we judge reasonable to protect Caido Labs Inc. and Caido users

---

---
url: /plugins/reference/sdks/frontend/editor.md
---
# Editor

### Editor

> **Editor** = `object`

Generic editor interface.

#### Properties

##### focus()

> **focus**: () => `void`

Focus the editor.

###### Returns

`void`

##### getEditorView()

> **getEditorView**: () => `EditorView`

Get the editor view.

###### Returns

`EditorView`

The CodeMirror [EditorView](https://codemirror.net/docs/ref/#view.EditorView).

##### getSelectedText()

> **getSelectedText**: () => `string`

Get the currently selected text of the editor.

###### Returns

`string`

##### isReadOnly()

> **isReadOnly**: () => `boolean`

Check whether the editor is read-only.

###### Returns

`boolean`

Whether the editor is read-only.

##### replaceSelectedText()

> **replaceSelectedText**: (`text`: `string`) => `void`

Replace the currently selected text of the editor.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `text` | `string` | The text to replace the selection with. |

###### Returns

`void`

***

### HTTPRequestEditor

> **HTTPRequestEditor** = `object`

An HTTP request editor interface.

#### Properties

##### getEditorView()

> **getEditorView**: () => `EditorView`

Get the editor view.

###### Returns

`EditorView`

The CodeMirror [EditorView](https://codemirror.net/docs/ref/#view.EditorView).

##### getElement()

> **getElement**: () => `HTMLElement`

Get the editor element.
Append this to your DOM to display the editor.

###### Returns

`HTMLElement`

The editor element.

***

### HTTPResponseEditor

> **HTTPResponseEditor** = `object`

An HTTP response editor interface.

#### Properties

##### getEditorView()

> **getEditorView**: () => `EditorView`

Get the editor view.

###### Returns

`EditorView`

The CodeMirror [EditorView](https://codemirror.net/docs/ref/#view.EditorView).

##### getElement()

> **getElement**: () => `HTMLElement`

Get the editor element.
Append this to your DOM to display the editor.

###### Returns

`HTMLElement`

The editor element.

---

---
url: /plugins/reference/sdks/backend/environment.md
---
# Environment

### Environment

> **Environment** = `object`

A saved immutable Environment.

#### Properties

##### id

> `readonly` **id**: [`ID`](shared.md#id)

The ID of the environment.

##### name

> `readonly` **name**: `string`

The name of the environment.

##### variables

> `readonly` **variables**: [`EnvironmentVariable`](#environmentvariable)\[]

The variables of the environment.

##### version

> `readonly` **version**: `number`

The version of the environment.

***

### EnvironmentSDK

> **EnvironmentSDK** = `object`

The SDK for the Environment service.

#### Methods

##### createEnvironment()

> **createEnvironment**(`input`: [`CreateEnvironmentInput`](other.md#createenvironmentinput)): `Promise`<[`Environment`](#environment)>

Create a new environment.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `input` | [`CreateEnvironmentInput`](other.md#createenvironmentinput) | The input for the creation. |

###### Returns

`Promise`<[`Environment`](#environment)>

The created environment.

##### deleteEnvironment()

> **deleteEnvironment**(`id`: [`ID`](shared.md#id)): `Promise`<`void`>

Delete an environment by its ID.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](shared.md#id) | The ID of the environment. |

###### Returns

`Promise`<`void`>

##### getEnvironment()

> **getEnvironment**(`id`: [`ID`](shared.md#id)): `Promise`<[`Environment`](#environment) | `undefined`>

Get an environment by its ID.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](shared.md#id) | The ID of the environment. |

###### Returns

`Promise`<[`Environment`](#environment) | `undefined`>

The environment or undefined if not found.

##### getEnvironments()

> **getEnvironments**(): `Promise`<[`Environment`](#environment)\[]>

Get all the environments.

###### Returns

`Promise`<[`Environment`](#environment)\[]>

An array of [Environment](#environment)

##### getVar()

> **getVar**(`name`: `string`): `string` | `undefined`

Get the value of an environment variable.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `name` | `string` | The name of the environment variable. |

###### Returns

`string` | `undefined`

The value of the environment variable.

##### getVars()

> **getVars**(): [`EnvironmentVariable`](#environmentvariable)\[]

Get all the environment variables.
It includes the global environment and the selected environment.
Those variables can change over time so avoid caching them.

###### Returns

[`EnvironmentVariable`](#environmentvariable)\[]

An array of [EnvironmentVariable](#environmentvariable)

##### setVar()

> **setVar**(`input`: [`SetVarInput`](#setvarinput)): `Promise`<`void`>

Sets an environment variable to a given value.
This will override any existing value.
The environment variable can be set either on the currently
selected environment or the global environment.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | [`SetVarInput`](#setvarinput) |

###### Returns

`Promise`<`void`>

###### Throws

If trying to set when a project is not selected.

###### Throws

If trying to set when an environment is not selected (with `global: false`).

###### Example

```js
await sdk.env.setVar({
  name: "USER_SECRET",
  value: "my secret value",
  secret: true,
  global: false
});
```

##### updateEnvironment()

> **updateEnvironment**(`id`: [`ID`](shared.md#id), `input`: [`UpdateEnvironmentInput`](other.md#updateenvironmentinput)): `Promise`<[`Environment`](#environment)>

Update an environment.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](shared.md#id) | The ID of the environment. |
| `input` | [`UpdateEnvironmentInput`](other.md#updateenvironmentinput) | The input for the update. |

###### Returns

`Promise`<[`Environment`](#environment)>

The updated environment.

###### Throws

If the version passed in is not equal to the current version of the environment.

###### Example

```js
const environment = await sdk.env.getEnvironment(id);
await sdk.env.updateEnvironment(id, {
  version: environment.version,
  name: "new name",
  variables: [{ name: "USER_SECRET", value: "new secret value", secret: true }],
});
```

***

### EnvironmentVariable

> **EnvironmentVariable** = `object`

A saved immutable Finding.

#### Properties

##### isSecret

> `readonly` **isSecret**: `boolean`

If the environment variable is a secret

##### name

> `readonly` **name**: `string`

The name of the environment variable

##### value

> `readonly` **value**: `string`

The value of the environment variable

***

### SetVarInput

> **SetVarInput** = `object`

Input for the `setVar` of [EnvironmentSDK](#environmentsdk).

#### Properties

##### env?

> `optional` **env**: `string`

The `name` of the Environment to set the variable on.
This will take precedence over the `global` flag if provided.

##### global

> **global**: `boolean`

If the environment variable should be set on the global
environment or the currently selected environment.
By default, it will be set globally.

###### Default

```ts
true
```

##### name

> **name**: `string`

Name of the environment variable

##### secret

> **secret**: `boolean`

If the environment variable should be treated as secret.

###### Default

```ts
false
```

##### value

> **value**: `string`

Value of the environment variable

---

---
url: /plugins/reference/sdks/frontend/environment.md
---
# Environment

### EnvironmentPageContext

> **EnvironmentPageContext** = `object`

Environment page context.

#### Properties

##### kind

> **kind**: `"Environment"`

##### selection

> **selection**: [`Selection`](utils.md#selection)<[`ID`](utils.md#id)>

***

### EnvironmentSDK

> **EnvironmentSDK** = `object`

Utilities to interact with the environment.

#### Properties

##### getVar()

> **getVar**: (`name`: `string`) => `string` | `undefined`

Get the value of an environment variable.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `name` | `string` | The name of the environment variable. |

###### Returns

`string` | `undefined`

The value of the environment variable.

##### getVars()

> **getVars**: () => [`EnvironmentVariable`](#environmentvariable)\[]

Get all environment variables available in the global environment and the selected environment.

###### Returns

[`EnvironmentVariable`](#environmentvariable)\[]

All environment variables.

***

### EnvironmentVariable

> **EnvironmentVariable** = `object`

Represents an environment variable.

#### Properties

##### isSecret

> **isSecret**: `boolean`

Whether the environment variable is a secret.

##### name

> **name**: `string`

The name of the environment variable.

##### value

> **value**: `string`

The value of the environment variable.

---

---
url: /plugins/reference/sdks/workflow/environment.md
---
# Environment

### Environment

> **Environment** = `object`

A saved immutable Environment.

#### Properties

##### id

> `readonly` **id**: [`ID`](shared.md#id)

The ID of the environment.

##### name

> `readonly` **name**: `string`

The name of the environment.

##### variables

> `readonly` **variables**: [`EnvironmentVariable`](#environmentvariable)\[]

The variables of the environment.

##### version

> `readonly` **version**: `number`

The version of the environment.

***

### EnvironmentSDK

> **EnvironmentSDK** = `object`

The SDK for the Environment service.

#### Methods

##### createEnvironment()

> **createEnvironment**(`input`: [`CreateEnvironmentInput`](other.md#createenvironmentinput)): `Promise`<[`Environment`](#environment)>

Create a new environment.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `input` | [`CreateEnvironmentInput`](other.md#createenvironmentinput) | The input for the creation. |

###### Returns

`Promise`<[`Environment`](#environment)>

The created environment.

##### deleteEnvironment()

> **deleteEnvironment**(`id`: [`ID`](shared.md#id)): `Promise`<`void`>

Delete an environment by its ID.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](shared.md#id) | The ID of the environment. |

###### Returns

`Promise`<`void`>

##### getEnvironment()

> **getEnvironment**(`id`: [`ID`](shared.md#id)): `Promise`<[`Environment`](#environment) | `undefined`>

Get an environment by its ID.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](shared.md#id) | The ID of the environment. |

###### Returns

`Promise`<[`Environment`](#environment) | `undefined`>

The environment or undefined if not found.

##### getEnvironments()

> **getEnvironments**(): `Promise`<[`Environment`](#environment)\[]>

Get all the environments.

###### Returns

`Promise`<[`Environment`](#environment)\[]>

An array of [Environment](#environment)

##### getVar()

> **getVar**(`name`: `string`): `string` | `undefined`

Get the value of an environment variable.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `name` | `string` | The name of the environment variable. |

###### Returns

`string` | `undefined`

The value of the environment variable.

##### getVars()

> **getVars**(): [`EnvironmentVariable`](#environmentvariable)\[]

Get all the environment variables.
It includes the global environment and the selected environment.
Those variables can change over time so avoid caching them.

###### Returns

[`EnvironmentVariable`](#environmentvariable)\[]

An array of [EnvironmentVariable](#environmentvariable)

##### setVar()

> **setVar**(`input`: [`SetVarInput`](#setvarinput)): `Promise`<`void`>

Sets an environment variable to a given value.
This will override any existing value.
The environment variable can be set either on the currently
selected environment or the global environment.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | [`SetVarInput`](#setvarinput) |

###### Returns

`Promise`<`void`>

###### Throws

If trying to set when a project is not selected.

###### Throws

If trying to set when an environment is not selected (with `global: false`).

###### Example

```js
await sdk.env.setVar({
  name: "USER_SECRET",
  value: "my secret value",
  secret: true,
  global: false
});
```

##### updateEnvironment()

> **updateEnvironment**(`id`: [`ID`](shared.md#id), `input`: [`UpdateEnvironmentInput`](other.md#updateenvironmentinput)): `Promise`<[`Environment`](#environment)>

Update an environment.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](shared.md#id) | The ID of the environment. |
| `input` | [`UpdateEnvironmentInput`](other.md#updateenvironmentinput) | The input for the update. |

###### Returns

`Promise`<[`Environment`](#environment)>

The updated environment.

###### Throws

If the version passed in is not equal to the current version of the environment.

###### Example

```js
const environment = await sdk.env.getEnvironment(id);
await sdk.env.updateEnvironment(id, {
  version: environment.version,
  name: "new name",
  variables: [{ name: "USER_SECRET", value: "new secret value", secret: true }],
});
```

***

### EnvironmentVariable

> **EnvironmentVariable** = `object`

A saved immutable Finding.

#### Properties

##### isSecret

> `readonly` **isSecret**: `boolean`

If the environment variable is a secret

##### name

> `readonly` **name**: `string`

The name of the environment variable

##### value

> `readonly` **value**: `string`

The value of the environment variable

***

### SetVarInput

> **SetVarInput** = `object`

Input for the `setVar` of [EnvironmentSDK](#environmentsdk).

#### Properties

##### env?

> `optional` **env**: `string`

The `name` of the Environment to set the variable on.
This will take precedence over the `global` flag if provided.

##### global

> **global**: `boolean`

If the environment variable should be set on the global
environment or the currently selected environment.
By default, it will be set globally.

###### Default

```ts
true
```

##### name

> **name**: `string`

Name of the environment variable

##### secret

> **secret**: `boolean`

If the environment variable should be treated as secret.

###### Default

```ts
false
```

##### value

> **value**: `string`

Value of the environment variable

---

---
url: /client-sdk/guides/environments.md
---
# Environments and Variables

The Client SDK exposes Caido's environments and their variables through `client.environment`. Environments hold named values (plain or secret) that you can reference in requests and workflows, which is useful for parameterizing scripts across different targets, API keys, or stages.

::: info
Environments are project-scoped. A project must be open on the instance for these calls to succeed. Every project also starts with a default `Global` environment that you can use directly or alongside your own.
:::

## List Environments

To get every environment in the current project, await `client.environment.list()`:

```ts
const envs = await client.environment.list();
for (const env of envs) {
  console.log(`${env.name} (${env.variables.length} variable(s))`);
}
```

Each entry is a plain `Environment` object with `id`, `name`, `version`, and `variables`.

## Create an Environment

To create a new environment, call `client.environment.create()` with a name and the initial variables. Variables can be `"PLAIN"` (visible) or `"SECRET"` (masked):

```ts
const env = await client.environment.create({
  name: "staging",
  variables: [
    { name: "API_URL", value: "https://api.staging.example.com", kind: "PLAIN" },
    { name: "API_KEY", value: "secret-123", kind: "SECRET" },
  ],
});

console.log("Created environment", env.id);
```

`create()` returns an `EnvironmentInstance` that you keep around to manage variables on this environment. The instance tracks the environment's version internally, so successive variable changes update the local state automatically without needing to refetch.

## Get a Single Environment

To pick up an existing environment for variable management, look it up by ID with `client.environment.get(id)`. It returns an `EnvironmentInstance` or `undefined` when the environment does not exist:

```ts
const env = await client.environment.get("2");
if (env === undefined) {
  throw new Error("Environment not found");
}
```

## Add, Update, and Delete Variables

To change variables on an environment, use the instance methods. Each call writes through to Caido and refreshes the local state:

```ts
// Add a new variable
await env.addVariable({ name: "REGION", value: "us-east-1", kind: "PLAIN" });

// Update an existing variable by name (merges with the current value)
await env.updateVariable("API_KEY", { value: "secret-rotated" });

// Delete a variable by name
await env.deleteVariable("REGION");

console.log(env.variables);
```

The variable list available on `env.variables` always reflects the latest server state after each call.

## Select the Active Environment

Only one environment is active at a time in Caido. To switch the active environment from a script, call `client.environment.select(id)`. Pass `undefined` to deselect the current one:

```ts
// Make this environment active
const active = await client.environment.select(env.id);
console.log("Active environment:", active?.name);

// Deselect
await client.environment.select();
```

## Delete an Environment

To remove an environment, call `client.environment.delete(id)`:

```ts
await client.environment.delete(env.id);
```

::: warning
Deletion is permanent and removes all variables on the environment. Any request or workflow that references variables from the deleted environment will fail until you point them at another environment.
:::

## Examples

The script below provisions a `staging` environment with two variables, selects it, and prints the final state:

### index.ts

```ts
import { Client } from "@caido/sdk-client";

async function main() {
  const client = new Client({
    url: process.env["CAIDO_INSTANCE_URL"] ?? "http://localhost:8080",
    auth: {
      pat: process.env["CAIDO_PAT"]!,
      cache: { file: ".caido-token.json" },
    },
  });

  await client.connect();

  const env = await client.environment.create({
    name: "staging",
    variables: [
      { name: "API_URL", value: "https://api.staging.example.com", kind: "PLAIN" },
      { name: "API_KEY", value: "secret-123", kind: "SECRET" },
    ],
  });

  await env.addVariable({ name: "REGION", value: "us-east-1", kind: "PLAIN" });
  await env.updateVariable("API_KEY", { value: "secret-rotated" });

  await client.environment.select(env.id);

  console.log(`Active: ${env.name}`);
  for (const v of env.variables) {
    const display = v.kind === "SECRET" ? "***" : v.value;
    console.log(`  ${v.name} = ${display} (${v.kind})`);
  }
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});
```

Run it with:

```bash
export CAIDO_PAT=caido_xxxxx
npx tsx ./index.ts
```

A successful run prints:

```txt
[caido] Attempting to load cached token
[caido] Loaded token from cache
Active: staging
  API_URL = https://api.staging.example.com (PLAIN)
  API_KEY = *** (SECRET)
  REGION = us-east-1 (PLAIN)
```

---

---
url: /plugins/reference/sdks/backend/events.md
---
# Events

### EventsSDK

> **EventsSDK**<`API`, `Events`> = `object`

The SDK for the API RPC service.

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `API` | `object` |
| `Events` | `object` |

#### Methods

##### onInterceptRequest()

> **onInterceptRequest**(`callback`: (`sdk`: [`SDK`](index.md#sdk)<`API`, `Events`>, `request`: [`Request`](requests.md#request)) => [`MaybePromise`](shared.md#maybepromise)<`void`>): `void`

Registers an callback on new intercepted requests.

This callback is called asynchronously and cannot modify requests.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `callback` | (`sdk`: [`SDK`](index.md#sdk)<`API`, `Events`>, `request`: [`Request`](requests.md#request)) => [`MaybePromise`](shared.md#maybepromise)<`void`> |

###### Returns

`void`

###### Example

```ts
sdk.events.onInterceptRequest((sdk, request) => {
   // Do something with the request
});
```

##### onInterceptResponse()

> **onInterceptResponse**(`callback`: (`sdk`: [`SDK`](index.md#sdk)<`API`, `Events`>, `request`: [`Request`](requests.md#request), `response`: [`Response`](requests.md#response)) => [`MaybePromise`](shared.md#maybepromise)<`void`>): `void`

Registers an callback on new intercepted responses.

This callback is called asynchronously and cannot modify responses.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `callback` | (`sdk`: [`SDK`](index.md#sdk)<`API`, `Events`>, `request`: [`Request`](requests.md#request), `response`: [`Response`](requests.md#response)) => [`MaybePromise`](shared.md#maybepromise)<`void`> |

###### Returns

`void`

###### Example

```ts
sdk.events.onInterceptResponse((sdk, request, response) => {
   // Do something with the request/response
});
```

##### onProjectChange()

> **onProjectChange**(`callback`: (`sdk`: [`SDK`](index.md#sdk)<`API`, `Events`>, `project`: [`Project`](projects.md#project) | `null`) => [`MaybePromise`](shared.md#maybepromise)<`void`>): `void`

Registers an callback on project change.

This callback is called asynchronously and cannot modify the project.

It can happen that the project is null if the user deleted the currently selected one.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `callback` | (`sdk`: [`SDK`](index.md#sdk)<`API`, `Events`>, `project`: [`Project`](projects.md#project) | `null`) => [`MaybePromise`](shared.md#maybepromise)<`void`> |

###### Returns

`void`

###### Example

```ts
sdk.events.onProjectChange((sdk, project) => {
  if (project !== null) {
    // Do something with the project
  }
});
```

##### onUpstream()

> **onUpstream**(`callback`: (`sdk`: [`SDK`](index.md#sdk)<`API`, `Events`>, `request`: [`RequestSpecRaw`](requests.md#requestspecraw)) => [`MaybePromise`](shared.md#maybepromise)<[`UpstreamResult`](#upstreamresult)>): `void`

Callback called before the request is sent to the target.

This callback is called synchronously so special care should be taken
to not impact overall performance.

The callback can return a `Connection` that will then be used to send the request.
It can also return a `RequestSpec` to override the request sent to the target.

This will only be called if the user has enabled it for a given domain
in the settings for Upstream Plugins.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `callback` | (`sdk`: [`SDK`](index.md#sdk)<`API`, `Events`>, `request`: [`RequestSpecRaw`](requests.md#requestspecraw)) => [`MaybePromise`](shared.md#maybepromise)<[`UpstreamResult`](#upstreamresult)> |

###### Returns

`void`

###### Example

```ts
sdk.events.onUpstream(async (sdk, request) => {
   // Send all requests to example.com
   return {
     connection: await sdk.net.connect("https://example.com"),
   };
});
```

***

### UpstreamResult

> **UpstreamResult** = [`Connection`](net.md#connection) | [`RequestSpec`](requests.md#requestspec) | { `connection?`: [`Connection`](net.md#connection); `request?`: [`RequestSpec`](requests.md#requestspec); } | `undefined`

The result of an upstream callback.

---

---
url: /plugins/reference/modules/llrt/path/namespaces/export=.md
---
[@caido/quickjs-types](../../../index.md) / [llrt/path](../index.md) / export=

# export=

## References

### FormatInputPathObject

Re-exports [FormatInputPathObject](../index.md#formatinputpathobject)

***

### ParsedPath

Re-exports [ParsedPath](../index.md#parsedpath)

***

### PlatformPath

Re-exports [PlatformPath](../index.md#platformpath)

---

---
url: /plugins/reference/sdks/frontend/exports.md
---
# Exports

### ExportsPageContext

> **ExportsPageContext** = `object`

Exports page context.

#### Properties

##### kind

> **kind**: `"Exports"`

---

---
url: /plugins/guides/editor_extensions.md
---
# Extend Editors

You can extend the request and response editors in Caido with CodeMirror extensions to add custom functionality like syntax highlighting, validation, autocomplete, custom keybindings, and editor themes.

::: tip
CodeMirror extensions are powerful and flexible. Refer to the [CodeMirror documentation](https://codemirror.net/docs/) for more advanced extension patterns.
:::

::: warning
Be careful with extensions that modify editor behavior significantly, as they may interfere with Caido's built-in editor functionality.
:::

## Adding Editor Extensions

Editor extensions are available on multiple pages in Caido. You can add extensions to request editors and response editors (where available).

### Request Editor Extensions

Request editor extensions are available on:

* HTTP History (`sdk.httpHistory.addRequestEditorExtension()`)
* Replay (`sdk.replay.addRequestEditorExtension()`)
* Search (`sdk.search.addRequestEditorExtension()`)
* Sitemap (`sdk.sitemap.addRequestEditorExtension()`)
* Automate (`sdk.automate.addRequestEditorExtension()`)
* Findings (`sdk.findings.addRequestEditorExtension()`)

```ts
import { Extension } from "@codemirror/state";

const myExtension: Extension = [
  // Your CodeMirror extension configuration
];

sdk.httpHistory.addRequestEditorExtension(myExtension);
```

### Response Editor Extensions

Response editor extensions are available on:

* HTTP History (`sdk.httpHistory.addResponseEditorExtension()`)

```ts
sdk.httpHistory.addResponseEditorExtension(myExtension);
```

## Adding Multiple Extensions

You can add multiple extensions to the same editor:

```ts
export const init = (sdk: CaidoSDK) => {
  sdk.httpHistory.addRequestEditorExtension([
    customHighlightExtension,
    customKeymapExtension,
    darkThemeExtension,
  ]);
};
```

## Accessing the Editor View

If you need to access the editor view directly, you can use `sdk.window.getActiveEditor()`:

```ts
const editor = sdk.window.getActiveEditor();
if (editor) {
  const view = editor.getEditorView();
  // Use the CodeMirror EditorView
}
```

## Examples

### Custom Syntax Highlighting

This example creates a custom syntax highlighting extension that colors strings green and numbers blue. The extension is applied to both HTTP History and Replay request editors.

```ts
import type { Caido } from "@caido/sdk-frontend";
import { Extension } from "@codemirror/state";
import { syntaxHighlighting, HighlightStyle } from "@codemirror/language";
import { tags } from "@lezer/highlight";

export type CaidoSDK = Caido;

const customHighlight = HighlightStyle.define([
  { tag: tags.string, color: "#0a0" },
  { tag: tags.number, color: "#00a" },
]);

const customHighlightExtension: Extension = syntaxHighlighting(customHighlight);

export const init = (sdk: CaidoSDK) => {
  // Add to HTTP History request editor
  sdk.httpHistory.addRequestEditorExtension(customHighlightExtension);
  
  // Add to Replay request editor
  sdk.replay.addRequestEditorExtension(customHighlightExtension);
};
```

### Custom Keybindings

This example adds a custom keyboard shortcut (Ctrl+Enter) that logs the currently selected text in the editor. The keybinding is registered as a CodeMirror extension.

```ts
import type { Caido } from "@caido/sdk-frontend";
import { Extension } from "@codemirror/state";
import { keymap } from "@codemirror/view";
import { EditorView } from "@codemirror/view";

export type CaidoSDK = Caido;

const customKeymapExtension: Extension = keymap.of([
  {
    key: "Ctrl-Enter",
    run: (view: EditorView) => {
      // Custom action on Ctrl+Enter
      const selection = view.state.selection.main;
      const text = view.state.doc.sliceString(selection.from, selection.to);
      console.log("Selected text:", text);
      return true;
    },
  },
]);

export const init = (sdk: CaidoSDK) => {
  sdk.httpHistory.addRequestEditorExtension(customKeymapExtension);
};
```

---

---
url: /plugins/reference/modules/extra/console.md
---
[@caido/quickjs-types](../index.md) / extra/console

# extra/console

## Type Aliases

### Console

> **Console** = `object`

Console interface for logging.

Currently logs are only available in the backend logs.
See the [documentation](https://docs.caido.io/app/troubleshooting/report_bug.html#1-backend-logs) on how to retrieve them.

#### Methods

##### debug()

> **debug**(`message`: `any`): `void`

Log a message with the debug level.

Usually used for troubleshooting purposes.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `message` | `any` |

###### Returns

`void`

##### error()

> **error**(`message`: `any`): `void`

Log a message with the error level.

Usually used for critical errors.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `message` | `any` |

###### Returns

`void`

##### log()

> **log**(`message`: `any`): `void`

Log a message with the info level.

Usually used for general information.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `message` | `any` |

###### Returns

`void`

##### warn()

> **warn**(`message`: `any`): `void`

Log a message with the warn level.

Usually used for unexpected behaviors.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `message` | `any` |

###### Returns

`void`

## Variables

### console

> **console**: [`Console`](#console)

---

---
url: /plugins/reference/modules/extra/os.md
---
[@caido/quickjs-types](../index.md) / extra/os

# extra/os

## Variables

### EOL

> `const` **EOL**: `string`

The operating system-specific end-of-line marker.

* `\n` on POSIX
* `\r\n` on Windows

## Functions

### arch()

> **arch**(): `string`

Returns the operating system CPU architecture for which the LLRT binary was compiled.
Possible values are 'arm64', 'x64'. The return value is equivalent to `process.arch`.

#### Returns

`string`

***

### homedir()

> **homedir**(): `string`

Returns the string path of the current user's home directory.

On POSIX, it uses the `$HOME` environment variable if defined. Otherwise it
uses the [effective UID](https://en.wikipedia.org/wiki/User_identifier#Effective_user_ID) to look up the user's home directory.

On Windows, it uses the `USERPROFILE` environment variable if defined.
Otherwise it uses the path to the profile directory of the current user.

#### Returns

`string`

***

### platform()

> **platform**(): [`Platform`](../llrt/globals/namespaces/QuickJS.md#platform)

Returns a string identifying the operating system platform for which
the Node.js binary was compiled. The value is set at compile time.

#### Returns

[`Platform`](../llrt/globals/namespaces/QuickJS.md#platform)

***

### release()

> **release**(): `string`

Returns the operating system release as a string.

On POSIX systems, the operating system release is determined by calling [`uname(3)`](https://linux.die.net/man/3/uname). On Windows, `RtlGetVersion()` is used. See
<https://en.wikipedia.org/wiki/Uname#Examples> for more information.

#### Returns

`string`

***

### tmpdir()

> **tmpdir**(): `string`

Returns the operating system's default directory for temporary files as a
string.

#### Returns

`string`

***

### type()

> **type**(): `string`

Returns the operating system name as returned by [`uname(3)`](https://linux.die.net/man/3/uname). For example, it
returns `'Linux'` on Linux, `'Darwin'` on macOS, and `'Windows_NT'` on Windows.

See <https://en.wikipedia.org/wiki/Uname#Examples> for additional information
about the output of running [`uname(3)`](https://linux.die.net/man/3/uname) on various operating systems.

#### Returns

`string`

***

### version()

> **version**(): `string`

Returns a string identifying the kernel version.

On POSIX systems, the operating system release is determined by calling [`uname(3)`](https://linux.die.net/man/3/uname). On Windows, `RtlGetVersion()` is used.
See <https://en.wikipedia.org/wiki/Uname#Examples> for more information.

#### Returns

`string`

---

---
url: /plugins/reference/modules/extra/sqlite.md
---
[@caido/quickjs-types](../index.md) / extra/sqlite

# extra/sqlite

## Classes

### Database

A SQLite database.

The implementation uses a connection pool and is fully asynchronous.
Each connection will be spawned in a worker thread.

#### Example

```ts
const db = await open({ filename: "path/to/database.sqlite" });
await db.exec("CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT);");
await db.exec("INSERT INTO test (name) VALUES ('foo');");
```

#### Constructors

##### Constructor

> **new Database**(): [`Database`](#database)

###### Returns

[`Database`](#database)

#### Methods

##### exec()

> **exec**(`sql`: `string`): `Promise`<`void`>

This method allows one or more SQL statements to be executed without returning any results.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `sql` | `string` |

###### Returns

`Promise`<`void`>

##### prepare()

> **prepare**(`sql`: `string`): `Promise`<[`Statement`](#statement)>

Compiles a SQL statement into a [prepared statement](https://www.sqlite.org/c3ref/stmt.html).

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `sql` | `string` |

###### Returns

`Promise`<[`Statement`](#statement)>

***

### Statement

This class represents a single prepared statement. This class cannot be instantiated via its constructor.
Instead, instances are created via the database.prepare() method.

#### Constructors

##### Constructor

> **new Statement**(): [`Statement`](#statement)

###### Returns

[`Statement`](#statement)

#### Methods

##### all()

> **all**<`T`>(...`params`: [`Parameter`](#parameter)\[]): `Promise`<`T`\[]>

This method executes a prepared statement and returns all results as an array of objects.
If the prepared statement does not return any results, this method returns an empty array.
The prepared statement [parameters are bound](https://www.sqlite.org/c3ref/bind_blob.html) using the values in `params`.

###### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `T` *extends* `object` | `object` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| ...`params` | [`Parameter`](#parameter)\[] | The values to bind to the prepared statement. Named parameters are not supported. |

###### Returns

`Promise`<`T`\[]>

##### get()

> **get**<`T`>(...`params`: [`Parameter`](#parameter)\[]): `Promise`<`T` | `undefined`>

This method executes a prepared statement and returns the first result as an object.
If the prepared statement does not return any results, this method returns undefined.
The prepared statement [parameters are bound](https://www.sqlite.org/c3ref/bind_blob.html) using the values in params.

###### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `T` *extends* `object` | `object` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| ...`params` | [`Parameter`](#parameter)\[] | The values to bind to the prepared statement. Named parameters are not supported. |

###### Returns

`Promise`<`T` | `undefined`>

##### run()

> **run**(...`params`: [`Parameter`](#parameter)\[]): `Promise`<[`Result`](#result)>

This method executes a prepared statement and returns an object summarizing the resulting changes.
The prepared statement [parameters are bound](https://www.sqlite.org/c3ref/bind_blob.html) using the values in params.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| ...`params` | [`Parameter`](#parameter)\[] | The values to bind to the prepared statement. Named parameters are not supported. |

###### Returns

`Promise`<[`Result`](#result)>

## Type Aliases

### OpenOptions

> **OpenOptions** = `object`

#### Properties

##### busyTimeout?

> `optional` **busyTimeout**: `number`

Time (in milliseconds) to wait for the database to be unlocked before throwing an error.

###### Default

```ts
5000
```

##### filename?

> `optional` **filename**: `string`

The filename of the database. If the file does not exist, a new one will be created.

##### foreignKeys?

> `optional` **foreignKeys**: `boolean`

Enable foreign key constraints.

##### idleTimeout?

> `optional` **idleTimeout**: `number`

Maximum amount of time (in seconds) that a connection is allowed to be idle before it is closed.

###### Default

```ts
infinity
```

##### in\_memory?

> `optional` **in\_memory**: `boolean`

If true, the database will be opened in-memory.

###### Default

```ts
false
```

##### maxConnections?

> `optional` **maxConnections**: `number`

Maximum number of connections to the database.

###### Default

```ts
5
```

##### maxLifetime?

> `optional` **maxLifetime**: `number`

Maximum amount of time (in seconds) that a connection is allowed to exist before it is closed.
Set to `null` to disable.

###### Default

```ts
3600
```

##### minConnections?

> `optional` **minConnections**: `number`

Minimum number of connections to the database.

###### Default

```ts
0
```

##### pageSize?

> `optional` **pageSize**: `number`

Set the SQlite page size.

###### Default

```ts
4096
```

##### wal?

> `optional` **wal**: `boolean`

If true, the database will use the WAL mode.

###### Default

```ts
true
```

***

### Parameter

> **Parameter** = `null` | `number` | `bigint` | `string` | `Uint8Array`

***

### Result

> **Result** = `object`

#### Properties

##### changes

> **changes**: `number`

##### lastInsertRowid

> **lastInsertRowid**: `number`

## Functions

### open()

> **open**(`options`: [`OpenOptions`](#openoptions)): `Promise`<[`Database`](#database)>

Open a SQLite database.

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`OpenOptions`](#openoptions) | The options to open the database. |

#### Returns

`Promise`<[`Database`](#database)>

---

---
url: /plugins/reference/modules/extra/timers.md
---
[@caido/quickjs-types](../index.md) / extra/timers

# extra/timers

## Classes

### Timeout

This object is created internally and is returned from `setTimeout()` and `setInterval()`. It can be passed to either `clearTimeout()` or `clearInterval()` in order to cancel the
scheduled actions.

#### Constructors

##### Constructor

> **new Timeout**(): [`Timeout`](#timeout)

###### Returns

[`Timeout`](#timeout)

## Functions

### clearInterval()

> **clearInterval**(`interval`: [`Timeout`](#timeout)): `void`

Cancels a `Timeout` object created by `setInterval()`.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `interval` | [`Timeout`](#timeout) |

#### Returns

`void`

***

### clearTimeout()

> **clearTimeout**(`timeout`: [`Timeout`](#timeout)): `void`

Cancels a `Timeout` object created by `setTimeout()`.

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `timeout` | [`Timeout`](#timeout) | A `Timeout` object as returned by [setTimeout](#settimeout). |

#### Returns

`void`

***

### setImmediate()

> **setImmediate**<`TArgs`>(`callback`: (...`args`: `TArgs`) => `void`): `void`

Schedules the "immediate" execution of the `callback` after I/O events'
callbacks.

#### Type Parameters

| Type Parameter |
| ------ |
| `TArgs` *extends* `any`\[] |

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `callback` | (...`args`: `TArgs`) => `void` | The function to call at the end of this turn of the Node.js `Event Loop` |

#### Returns

`void`

for use with clearImmediate

***

### setInterval()

> **setInterval**<`TArgs`>(`callback`: (...`args`: `TArgs`) => `void`, `ms?`: `number`): [`Timeout`](#timeout)

Schedules repeated execution of `callback` every `delay` milliseconds.

When `delay` isless than `4`, the `delay` will be set to `4`.

#### Type Parameters

| Type Parameter |
| ------ |
| `TArgs` *extends* `any`\[] |

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `callback` | (...`args`: `TArgs`) => `void` | The function to call when the timer elapses. |
| `ms?` | `number` | - |

#### Returns

[`Timeout`](#timeout)

for use with [clearInterval](#clearinterval)

***

### setTimeout()

> **setTimeout**<`TArgs`>(`callback`: (...`args`: `TArgs`) => `void`, `ms?`: `number`): [`Timeout`](#timeout)

Schedules execution of a one-time `callback` after `delay` milliseconds.

The `callback` will likely not be invoked in precisely `delay` milliseconds.
Caido makes no guarantees about the exact timing of when callbacks will fire,
nor of their ordering. The callback will be called as close as possible to the
time specified.

When `delay` is less than `4`, the `delay` will be set to `4`.

#### Type Parameters

| Type Parameter |
| ------ |
| `TArgs` *extends* `any`\[] |

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `callback` | (...`args`: `TArgs`) => `void` | The function to call when the timer elapses. |
| `ms?` | `number` | - |

#### Returns

[`Timeout`](#timeout)

for use with [clearTimeout](#cleartimeout)

---

---
url: /client-sdk/guides/extract_requests.md
---
# Extract Requests

The Client SDK exposes the proxied HTTP history of a Caido instance through `client.request`. You can list requests with filters, ordering, and pagination, or fetch a single request by ID. This is the foundation for any automation that needs to read or process traffic captured by the proxy.

::: info
A project must be open on the instance for these calls to succeed. If no project is loaded, the database is not connected and the SDK will throw an error.
:::

## List Requests

To list requests, start a chain with `client.request.list()` and await it. The result is a paginated `Connection` with `pageInfo` (cursors) and `edges` (the requests):

```ts
const page = await client.request.list().first(10);

for (const edge of page.edges) {
  const req = edge.node.request;
  const code = edge.node.response?.statusCode ?? "no response";
  console.log(`${req.method} ${req.host}${req.path} -> ${code}`);
}
```

Each `edge.node` is a `{ request, response? }` pair. The response is `undefined` when the request did not complete (for example, an in-flight or dropped request).

## Filter with HTTPQL

To narrow the list, chain `.filter()` with an [HTTPQL](https://docs.caido.io/app/reference/httpql.html) query string. The same syntax used in the Caido HTTP History UI works here:

```ts
const errors = await client.request
  .list()
  .filter('resp.code.gte:400')
  .first(50);

console.log(`Got ${errors.edges.length} error response(s)`);
```

Integer values are unquoted (`resp.code.gte:400`), string values are quoted (`req.host.cont:"example.com"`). Combine clauses with `AND` / `OR` and parentheses, for example `'req.host.cont:"example.com" AND resp.code.gte:400'`.

## Order Results

To control sort order, chain `.ascending(target, field)` or `.descending(target, field)`. The `target` is `"req"` or `"resp"`, and the `field` is one of the supported order fields:

* Request fields: `created_at`, `host`, `method`, `path`, `query`, `ext`, `source`, `id`
* Response fields: `code`, `length`, `roundtrip`

```ts
const latest = await client.request
  .list()
  .descending("req", "created_at")
  .first(10);
```

## Skip Raw Bodies

To skip raw request and response bodies when you only need metadata (faster, less memory), call `.includeRaw(false)`. By default, every entry comes back with its full raw bytes attached.

```ts
const meta = await client.request.list().includeRaw(false).first(100);
// meta.edges[i].node.request.raw is undefined
```

To selectively keep one side, pass an object:

```ts
client.request.list().includeRaw({ request: true, response: false });
```

## Scope to a Caido Scope

To restrict the list to a specific Caido scope (the scopes you define under the **Scope** feature), chain `.scope(scopeId)`. You can list and look up scope IDs via `client.scope`:

```ts
const inScope = await client.request.list().scope(scopeId).first(50);
```

## Paginate

To walk through more results than fit in a single page, call `.next()` on the returned connection. It returns the next page or `undefined` when there are no more:

```ts
let page = await client.request.list().first(50);
while (page) {
  for (const edge of page.edges) {
    // process edge.node
  }
  page = await page.next();
}
```

Cursors in `page.pageInfo.startCursor` / `endCursor` are opaque strings. Treat them as a black box and feed them back to `.after(cursor)` or `.before(cursor)` if you need manual control.

## Get a Single Request

To fetch one request when you already know its ID, use `client.request.get(id)`. It returns the same `{ request, response? }` shape as a list edge, or `undefined` when the request does not exist:

```ts
const item = await client.request.get("1");
if (item === undefined) {
  throw new Error("Request not found");
}

console.log(item.request.method, item.request.host, item.request.path);
console.log("Response status:", item.response?.statusCode);
```

Pass an options object to skip the raw bodies on a per-call basis:

```ts
const item = await client.request.get("1", {
  requestRaw: false,
  responseRaw: false,
});
```

## Examples

The script below lists the latest 10 requests ordered by creation time, prints a one-line summary of each, and decodes the raw response of the first one.

### index.ts

```ts
import { Client } from "@caido/sdk-client";

async function main() {
  const client = new Client({
    url: process.env["CAIDO_INSTANCE_URL"] ?? "http://localhost:8080",
    auth: {
      pat: process.env["CAIDO_PAT"]!,
      cache: { file: ".caido-token.json" },
    },
  });

  await client.connect();

  const page = await client.request
    .list()
    .descending("req", "created_at")
    .first(10);

  for (const edge of page.edges) {
    const req = edge.node.request;
    const code = edge.node.response?.statusCode ?? "no response";
    console.log(`${req.method} ${req.host}${req.path} -> ${code}`);
  }

  const first = page.edges[0]?.node;
  if (first?.response?.raw) {
    const text = new TextDecoder().decode(first.response.raw);
    console.log("\n--- Raw response of first request ---");
    console.log(text.slice(0, 500));
  }
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});
```

Run it with:

```bash
export CAIDO_PAT=caido_xxxxx
npx tsx ./index.ts
```

A successful run prints a summary line per request followed by the first 500 bytes of the first response:

```txt
[caido] Attempting to load cached token
[caido] Loaded token from cache
GET detectportal.firefox.com/success.txt -> 200
GET detectportal.firefox.com/success.txt -> 200
GET detectportal.firefox.com/canonical.html -> 200
...

--- Raw response of first request ---
HTTP/1.1 200 OK
Server: nginx
Content-Length: 8
...
```

---

---
url: /plugins/guides/querying_requests.md
---
# Fetch Proxied Requests

In this guide, we'll cover how to fetch proxied requests in a backend plugin.

## Querying Requests

The `query()` method queries proxied requests belonging to the current [Project](https://docs.caido.io/app/guides/projects_backups).

```ts
let query = sdk.requests.query();
```

This method returns the results as a [RequestsQuery](/plugins/reference/sdks/backend/#requestsquery) object.

## Executing a Query

Queries for requests are executed with the `execute()` method.

```ts
const results = await query.execute();
```

::: info
Caido utilizes cursor-based pagination, meaning that instead of the dataset being divided into fixed subsets across numbered "pages" as seen in offset-based pagination, references to requests rely on their unique "cursors" which identify their position.

By referencing a request's cursor, you can fetch it or mark it as the starting position for operations on the dataset.
:::

This method returns a Promise that resolves to a [RequestsConnection](/plugins/reference/sdks/backend/#requestsconnection) object that represents the returned dataset, in this case the requests.

The `RequestsConnection` object has two parent fields: `items` and `pageInfo`.

### items

The `items` field is an array of `RequestsConnectionItem` objects. The fields of the `RequestConnectionItem` object are:

* `request`: The [Request](/plugins/reference/sdks/backend/#request) object itself.
* `cursor`: The cursor of the associated request.
* `response`: The paired [Response](/plugins/reference/sdks/backend/#response-3) object of the associated request if available.

### pageInfo

The fields of the `pageInfo` object are:

* `startCursor` - The cursor of the starting request in the dataset.
* `endCursor` - The cursor of the ending request in the dataset.
* `hasPreviousPage` - Returns either `true` or `false` to indicate whether more data before the current set is available.
* `hasNextPage` - Returns either `true` or `false` to indicate whether more data after the current set is available.

## Refining Your Dataset View

However, for Projects with a large number of requests, executing such a broad query would be memory exhaustive and inefficient. To account for this, Caido's SDK also offers a variety of additional methods that can be chained in order to refine the view of the requests dataset.

### Filtering

With the `filter()` method, you can target specific requests using [HTTPQL](https://docs.caido.io/app/reference/httpql.html) query statements as a parameter.

```ts
 let query = sdk.requests.query().filter('req.host.eq:"example.com"');
```

### Sorting

The following methods can be used to sort results to determine their ordering:

* `ascending()` - Sorts results in ascending order.
* `descending()` - Sorts results in descending order.

Both methods can target either requests or responses by supplying either `"req"` or `"resp"` as their first parameter.

The element that determines the sort order is either a [RequestOrderField](/plugins/reference/sdks/backend/#requestorderfield) or a [ResponseOrderField](/plugins/reference/sdks/backend/#responseorderfield) depending on the target and is supplied as the second parameter.

```ts
query = query.ascending("req", "id");
```

#### Cursor

The following methods can be used to paginate through the dataset:

* `after()` - Fetches requests that come after a cursor.
* `before()` - Fetches requests that come before a cursor.

#### Limiting

The following methods can be used to limit the number of requests to process:

* `first()` - Specifies the number of requests from the beginning of the dataset view.
* `last()` - Specifies the number of requests from the end of the dataset view.

Both `first()` and `last()` take an integer as their parameter that represents the number of requests to process.

## Building and Executing a Query

### /packages/backend/src/index.ts

```ts
import type { DefineAPI, SDK } from "caido:plugin";

export async function fetchRequests(sdk: SDK) {
  let totalRequestsQueried = 0;

  while (true) {
    let cursor = null;
    let query = sdk.requests
      .query()
      .filter('req.host.eq:"example.com"')
      .first(1000);

    query = query.ascending("req", "created_at");

    if (cursor) {
      query = query.after(cursor);
    }

    const requests = await query.execute();

    totalRequestsQueried += requests.items.length;

    if (requests.pageInfo.hasNextPage) {
      cursor = requests.pageInfo.endCursor;
    } else {
      break;
    }
  }

  return totalRequestsQueried;
}

export type API = DefineAPI<{
  fetchRequests: typeof fetchRequests;
}>;

export async function init(sdk: SDK<API>) {
  sdk.api.register("fetchRequests", fetchRequests);
}
```

### Script Breakdown

First, the necessary type aliases are imported. `SDK` is the interface used to interact with Caido. `DefineAPI` is used to structure the API: definining what methods or endpoints are available, the parameters those methods accept and what types of values they return.

```ts
import type { DefineAPI, SDK } from "caido:plugin";
```

Next, the function is defined. The function takes the `sdk` parameter typed using the `SDK` alias to give the function access to it's utilities. To keep track of the total number of requests queried, the `totalRequestsQueried` variable is created with an initial value of `0`. A `while` loop is created to continuously process the dataset. The `cursor` variable is initially set to `null` since we are starting from the very beginning of the dataset and don't have a previous position to continue from. The dataset is queried for any requests that have been made to `example.com` using the HTTPQL statement `req.host.eq:"example.com"` in the `.filter()` method. With `.first(1000)` the query processes batches of 1,000 requests at a time.

```ts
export async function fetchRequests(sdk: SDK) {
  let totalRequestsQueried = 0;

  while (true) {
    let cursor = null;
    let query = sdk.requests
      .query()
      .filter('req.host.eq:"example.com"')
      .first(1000);
```

Next, the request batches are sorted in ascending order, by their `created_at` time for a chronological view of the dataset. The `if` statement implements pagination by marking a cursor pointing to where the processing left off and instructs the query to start from this position, not the very beginning. With the query constructed, it is executed with the `await` directive to account for the processing time. The returned `RequestsConnection` object is stored in the `requests` variable.

```ts
    query = query.ascending("req", "created_at");

    if (cursor) {
      query = query.after(cursor);
    }

    const requests = await query.execute();
```

The number of requests that match the query in each processed batch are added to the existing total. The `if` statement checks if there are more pages to process. If there are more pages, `requests.pageInfo.endCursor` saves the cursor pointing to the last request of the current batch in the `cursor` variable. With this updated cursor, processing will always begin where it left off.

```ts
    totalRequestsQueried += requests.items.length;

    if (requests.pageInfo.hasNextPage) {
      cursor = requests.pageInfo.endCursor;
    } else {
      break;
    }
  }

  return totalRequestsQueried;
}
```

The `fetchRequests` function is [added to the API](/plugins/guides/rpc.md) and exported so it can be used in other files. Finally, the base `SDK` is extended bu adding the `<API>`. In order to register the function, we use the `sdk.api.register()` method which takes two parameters: a string name for the function and the function it refers to. We give the name `"fetchRequests"` to the `fetchRequests` function.

```ts
export type API = DefineAPI<{
  fetchRequests: typeof fetchRequests;
}>;

export async function init(sdk: SDK<API>) {
  sdk.api.register("fetchRequests", fetchRequests);
}
```

::: tip
To view how the endpoint can be called with a frontend plugin, expand the following:

```vue
<script setup lang="ts">
import Button from "primevue/button";
import InputText from "primevue/inputtext";
import DataTable from "primevue/datatable";
import Column from "primevue/column";
import { ref } from "vue";

import { useSDK } from "@/plugins/sdk";

// Retrieve the SDK instance to interact with the backend.
const sdk = useSDK();

const loading = ref(false);
const result = ref<number | null>(null);

const fetchRequests = async () => {
  loading.value = true;
  try {
    // Call the backend fetchRequests function.
    result.value = await sdk.backend.fetchRequests();
  } catch (e) {
    console.error("Error fetching requests:", e);
    result.value = null;
  } finally {
    loading.value = false;
  }
};
</script>

<template>
  <div class="p-4">
    <Button
      label="Fetch Requests"
      :loading="loading"
      @click="fetchRequests"
      class="mb-2"
    />
    <div v-if="result !== null">
      <p>Total requests queried: {{ result }}</p>
    </div>
  </div>
</template>
```

---

---
url: /plugins/reference/sdks/frontend/files.md
---
# Files

### Asset

> **Asset** = `object`

A static asset.

#### Properties

##### asArrayBuffer()

> **asArrayBuffer**: () => `Promise`<`ArrayBuffer`>

###### Returns

`Promise`<`ArrayBuffer`>

##### asJson()

> **asJson**: <`T`>() => `Promise`<`T`>

###### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `T` | `unknown` |

###### Returns

`Promise`<`T`>

##### asReadableStream()

> **asReadableStream**: () => `ReadableStream`

###### Returns

`ReadableStream`

##### asString()

> **asString**: () => `Promise`<`string`>

###### Returns

`Promise`<`string`>

***

### AssetsSDK

> **AssetsSDK** = `object`

Utilities to interact with the plugin's static assets.

#### Properties

##### get()

> **get**: (`path`: `string`) => `Promise`<[`Asset`](#asset)>

Get a file from the assets folder.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `path` | `string` |

###### Returns

`Promise`<[`Asset`](#asset)>

The asset file.

***

### FilesPageContext

> **FilesPageContext** = `object`

Files page context.

#### Properties

##### kind

> **kind**: `"Files"`

***

### FilesSDK

> **FilesSDK** = `object`

SDK for interacting with the Files page.

#### Properties

##### create()

> **create**: (`file`: `File`) => `Promise`<[`HostedFile`](#hostedfile)>

Uploads a file to the host.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `file` | `File` | The file to upload. |

###### Returns

`Promise`<[`HostedFile`](#hostedfile)>

The uploaded file.

##### delete()

> **delete**: (`id`: `string`) => `Promise`<`void`>

Deletes a file from the host.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | `string` | The ID of the file to delete. |

###### Returns

`Promise`<`void`>

The deleted file.

##### getAll()

> **getAll**: () => [`HostedFile`](#hostedfile)\[]

Gets all hosted files.

###### Returns

[`HostedFile`](#hostedfile)\[]

The files.

##### onDeletedHostedFile()

> **onDeletedHostedFile**: (`callback`: (`fileId`: `string`) => `void`) => `ListenerHandle`

Listen for deleted hosted files.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `callback` | (`fileId`: `string`) => `void` | The callback function that receives the file ID. |

###### Returns

`ListenerHandle`

A handle object with a `stop` method to stop listening.

###### Example

```ts
const handle = sdk.files.onDeletedHostedFile((fileId) => {
  console.log(`Hosted file deleted:`, fileId);
});

// Later, stop listening
handle.stop();
```

##### onUpdatedHostedFile()

> **onUpdatedHostedFile**: (`callback`: (`event`: [`HostedFile`](#hostedfile)) => `void`) => `ListenerHandle`

Listen for updated hosted files.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `callback` | (`event`: [`HostedFile`](#hostedfile)) => `void` | The callback function that receives the hosted file. |

###### Returns

`ListenerHandle`

A handle object with a `stop` method to stop listening.

###### Example

```ts
const handle = sdk.files.onUpdatedHostedFile((hostedFile) => {
  console.log(`Hosted file updated:`, hostedFile);
});

// Later, stop listening
handle.stop();
```

##### onUploadedHostedFile()

> **onUploadedHostedFile**: (`callback`: (`event`: [`HostedFile`](#hostedfile)) => `void`) => `ListenerHandle`

Listen for uploaded hosted files.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `callback` | (`event`: [`HostedFile`](#hostedfile)) => `void` | The callback function that receives the hosted file. |

###### Returns

`ListenerHandle`

A handle object with a `stop` method to stop listening.

###### Example

```ts
const handle = sdk.files.onUploadedHostedFile((hostedFile) => {
  console.log(`Hosted file uploaded:`, hostedFile);
});

// Later, stop listening
handle.stop();
```

##### rename()

> **rename**: (`id`: `string`, `name`: `string`) => `Promise`<[`HostedFile`](#hostedfile)>

Renames a file on the host.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | `string` | The ID of the file to rename. |
| `name` | `string` | The new name of the file. |

###### Returns

`Promise`<[`HostedFile`](#hostedfile)>

The renamed file.

***

### HostedFile

> **HostedFile** = `object`

A hosted file.

#### Properties

##### createdAt

> **createdAt**: `Date`

The date the file was created.

##### id

> **id**: `string`

The ID of the file.

##### name

> **name**: `string`

The name of the file.

##### path

> **path**: `string`

The path of the file.

##### size

> **size**: `number`

The size of the file in bytes.

##### status

> **status**: `"ready"` | `"error"`

The status of the file.

##### updatedAt

> **updatedAt**: `Date`

The date the file was updated.

---

---
url: /plugins/reference/sdks/frontend/filter.md
---
# Filter

### FilterSlotContent

> **FilterSlotContent** = `object`

Content that can be added to filter slots.

#### Properties

##### create-header

> **create-header**: [`ButtonSlotContent`](slots.md#buttonslotcontent) | [`CustomSlotContent`](slots.md#customslotcontent) | [`CommandSlotContent`](slots.md#commandslotcontent)

##### update-header

> **update-header**: [`ButtonSlotContent`](slots.md#buttonslotcontent) | [`CustomSlotContent`](slots.md#customslotcontent) | [`CommandSlotContent`](slots.md#commandslotcontent)

---

---
url: /plugins/reference/sdks/frontend/filters.md
---
# Filters

### CurrentFilterChangeEvent

> **CurrentFilterChangeEvent** = `object`

Event fired when the current filter changes.

#### Properties

##### filterId

> **filterId**: [`ID`](utils.md#id) | `undefined`

The ID of the newly selected filter, or undefined if no filter is selected.

***

### Filter

> **Filter** = `object`

Represents a filter.

#### Properties

##### alias

> **alias**: `string`

The alias of the filter.
This alias is used when referencing the filter in an HTTPQL query (e.g. `preset:my-alias`).

##### id

> **id**: [`ID`](utils.md#id)

The ID of the filter.

##### name

> **name**: `string`

The name of the filter.

##### query

> **query**: [`HTTPQL`](utils.md#httpql)

The HTTPQL expression of the filter.

***

### FilterPageContext

> **FilterPageContext** = `object`

Filter page context.

#### Properties

##### kind

> **kind**: `"Filter"`

##### selection

> **selection**: [`Selection`](utils.md#selection)<[`ID`](utils.md#id)>

***

### FiltersSDK

> **FiltersSDK** = `object`

SDK for interacting with the Filters page.

#### Properties

##### addToSlot

> **addToSlot**: [`DefineAddToSlotFn`](slots.md#defineaddtoslotfn)<[`FilterSlotContent`](filter.md#filterslotcontent)>

Add a component to a slot.

###### Param

The slot to add the component to.

###### Param

The content to add to the slot.

###### Example

```ts
sdk.filters.addToSlot(FilterSlot.UpdateHeader, {
  type: "Button",
  label: "My Button",
  icon: "my-icon",
  onClick: () => {
    console.log("Button clicked");
  },
});

sdk.filters.addToSlot(FilterSlot.CreateHeader, {
  type: "Custom",
  definition: MyComponent,
});

sdk.filters.addToSlot(FilterSlot.UpdateHeader, {
  type: "Command",
  commandId: "my-command",
  icon: "my-icon",
});
```

##### create()

> **create**: (`options`: `object`) => `Promise`<[`Filter`](#filter)>

Creates a filter.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | { `alias`: `string`; `name`: `string`; `query`: [`HTTPQL`](utils.md#httpql); } | Options for the filter. |
| `options.alias` | `string` | The alias of the filter. Used when referencing the filter in an HTTPQL query (e.g. `preset:my-alias`). Should be unique and follow the format `[a-zA-Z0-9_-]+`. |
| `options.name` | `string` | The name of the filter. Should be unique. |
| `options.query` | [`HTTPQL`](utils.md#httpql) | The HTTPQL query of the filter. |

###### Returns

`Promise`<[`Filter`](#filter)>

The created filter.

##### delete()

> **delete**: (`id`: [`ID`](utils.md#id)) => `Promise`<`void`>

Deletes a filter.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](utils.md#id) | The ID of the filter to delete. |

###### Returns

`Promise`<`void`>

##### getAll()

> **getAll**: () => [`Filter`](#filter)\[]

Gets all filters.

###### Returns

[`Filter`](#filter)\[]

The filters.

##### getCurrentFilter()

> **getCurrentFilter**: () => [`Filter`](#filter) | `undefined`

Get the currently selected filter.

###### Returns

[`Filter`](#filter) | `undefined`

The currently selected filter, or undefined if no filter is selected.

##### onCurrentFilterChange()

> **onCurrentFilterChange**: (`callback`: (`event`: [`CurrentFilterChangeEvent`](#currentfilterchangeevent)) => `void`) => [`ListenerHandle`](utils.md#listenerhandle)

Subscribe to current filter changes.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `callback` | (`event`: [`CurrentFilterChangeEvent`](#currentfilterchangeevent)) => `void` | The callback to call when the selected filter changes. |

###### Returns

[`ListenerHandle`](utils.md#listenerhandle)

An object with a `stop` method that can be called to stop listening to filter changes.

###### Example

```ts
const handler = sdk.filters.onCurrentFilterChange((event) => {
  console.log(`Filter ${event.filterId} got selected!`);
});

// Later, stop listening
handler.stop();
```

##### update()

> **update**: (`id`: [`ID`](utils.md#id), `options`: `object`) => `Promise`<[`Filter`](#filter)>

Updates a filter.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](utils.md#id) | The ID of the filter to update. |
| `options` | { `alias`: `string`; `name`: `string`; `query`: [`HTTPQL`](utils.md#httpql); } | Options for the filter. |
| `options.alias` | `string` | The alias of the filter. |
| `options.name` | `string` | The name of the filter. |
| `options.query` | [`HTTPQL`](utils.md#httpql) | The HTTPQL query of the filter. |

###### Returns

`Promise`<[`Filter`](#filter)>

The updated filter.

***

### FilterSlot

> `const` **FilterSlot**: `object`

The slots in the Filters UI.

#### Type Declaration

##### CreateHeader

> `readonly` **CreateHeader**: `"create-header"`

The header area of the preset form create component.

##### UpdateHeader

> `readonly` **UpdateHeader**: `"update-header"`

The header area of the preset form update component.

---

---
url: /plugins/reference/sdks/backend/findings.md
---
# Findings

### DedupeKey

> **DedupeKey** = `string` & `object`

A deduplication key.

#### Type Declaration

##### \_\_dedupeKey?

> `optional` **\_\_dedupeKey**: `never`

***

### Finding

> **Finding** = `object`

A saved immutable Finding.

#### Methods

##### getDedupeKey()

> **getDedupeKey**(): [`DedupeKey`](#dedupekey) | `undefined`

The deduplication key of the finding.

###### Returns

[`DedupeKey`](#dedupekey) | `undefined`

##### getDescription()

> **getDescription**(): `string` | `undefined`

The description of the finding.

###### Returns

`string` | `undefined`

##### getId()

> **getId**(): [`ID`](shared.md#id)

The unique Caido [ID](shared.md#id) of the finding.

###### Returns

[`ID`](shared.md#id)

##### getReporter()

> **getReporter**(): `string`

The name of the reporter.

###### Returns

`string`

##### getRequestId()

> **getRequestId**(): `string`

The ID of the associated [Request](requests.md#request).

###### Returns

`string`

##### getTitle()

> **getTitle**(): `string`

The title of the finding.

###### Returns

`string`

***

### FindingSpec

> **FindingSpec** = `object`

A mutable Finding not yet created.

#### Properties

##### dedupeKey?

> `optional` **dedupeKey**: [`DedupeKey`](#dedupekey)

Deduplication key for findings.
If a finding with the same dedupe key already exists, it will not be created.

##### description?

> `optional` **description**: `string`

The description of the finding.

##### reporter

> **reporter**: `string`

The name of the reporter.
It will be used to group findings.

##### request

> **request**: [`Request`](requests.md#request)

The associated [Request](requests.md#request).

##### title

> **title**: `string`

The title of the finding.

***

### FindingsSDK

> **FindingsSDK** = `object`

The SDK for the Findings service.

#### Methods

##### create()

> **create**(`spec`: [`FindingSpec`](#findingspec)): `Promise`<[`Finding`](#finding)>

Creates a new Finding.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `spec` | [`FindingSpec`](#findingspec) |

###### Returns

`Promise`<[`Finding`](#finding)>

###### Throws

If the request cannot be saved.

###### Example

```js
await sdk.findings.create({
  title: "Title",
  description: "Description",
  reporter: "Reporter",
  dedupeKey: `${request.getHost()}-${request.getPath()}`,
  request,
});
```

##### exists()

> **exists**(`input`: [`GetFindingInput`](#getfindinginput)): `Promise`<`boolean`>

Check if a [Finding](#finding) exists.
Similar to `get`, but returns a boolean.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | [`GetFindingInput`](#getfindinginput) |

###### Returns

`Promise`<`boolean`>

###### Example

```js
await sdk.findings.exists("my-dedupe-key");
```

##### get()

> **get**(`input`: [`GetFindingInput`](#getfindinginput)): `Promise`<[`Finding`](#finding) | `undefined`>

Try to get a [Finding](#finding) for a request.

Since a request can have multiple findings, this will return the first one found.
You can also filter by reporter to get a specific finding.

Finally, you can use a deduplication key to get a specific finding.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | [`GetFindingInput`](#getfindinginput) |

###### Returns

`Promise`<[`Finding`](#finding) | `undefined`>

###### Example

```js
await sdk.findings.get({
 reporter: "Reporter",
 request,
});
```

***

### GetFindingInput

> **GetFindingInput** = [`DedupeKey`](#dedupekey) | { `reporter?`: `string`; `request`: [`Request`](requests.md#request); }

Input to get a [Finding](#finding).

#### Type Declaration

[`DedupeKey`](#dedupekey)

{ `reporter?`: `string`; `request`: [`Request`](requests.md#request); }

##### reporter?

> `optional` **reporter**: `string`

The name of the reporter.

##### request

> **request**: [`Request`](requests.md#request)

The associated [Request](requests.md#request).

---

---
url: /plugins/reference/sdks/frontend/findings.md
---
# Findings

### Finding

> **Finding** = `object`

Represents a <https://docs.caido.io/reference/features/logging/findings|Finding>.

#### Properties

##### description?

> `optional` **description**: `string`

The description of the finding.

##### host

> **host**: `string`

The host of the request attached to this finding

##### id

> **id**: [`ID`](utils.md#id)

The ID of the finding.

##### path

> **path**: `string`

The path of the request attached to this finding

##### reporter

> **reporter**: `string`

The reporter of the finding.

##### title

> **title**: `string`

The title of the finding.

***

### FindingsPageContext

> **FindingsPageContext** = `object`

Findings page context.

#### Properties

##### kind

> **kind**: `"Findings"`

##### selection

> **selection**: [`Selection`](utils.md#selection)<[`ID`](utils.md#id)>

***

### FindingsSDK

> **FindingsSDK** = `object`

Utilities to interact with findings

#### Properties

##### addRequestEditorExtension()

> **addRequestEditorExtension**: (`extension`: `Extension`) => `void`

Add an extension to the request editor.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `extension` | `Extension` | The extension to add. |

###### Returns

`void`

##### addRequestViewMode()

> **addRequestViewMode**: (`options`: [`RequestViewModeOptions`](request.md#requestviewmodeoptions)) => `void`

Add a custom request view mode.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`RequestViewModeOptions`](request.md#requestviewmodeoptions) | The view mode options. |

###### Returns

`void`

##### addResponseViewMode()

> **addResponseViewMode**: (`options`: [`ResponseViewModeOptions`](response.md#responseviewmodeoptions)) => `void`

Add a custom response view mode.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`ResponseViewModeOptions`](response.md#responseviewmodeoptions) | The view mode options. |

###### Returns

`void`

##### createFinding()

> **createFinding**: (`requestId`: [`ID`](utils.md#id), `options`: `object`) => `Promise`<[`Finding`](#finding) | `undefined`>

Create a [Finding](#finding).

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `requestId` | [`ID`](utils.md#id) | The id of the request the finding is associated with. |
| `options` | { `dedupeKey?`: `string`; `description?`: `string`; `reporter`: `string`; `title`: `string`; } | Options for the finding. |
| `options.dedupeKey?` | `string` | If a finding with the same deduplication key already exists, it will not create a new finding. |
| `options.description?` | `string` | The description of the finding. |
| `options.reporter` | `string` | The reporter of the finding. |
| `options.title` | `string` | The title of the finding. |

###### Returns

`Promise`<[`Finding`](#finding) | `undefined`>

The created finding.

---

---
url: /plugins/reference/sdks/workflow/findings.md
---
# Findings

### DedupeKey

> **DedupeKey** = `string` & `object`

A deduplication key.

#### Type Declaration

##### \_\_dedupeKey?

> `optional` **\_\_dedupeKey**: `never`

***

### Finding

> **Finding** = `object`

A saved immutable Finding.

#### Methods

##### getDedupeKey()

> **getDedupeKey**(): [`DedupeKey`](#dedupekey) | `undefined`

The deduplication key of the finding.

###### Returns

[`DedupeKey`](#dedupekey) | `undefined`

##### getDescription()

> **getDescription**(): `string` | `undefined`

The description of the finding.

###### Returns

`string` | `undefined`

##### getId()

> **getId**(): [`ID`](shared.md#id)

The unique Caido [ID](shared.md#id) of the finding.

###### Returns

[`ID`](shared.md#id)

##### getReporter()

> **getReporter**(): `string`

The name of the reporter.

###### Returns

`string`

##### getRequestId()

> **getRequestId**(): `string`

The ID of the associated [Request](requests.md#request).

###### Returns

`string`

##### getTitle()

> **getTitle**(): `string`

The title of the finding.

###### Returns

`string`

***

### FindingSpec

> **FindingSpec** = `object`

A mutable Finding not yet created.

#### Properties

##### dedupeKey?

> `optional` **dedupeKey**: [`DedupeKey`](#dedupekey)

Deduplication key for findings.
If a finding with the same dedupe key already exists, it will not be created.

##### description?

> `optional` **description**: `string`

The description of the finding.

##### reporter

> **reporter**: `string`

The name of the reporter.
It will be used to group findings.

##### request

> **request**: [`Request`](requests.md#request)

The associated [Request](requests.md#request).

##### title

> **title**: `string`

The title of the finding.

***

### FindingsSDK

> **FindingsSDK** = `object`

The SDK for the Findings service.

#### Methods

##### create()

> **create**(`spec`: [`FindingSpec`](#findingspec)): `Promise`<[`Finding`](#finding)>

Creates a new Finding.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `spec` | [`FindingSpec`](#findingspec) |

###### Returns

`Promise`<[`Finding`](#finding)>

###### Throws

If the request cannot be saved.

###### Example

```js
await sdk.findings.create({
  title: "Title",
  description: "Description",
  reporter: "Reporter",
  dedupeKey: `${request.getHost()}-${request.getPath()}`,
  request,
});
```

##### exists()

> **exists**(`input`: [`GetFindingInput`](#getfindinginput)): `Promise`<`boolean`>

Check if a [Finding](#finding) exists.
Similar to `get`, but returns a boolean.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | [`GetFindingInput`](#getfindinginput) |

###### Returns

`Promise`<`boolean`>

###### Example

```js
await sdk.findings.exists("my-dedupe-key");
```

##### get()

> **get**(`input`: [`GetFindingInput`](#getfindinginput)): `Promise`<[`Finding`](#finding) | `undefined`>

Try to get a [Finding](#finding) for a request.

Since a request can have multiple findings, this will return the first one found.
You can also filter by reporter to get a specific finding.

Finally, you can use a deduplication key to get a specific finding.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | [`GetFindingInput`](#getfindinginput) |

###### Returns

`Promise`<[`Finding`](#finding) | `undefined`>

###### Example

```js
await sdk.findings.get({
 reporter: "Reporter",
 request,
});
```

***

### GetFindingInput

> **GetFindingInput** = [`DedupeKey`](#dedupekey) | { `reporter?`: `string`; `request`: [`Request`](requests.md#request); }

Input to get a [Finding](#finding).

#### Type Declaration

[`DedupeKey`](#dedupekey)

{ `reporter?`: `string`; `request`: [`Request`](requests.md#request); }

##### reporter?

> `optional` **reporter**: `string`

The name of the reporter.

##### request

> **request**: [`Request`](requests.md#request)

The associated [Request](requests.md#request).

---

---
url: /plugins/reference/sdks/frontend/footer.md
---
# Footer

### FooterSDK

> **FooterSDK** = `object`

Utilities to interact with the footer.

#### Properties

##### addToSlot

> **addToSlot**: [`DefineAddToSlotFn`](slots.md#defineaddtoslotfn)<[`FooterSlotContent`](#footerslotcontent)>

Add a component to a slot.

###### Param

The slot to add the component to.

###### Param

The content to add to the slot.

###### Example

```ts
addToSlot(FooterSlot.FooterSlotPrimary, {
  kind: "Command",
  commandId: "my-command",
  icon: "my-icon",
});

addToSlot(FooterSlot.FooterSlotPrimary, {
  kind: "Button",
  label: "My button",
  icon: "fas fa-rocket",
  onClick: () => {
    console.log("Button clicked");
  },
});

addToSlot(FooterSlot.FooterSlotSecondary, {
  kind: "Custom",
  component: MyComponent,
});
```

***

### FooterSlotContent

> **FooterSlotContent** = `object`

Content that can be added to footer slots.

#### Properties

##### footer-primary

> **footer-primary**: [`ButtonSlotContent`](slots.md#buttonslotcontent) | [`CustomSlotContent`](slots.md#customslotcontent) | [`CommandSlotContent`](slots.md#commandslotcontent)

##### footer-secondary

> **footer-secondary**: [`ButtonSlotContent`](slots.md#buttonslotcontent) | [`CustomSlotContent`](slots.md#customslotcontent) | [`CommandSlotContent`](slots.md#commandslotcontent)

***

### FooterSlot

> `const` **FooterSlot**: `object`

The slots in the Footer UI.

#### Type Declaration

##### FooterSlotPrimary

> `readonly` **FooterSlotPrimary**: `"footer-primary"`

##### FooterSlotSecondary

> `readonly` **FooterSlotSecondary**: `"footer-secondary"`

---

---
url: /plugins/guides/runtime.md
---
# Get Version Information

You can retrieve the current Caido version to check compatibility, enable version-specific features, or display version information in your plugin.

## Getting the Version

To get the current Caido version:

```ts
const version = sdk.runtime.version;
```

The version is returned as a string (e.g., `"1.0.0"`).

::: warning
Always test your plugin on the minimum required version to ensure compatibility. Version checks help prevent runtime errors but don't guarantee feature availability.
:::

## Examples

### Version Check

This example checks if the current Caido version meets a minimum requirement (1.2.0). It parses the version string, compares it to the minimum version, and displays a warning toast if the version is too old.

```ts
import type { Caido } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  const version = sdk.runtime.version;
  sdk.log.info(`Caido version: ${version}`);

  // Check for minimum version
  const [major, minor, patch] = version.split(".").map(Number);
  if (major < 1 || (major === 1 && minor < 2)) {
    sdk.window.showToast("This plugin requires Caido 1.2.0 or higher", {
      variant: "warning",
    });
  }
};
```

### Version Display

This example displays the current Caido version and plugin compatibility status.

```vue
<script setup lang="ts">
import { inject, computed } from "vue";

const sdk = inject<CaidoSDK>("sdk");
const version = computed(() => sdk?.runtime.version || "Unknown");
</script>

<template>
  <div class="p-4">
    <div class="p-4 bg-gray-800 rounded">
      <h3 class="text-lg font-bold mb-2">Caido Version</h3>
      <p><strong>Version:</strong> {{ version }}</p>
      <p><strong>Plugin Compatibility:</strong> ✓ Compatible</p>
    </div>
  </div>
</template>
```

::: info
For information on creating pages and setting up Vue components, see [Create a Page](/plugins/guides/page.md).
:::

::: tip
Use version checks to ensure your plugin works correctly across different Caido versions and to provide helpful error messages when requirements aren't met.
:::

::: info
Version strings follow semantic versioning (major.minor.patch). Parse the version string to compare versions programmatically.
:::

---

---
url: /plugins/guides.md
---
# Getting Started

Caido allows users to develop custom features in the form of plugins.

Plugin development is done in JavaScript and consists of many parts:

* A `caido.config.ts`/`manifest.json` file
* A frontend plugin
* A backend plugin

These parts are packaged together in a single entity known as a **plugin package**.

For more information on the structure of a plugin package, see [Plugin Architecture](/plugins/concepts/package.md).

## Creating a Plugin Package

::: info Requirements
Plugins are developed in JavaScript and require the following to be installed on your device:

* [Node.js](https://nodejs.org/en/) (Version 18+ or 20+)
* [pnpm](https://pnpm.io/installation)

:::

To get started with plugin development, run the following command:

```bash
pnpm create @caido-community/plugin
```

Then follow the prompts! This will create a new directory containing a template plugin package.

From inside the package directory, run the following command to install the project dependencies:

```bash
pnpm install
```

Finally, run the following command to build your plugin into a `dist/plugin_package.zip` file:

```bash
pnpm build
```

You can then install this plugin package directly from the Caido application.

## Hot Reload

Instead of uninstalling, rebuilding, and installing your plugin to view the changes you make during development, Caido offers the [Devtools](https://github.com/caido-community/devtools) plugin that will auto-update the plugin whenever code changes are detected.

To use the Devtools plugin:

1. First navigate to the [Plugins](https://docs.caido.io/app/quickstart/plugins) interface, select Community Store, and click `+ Install`.

2. Next, run the following command from the root directory of the plugin to both build and watch for file changes:

```bash
pnpm watch
```

3. Then, input the development server URL in the Devtools plugin and click the `Connect` button.

## What's next?

Now that you've created your first package, you can start building out your own frontend and backend plugins.

We highly recommend looking at existing plugins in the [Community Store](https://github.com/caido-community) to get an idea of what's possible. All plugins are open-sourced and available for you to review and learn from.

There are also a few guides available on this site to help you get started.

::: tip
[Learn how to leverage AI tools to build Caido plugins.](./vibe_coding.md)
:::

---

---
url: /client-sdk/concepts/community_golang.md
---
# Golang SDK

A community-maintained Go port of the official [JavaScript Client SDK](https://github.com/caido/sdk-js), hosted at [`caido-community/sdk-go`](https://github.com/caido-community/sdk-go) under the MIT license. It mirrors the API surface of `@caido/sdk-client` and uses [`genqlient`](https://github.com/Khan/genqlient) for type-safe GraphQL code generation, tracking the same schema the official SDK consumes.

The Go SDK exposes the same domain-specific clients as the JavaScript SDK (requests, intercept, replay, findings, scopes, projects, environments, hosted files, workflows, tasks, filters, plugins, and more), plus low-level GraphQL access for operations not covered by domain methods.

Initialization mirrors the JavaScript SDK's `Client` constructor:

```go
client, _ := caido.NewClient(caido.Options{
    URL:  "http://localhost:8080",
    Auth: caido.PATAuth("caido_xxxxx"),
})
client.Connect(context.Background())
```

## Differences from the JavaScript SDK

Coverage of the authentication model is intentional rather than exhaustive:

* **Browser Login** is not exposed in the public API. Only [Personal Access Token](./auth_methods.md#personal-access-token) (`caido.PATAuth`) and [Direct Token](./auth_methods.md#direct-token) (`caido.TokenAuth(accessToken, refreshToken)`) are supported.
* **[Token caching](./auth_caching.md)** is not built in. Tokens are held in memory for the lifetime of the `Client`, and refresh is driven by an optional `TokenRefreshFunc` callback that the script provides. Persisting tokens across runs is the script's responsibility.

---

---
url: /plugins/reference/sdks/backend/graphql.md
---
# GraphQL

### GraphQLError

> **GraphQLError** = `object`

An error from a GraphQL query.

#### Properties

##### extensions

> **extensions**: `Record`<`string`, `any`>

##### locations

> **locations**: [`GraphQLLocation`](#graphqllocation)\[]

##### message

> **message**: `string`

##### path

> **path**: [`GraphQLPathSegment`](#graphqlpathsegment)\[]

***

### GraphQLLocation

> **GraphQLLocation** = `object`

A location in a GraphQL query.

#### Properties

##### column

> **column**: `number`

##### line

> **line**: `number`

***

### GraphQLPathSegment

> **GraphQLPathSegment** = `string` | `number`

A segment of a path in a GraphQL query.

***

### GraphQLResponse

> **GraphQLResponse**<`T`> = `object`

The response from a GraphQL query.

#### Type Parameters

| Type Parameter |
| ------ |
| `T` |

#### Properties

##### data?

> `optional` **data**: `T`

##### errors?

> `optional` **errors**: [`GraphQLError`](#graphqlerror)\[]

***

### GraphQLSDK

> **GraphQLSDK** = `object`

The SDK for the GraphQL service.

#### Methods

##### execute()

> **execute**<`T`>(`query`: `string`, `variables?`: `Record`<`string`, `any`>): `Promise`<[`GraphQLResponse`](#graphqlresponse)<`T`>>

Executes a GraphQL query.

###### Type Parameters

| Type Parameter |
| ------ |
| `T` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `query` | `string` |
| `variables?` | `Record`<`string`, `any`> |

###### Returns

`Promise`<[`GraphQLResponse`](#graphqlresponse)<`T`>>

###### Example

```js
await sdk.graphql.execute(`
  query {
    viewer
  }
`);
```

---

---
url: /plugins/reference/sdks/workflow/graphql.md
---
# GraphQL

### GraphQLError

> **GraphQLError** = `object`

An error from a GraphQL query.

#### Properties

##### extensions

> **extensions**: `Record`<`string`, `any`>

##### locations

> **locations**: [`GraphQLLocation`](#graphqllocation)\[]

##### message

> **message**: `string`

##### path

> **path**: [`GraphQLPathSegment`](#graphqlpathsegment)\[]

***

### GraphQLLocation

> **GraphQLLocation** = `object`

A location in a GraphQL query.

#### Properties

##### column

> **column**: `number`

##### line

> **line**: `number`

***

### GraphQLPathSegment

> **GraphQLPathSegment** = `string` | `number`

A segment of a path in a GraphQL query.

***

### GraphQLResponse

> **GraphQLResponse**<`T`> = `object`

The response from a GraphQL query.

#### Type Parameters

| Type Parameter |
| ------ |
| `T` |

#### Properties

##### data?

> `optional` **data**: `T`

##### errors?

> `optional` **errors**: [`GraphQLError`](#graphqlerror)\[]

***

### GraphQLSDK

> **GraphQLSDK** = `object`

The SDK for the GraphQL service.

#### Methods

##### execute()

> **execute**<`T`>(`query`: `string`, `variables?`: `Record`<`string`, `any`>): `Promise`<[`GraphQLResponse`](#graphqlresponse)<`T`>>

Executes a GraphQL query.

###### Type Parameters

| Type Parameter |
| ------ |
| `T` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `query` | `string` |
| `variables?` | `Record`<`string`, `any`> |

###### Returns

`Promise`<[`GraphQLResponse`](#graphqlresponse)<`T`>>

###### Example

```js
await sdk.graphql.execute(`
  query {
    viewer
  }
`);
```

---

---
url: /plugins/guides/backend_events.md
---
# Handle Backend Events

In this guide, you will learn how to handle backend events in the frontend of your Caido plugin.

This can be accomplished using the three event handlers provided by the SDK:

## Listening for Project Changes

An event will be triggered when the active [Project](https://docs.caido.io/app/quickstart/workspace) changes.

### /packages/backend/src/index.ts

```ts
import type { DefineAPI, SDK } from "caido:plugin";

export type API = DefineAPI<{}>;

let previousProject: string | null = null;

export function init(sdk: SDK<API>) {
  sdk.events.onProjectChange((sdk, project) => {
    const newProjectName = project?.getName() ?? null;
    sdk.console.log(`Project changed from "${previousProject}" to "${newProjectName}."`);
    previousProject = newProjectName;
  });
}
```

## The Result

```txt
Project changed from "Caido" to "Example".
```

## Intercepting Requests and Responses

An event will be triggered with `onInterceptRequest` and `onInterceptResponse` when a request or response is proxied through Caido respectively.

### /packages/backend/src/index.ts

```ts
import type { DefineAPI, SDK } from "caido:plugin";
import type { Request, Response } from "caido:utils";

export type API = DefineAPI<{}>;

export function init(sdk: SDK<API>) {
  sdk.events.onInterceptRequest((sdk, request: Request) => {
    sdk.console.log(`Intercepted ${request.getMethod()} request to ${request.getUrl()}`);
  });

  sdk.events.onInterceptResponse((sdk, request: Request, response: Response) => {
    sdk.console.log(`Intercepted response from ${request.getUrl()} with status ${response.getCode()}`);
  });
}
```

## The Result

```txt
Intercepted GET request to https://example.com/path
Intercepted response from https://example.com/path with status 304
```

---

---
url: /plugins/reference/sdks/backend/hostedfile.md
---
# HostedFile

### HostedFile

> **HostedFile** = `object`

A hosted file.

#### Properties

##### id

> **id**: `string`

The unique Caido [ID](shared.md#id) of the project.

##### name

> **name**: `string`

The name of the project.

##### path

> **path**: `string`

The path of the file.

***

### HostedFileSDK

> **HostedFileSDK** = `object`

The SDK for the HostedFile service.

#### Methods

##### create()

> **create**(`spec`: [`HostedFileSpec`](#hostedfilespec)): `Promise`<[`HostedFile`](#hostedfile)>

Create a hosted file.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `spec` | [`HostedFileSpec`](#hostedfilespec) |

###### Returns

`Promise`<[`HostedFile`](#hostedfile)>

###### Example

```js
await sdk.hostedFile.create({ name: "My File", content: "Hello, world!" });
```

##### getAll()

> **getAll**(): `Promise`<[`HostedFile`](#hostedfile)\[]>

Get all hosted files.

###### Returns

`Promise`<[`HostedFile`](#hostedfile)\[]>

###### Example

```js
await sdk.hostedFile.getAll();
```

***

### HostedFileSpec

> **HostedFileSpec** = `object`

A specification for creating a hosted file.

#### Properties

##### content

> **content**: [`Bytes`](shared.md#bytes)

##### name

> **name**: `string`

---

---
url: /plugins/reference/sdks/workflow/hostedfile.md
---
# HostedFile

### HostedFile

> **HostedFile** = `object`

A hosted file.

#### Properties

##### id

> **id**: `string`

The unique Caido [ID](shared.md#id) of the project.

##### name

> **name**: `string`

The name of the project.

##### path

> **path**: `string`

The path of the file.

***

### HostedFileSDK

> **HostedFileSDK** = `object`

The SDK for the HostedFile service.

#### Methods

##### create()

> **create**(`spec`: [`HostedFileSpec`](#hostedfilespec)): `Promise`<[`HostedFile`](#hostedfile)>

Create a hosted file.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `spec` | [`HostedFileSpec`](#hostedfilespec) |

###### Returns

`Promise`<[`HostedFile`](#hostedfile)>

###### Example

```js
await sdk.hostedFile.create({ name: "My File", content: "Hello, world!" });
```

##### getAll()

> **getAll**(): `Promise`<[`HostedFile`](#hostedfile)\[]>

Get all hosted files.

###### Returns

`Promise`<[`HostedFile`](#hostedfile)\[]>

###### Example

```js
await sdk.hostedFile.getAll();
```

***

### HostedFileSpec

> **HostedFileSpec** = `object`

A specification for creating a hosted file.

#### Properties

##### content

> **content**: [`Bytes`](shared.md#bytes)

##### name

> **name**: `string`

---

---
url: /plugins/reference/sdks/frontend/http-history.md
---
# HTTP History

### HTTPHistoryPageContext

> **HTTPHistoryPageContext** = `object`

HTTP history page context.

#### Properties

##### kind

> **kind**: `"HTTPHistory"`

##### selection

> **selection**: [`Selection`](utils.md#selection)<[`ID`](utils.md#id)>

***

### HTTPHistorySDK

> **HTTPHistorySDK** = `object`

Utilities to interact with the HTTP History page.

#### Properties

##### addRequestEditorExtension()

> **addRequestEditorExtension**: (`extension`: `Extension`) => `void`

Add an extension to the request editor.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `extension` | `Extension` | The extension to add. |

###### Returns

`void`

##### addRequestViewMode()

> **addRequestViewMode**: (`options`: [`RequestViewModeOptions`](request.md#requestviewmodeoptions)) => `void`

Add a custom request view mode.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`RequestViewModeOptions`](request.md#requestviewmodeoptions) | The view mode options. |

###### Returns

`void`

##### addResponseEditorExtension()

> **addResponseEditorExtension**: (`extension`: `Extension`) => `void`

Add an extension to the response editor.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `extension` | `Extension` | The extension to add. |

###### Returns

`void`

##### addResponseViewMode()

> **addResponseViewMode**: (`options`: [`ResponseViewModeOptions`](response.md#responseviewmodeoptions)) => `void`

Add a custom response view mode.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`ResponseViewModeOptions`](response.md#responseviewmodeoptions) | The view mode options. |

###### Returns

`void`

##### addToSlot

> **addToSlot**: [`DefineAddToSlotFn`](slots.md#defineaddtoslotfn)<[`HTTPHistorySlotContent`](other.md#httphistoryslotcontent)>

Add a component to a slot.

###### Param

The slot to add the component to.

###### Param

The content to add to the slot.

###### Example

```ts
sdk.httpHistory.addToSlot(HTTPHistorySlot.ToolbarPrimary, {
  type: "Button",
  label: "My Button",
  icon: "my-icon",
  onClick: () => {
    console.log("Button clicked");
  },
});

sdk.httpHistory.addToSlot(HTTPHistorySlot.ToolbarPrimary, {
  type: "Custom",
  definition: MyComponent,
});

sdk.httpHistory.addToSlot(HTTPHistorySlot.ToolbarPrimary, {
  type: "Command",
  commandId: "my-command",
  icon: "my-icon",
});
```

##### getQuery()

> **getQuery**: () => [`HTTPQL`](utils.md#httpql)

Get the current HTTPQL query.

###### Returns

[`HTTPQL`](utils.md#httpql)

The current HTTPQL query.

##### getScopeId()

> **getScopeId**: () => [`ID`](utils.md#id) | `undefined`

Get the current scope ID.

###### Returns

[`ID`](utils.md#id) | `undefined`

The current scope ID.

##### scrollTo()

> **scrollTo**: (`id`: [`ID`](utils.md#id)) => `void`

Scrolls the HTTP History table to a specific entry.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](utils.md#id) | The ID of the entry to scroll to. |

###### Returns

`void`

##### setQuery()

> **setQuery**: (`query`: [`HTTPQL`](utils.md#httpql)) => `void`

Set the HTTPQL query that will be applied on the HTTP History table results.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `query` | [`HTTPQL`](utils.md#httpql) | The HTTPQL query. |

###### Returns

`void`

##### setScope()

> **setScope**: (`id`: [`ID`](utils.md#id) | `undefined`) => `Promise`<`void`>

Set the current scope.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](utils.md#id) | `undefined` | The ID of the scope to set. |

###### Returns

`Promise`<`void`>

***

### HTTPHistorySlot

> `const` **HTTPHistorySlot**: `object`

The slots in the HTTP History UI.

#### Type Declaration

##### ToolbarPrimary

> `readonly` **ToolbarPrimary**: `"toolbar-primary"`

The toolbar.

---

---
url: /client-sdk/guides/install_plugin.md
---
# Install a Plugin

The Client SDK can install plugin packages on your Caido instance programmatically. This is useful for scripting plugin deployment, bootstrapping CI/CD environments, or pre-configuring instances before handing them to other users.

The `client.plugin.install()` method accepts two source shapes:

1. **Manifest ID** to install a plugin published in the [Caido community store](https://github.com/caido/store).
2. **Package file** to install a plugin from a local `.zip` archive.

::: info
Both methods enable the installed plugins automatically. No separate enable step is required.
:::

## 1. Installing from the Caido Store

To install a plugin from the store, you need its **manifest ID**. This is the `id` field declared in the plugin's `manifest.json` file, and it is what uniquely identifies the plugin in the store. You can find it in the [store manifest](https://github.com/caido/store/blob/main/plugin_packages.json) or in the plugin's repository under [caido-community](https://github.com/caido-community).

### index.ts

```ts
import { Client } from "@caido/sdk-client";

async function main() {
  const client = new Client({
    url: "http://localhost:8080",
    auth: { pat: process.env["CAIDO_PAT"]! },
  });

  await client.connect();

  const pkg = await client.plugin.install({ manifestId: "scanner" });

  console.log("Installed:", pkg.manifestId);
}

main();
```

## 2. Installing from a Local Package File

To install a plugin from a local archive, you need its **plugin package**. This is a signed `.zip` file attached to each [plugin release](/plugins/guides/repository.md#5-create-a-release) on GitHub. Download the archive, load it into a `File` object, then pass it to `install()`.

### index.ts

```ts
import { readFileSync } from "node:fs";

import { Client } from "@caido/sdk-client";

async function main() {
  const client = new Client({
    url: "http://localhost:8080",
    auth: { pat: process.env["CAIDO_PAT"]! },
  });

  await client.connect();

  const buffer = readFileSync("./plugin_package.zip");
  const file = new File([new Uint8Array(buffer)], "plugin_package.zip", {
    type: "application/zip",
  });

  const pkg = await client.plugin.install({ file });

  console.log("Installed:", pkg.manifestId);
}

main();
```

## Re-installing an Existing Plugin

To re-install a plugin that is already installed, you need to bypass the version check that `install()` performs by default. Without it, the call rejects with an `AlreadyInstalled` error whenever the new version is not greater than the installed version. Pass `force: true` to overwrite the installed package regardless of version:

```ts
const pkg = await client.plugin.install({
  manifestId: "scanner",
  force: true,
});
```

## Reading the Returned Package Handle

When `install()` succeeds, it returns a `PluginPackageHandle` that describes the installed package and every plugin inside it. A single package can ship a backend plugin, a frontend plugin, and a workflow plugin, each with its own ID and `enabled` flag.

```txt
{
  id: "068a80a3-c1ab-4116-8b89-e7ee64be4534",
  manifestId: "scanner",
  plugins: [
    { kind: "PluginBackend",  manifestId: "backend",  enabled: true },
    { kind: "PluginFrontend", manifestId: "frontend", enabled: true }
  ]
}
```

The handle also exposes `callFunction()` and `subscribeEvent()` for interacting with a backend plugin's exported functions and events. Those are covered in the next guides.

## Examples

The script below bootstraps a Caido instance by installing several plugins from the store. Plugins that are already installed at the same or newer version are skipped, and the failure is reported without aborting the rest of the run.

### index.ts

```ts
import { Client } from "@caido/sdk-client";

async function main() {
  const client = new Client({
    url: process.env["CAIDO_INSTANCE_URL"] ?? "http://localhost:8080",
    auth: {
      pat: process.env["CAIDO_PAT"]!,
      cache: { file: ".caido-token.json" },
    },
  });

  await client.connect();

  const manifestIds = ["scanner", "quickssrf", "autorize"];

  for (const manifestId of manifestIds) {
    try {
      const pkg = await client.plugin.install({ manifestId });
      console.log(`Installed ${pkg.manifestId} (${pkg.plugins.length} plugins)`);
    } catch (error) {
      console.error(`Failed to install ${manifestId}:`, error);
    }
  }
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});
```

Run it with:

```bash
export CAIDO_PAT=caido_xxxxx
npx tsx ./index.ts
```

A successful run prints:

```txt
[caido] Loaded token from cache
Installed scanner (2 plugins)
Installed quickssrf (2 plugins)
Installed autorize (2 plugins)
```

---

---
url: /client-sdk/guides/install.md
---
# Install the SDK

The Caido Client SDK lets external scripts and tools interact with a Caido instance from outside the application. It handles authentication, GraphQL queries, and REST calls so you can focus on your automation logic.

::: info Requirements

* [Node.js](https://nodejs.org/en/) 18 or higher
* A package manager: [pnpm](https://pnpm.io/installation), [npm](https://www.npmjs.com/), or [yarn](https://yarnpkg.com/)
  :::

## Add the package

Install [`@caido/sdk-client`](https://www.npmjs.com/package/@caido/sdk-client) into your project:

::: code-group

```bash [pnpm]
pnpm add @caido/sdk-client
```

```bash [npm]
npm install @caido/sdk-client
```

```bash [yarn]
yarn add @caido/sdk-client
```

:::

## Import the client

The SDK exposes a `Client` class as the entry point for every API call. Create an `index.ts` file and instantiate the client with the URL of your Caido instance:

### index.ts

```ts
import { Client } from "@caido/sdk-client";

const client = new Client({
  url: "http://localhost:8080",
});
```

If your TypeScript or runtime resolves the import without errors, the SDK is installed correctly.

Continue to [Base Setup](./base_setup.md) to configure authentication and make your first call.

---

---
url: /plugins/guides/workflows.md
---
# Interact with Workflows

Workflows in Caido allow you to automate sequences of actions. You can programmatically retrieve workflows and subscribe to workflow lifecycle events to react to changes.

## Getting Workflows

To retrieve all workflows:

```ts
const workflows = sdk.workflows.getWorkflows();
```

## Subscribing to Workflow Events

You can subscribe to three types of workflow events:

::: tip
Use workflow events to keep your plugin's state synchronized with workflow changes, enabling reactive behavior and automation.
:::

::: info
Workflow events are fired for all workflow changes, not just those made by your plugin. This allows you to react to user actions and other plugin modifications.
:::

### Workflow Created

To listen for when a workflow is created:

```ts
const handler = sdk.workflows.onCreatedWorkflow((workflow) => {
  console.log("Workflow created:", workflow.name);
});

// Later, stop listening
handler.stop();
```

### Workflow Updated

To listen for when a workflow is updated:

```ts
const handler = sdk.workflows.onUpdatedWorkflow((workflow) => {
  console.log("Workflow updated:", workflow.name);
});

// Later, stop listening
handler.stop();
```

### Workflow Deleted

To listen for when a workflow is deleted:

```ts
const handler = sdk.workflows.onDeletedWorkflow((workflowId) => {
  console.log("Workflow deleted:", workflowId);
});

// Later, stop listening
handler.stop();
```

::: warning
Be mindful of performance when subscribing to workflow events. Avoid performing expensive operations in event handlers, especially if workflows change frequently.
:::

## Examples

### Workflow Automation

This example demonstrates reactive workflow management by subscribing to workflow lifecycle events. It logs workflow changes and can trigger automation, notifications, or UI updates when workflows are created, updated, or deleted.

```ts
import type { Caido } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  // Get all workflows on initialization
  const workflows = sdk.workflows.getWorkflows();
  sdk.log.info(`Found ${workflows.length} workflows`);

  // React to workflow changes
  sdk.workflows.onCreatedWorkflow((workflow) => {
    sdk.log.info(`New workflow created: ${workflow.name}`);
    // Perform actions when a new workflow is created
    // e.g., send notification, update UI, etc.
  });

  sdk.workflows.onUpdatedWorkflow((workflow) => {
    sdk.log.info(`Workflow updated: ${workflow.name}`);
    // React to workflow updates
    // e.g., refresh related data, update cache, etc.
  });

  sdk.workflows.onDeletedWorkflow((workflowId) => {
    sdk.log.info(`Workflow deleted: ${workflowId}`);
    // Clean up resources related to the deleted workflow
  });
};
```

### Workflow Discovery

This example implements a workflow discovery system that logs all workflows on initialization and re-discovers them whenever workflows are created or deleted. This keeps the plugin's workflow list synchronized with Caido's state.

```ts
import type { Caido } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  const discoverWorkflows = () => {
    const workflows = sdk.workflows.getWorkflows();

    workflows.forEach((workflow) => {
      sdk.log.info(`Workflow: ${workflow.name} (ID: ${workflow.id})`);
    });

    return workflows;
  };

  // Discover workflows on initialization
  const workflows = discoverWorkflows();

  // Re-discover when workflows change
  sdk.workflows.onCreatedWorkflow(() => {
    discoverWorkflows();
  });

  sdk.workflows.onDeletedWorkflow(() => {
    discoverWorkflows();
  });
};
```

---

---
url: /plugins/reference/sdks/frontend/intercept.md
---
# Intercept

### InterceptMessageId

> **InterceptMessageId** = `string` & `object`

A unique intercept message identifier.

#### Type Declaration

##### \_\_interceptMessageId?

> `optional` **\_\_interceptMessageId**: `never`

***

### InterceptPageContext

> **InterceptPageContext** = `object`

Intercept page context.

#### Properties

##### kind

> **kind**: `"Intercept"`

##### requestSelection

> **requestSelection**: [`Selection`](utils.md#selection)<[`InterceptMessageId`](#interceptmessageid)>

##### responseSelection

> **responseSelection**: [`Selection`](utils.md#selection)<[`InterceptMessageId`](#interceptmessageid)>

##### websocketSelection

> **websocketSelection**: [`Selection`](utils.md#selection)<[`InterceptMessageId`](#interceptmessageid)>

***

### InterceptSDK

> **InterceptSDK** = `object`

Utilities to interact with the Intercept page.

#### Properties

##### addRequestViewMode()

> **addRequestViewMode**: (`options`: [`RequestViewModeOptions`](request.md#requestviewmodeoptions)) => `void`

Add a custom request view mode.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`RequestViewModeOptions`](request.md#requestviewmodeoptions) | The view mode options. |

###### Returns

`void`

##### addResponseViewMode()

> **addResponseViewMode**: (`options`: [`ResponseViewModeOptions`](response.md#responseviewmodeoptions)) => `void`

Add a custom response view mode.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`ResponseViewModeOptions`](response.md#responseviewmodeoptions) | The view mode options. |

###### Returns

`void`

##### getScopeId()

> **getScopeId**: () => [`ID`](utils.md#id) | `undefined`

Get the current scope ID.

###### Returns

[`ID`](utils.md#id) | `undefined`

The current scope ID.

##### setScope()

> **setScope**: (`id`: [`ID`](utils.md#id) | `undefined`) => `void`

Set the current scope.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `id` | [`ID`](utils.md#id) | `undefined` |

###### Returns

`void`

---

---
url: /plugins/guides/plugin_upstream.md
---
# Intercept Requests and Connections

The `onUpstream` hook allows backend plugins to intercept and modify HTTP requests before they are sent to their target. This enables powerful use cases such as adding authentication headers, routing requests through proxies, implementing custom authentication flows, and more.

::: info
The `onUpstream` callback is called synchronously, so it's important to keep operations fast to avoid impacting overall performance.
:::

## Understanding Upstream Plugins

Upstream plugins act similar to upstream proxies. They are configured as a set of rules in Caido's settings that map domains to plugins. For example, a rule might say "for domain `api.example.com`, call plugin `my-auth-plugin`". When a request matches a configured domain, Caido checks if the specified plugin has an `onUpstream` hook, and if so, invokes it synchronously before the request is sent.

The callback receives a `RequestSpecRaw` object representing the request that's about to be sent. You can:

* Modify the request (headers, URL, body, etc.)
* Provide a different connection to use
* Return `undefined` to let other plugins handle the request

::: tip
We recommend including upstream plugin rule management in your plugin's UI to simplify setup for users. This allows users to configure which domains your plugin should handle directly from your plugin's interface.
:::

## Registering the Upstream Callback

To intercept requests, register your callback using `sdk.events.onUpstream()` in your plugin's initialization function:

```ts
import type { DefineAPI, SDK } from "caido:plugin";
import type { RequestSpecRaw } from "caido:utils";

export type API = DefineAPI<{}>;

export function init(sdk: SDK<API>) {
  sdk.events.onUpstream(async (sdk, request: RequestSpecRaw) => {
    // Your upstream logic here
  });
}
```

The callback receives two parameters:

* `sdk`: The SDK instance (same as the one passed to `init`)
* `request`: A `RequestSpecRaw` object representing the request to be sent

## Return Values

Your callback can return different values to control how the request is handled:

* **`undefined`**: Let other upstream plugins handle the request (or proceed normally if no other plugins match)
* **`Connection`**: Use the provided connection to send the request
* **`RequestSpec`**: Use the modified request instead of the original
* **`{ connection?, request? }`**: Provide both a connection and/or a modified request

## Modifying Requests

You can modify requests by converting the `RequestSpecRaw` to a `RequestSpec` using `toSpec()`, making your changes, and returning the modified request.

### Adding Headers

Add custom headers to requests before they're sent:

```ts
import type { DefineAPI, SDK } from "caido:plugin";
import type { RequestSpecRaw } from "caido:utils";
import { RequestSpec } from "caido:utils";

export type API = DefineAPI<{}>;

export function init(sdk: SDK<API>) {
  sdk.events.onUpstream(async (sdk, request: RequestSpecRaw) => {
    const spec = request.toSpec();
    spec.setHeader("X-Custom-Header", "custom-value");
    spec.setHeader("Authorization", "Bearer token123");
    return spec;
  });
}
```

### Changing Request Properties

Modify the URL, method, body, or other request properties:

```ts
import type { DefineAPI, SDK } from "caido:plugin";
import type { RequestSpecRaw } from "caido:utils";
import { RequestSpec } from "caido:utils";

export type API = DefineAPI<{}>;

export function init(sdk: SDK<API>) {
  sdk.events.onUpstream(async (sdk, request: RequestSpecRaw) => {
    const spec = request.toSpec();

    // Change the target URL
    spec.setHost("proxy.example.com");
    spec.setPort(8080);
    spec.setTls(false);

    // Modify the method
    spec.setMethod("POST");

    // Change the body
    spec.setBody("Modified request body");

    return spec;
  });
}
```

::: warning
At the moment, modifying the host/port will **NOT** modify how the connection is opened by Caido.
If you need to change the target host of the connection, use `sdk.net.connect`.
:::

## Modifying Connections

You can provide a custom connection that will be used to send the request. This is useful for routing requests through proxies or reusing existing connections.

### Routing Through a Proxy

Create a new connection to a proxy server:

```ts
import type { DefineAPI, SDK } from "caido:plugin";
import type { RequestSpecRaw } from "caido:utils";

export type API = DefineAPI<{}>;

export function init(sdk: SDK<API>) {
  sdk.events.onUpstream(async (sdk, request: RequestSpecRaw) => {
    // Create a connection to a proxy server
    const proxyConnection = await sdk.net.connect("https://proxy.example.com:8080");

    return {
      connection: proxyConnection,
      request: request.toSpec(), // Optionally modify the request too
    };
  });
}
```

## Examples

### Implementing NTLM Authentication

Complex authentication flows like NTLM require multiple request-response exchanges. You can use `sdk.requests.send()` within your upstream callback to perform these exchanges, then return the authenticated connection and modified request.

This example demonstrates how to implement NTLM authentication by performing the three-message handshake:

```ts
import type { DefineAPI, SDK } from "caido:plugin";
import type { RequestSpecRaw } from "caido:utils";
import { RequestSpec } from "caido:utils";

export type API = DefineAPI<{}>;

const credentials = {
  username: "user",
  password: "pass",
  domain: "DOMAIN",
};

export function init(sdk: SDK<API>) {
  sdk.events.onUpstream(async (sdk, request: RequestSpecRaw) => {
    const domain = request.getHost();

    // Check if this domain requires NTLM authentication
    if (!domain.includes("example.com")) {
      return undefined; // Let other plugins handle it
    }

    try {
      const spec = request.toSpec();

      // Step 1: Send Type 1 message (negotiate)
      const type1Message = createType1Message("", "");
      spec.setHeader("Authorization", type1Message);
      spec.setHeader("Connection", "keep-alive");

      const { response, connection } = await sdk.requests.send(spec, {
        save: false,
        // plugins defaults to false when called from onUpstream, preventing recursion
      });

      // Step 2: Extract Type 2 message (challenge)
      const wwwAuthenticate = response.getHeader("WWW-Authenticate")?.[0];
      if (!wwwAuthenticate) {
        return undefined;
      }

      const type2Message = decodeType2Message(wwwAuthenticate);

      // Step 3: Create Type 3 message (authenticate)
      const type3Message = createType3Message(
        type2Message,
        credentials.username,
        credentials.password,
      );

      // Return the authenticated connection and request
      const finalSpec = request.toSpec();
      finalSpec.setHeader("Authorization", type3Message);
      finalSpec.setHeader("Connection", "Close");

      return {
        connection,
        request: finalSpec,
      };
    } catch (error) {
      sdk.console.error("NTLM authentication failed:", error);
      return undefined;
    }
  });
}
```

::: warning
When calling `sdk.requests.send()` from within an `onUpstream` callback, the `plugins` option defaults to `false` to prevent recursion. This ensures your helper request doesn't trigger upstream plugins again. However, when calling `sdk.requests.send()` from other functions (not within `onUpstream`), `plugins` defaults to `true`.
:::

### Routing Requests to Different Servers

Route requests to different servers based on domain or other criteria:

```ts
import type { DefineAPI, SDK } from "caido:plugin";
import type { RequestSpecRaw } from "caido:utils";
import { RequestSpec } from "caido:utils";

export type API = DefineAPI<{}>;

const routingRules: Record<string, string> = {
  "api.example.com": "https://api-backup.example.com",
  "cdn.example.com": "https://cdn-mirror.example.com",
};

export function init(sdk: SDK<API>) {
  sdk.events.onUpstream(async (sdk, request: RequestSpecRaw) => {
    const originalHost = request.getHost();
    const targetHost = routingRules[originalHost];

    if (!targetHost) {
      return undefined; // No routing rule, proceed normally
    }

    // Create connection to the target server
    const connection = await sdk.net.connect(targetHost);

    // Modify the request to use the new host
    const spec = request.toSpec();
    spec.setHost(new URL(targetHost).hostname);
    spec.setPort(parseInt(new URL(targetHost).port) || (targetHost.startsWith("https") ? 443 : 80));
    spec.setTls(targetHost.startsWith("https"));

    return {
      connection,
      request: spec,
    };
  });
}
```

### Logging and Monitoring Requests

Log requests before they're sent for monitoring or debugging purposes:

```ts
import type { DefineAPI, SDK } from "caido:plugin";
import type { RequestSpecRaw } from "caido:utils";

export type API = DefineAPI<{}>;

export function init(sdk: SDK<API>) {
  sdk.events.onUpstream(async (sdk, request: RequestSpecRaw) => {
    const spec = request.toSpec();
    const url = spec.getUrl();
    const method = spec.getMethod();
    const headers = spec.getHeaders();

    sdk.console.log(`[Upstream] ${method} ${url}`);
    sdk.console.log(`[Upstream] Headers: ${JSON.stringify(headers)}`);

    // Return undefined to proceed normally after logging
    return undefined;
  });
}
```

## Plugin Ordering and Multiple Plugins

When multiple upstream plugins are enabled for the same domain, they are called in the order configured by the user in Caido's upstream plugin settings. If your plugin returns `undefined`, the next plugin in the chain will be tried. If all plugins return `undefined`, the request proceeds normally.

This allows multiple plugins to work together:

* A logging plugin can log requests and return `undefined`
* An authentication plugin can add auth headers and return `undefined`
* A routing plugin can change the target server

---

---
url: /plugins/reference/sdks/frontend/json.md
---
# JSON

### JSONCompatible

> **JSONCompatible**<`T`> = `unknown` *extends* `T` ? `never` : `{ [P in keyof T]: T[P] extends JSONValue ? T[P] : T[P] extends NotAssignableToJson ? never : JSONCompatible<T[P]> }`

A type that ensures all properties of T are JSON-compatible.

#### Type Parameters

| Type Parameter |
| ------ |
| `T` |

***

### JSONValue

> **JSONValue** = [`JSONPrimitive`](other.md#jsonprimitive) | [`JSONValue`](#jsonvalue)\[] | {\[`key`: `string`]: [`JSONValue`](#jsonvalue); }

A JSON-serializable value.

---

---
url: /plugins/guides/navigation_events.md
---
# Listen to Navigation Events

You can subscribe to page navigation changes to react when users navigate between different pages in Caido. This is useful for updating UI based on the current page, performing page-specific initialization, or cleaning up resources.

## Subscribing to Page Changes

To listen for page navigation changes, use `sdk.navigation.onPageChange()`:

```ts
const handler = sdk.navigation.onPageChange((event) => {
  console.log("Page changed to:", event.routeId);
  console.log("Path:", event.path);
});
```

The callback receives a `PageChangeEvent` object containing:

* `routeId` - The route ID of the new page
* `path` - The path of the new page

## Stopping the Listener

The method returns a `ListenerHandle` object with a `stop()` method to unsubscribe:

```ts
const handler = sdk.navigation.onPageChange((event) => {
  // Handle page change
});

// Later, stop listening
handler.stop();
```

## Examples

### Page-Specific Initialization

This example performs cleanup when leaving pages and initialization when entering new pages. It tracks the current page and executes page-specific setup code for Replay and HTTP History pages.

```ts
import type { Caido } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  let currentPage: string | undefined;

  const handler = sdk.navigation.onPageChange((event) => {
    // Clean up previous page
    if (currentPage) {
      sdk.log.debug("Leaving page:", currentPage);
      // Perform cleanup
    }

    // Initialize new page
    currentPage = event.routeId;
    sdk.log.debug("Entering page:", currentPage);

    // Perform page-specific initialization
    if (event.routeId === "replay") {
      sdk.log.info("Replay page opened");
      // Initialize replay-specific features
    } else if (event.routeId === "http-history") {
      sdk.log.info("HTTP History page opened");
      // Initialize HTTP history features
    }
  });

  // Store handler for cleanup if needed
  // handler.stop() can be called when plugin is unloaded
};
```

### Conditional Feature Activation

This example conditionally enables or disables a feature based on the current page. The feature is only active on Replay or HTTP History pages, and is automatically deactivated when navigating to other pages.

```ts
import type { Caido } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  let featureEnabled = false;

  const handler = sdk.navigation.onPageChange((event) => {
    // Enable feature only on specific pages
    if (event.routeId === "replay" || event.routeId === "http-history") {
      if (!featureEnabled) {
        featureEnabled = true;
        sdk.log.info("Feature enabled for", event.routeId);
        // Activate feature
      }
    } else {
      if (featureEnabled) {
        featureEnabled = false;
        sdk.log.info("Feature disabled");
        // Deactivate feature
      }
    }
  });
};
```

---

---
url: /plugins/reference/modules/llrt/abort.md
---
[@caido/quickjs-types](../index.md) / llrt/abort

# llrt/abort

## Classes

### AbortController

#### Constructors

##### Constructor

> **new AbortController**(): [`AbortController`](#abortcontroller)

Creates a new `AbortController` object instance.

###### Returns

[`AbortController`](#abortcontroller)

#### Properties

##### signal

> `readonly` **signal**: [`AbortSignal`](#abortsignal)

Returns the AbortSignal object associated with this object.

#### Methods

##### abort()

> **abort**(`reason?`: `any`): `void`

Invoking this method will set this object's AbortSignal's aborted flag and signal to any observers that the associated activity is to be aborted.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `reason?` | `any` |

###### Returns

`void`

***

### AbortSignal

A signal object that allows you to communicate with a DOM request (such as a Fetch) and abort it if required via an AbortController object.

#### Extends

* [`EventTarget`](dom-events.md#eventtarget)

#### Constructors

##### Constructor

> **new AbortSignal**(): [`AbortSignal`](#abortsignal)

Creates a new `AbortSignal` object instance.

###### Returns

[`AbortSignal`](#abortsignal)

###### Overrides

[`EventTarget`](dom-events.md#eventtarget).[`constructor`](dom-events.md#constructor-1)

#### Properties

##### aborted

> `readonly` **aborted**: `boolean`

Returns true if this AbortSignal's AbortController has signaled to abort, and false otherwise.

##### onabort

> **onabort**: (`this`: [`AbortSignal`](#abortsignal), `event`: [`Event`](dom-events.md#event)) => `any` | `null`

Registers an event listener callback to execute when an `abort` event is observed.

##### reason

> `readonly` **reason**: `any`

A JavaScript value providing the abort reason, once the signal has aborted.

#### Methods

##### addEventListener()

> **addEventListener**(`type`: [`EventKey`](dom-events.md#eventkey), `listener`: [`EventListener`](dom-events.md#eventlistener), `options?`: [`AddEventListenerOptions`](dom-events.md#addeventlisteneroptions)): `void`

Adds a new handler for the `type` event. Any given `listener` is added only once per `type`.

If the `once` option is true, the `listener` is removed after the next time a `type` event is dispatched.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `type` | [`EventKey`](dom-events.md#eventkey) |
| `listener` | [`EventListener`](dom-events.md#eventlistener) |
| `options?` | [`AddEventListenerOptions`](dom-events.md#addeventlisteneroptions) |

###### Returns

`void`

###### Inherited from

[`EventTarget`](dom-events.md#eventtarget).[`addEventListener`](dom-events.md#addeventlistener)

##### dispatchEvent()

> **dispatchEvent**(`event`: [`Event`](dom-events.md#event)): `void`

Dispatches a synthetic event event to target

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | [`Event`](dom-events.md#event) |

###### Returns

`void`

###### Inherited from

[`EventTarget`](dom-events.md#eventtarget).[`dispatchEvent`](dom-events.md#dispatchevent)

##### removeEventListener()

> **removeEventListener**(`type`: [`EventKey`](dom-events.md#eventkey), `listener`: [`EventListener`](dom-events.md#eventlistener)): `void`

Removes the event listener in target's event listener list with the same type and callback

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `type` | [`EventKey`](dom-events.md#eventkey) |
| `listener` | [`EventListener`](dom-events.md#eventlistener) |

###### Returns

`void`

###### Inherited from

[`EventTarget`](dom-events.md#eventtarget).[`removeEventListener`](dom-events.md#removeeventlistener)

##### throwIfAborted()

> **throwIfAborted**(): `void`

Throws the signal's abort reason if the signal has been aborted; otherwise it does nothing.

###### Returns

`void`

##### abort()

> `static` **abort**(`reason?`: `any`): [`AbortSignal`](#abortsignal)

Returns an `AbortSignal` instance that is already set as aborted.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `reason?` | `any` | The reason for the abort. |

###### Returns

[`AbortSignal`](#abortsignal)

##### any()

> `static` **any**(`signals`: [`AbortSignal`](#abortsignal)\[]): [`AbortSignal`](#abortsignal)

Returns an `AbortSignal` that aborts when any of the given abort signals abort.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `signals` | [`AbortSignal`](#abortsignal)\[] | An array of `AbortSignal` objects to observe. |

###### Returns

[`AbortSignal`](#abortsignal)

##### timeout()

> `static` **timeout**(`milliseconds`: `number`): [`AbortSignal`](#abortsignal)

Returns an `AbortSignal` instance that will automatically abort after a specified time.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `milliseconds` | `number` | The number of milliseconds to wait before aborting. |

###### Returns

[`AbortSignal`](#abortsignal)

---

---
url: /plugins/reference/modules/llrt/buffer.md
---
[@caido/quickjs-types](../index.md) / llrt/buffer

# llrt/buffer

## Interfaces

### Buffer

#### Extends

* `Uint8Array`

#### Indexable

\[`index`: `number`]: `number`

#### Methods

##### copy()

> **copy**(`target`: `Uint8Array`, `targetStart?`: `number`, `sourceStart?`: `number`, `sourceEnd?`: `number`): `number`

Copies data from a region of `buf` to a region in `target`, even if the `target`memory region overlaps with `buf`.

[`TypedArray.prototype.set()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/set) performs the same operation, and is available
for all TypedArrays, including `Buffer`s, although it takes
different function arguments.

```js
import { Buffer } from 'buffer';

// Create two `Buffer` instances.
const buf1 = Buffer.allocUnsafe(26);
const buf2 = Buffer.allocUnsafe(26).fill('!');

for (let i = 0; i < 26; i++) {
  // 97 is the decimal ASCII value for 'a'.
  buf1[i] = i + 97;
}

// Copy `buf1` bytes 16 through 19 into `buf2` starting at byte 8 of `buf2`.
buf1.copy(buf2, 8, 16, 20);
// This is equivalent to:
// buf2.set(buf1.subarray(16, 20), 8);

console.log(buf2.toString('ascii', 0, 25));
// Prints: !!!!!!!!qrst!!!!!!!!!!!!!
```

```js
import { Buffer } from 'buffer';

// Create a `Buffer` and copy data from one region to an overlapping region
// within the same `Buffer`.

const buf = Buffer.allocUnsafe(26);

for (let i = 0; i < 26; i++) {
  // 97 is the decimal ASCII value for 'a'.
  buf[i] = i + 97;
}

buf.copy(buf, 0, 4, 10);

console.log(buf.toString());
// Prints: efghijghijklmnopqrstuvwxyz
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `target` | `Uint8Array` | A `Buffer` or Uint8Array to copy into. |
| `targetStart?` | `number` | The offset within `target` at which to begin writing. |
| `sourceStart?` | `number` | The offset within `buf` from which to begin copying. |
| `sourceEnd?` | `number` | The offset within `buf` at which to stop copying (not inclusive). |

###### Returns

`number`

The number of bytes copied.

##### readBigInt64BE()

> **readBigInt64BE**(`offset?`: `number`): `bigint`

Reads a signed, big-endian 64-bit integer from `buf` at the specified `offset`.

Integers read from a `Buffer` are interpreted as two's complement signed
values.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `offset?` | `number` | Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - 8`. |

###### Returns

`bigint`

##### readBigInt64LE()

> **readBigInt64LE**(`offset?`: `number`): `bigint`

Reads a signed, little-endian 64-bit integer from `buf` at the specified`offset`.

Integers read from a `Buffer` are interpreted as two's complement signed
values.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `offset?` | `number` | Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - 8`. |

###### Returns

`bigint`

##### readBigUint64BE()

> **readBigUint64BE**(`offset?`: `number`): `bigint`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `offset?` | `number` |

###### Returns

`bigint`

###### Alias

Buffer.readBigUInt64BE

##### readBigUInt64BE()

> **readBigUInt64BE**(`offset?`: `number`): `bigint`

Reads an unsigned, big-endian 64-bit integer from `buf` at the specified`offset`.

This function is also available under the `readBigUint64BE` alias.

```js
import { Buffer } from 'buffer';

const buf = Buffer.from([0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff]);

console.log(buf.readBigUInt64BE(0));
// Prints: 4294967295n
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `offset?` | `number` | Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - 8`. |

###### Returns

`bigint`

##### readBigUint64LE()

> **readBigUint64LE**(`offset?`: `number`): `bigint`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `offset?` | `number` |

###### Returns

`bigint`

###### Alias

Buffer.readBigUInt64LE

##### readBigUInt64LE()

> **readBigUInt64LE**(`offset?`: `number`): `bigint`

Reads an unsigned, little-endian 64-bit integer from `buf` at the specified`offset`.

This function is also available under the `readBigUint64LE` alias.

```js
import { Buffer } from 'buffer';

const buf = Buffer.from([0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff]);

console.log(buf.readBigUInt64LE(0));
// Prints: 18446744069414584320n
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `offset?` | `number` | Number of bytes to skip before starting to read. Must satisfy: `0 <= offset <= buf.length - 8`. |

###### Returns

`bigint`

##### readDoubleBE()

> **readDoubleBE**(`offset?`: `number`): `number`

Reads a 64-bit, big-endian double from `buf` at the specified `offset`.

```js
import { Buffer } from 'buffer';

const buf = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8]);

console.log(buf.readDoubleBE(0));
// Prints: 8.20788039913184e-304
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `offset?` | `number` | Number of bytes to skip before starting to read. Must satisfy `0 <= offset <= buf.length - 8`. |

###### Returns

`number`

##### readDoubleLE()

> **readDoubleLE**(`offset?`: `number`): `number`

Reads a 64-bit, little-endian double from `buf` at the specified `offset`.

```js
import { Buffer } from 'buffer';

const buf = Buffer.from([1, 2, 3, 4, 5, 6, 7, 8]);

console.log(buf.readDoubleLE(0));
// Prints: 5.447603722011605e-270
console.log(buf.readDoubleLE(1));
// Throws ERR_OUT_OF_RANGE.
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `offset?` | `number` | Number of bytes to skip before starting to read. Must satisfy `0 <= offset <= buf.length - 8`. |

###### Returns

`number`

##### readFloatBE()

> **readFloatBE**(`offset?`: `number`): `number`

Reads a 32-bit, big-endian float from `buf` at the specified `offset`.

```js
import { Buffer } from 'buffer';

const buf = Buffer.from([1, 2, 3, 4]);

console.log(buf.readFloatBE(0));
// Prints: 2.387939260590663e-38
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `offset?` | `number` | Number of bytes to skip before starting to read. Must satisfy `0 <= offset <= buf.length - 4`. |

###### Returns

`number`

##### readFloatLE()

> **readFloatLE**(`offset?`: `number`): `number`

Reads a 32-bit, little-endian float from `buf` at the specified `offset`.

```js
import { Buffer } from 'buffer';

const buf = Buffer.from([1, 2, 3, 4]);

console.log(buf.readFloatLE(0));
// Prints: 1.539989614439558e-36
console.log(buf.readFloatLE(1));
// Throws ERR_OUT_OF_RANGE.
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `offset?` | `number` | Number of bytes to skip before starting to read. Must satisfy `0 <= offset <= buf.length - 4`. |

###### Returns

`number`

##### readInt16BE()

> **readInt16BE**(`offset?`: `number`): `number`

Reads a signed, big-endian 16-bit integer from `buf` at the specified `offset`.

Integers read from a `Buffer` are interpreted as two's complement signed values.

```js
import { Buffer } from 'buffer';

const buf = Buffer.from([0, 5]);

console.log(buf.readInt16BE(0));
// Prints: 5
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `offset?` | `number` | Number of bytes to skip before starting to read. Must satisfy `0 <= offset <= buf.length - 2`. |

###### Returns

`number`

##### readInt16LE()

> **readInt16LE**(`offset?`: `number`): `number`

Reads a signed, little-endian 16-bit integer from `buf` at the specified`offset`.

Integers read from a `Buffer` are interpreted as two's complement signed values.

```js
import { Buffer } from 'buffer';

const buf = Buffer.from([0, 5]);

console.log(buf.readInt16LE(0));
// Prints: 1280
console.log(buf.readInt16LE(1));
// Throws ERR_OUT_OF_RANGE.
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `offset?` | `number` | Number of bytes to skip before starting to read. Must satisfy `0 <= offset <= buf.length - 2`. |

###### Returns

`number`

##### readInt32BE()

> **readInt32BE**(`offset?`: `number`): `number`

Reads a signed, big-endian 32-bit integer from `buf` at the specified `offset`.

Integers read from a `Buffer` are interpreted as two's complement signed values.

```js
import { Buffer } from 'buffer';

const buf = Buffer.from([0, 0, 0, 5]);

console.log(buf.readInt32BE(0));
// Prints: 5
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `offset?` | `number` | Number of bytes to skip before starting to read. Must satisfy `0 <= offset <= buf.length - 4`. |

###### Returns

`number`

##### readInt32LE()

> **readInt32LE**(`offset?`: `number`): `number`

Reads a signed, little-endian 32-bit integer from `buf` at the specified`offset`.

Integers read from a `Buffer` are interpreted as two's complement signed values.

```js
import { Buffer } from 'buffer';

const buf = Buffer.from([0, 0, 0, 5]);

console.log(buf.readInt32LE(0));
// Prints: 83886080
console.log(buf.readInt32LE(1));
// Throws ERR_OUT_OF_RANGE.
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `offset?` | `number` | Number of bytes to skip before starting to read. Must satisfy `0 <= offset <= buf.length - 4`. |

###### Returns

`number`

##### readInt8()

> **readInt8**(`offset?`: `number`): `number`

Reads a signed 8-bit integer from `buf` at the specified `offset`.

Integers read from a `Buffer` are interpreted as two's complement signed values.

```js
import { Buffer } from 'buffer';

const buf = Buffer.from([-1, 5]);

console.log(buf.readInt8(0));
// Prints: -1
console.log(buf.readInt8(1));
// Prints: 5
console.log(buf.readInt8(2));
// Throws ERR_OUT_OF_RANGE.
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `offset?` | `number` | Number of bytes to skip before starting to read. Must satisfy `0 <= offset <= buf.length - 1`. |

###### Returns

`number`

##### readUint16BE()

> **readUint16BE**(`offset?`: `number`): `number`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `offset?` | `number` |

###### Returns

`number`

###### Alias

Buffer.readUInt16BE

##### readUInt16BE()

> **readUInt16BE**(`offset?`: `number`): `number`

Reads an unsigned, big-endian 16-bit integer from `buf` at the specified`offset`.

This function is also available under the `readUint16BE` alias.

```js
import { Buffer } from 'buffer';

const buf = Buffer.from([0x12, 0x34, 0x56]);

console.log(buf.readUInt16BE(0).toString(16));
// Prints: 1234
console.log(buf.readUInt16BE(1).toString(16));
// Prints: 3456
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `offset?` | `number` | Number of bytes to skip before starting to read. Must satisfy `0 <= offset <= buf.length - 2`. |

###### Returns

`number`

##### readUint16LE()

> **readUint16LE**(`offset?`: `number`): `number`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `offset?` | `number` |

###### Returns

`number`

###### Alias

Buffer.readUInt16LE

##### readUInt16LE()

> **readUInt16LE**(`offset?`: `number`): `number`

Reads an unsigned, little-endian 16-bit integer from `buf` at the specified `offset`.

This function is also available under the `readUint16LE` alias.

```js
import { Buffer } from 'buffer';

const buf = Buffer.from([0x12, 0x34, 0x56]);

console.log(buf.readUInt16LE(0).toString(16));
// Prints: 3412
console.log(buf.readUInt16LE(1).toString(16));
// Prints: 5634
console.log(buf.readUInt16LE(2).toString(16));
// Throws ERR_OUT_OF_RANGE.
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `offset?` | `number` | Number of bytes to skip before starting to read. Must satisfy `0 <= offset <= buf.length - 2`. |

###### Returns

`number`

##### readUint32LE()

> **readUint32LE**(`offset?`: `number`): `number`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `offset?` | `number` |

###### Returns

`number`

###### Alias

Buffer.readUInt32LE

##### readUInt32LE()

> **readUInt32LE**(`offset?`: `number`): `number`

Reads an unsigned, little-endian 32-bit integer from `buf` at the specified`offset`.

This function is also available under the `readUint32LE` alias.

```js
import { Buffer } from 'buffer';

const buf = Buffer.from([0x12, 0x34, 0x56, 0x78]);

console.log(buf.readUInt32LE(0).toString(16));
// Prints: 78563412
console.log(buf.readUInt32LE(1).toString(16));
// Throws ERR_OUT_OF_RANGE.
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `offset?` | `number` | Number of bytes to skip before starting to read. Must satisfy `0 <= offset <= buf.length - 4`. |

###### Returns

`number`

##### readUint8()

> **readUint8**(`offset?`: `number`): `number`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `offset?` | `number` |

###### Returns

`number`

###### Alias

Buffer.readUInt8

##### readUInt8()

> **readUInt8**(`offset?`: `number`): `number`

Reads an unsigned 8-bit integer from `buf` at the specified `offset`.

This function is also available under the `readUint8` alias.

```js
import { Buffer } from 'buffer';

const buf = Buffer.from([1, -2]);

console.log(buf.readUInt8(0));
// Prints: 1
console.log(buf.readUInt8(1));
// Prints: 254
console.log(buf.readUInt8(2));
// Throws ERR_OUT_OF_RANGE.
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `offset?` | `number` | Number of bytes to skip before starting to read. Must satisfy `0 <= offset <= buf.length - 1`. |

###### Returns

`number`

##### subarray()

> **subarray**(`start?`: `number`, `end?`: `number`): [`Buffer`](#buffer)

Returns a new `Buffer` that references the same memory as the original, but
offset and cropped by the `start` and `end` indices.

Specifying `end` greater than `buf.length` will return the same result as
that of `end` equal to `buf.length`.

This method is inherited from [`TypedArray.prototype.subarray()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/subarray).

Modifying the new `Buffer` slice will modify the memory in the original `Buffer`because the allocated memory of the two objects overlap.

```js
import { Buffer } from 'buffer';

// Create a `Buffer` with the ASCII alphabet, take a slice, and modify one byte
// from the original `Buffer`.

const buf1 = Buffer.alloc(26);

for (let i = 0; i < 26; i++) {
  // 97 is the decimal ASCII value for 'a'.
  buf1[i] = i + 97;
}

const buf2 = buf1.subarray(0, 3);

console.log(buf2.toString('ascii', 0, buf2.length));
// Prints: abc

buf1[0] = 33;

console.log(buf2.toString('ascii', 0, buf2.length));
// Prints: !bc
```

Specifying negative indexes causes the slice to be generated relative to the
end of `buf` rather than the beginning.

```js
import { Buffer } from 'buffer';

const buf = Buffer.from('buffer');

console.log(buf.subarray(-6, -1).toString());
// Prints: buffe
// (Equivalent to buf.subarray(0, 5).)

console.log(buf.subarray(-6, -2).toString());
// Prints: buff
// (Equivalent to buf.subarray(0, 4).)

console.log(buf.subarray(-5, -2).toString());
// Prints: uff
// (Equivalent to buf.subarray(1, 4).)
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `start?` | `number` | Where the new `Buffer` will start. |
| `end?` | `number` | Where the new `Buffer` will end (not inclusive). |

###### Returns

[`Buffer`](#buffer)

###### Overrides

`Uint8Array.subarray`

##### toString()

> **toString**(`encoding?`: [`BufferEncoding`](#bufferencoding), `start?`: `number`, `end?`: `number`): `string`

Decodes `buf` to a string according to the specified character encoding in`encoding`. `start` and `end` may be passed to decode only a subset of `buf`.

If `encoding` is `'utf8'` and a byte sequence in the input is not valid UTF-8,
then each invalid byte is replaced with the replacement character `U+FFFD`.

```js
import { Buffer } from 'node:buffer';

const buf1 = Buffer.allocUnsafe(26);

for (let i = 0; i < 26; i++) {
  // 97 is the decimal ASCII value for 'a'.
  buf1[i] = i + 97;
}

console.log(buf1.toString('utf8'));
// Prints: abcdefghijklmnopqrstuvwxyz
console.log(buf1.toString('utf8', 0, 5));
// Prints: abcde

const buf2 = Buffer.from('tést');

console.log(buf2.toString('hex'));
// Prints: 74c3a97374
console.log(buf2.toString('utf8', 0, 3));
// Prints: té
console.log(buf2.toString(undefined, 0, 3));
// Prints: té
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `encoding?` | [`BufferEncoding`](#bufferencoding) | The character encoding to use. |
| `start?` | `number` | The byte offset to start decoding at. |
| `end?` | `number` | The byte offset to stop decoding at (not inclusive). |

###### Returns

`string`

###### Overrides

`Uint8Array.toString`

##### write()

###### Call Signature

> **write**(`string`: `string`, `encoding?`: [`BufferEncoding`](#bufferencoding)): `number`

Writes `string` to `buf` at `offset` according to the character encoding in`encoding`. The `length` parameter is the number of bytes to write. If `buf` did
not contain enough space to fit the entire string, only part of `string` will be
written. However, partially encoded characters will not be written.

```js
import { Buffer } from 'buffer';

const buf = Buffer.alloc(256);

const len = buf.write('\u00bd + \u00bc = \u00be', 0);

console.log(`${len} bytes: ${buf.toString('utf8', 0, len)}`);
// Prints: 12 bytes: ½ + ¼ = ¾

const buffer = Buffer.alloc(10);

const length = buffer.write('abcd', 8);

console.log(`${length} bytes: ${buffer.toString('utf8', 8, 10)}`);
// Prints: 2 bytes : ab
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `string` | `string` | String to write to `buf`. |
| `encoding?` | [`BufferEncoding`](#bufferencoding) | The character encoding of `string`. |

###### Returns

`number`

Number of bytes written.

###### Call Signature

> **write**(`string`: `string`, `offset`: `number`, `encoding?`: [`BufferEncoding`](#bufferencoding)): `number`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `string` | `string` |
| `offset` | `number` |
| `encoding?` | [`BufferEncoding`](#bufferencoding) |

###### Returns

`number`

###### Call Signature

> **write**(`string`: `string`, `offset`: `number`, `length`: `number`, `encoding?`: [`BufferEncoding`](#bufferencoding)): `number`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `string` | `string` |
| `offset` | `number` |
| `length` | `number` |
| `encoding?` | [`BufferEncoding`](#bufferencoding) |

###### Returns

`number`

##### writeBigInt64BE()

> **writeBigInt64BE**(`value`: `bigint`, `offset?`: `number`): `number`

Writes `value` to `buf` at the specified `offset` as big-endian.

`value` is interpreted and written as a two's complement signed integer.

```js
import { Buffer } from 'buffer';

const buf = Buffer.allocUnsafe(8);

buf.writeBigInt64BE(0x0102030405060708n, 0);

console.log(buf);
// Prints: <Buffer 01 02 03 04 05 06 07 08>
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `value` | `bigint` | Number to be written to `buf`. |
| `offset?` | `number` | Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - 8`. |

###### Returns

`number`

`offset` plus the number of bytes written.

##### writeBigInt64LE()

> **writeBigInt64LE**(`value`: `bigint`, `offset?`: `number`): `number`

Writes `value` to `buf` at the specified `offset` as little-endian.

`value` is interpreted and written as a two's complement signed integer.

```js
import { Buffer } from 'buffer';

const buf = Buffer.allocUnsafe(8);

buf.writeBigInt64LE(0x0102030405060708n, 0);

console.log(buf);
// Prints: <Buffer 08 07 06 05 04 03 02 01>
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `value` | `bigint` | Number to be written to `buf`. |
| `offset?` | `number` | Number of bytes to skip before starting to write. Must satisfy: `0 <= offset <= buf.length - 8`. |

###### Returns

`number`

`offset` plus the number of bytes written.

##### writeBigUint64BE()

> **writeBigUint64BE**(`value`: `bigint`, `offset?`: `number`): `number`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `value` | `bigint` |
| `offset?` | `number` |

###### Returns

`number`

###### Alias

Buffer.writeBigUInt64BE

##### writeBigUint64LE()

> **writeBigUint64LE**(`value`: `bigint`, `offset?`: `number`): `number`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `value` | `bigint` |
| `offset?` | `number` |

###### Returns

`number`

###### Alias

Buffer.writeBigUInt64LE

##### writeDoubleBE()

> **writeDoubleBE**(`value`: `number`, `offset?`: `number`): `number`

Writes `value` to `buf` at the specified `offset` as big-endian. The `value` must be a JavaScript number. Behavior is undefined when `value` is anything
other than a JavaScript number.

```js
import { Buffer } from 'buffer';

const buf = Buffer.allocUnsafe(8);

buf.writeDoubleBE(123.456, 0);

console.log(buf);
// Prints: <Buffer 40 5e dd 2f 1a 9f be 77>
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `value` | `number` | Number to be written to `buf`. |
| `offset?` | `number` | Number of bytes to skip before starting to write. Must satisfy `0 <= offset <= buf.length - 8`. |

###### Returns

`number`

`offset` plus the number of bytes written.

##### writeDoubleLE()

> **writeDoubleLE**(`value`: `number`, `offset?`: `number`): `number`

Writes `value` to `buf` at the specified `offset` as little-endian. The `value` must be a JavaScript number. Behavior is undefined when `value` is anything
other than a JavaScript number.

```js
import { Buffer } from 'buffer';

const buf = Buffer.allocUnsafe(8);

buf.writeDoubleLE(123.456, 0);

console.log(buf);
// Prints: <Buffer 77 be 9f 1a 2f dd 5e 40>
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `value` | `number` | Number to be written to `buf`. |
| `offset?` | `number` | Number of bytes to skip before starting to write. Must satisfy `0 <= offset <= buf.length - 8`. |

###### Returns

`number`

`offset` plus the number of bytes written.

##### writeFloatBE()

> **writeFloatBE**(`value`: `number`, `offset?`: `number`): `number`

Writes `value` to `buf` at the specified `offset` as big-endian. Behavior is
undefined when `value` is anything other than a JavaScript number.

```js
import { Buffer } from 'buffer';

const buf = Buffer.allocUnsafe(4);

buf.writeFloatBE(0xcafebabe, 0);

console.log(buf);
// Prints: <Buffer 4f 4a fe bb>
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `value` | `number` | Number to be written to `buf`. |
| `offset?` | `number` | Number of bytes to skip before starting to write. Must satisfy `0 <= offset <= buf.length - 4`. |

###### Returns

`number`

`offset` plus the number of bytes written.

##### writeFloatLE()

> **writeFloatLE**(`value`: `number`, `offset?`: `number`): `number`

Writes `value` to `buf` at the specified `offset` as little-endian. Behavior is
undefined when `value` is anything other than a JavaScript number.

```js
import { Buffer } from 'buffer';

const buf = Buffer.allocUnsafe(4);

buf.writeFloatLE(0xcafebabe, 0);

console.log(buf);
// Prints: <Buffer bb fe 4a 4f>
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `value` | `number` | Number to be written to `buf`. |
| `offset?` | `number` | Number of bytes to skip before starting to write. Must satisfy `0 <= offset <= buf.length - 4`. |

###### Returns

`number`

`offset` plus the number of bytes written.

##### writeInt16BE()

> **writeInt16BE**(`value`: `number`, `offset?`: `number`): `number`

Writes `value` to `buf` at the specified `offset` as big-endian.  The `value` must be a valid signed 16-bit integer. Behavior is undefined when `value` is
anything other than a signed 16-bit integer.

The `value` is interpreted and written as a two's complement signed integer.

```js
import { Buffer } from 'buffer';

const buf = Buffer.allocUnsafe(2);

buf.writeInt16BE(0x0102, 0);

console.log(buf);
// Prints: <Buffer 01 02>
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `value` | `number` | Number to be written to `buf`. |
| `offset?` | `number` | Number of bytes to skip before starting to write. Must satisfy `0 <= offset <= buf.length - 2`. |

###### Returns

`number`

`offset` plus the number of bytes written.

##### writeInt16LE()

> **writeInt16LE**(`value`: `number`, `offset?`: `number`): `number`

Writes `value` to `buf` at the specified `offset` as little-endian.  The `value` must be a valid signed 16-bit integer. Behavior is undefined when `value` is
anything other than a signed 16-bit integer.

The `value` is interpreted and written as a two's complement signed integer.

```js
import { Buffer } from 'buffer';

const buf = Buffer.allocUnsafe(2);

buf.writeInt16LE(0x0304, 0);

console.log(buf);
// Prints: <Buffer 04 03>
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `value` | `number` | Number to be written to `buf`. |
| `offset?` | `number` | Number of bytes to skip before starting to write. Must satisfy `0 <= offset <= buf.length - 2`. |

###### Returns

`number`

`offset` plus the number of bytes written.

##### writeInt32BE()

> **writeInt32BE**(`value`: `number`, `offset?`: `number`): `number`

Writes `value` to `buf` at the specified `offset` as big-endian. The `value` must be a valid signed 32-bit integer. Behavior is undefined when `value` is
anything other than a signed 32-bit integer.

The `value` is interpreted and written as a two's complement signed integer.

```js
import { Buffer } from 'buffer';

const buf = Buffer.allocUnsafe(4);

buf.writeInt32BE(0x01020304, 0);

console.log(buf);
// Prints: <Buffer 01 02 03 04>
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `value` | `number` | - |
| `offset?` | `number` | Number of bytes to skip before starting to write. Must satisfy `0 <= offset <= buf.length - 4`. |

###### Returns

`number`

`offset` plus the number of bytes written.

##### writeInt32LE()

> **writeInt32LE**(`value`: `number`, `offset?`: `number`): `number`

Writes `value` to `buf` at the specified `offset` as little-endian. The `value` must be a valid signed 32-bit integer. Behavior is undefined when `value` is
anything other than a signed 32-bit integer.

The `value` is interpreted and written as a two's complement signed integer.

```js
import { Buffer } from 'buffer';

const buf = Buffer.allocUnsafe(4);

buf.writeInt32LE(0x05060708, 0);

console.log(buf);
// Prints: <Buffer 08 07 06 05>
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `value` | `number` | Number to be written to `buf`. |
| `offset?` | `number` | Number of bytes to skip before starting to write. Must satisfy `0 <= offset <= buf.length - 4`. |

###### Returns

`number`

`offset` plus the number of bytes written.

##### writeInt8()

> **writeInt8**(`value`: `number`, `offset?`: `number`): `number`

Writes `value` to `buf` at the specified `offset`. `value` must be a valid
signed 8-bit integer. Behavior is undefined when `value` is anything other than
a signed 8-bit integer.

`value` is interpreted and written as a two's complement signed integer.

```js
import { Buffer } from 'buffer';

const buf = Buffer.allocUnsafe(2);

buf.writeInt8(2, 0);
buf.writeInt8(-2, 1);

console.log(buf);
// Prints: <Buffer 02 fe>
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `value` | `number` | Number to be written to `buf`. |
| `offset?` | `number` | Number of bytes to skip before starting to write. Must satisfy `0 <= offset <= buf.length - 1`. |

###### Returns

`number`

`offset` plus the number of bytes written.

##### writeUint16BE()

> **writeUint16BE**(`value`: `number`, `offset?`: `number`): `number`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `value` | `number` |
| `offset?` | `number` |

###### Returns

`number`

###### Alias

Buffer.writeUInt16BE

##### writeUInt16BE()

> **writeUInt16BE**(`value`: `number`, `offset?`: `number`): `number`

Writes `value` to `buf` at the specified `offset` as big-endian. The `value` must be a valid unsigned 16-bit integer. Behavior is undefined when `value`is anything other than an
unsigned 16-bit integer.

This function is also available under the `writeUint16BE` alias.

```js
import { Buffer } from 'buffer';

const buf = Buffer.allocUnsafe(4);

buf.writeUInt16BE(0xdead, 0);
buf.writeUInt16BE(0xbeef, 2);

console.log(buf);
// Prints: <Buffer de ad be ef>
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `value` | `number` | Number to be written to `buf`. |
| `offset?` | `number` | Number of bytes to skip before starting to write. Must satisfy `0 <= offset <= buf.length - 2`. |

###### Returns

`number`

`offset` plus the number of bytes written.

##### writeUint16LE()

> **writeUint16LE**(`value`: `number`, `offset?`: `number`): `number`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `value` | `number` |
| `offset?` | `number` |

###### Returns

`number`

###### Alias

Buffer.writeUInt16LE

##### writeUInt16LE()

> **writeUInt16LE**(`value`: `number`, `offset?`: `number`): `number`

Writes `value` to `buf` at the specified `offset` as little-endian. The `value` must be a valid unsigned 16-bit integer. Behavior is undefined when `value` is
anything other than an unsigned 16-bit integer.

This function is also available under the `writeUint16LE` alias.

```js
import { Buffer } from 'buffer';

const buf = Buffer.allocUnsafe(4);

buf.writeUInt16LE(0xdead, 0);
buf.writeUInt16LE(0xbeef, 2);

console.log(buf);
// Prints: <Buffer ad de ef be>
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `value` | `number` | Number to be written to `buf`. |
| `offset?` | `number` | Number of bytes to skip before starting to write. Must satisfy `0 <= offset <= buf.length - 2`. |

###### Returns

`number`

`offset` plus the number of bytes written.

##### writeUint32BE()

> **writeUint32BE**(`value`: `number`, `offset?`: `number`): `number`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `value` | `number` |
| `offset?` | `number` |

###### Returns

`number`

###### Alias

Buffer.writeUInt32BE

##### writeUInt32BE()

> **writeUInt32BE**(`value`: `number`, `offset?`: `number`): `number`

Writes `value` to `buf` at the specified `offset` as big-endian. The `value` must be a valid unsigned 32-bit integer. Behavior is undefined when `value`is anything other than an
unsigned 32-bit integer.

This function is also available under the `writeUint32BE` alias.

```js
import { Buffer } from 'buffer';

const buf = Buffer.allocUnsafe(4);

buf.writeUInt32BE(0xfeedface, 0);

console.log(buf);
// Prints: <Buffer fe ed fa ce>
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `value` | `number` | Number to be written to `buf`. |
| `offset?` | `number` | Number of bytes to skip before starting to write. Must satisfy `0 <= offset <= buf.length - 4`. |

###### Returns

`number`

`offset` plus the number of bytes written.

##### writeUint32LE()

> **writeUint32LE**(`value`: `number`, `offset?`: `number`): `number`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `value` | `number` |
| `offset?` | `number` |

###### Returns

`number`

###### Alias

Buffer.writeUInt32LE

##### writeUInt32LE()

> **writeUInt32LE**(`value`: `number`, `offset?`: `number`): `number`

Writes `value` to `buf` at the specified `offset` as little-endian. The `value` must be a valid unsigned 32-bit integer. Behavior is undefined when `value` is
anything other than an unsigned 32-bit integer.

This function is also available under the `writeUint32LE` alias.

```js
import { Buffer } from 'buffer';

const buf = Buffer.allocUnsafe(4);

buf.writeUInt32LE(0xfeedface, 0);

console.log(buf);
// Prints: <Buffer ce fa ed fe>
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `value` | `number` | Number to be written to `buf`. |
| `offset?` | `number` | Number of bytes to skip before starting to write. Must satisfy `0 <= offset <= buf.length - 4`. |

###### Returns

`number`

`offset` plus the number of bytes written.

##### writeUint8()

> **writeUint8**(`value`: `number`, `offset?`: `number`): `number`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `value` | `number` |
| `offset?` | `number` |

###### Returns

`number`

###### Alias

Buffer.writeUInt8

##### writeUInt8()

> **writeUInt8**(`value`: `number`, `offset?`: `number`): `number`

Writes `value` to `buf` at the specified `offset`. `value` must be a
valid unsigned 8-bit integer. Behavior is undefined when `value` is anything
other than an unsigned 8-bit integer.

This function is also available under the `writeUint8` alias.

```js
import { Buffer } from 'buffer';

const buf = Buffer.allocUnsafe(4);

buf.writeUInt8(0x3, 0);
buf.writeUInt8(0x4, 1);
buf.writeUInt8(0x23, 2);
buf.writeUInt8(0x42, 3);

console.log(buf);
// Prints: <Buffer 03 04 23 42>
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `value` | `number` | Number to be written to `buf`. |
| `offset?` | `number` | Number of bytes to skip before starting to write. Must satisfy `0 <= offset <= buf.length - 1`. |

###### Returns

`number`

`offset` plus the number of bytes written.

***

### BufferConstructor

#### Methods

##### alloc()

> **alloc**(`size`: `number`, `fill?`: `string` | `number` | `Uint8Array`, `encoding?`: [`BufferEncoding`](#bufferencoding)): [`Buffer`](#buffer)

Allocates a new `Buffer` of `size` bytes. If `fill` is `undefined`, the `Buffer` will be zero-filled.

```js
import { Buffer } from 'buffer';

const buf = Buffer.alloc(5);

console.log(buf);
// Prints: <Buffer 00 00 00 00 00>
```

If `fill` is specified, the allocated `Buffer` will be initialized by calling `Buffer.alloc(size, fill)`.

```js
import { Buffer } from 'buffer';

const buf = Buffer.alloc(5, 'a');

console.log(buf);
// Prints: <Buffer 61 61 61 61 61>
```

If both `fill` and `encoding` are specified, the allocated `Buffer` will be
initialized by calling `Buffer.aloc(size, fill, encoding)`.

```js
import { Buffer } from 'buffer';

const buf = Buffer.alloc(11, 'aGVsbG8gd29ybGQ=', 'base64');

console.log(buf);
// Prints: <Buffer 68 65 6c 6c 6f 20 77 6f 72 6c 64>
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `size` | `number` | The desired length of the new `Buffer`. |
| `fill?` | `string` | `number` | `Uint8Array` | A value to pre-fill the new `Buffer` with. |
| `encoding?` | [`BufferEncoding`](#bufferencoding) | If `fill` is a string, this is its encoding. |

###### Returns

[`Buffer`](#buffer)

##### allocUnsafe()

> **allocUnsafe**(`size`: `number`): [`Buffer`](#buffer)

Allocates a new `Buffer` of `size` bytes.

The underlying memory for `Buffer` instances created in this way is *not*
*initialized*. The contents of the newly created `Buffer` are unknown and *may contain sensitive data*. Use `Buffer.alloc()` instead to initialize`Buffer` instances with zeroes.

```js
import { Buffer } from 'buffer';

const buf = Buffer.allocUnsafe(10);

console.log(buf);
// Prints (contents may vary): <Buffer a0 8b 28 3f 01 00 00 00 50 32>

buf.fill(0);

console.log(buf);
// Prints: <Buffer 00 00 00 00 00 00 00 00 00 00>
```

A `TypeError` will be thrown if `size` is not a number.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `size` | `number` | The desired length of the new `Buffer`. |

###### Returns

[`Buffer`](#buffer)

##### allocUnsafeSlow()

> **allocUnsafeSlow**(`size`: `number`): [`Buffer`](#buffer)

Allocates a new `Buffer` of `size` bytes.

The underlying memory for `Buffer` instances created in this way is *not*
*initialized*. The contents of the newly created `Buffer` are unknown and *may contain sensitive data*. Use `buf.fill(0)` to initialize
such `Buffer` instances with zeroes.

```js
import { Buffer } from 'buffer';

// Need to keep around a few small chunks of memory.
const store = [];

socket.on('readable', () => {
  let data;
  while (null !== (data = readable.read())) {
    // Allocate for retained data.
    const sb = Buffer.allocUnsafeSlow(10);

    // Copy the data into the new allocation.
    data.copy(sb, 0, 0, 10);

    store.push(sb);
  }
});
```

A `TypeError` will be thrown if `size` is not a number.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `size` | `number` | The desired length of the new `Buffer`. |

###### Returns

[`Buffer`](#buffer)

##### byteLength()

> **byteLength**(`string`: `string` | [`ArrayBufferView`](globals/namespaces/QuickJS.md#arraybufferview) | [`Buffer`](#buffer) | `ArrayBuffer` | `SharedArrayBuffer`, `encoding?`: [`BufferEncoding`](#bufferencoding)): `number`

Returns the byte length of a string when encoded using `encoding`.
This is not the same as [`String.prototype.length`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/length), which does not account
for the encoding that is used to convert the string into bytes.

```js
import { Buffer } from 'buffer';

const str = '\u00bd + \u00bc = \u00be';

console.log(`${str}: ${str.length} characters, ` +
            `${Buffer.byteLength(str, 'utf8')} bytes`);
// Prints: ½ + ¼ = ¾: 9 characters, 12 bytes
```

When `string` is a
`Buffer`/[`DataView`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/DataView)/[`TypedArray`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray)/[`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer)/[`SharedArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer), the byte length as reported by `.byteLength`is returned.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `string` | `string` | [`ArrayBufferView`](globals/namespaces/QuickJS.md#arraybufferview) | [`Buffer`](#buffer) | `ArrayBuffer` | `SharedArrayBuffer` | A value to calculate the length of. |
| `encoding?` | [`BufferEncoding`](#bufferencoding) | If `string` is a string, this is its encoding. |

###### Returns

`number`

The number of bytes contained within `string`.

##### concat()

> **concat**(`list`: readonly `Uint8Array`\[], `totalLength?`: `number`): [`Buffer`](#buffer)

Returns a new `Buffer` which is the result of concatenating all the `Buffer` instances in the `list` together.

If the list has no items, or if the `totalLength` is 0, then a new zero-length `Buffer` is returned.

If `totalLength` is not provided, it is calculated from the `Buffer` instances
in `list` by adding their lengths.

If `totalLength` is provided, it is coerced to an unsigned integer. If the
combined length of the `Buffer`s in `list` exceeds `totalLength`, the result is
truncated to `totalLength`.

```js
import { Buffer } from 'buffer';

// Create a single `Buffer` from a list of three `Buffer` instances.

const buf1 = Buffer.alloc(10);
const buf2 = Buffer.alloc(14);
const buf3 = Buffer.alloc(18);
const totalLength = buf1.length + buf2.length + buf3.length;

console.log(totalLength);
// Prints: 42

const bufA = Buffer.concat([buf1, buf2, buf3], totalLength);

console.log(bufA);
// Prints: <Buffer 00 00 00 00 ...>
console.log(bufA.length);
// Prints: 42
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `list` | readonly `Uint8Array`\[] | List of `Buffer` or Uint8Array instances to concatenate. |
| `totalLength?` | `number` | Total length of the `Buffer` instances in `list` when concatenated. |

###### Returns

[`Buffer`](#buffer)

##### from()

###### Call Signature

> **from**(`arrayBuffer`: [`WithImplicitCoercion`](#withimplicitcoercion)<`ArrayBuffer` | `SharedArrayBuffer`>, `byteOffset?`: `number`, `length?`: `number`): [`Buffer`](#buffer)

Allocates a new `Buffer` using an `array` of bytes in the range `0` – `255`.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `arrayBuffer` | [`WithImplicitCoercion`](#withimplicitcoercion)<`ArrayBuffer` | `SharedArrayBuffer`> |
| `byteOffset?` | `number` |
| `length?` | `number` |

###### Returns

[`Buffer`](#buffer)

###### Call Signature

> **from**(`data`: `Uint8Array` | readonly `number`\[]): [`Buffer`](#buffer)

Creates a new Buffer using the passed {data}

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `data` | `Uint8Array` | readonly `number`\[] | data to create a new Buffer |

###### Returns

[`Buffer`](#buffer)

###### Call Signature

> **from**(`data`: [`WithImplicitCoercion`](#withimplicitcoercion)<`string` | `Uint8Array` | readonly `number`\[]>): [`Buffer`](#buffer)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `data` | [`WithImplicitCoercion`](#withimplicitcoercion)<`string` | `Uint8Array` | readonly `number`\[]> |

###### Returns

[`Buffer`](#buffer)

###### Call Signature

> **from**(`str`: [`WithImplicitCoercion`](#withimplicitcoercion)<`string`> | { `[toPrimitive]`: `string`; }, `encoding?`: [`BufferEncoding`](#bufferencoding)): [`Buffer`](#buffer)

Creates a new Buffer containing the given JavaScript string {str}.
If provided, the {encoding} parameter identifies the character encoding.
If not provided, {encoding} defaults to 'utf8'.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `str` | [`WithImplicitCoercion`](#withimplicitcoercion)<`string`> | { `[toPrimitive]`: `string`; } |
| `encoding?` | [`BufferEncoding`](#bufferencoding) |

###### Returns

[`Buffer`](#buffer)

##### isBuffer()

> **isBuffer**(`obj`: `any`): `obj is Buffer`

Returns `true` if `obj` is a `Buffer`, `false` otherwise.

```js
import { Buffer } from 'buffer';

Buffer.isBuffer(Buffer.alloc(10)); // true
Buffer.isBuffer(Buffer.from('foo')); // true
Buffer.isBuffer('a string'); // false
Buffer.isBuffer([]); // false
Buffer.isBuffer(new Uint8Array(1024)); // false
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `obj` | `any` |

###### Returns

`obj is Buffer`

##### isEncoding()

> **isEncoding**(`encoding`: `string`): `encoding is BufferEncoding`

Returns `true` if `encoding` is the name of a supported character encoding,
or `false` otherwise.

```js
import { Buffer } from 'buffer';

console.log(Buffer.isEncoding('utf8'));
// Prints: true

console.log(Buffer.isEncoding('hex'));
// Prints: true

console.log(Buffer.isEncoding('utf/8'));
// Prints: false

console.log(Buffer.isEncoding(''));
// Prints: false
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `encoding` | `string` | A character encoding name to check. |

###### Returns

`encoding is BufferEncoding`

## Type Aliases

### BufferEncoding

> **BufferEncoding** = `"hex"` | `"base64"` | `"utf-8"` | `"utf8"` | `"unicode-1-1-utf8"` | `"ucs2"` | `"ucs-2"` | `"utf-16le"` | `"utf16le"` | `"utf-16"` | `"utf16"` | `"utf-16be"` | `"utf16be"` | `"windows-1252"` | `"ansi_x3.4-1968"` | `"ascii"` | `"cp1252"` | `"cp819"` | `"csisolatin1"` | `"ibm819"` | `"iso-8859-1"` | `"iso-ir-100"` | `"iso8859-1"` | `"iso88591"` | `"iso_8859-1"` | `"iso_8859-1:1987"` | `"l1"` | `"latin1"` | `"us-ascii"` | `"x-cp1252"`

***

### WithImplicitCoercion

> **WithImplicitCoercion**<`T`> = `T` | { `valueOf`: `T`; }

#### Type Parameters

| Type Parameter |
| ------ |
| `T` |

## Variables

### Buffer

> **Buffer**: [`BufferConstructor`](#bufferconstructor)

***

### constants

> `const` **constants**: `object`

#### Type Declaration

##### MAX\_LENGTH

> **MAX\_LENGTH**: `number`

##### MAX\_STRING\_LENGTH

> **MAX\_STRING\_LENGTH**: `number`

## Functions

### atob()

> **atob**(`data`: `string`): `string`

Decodes a string of Base64-encoded data into bytes, and encodes those bytes
into a string using UTF-8.

The `data` may be any JavaScript-value that can be coerced into a string.

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `data` | `string` | The Base64-encoded input string. |

#### Returns

`string`

#### Legacy

Use `Buffer.from(data, 'base64')` instead.

***

### btoa()

> **btoa**(`data`: `string`): `string`

Decodes a string into bytes using UTF-8, and encodes those bytes
into a string using Base64.

The `data` may be any JavaScript-value that can be coerced into a string.

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `data` | `string` | An ASCII (Latin1) string. |

#### Returns

`string`

#### Legacy

Use `buf.toString('base64')` instead.

---

---
url: /plugins/reference/modules/llrt/child_process.md
---
[@caido/quickjs-types](../index.md) / llrt/child\_process

# llrt/child\_process

## Classes

### ChildProcess

Instances of the `ChildProcess` represent spawned child processes.

Instances of `ChildProcess` are not intended to be created directly. Rather,
use the [spawn](#spawn) method to create instances of `ChildProcess`.

#### Extends

* [`EventEmitter`](events.md#eventemitter)

#### Extended by

* [`ChildProcessWithoutNullStreams`](#childprocesswithoutnullstreams)
* [`ChildProcessByStdio`](#childprocessbystdio)

#### Constructors

##### Constructor

> **new ChildProcess**(): [`ChildProcess`](#childprocess)

###### Returns

[`ChildProcess`](#childprocess)

###### Inherited from

[`EventEmitter`](events.md#eventemitter).[`constructor`](events.md#constructor)

#### Properties

##### pid?

> `readonly` `optional` **pid**: `number`

Returns the process identifier (PID) of the child process. If the child process
fails to spawn due to errors, then the value is `undefined` and `error` is
emitted.

```js
const { spawn } = require('child_process');
const grep = spawn('grep', ['ssh']);

console.log(`Spawned child pid: ${grep.pid}`);
grep.stdin.end();
```

##### stderr

> **stderr**: [`DefaultReadableStream`](stream/stream.md#defaultreadablestream) | `null`

A `Readable Stream` that represents the child process's `stderr`.

If the child was spawned with `stdio[2]` set to anything other than `'pipe'`,
then this will be `null`.

`subprocess.stderr` is an alias for `subprocess.stdio[2]`. Both properties will
refer to the same value.

The `subprocess.stderr` property can be `null` or `undefined` if the child process could not be successfully spawned.

##### stdin

> **stdin**: [`DefaultWritableStream`](stream/stream.md#defaultwritablestream) | `null`

A `Writable Stream` that represents the child process's `stdin`.

If a child process waits to read all of its input, the child will not continue
until this stream has been closed via `end()`.

If the child was spawned with `stdio[0]` set to anything other than `'pipe'`,
then this will be `null`.

`subprocess.stdin` is an alias for `subprocess.stdio[0]`. Both properties will
refer to the same value.

The `subprocess.stdin` property can be `null` or `undefined` if the child process could not be successfully spawned.

##### stdout

> **stdout**: [`DefaultReadableStream`](stream/stream.md#defaultreadablestream) | `null`

A `Readable Stream` that represents the child process's `stdout`.

If the child was spawned with `stdio[1]` set to anything other than `'pipe'`,
then this will be `null`.

`subprocess.stdout` is an alias for `subprocess.stdio[1]`. Both properties will
refer to the same value.

```js
const { spawn } = require('child_process');

const subprocess = spawn('ls');

subprocess.stdout.on('data', (data) => {
  console.log(`Received chunk ${data}`);
});
```

The `subprocess.stdout` property can be `null` or `undefined` if the child process could not be successfully spawned.

#### Methods

##### \[dispose]\()

> **\[dispose]**(): `void`

Calls [ChildProcess.kill](#kill) with `'SIGTERM'`.

###### Returns

`void`

##### addListener()

###### Call Signature

> **addListener**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

events.EventEmitter

1. close
2. error
3. exit

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `string` |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Overrides

[`EventEmitter`](events.md#eventemitter).[`addListener`](events.md#addlistener)

###### Call Signature

> **addListener**(`event`: `"close"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

events.EventEmitter

1. close
2. error
3. exit

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.addListener`

###### Call Signature

> **addListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

events.EventEmitter

1. close
2. error
3. exit

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.addListener`

###### Call Signature

> **addListener**(`event`: `"exit"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

events.EventEmitter

1. close
2. error
3. exit

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"exit"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.addListener`

##### emit()

###### Call Signature

> **emit**(`event`: `string` | `symbol`, ...`args`: `any`\[]): `boolean`

Synchronously calls each of the listeners registered for the event named `eventName`, in the order they were registered, passing the supplied arguments
to each.

```js
import { EventEmitter } from 'events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `string` | `symbol` |
| ...`args` | `any`\[] |

###### Returns

`boolean`

###### Overrides

[`EventEmitter`](events.md#eventemitter).[`emit`](events.md#emit)

###### Call Signature

> **emit**(`event`: `"close"`, `code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `code` | `number` | `null` |
| `signal` | [`Signals`](globals/namespaces/QuickJS.md#signals) | `null` |

###### Returns

`boolean`

###### Overrides

`EventEmitter.emit`

###### Call Signature

> **emit**(`event`: `"error"`, `err`: `Error`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `err` | `Error` |

###### Returns

`boolean`

###### Overrides

`EventEmitter.emit`

###### Call Signature

> **emit**(`event`: `"exit"`, `code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"exit"` |
| `code` | `number` | `null` |
| `signal` | [`Signals`](globals/namespaces/QuickJS.md#signals) | `null` |

###### Returns

`boolean`

###### Overrides

`EventEmitter.emit`

##### eventNames()

> **eventNames**(): [`EventKey`](dom-events.md#eventkey)\[]

Returns an array listing the events for which the emitter has registered
listeners. The values in the array are strings or `Symbol`s.

```js
import { EventEmitter } from 'events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]
```

###### Returns

[`EventKey`](dom-events.md#eventkey)\[]

###### Inherited from

[`EventEmitter`](events.md#eventemitter).[`eventNames`](events.md#eventnames)

##### kill()

> **kill**(`signal?`: `number` | [`Signals`](globals/namespaces/QuickJS.md#signals)): `boolean`

The `subprocess.kill()` method sends a signal to the child process. If no
argument is given, the process will be sent the `'SIGTERM'` signal. See [`signal(7)`](http://man7.org/linux/man-pages/man7/signal.7.html) for a list of available signals. This function
returns `true` if [`kill(2)`](http://man7.org/linux/man-pages/man2/kill.2.html) succeeds, and `false` otherwise.

```js
const { spawn } = require('child_process');
const grep = spawn('grep', ['ssh']);

grep.on('close', (code, signal) => {
  console.log(
    `child process terminated due to receipt of signal ${signal}`);
});

// Send SIGHUP to process.
grep.kill('SIGHUP');
```

The `ChildProcess` object may emit an `'error'` event if the signal
cannot be delivered. Sending a signal to a child process that has already exited
is not an error but may have unforeseen consequences. Specifically, if the
process identifier (PID) has been reassigned to another process, the signal will
be delivered to that process instead which can have unexpected results.

While the function is called `kill`, the signal delivered to the child process
may not actually terminate the process.

See [`kill(2)`](http://man7.org/linux/man-pages/man2/kill.2.html) for reference.

On Windows, where POSIX signals do not exist, the `signal` argument will be
ignored, and the process will be killed forcefully and abruptly (similar to `'SIGKILL'`).
See `Signal Events` for more details.

On Linux, child processes of child processes will not be terminated
when attempting to kill their parent. This is likely to happen when running a
new process in a shell or with the use of the `shell` option of `ChildProcess`:

```js
'use strict';
const { spawn } = require('child_process');

const subprocess = spawn(
  'sh',
  [
    '-c',
    `node -e "setInterval(() => {
      console.log(process.pid, 'is alive')
    }, 500);"`,
  ], {
    stdio: ['inherit', 'inherit', 'inherit'],
  },
);

setTimeout(() => {
  subprocess.kill(); // Does not terminate the Node.js process in the shell.
}, 2000);
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `signal?` | `number` | [`Signals`](globals/namespaces/QuickJS.md#signals) |

###### Returns

`boolean`

##### off()

> **off**<`K`>(`eventName`: [`EventKey`](dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Alias for `emitter.removeListener()`.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`EventKey`](dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`EventEmitter`](events.md#eventemitter).[`off`](events.md#off)

##### on()

###### Call Signature

> **on**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the end of the listeners array for the event
named `eventName`. No checks are made to see if the `listener` has already
been added. Multiple calls passing the same combination of `eventName` and
`listener` will result in the `listener` being added, and called, multiple times.

```js
server.on('connection', (stream) => {
  console.log('someone connected!');
});
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | `string` | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Overrides

[`EventEmitter`](events.md#eventemitter).[`on`](events.md#on)

###### Call Signature

> **on**(`event`: `"close"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.on`

###### Call Signature

> **on**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.on`

###### Call Signature

> **on**(`event`: `"exit"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"exit"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.on`

##### once()

###### Call Signature

> **once**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time** `listener` function for the event named `eventName`. The
next time `eventName` is triggered, this listener is removed and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependOnceListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | `string` | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Since

v0.3.0

###### Overrides

[`EventEmitter`](events.md#eventemitter).[`once`](events.md#once)

###### Call Signature

> **once**(`event`: `"close"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.once`

###### Call Signature

> **once**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.once`

###### Call Signature

> **once**(`event`: `"exit"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"exit"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.once`

##### prependListener()

###### Call Signature

> **prependListener**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the *beginning* of the listeners array for the
event named `eventName`. No checks are made to see if the `listener` has
already been added. Multiple calls passing the same combination of `eventName`
and `listener` will result in the `listener` being added, and called, multiple times.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | `string` | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Overrides

[`EventEmitter`](events.md#eventemitter).[`prependListener`](events.md#prependlistener)

###### Call Signature

> **prependListener**(`event`: `"close"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.prependListener`

###### Call Signature

> **prependListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.prependListener`

###### Call Signature

> **prependListener**(`event`: `"exit"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"exit"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.prependListener`

##### prependOnceListener()

###### Call Signature

> **prependOnceListener**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time**`listener` function for the event named `eventName` to the *beginning* of the listeners array.
The next time `eventName` is triggered, this listener is removed, and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | `string` | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Overrides

[`EventEmitter`](events.md#eventemitter).[`prependOnceListener`](events.md#prependoncelistener)

###### Call Signature

> **prependOnceListener**(`event`: `"close"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.prependOnceListener`

###### Call Signature

> **prependOnceListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.prependOnceListener`

###### Call Signature

> **prependOnceListener**(`event`: `"exit"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"exit"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.prependOnceListener`

##### removeListener()

> **removeListener**<`K`>(`eventName`: [`EventKey`](dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Removes the specified `listener` from the listener array for the event named `eventName`.

`removeListener()` will remove, at most, one instance of a listener from the
listener array. If any single listener has been added multiple times to the
listener array for the specified `eventName`, then `removeListener()` must be
called multiple times to remove each instance.

Once an event is emitted, all listeners attached to it at the time of emitting are called in order.
This implies that any `removeListener()` calls *after* emitting and *before* the last listener finishes execution
will not remove them from `emit()` in progress. Subsequent events behave as expected.

```js
import { EventEmitter } from 'events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A
```

Because listeners are managed using an internal array, calling this will
change the position indices of any listener registered *after* the listener
being removed. This will not impact the order in which listeners are called,
but it means that any copies of the listener array as returned by
the `emitter.listeners()` method will need to be recreated.

When a single function has been added as a handler multiple times for a single
event (as in the example below), `removeListener()` will remove the most
recently added instance. In the example the `once('ping')` listener is removed:

```js
import { EventEmitter } from 'events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`EventKey`](dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`EventEmitter`](events.md#eventemitter).[`removeListener`](events.md#removelistener)

## Interfaces

### ChildProcessByStdio

Instances of the `ChildProcess` represent spawned child processes.

Instances of `ChildProcess` are not intended to be created directly. Rather,
use the [spawn](#spawn) method to create instances of `ChildProcess`.

#### Extends

* [`ChildProcess`](#childprocess)

#### Type Parameters

| Type Parameter |
| ------ |
| `I` *extends* `null` | [`DefaultWritableStream`](stream/stream.md#defaultwritablestream) |
| `O` *extends* `null` | [`DefaultReadableStream`](stream/stream.md#defaultreadablestream) |
| `E` *extends* `null` | [`DefaultReadableStream`](stream/stream.md#defaultreadablestream) |

#### Properties

##### pid?

> `readonly` `optional` **pid**: `number`

Returns the process identifier (PID) of the child process. If the child process
fails to spawn due to errors, then the value is `undefined` and `error` is
emitted.

```js
const { spawn } = require('child_process');
const grep = spawn('grep', ['ssh']);

console.log(`Spawned child pid: ${grep.pid}`);
grep.stdin.end();
```

###### Inherited from

[`ChildProcessWithoutNullStreams`](#childprocesswithoutnullstreams).[`pid`](#pid-2)

##### stderr

> **stderr**: `E`

A `Readable Stream` that represents the child process's `stderr`.

If the child was spawned with `stdio[2]` set to anything other than `'pipe'`,
then this will be `null`.

`subprocess.stderr` is an alias for `subprocess.stdio[2]`. Both properties will
refer to the same value.

The `subprocess.stderr` property can be `null` or `undefined` if the child process could not be successfully spawned.

###### Overrides

[`ChildProcess`](#childprocess).[`stderr`](#stderr)

##### stdin

> **stdin**: `I`

A `Writable Stream` that represents the child process's `stdin`.

If a child process waits to read all of its input, the child will not continue
until this stream has been closed via `end()`.

If the child was spawned with `stdio[0]` set to anything other than `'pipe'`,
then this will be `null`.

`subprocess.stdin` is an alias for `subprocess.stdio[0]`. Both properties will
refer to the same value.

The `subprocess.stdin` property can be `null` or `undefined` if the child process could not be successfully spawned.

###### Overrides

[`ChildProcess`](#childprocess).[`stdin`](#stdin)

##### stdout

> **stdout**: `O`

A `Readable Stream` that represents the child process's `stdout`.

If the child was spawned with `stdio[1]` set to anything other than `'pipe'`,
then this will be `null`.

`subprocess.stdout` is an alias for `subprocess.stdio[1]`. Both properties will
refer to the same value.

```js
const { spawn } = require('child_process');

const subprocess = spawn('ls');

subprocess.stdout.on('data', (data) => {
  console.log(`Received chunk ${data}`);
});
```

The `subprocess.stdout` property can be `null` or `undefined` if the child process could not be successfully spawned.

###### Overrides

[`ChildProcess`](#childprocess).[`stdout`](#stdout)

#### Methods

##### \[dispose]\()

> **\[dispose]**(): `void`

Calls [ChildProcess.kill](#kill) with `'SIGTERM'`.

###### Returns

`void`

###### Inherited from

[`ChildProcess`](#childprocess).[`[dispose]`](#dispose)

##### addListener()

###### Call Signature

> **addListener**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

events.EventEmitter

1. close
2. error
3. exit

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `string` |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`addListener`](#addlistener)

###### Call Signature

> **addListener**(`event`: `"close"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

events.EventEmitter

1. close
2. error
3. exit

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`addListener`](#addlistener)

###### Call Signature

> **addListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

events.EventEmitter

1. close
2. error
3. exit

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`addListener`](#addlistener)

###### Call Signature

> **addListener**(`event`: `"exit"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

events.EventEmitter

1. close
2. error
3. exit

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"exit"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`addListener`](#addlistener)

##### emit()

###### Call Signature

> **emit**(`event`: `string` | `symbol`, ...`args`: `any`\[]): `boolean`

Synchronously calls each of the listeners registered for the event named `eventName`, in the order they were registered, passing the supplied arguments
to each.

```js
import { EventEmitter } from 'events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `string` | `symbol` |
| ...`args` | `any`\[] |

###### Returns

`boolean`

###### Inherited from

[`ChildProcess`](#childprocess).[`emit`](#emit)

###### Call Signature

> **emit**(`event`: `"close"`, `code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `code` | `number` | `null` |
| `signal` | [`Signals`](globals/namespaces/QuickJS.md#signals) | `null` |

###### Returns

`boolean`

###### Inherited from

[`ChildProcess`](#childprocess).[`emit`](#emit)

###### Call Signature

> **emit**(`event`: `"error"`, `err`: `Error`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `err` | `Error` |

###### Returns

`boolean`

###### Inherited from

[`ChildProcess`](#childprocess).[`emit`](#emit)

###### Call Signature

> **emit**(`event`: `"exit"`, `code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"exit"` |
| `code` | `number` | `null` |
| `signal` | [`Signals`](globals/namespaces/QuickJS.md#signals) | `null` |

###### Returns

`boolean`

###### Inherited from

[`ChildProcess`](#childprocess).[`emit`](#emit)

##### eventNames()

> **eventNames**(): [`EventKey`](dom-events.md#eventkey)\[]

Returns an array listing the events for which the emitter has registered
listeners. The values in the array are strings or `Symbol`s.

```js
import { EventEmitter } from 'events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]
```

###### Returns

[`EventKey`](dom-events.md#eventkey)\[]

###### Inherited from

[`ChildProcess`](#childprocess).[`eventNames`](#eventnames)

##### kill()

> **kill**(`signal?`: `number` | [`Signals`](globals/namespaces/QuickJS.md#signals)): `boolean`

The `subprocess.kill()` method sends a signal to the child process. If no
argument is given, the process will be sent the `'SIGTERM'` signal. See [`signal(7)`](http://man7.org/linux/man-pages/man7/signal.7.html) for a list of available signals. This function
returns `true` if [`kill(2)`](http://man7.org/linux/man-pages/man2/kill.2.html) succeeds, and `false` otherwise.

```js
const { spawn } = require('child_process');
const grep = spawn('grep', ['ssh']);

grep.on('close', (code, signal) => {
  console.log(
    `child process terminated due to receipt of signal ${signal}`);
});

// Send SIGHUP to process.
grep.kill('SIGHUP');
```

The `ChildProcess` object may emit an `'error'` event if the signal
cannot be delivered. Sending a signal to a child process that has already exited
is not an error but may have unforeseen consequences. Specifically, if the
process identifier (PID) has been reassigned to another process, the signal will
be delivered to that process instead which can have unexpected results.

While the function is called `kill`, the signal delivered to the child process
may not actually terminate the process.

See [`kill(2)`](http://man7.org/linux/man-pages/man2/kill.2.html) for reference.

On Windows, where POSIX signals do not exist, the `signal` argument will be
ignored, and the process will be killed forcefully and abruptly (similar to `'SIGKILL'`).
See `Signal Events` for more details.

On Linux, child processes of child processes will not be terminated
when attempting to kill their parent. This is likely to happen when running a
new process in a shell or with the use of the `shell` option of `ChildProcess`:

```js
'use strict';
const { spawn } = require('child_process');

const subprocess = spawn(
  'sh',
  [
    '-c',
    `node -e "setInterval(() => {
      console.log(process.pid, 'is alive')
    }, 500);"`,
  ], {
    stdio: ['inherit', 'inherit', 'inherit'],
  },
);

setTimeout(() => {
  subprocess.kill(); // Does not terminate the Node.js process in the shell.
}, 2000);
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `signal?` | `number` | [`Signals`](globals/namespaces/QuickJS.md#signals) |

###### Returns

`boolean`

###### Inherited from

[`ChildProcess`](#childprocess).[`kill`](#kill)

##### off()

> **off**<`K`>(`eventName`: [`EventKey`](dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Alias for `emitter.removeListener()`.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`EventKey`](dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`off`](#off)

##### on()

###### Call Signature

> **on**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the end of the listeners array for the event
named `eventName`. No checks are made to see if the `listener` has already
been added. Multiple calls passing the same combination of `eventName` and
`listener` will result in the `listener` being added, and called, multiple times.

```js
server.on('connection', (stream) => {
  console.log('someone connected!');
});
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | `string` | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`on`](#on)

###### Call Signature

> **on**(`event`: `"close"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`on`](#on)

###### Call Signature

> **on**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`on`](#on)

###### Call Signature

> **on**(`event`: `"exit"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"exit"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`on`](#on)

##### once()

###### Call Signature

> **once**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time** `listener` function for the event named `eventName`. The
next time `eventName` is triggered, this listener is removed and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependOnceListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | `string` | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Since

v0.3.0

###### Inherited from

[`ChildProcess`](#childprocess).[`once`](#once)

###### Call Signature

> **once**(`event`: `"close"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`once`](#once)

###### Call Signature

> **once**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`once`](#once)

###### Call Signature

> **once**(`event`: `"exit"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"exit"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`once`](#once)

##### prependListener()

###### Call Signature

> **prependListener**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the *beginning* of the listeners array for the
event named `eventName`. No checks are made to see if the `listener` has
already been added. Multiple calls passing the same combination of `eventName`
and `listener` will result in the `listener` being added, and called, multiple times.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | `string` | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`prependListener`](#prependlistener)

###### Call Signature

> **prependListener**(`event`: `"close"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`prependListener`](#prependlistener)

###### Call Signature

> **prependListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`prependListener`](#prependlistener)

###### Call Signature

> **prependListener**(`event`: `"exit"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"exit"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`prependListener`](#prependlistener)

##### prependOnceListener()

###### Call Signature

> **prependOnceListener**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time**`listener` function for the event named `eventName` to the *beginning* of the listeners array.
The next time `eventName` is triggered, this listener is removed, and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | `string` | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`prependOnceListener`](#prependoncelistener)

###### Call Signature

> **prependOnceListener**(`event`: `"close"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`prependOnceListener`](#prependoncelistener)

###### Call Signature

> **prependOnceListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`prependOnceListener`](#prependoncelistener)

###### Call Signature

> **prependOnceListener**(`event`: `"exit"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"exit"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`prependOnceListener`](#prependoncelistener)

##### removeListener()

> **removeListener**<`K`>(`eventName`: [`EventKey`](dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Removes the specified `listener` from the listener array for the event named `eventName`.

`removeListener()` will remove, at most, one instance of a listener from the
listener array. If any single listener has been added multiple times to the
listener array for the specified `eventName`, then `removeListener()` must be
called multiple times to remove each instance.

Once an event is emitted, all listeners attached to it at the time of emitting are called in order.
This implies that any `removeListener()` calls *after* emitting and *before* the last listener finishes execution
will not remove them from `emit()` in progress. Subsequent events behave as expected.

```js
import { EventEmitter } from 'events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A
```

Because listeners are managed using an internal array, calling this will
change the position indices of any listener registered *after* the listener
being removed. This will not impact the order in which listeners are called,
but it means that any copies of the listener array as returned by
the `emitter.listeners()` method will need to be recreated.

When a single function has been added as a handler multiple times for a single
event (as in the example below), `removeListener()` will remove the most
recently added instance. In the example the `once('ping')` listener is removed:

```js
import { EventEmitter } from 'events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`EventKey`](dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`removeListener`](#removelistener)

***

### ChildProcessWithoutNullStreams

Instances of the `ChildProcess` represent spawned child processes.

Instances of `ChildProcess` are not intended to be created directly. Rather,
use the [spawn](#spawn) method to create instances of `ChildProcess`.

#### Extends

* [`ChildProcess`](#childprocess)

#### Properties

##### pid?

> `readonly` `optional` **pid**: `number`

Returns the process identifier (PID) of the child process. If the child process
fails to spawn due to errors, then the value is `undefined` and `error` is
emitted.

```js
const { spawn } = require('child_process');
const grep = spawn('grep', ['ssh']);

console.log(`Spawned child pid: ${grep.pid}`);
grep.stdin.end();
```

###### Inherited from

[`ChildProcessWithoutNullStreams`](#childprocesswithoutnullstreams).[`pid`](#pid-2)

##### stderr

> **stderr**: [`DefaultReadableStream`](stream/stream.md#defaultreadablestream)

A `Readable Stream` that represents the child process's `stderr`.

If the child was spawned with `stdio[2]` set to anything other than `'pipe'`,
then this will be `null`.

`subprocess.stderr` is an alias for `subprocess.stdio[2]`. Both properties will
refer to the same value.

The `subprocess.stderr` property can be `null` or `undefined` if the child process could not be successfully spawned.

###### Overrides

[`ChildProcess`](#childprocess).[`stderr`](#stderr)

##### stdin

> **stdin**: [`DefaultWritableStream`](stream/stream.md#defaultwritablestream)

A `Writable Stream` that represents the child process's `stdin`.

If a child process waits to read all of its input, the child will not continue
until this stream has been closed via `end()`.

If the child was spawned with `stdio[0]` set to anything other than `'pipe'`,
then this will be `null`.

`subprocess.stdin` is an alias for `subprocess.stdio[0]`. Both properties will
refer to the same value.

The `subprocess.stdin` property can be `null` or `undefined` if the child process could not be successfully spawned.

###### Overrides

[`ChildProcess`](#childprocess).[`stdin`](#stdin)

##### stdout

> **stdout**: [`DefaultReadableStream`](stream/stream.md#defaultreadablestream)

A `Readable Stream` that represents the child process's `stdout`.

If the child was spawned with `stdio[1]` set to anything other than `'pipe'`,
then this will be `null`.

`subprocess.stdout` is an alias for `subprocess.stdio[1]`. Both properties will
refer to the same value.

```js
const { spawn } = require('child_process');

const subprocess = spawn('ls');

subprocess.stdout.on('data', (data) => {
  console.log(`Received chunk ${data}`);
});
```

The `subprocess.stdout` property can be `null` or `undefined` if the child process could not be successfully spawned.

###### Overrides

[`ChildProcess`](#childprocess).[`stdout`](#stdout)

#### Methods

##### \[dispose]\()

> **\[dispose]**(): `void`

Calls [ChildProcess.kill](#kill) with `'SIGTERM'`.

###### Returns

`void`

###### Inherited from

[`ChildProcess`](#childprocess).[`[dispose]`](#dispose)

##### addListener()

###### Call Signature

> **addListener**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

events.EventEmitter

1. close
2. error
3. exit

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `string` |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`addListener`](#addlistener)

###### Call Signature

> **addListener**(`event`: `"close"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

events.EventEmitter

1. close
2. error
3. exit

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`addListener`](#addlistener)

###### Call Signature

> **addListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

events.EventEmitter

1. close
2. error
3. exit

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`addListener`](#addlistener)

###### Call Signature

> **addListener**(`event`: `"exit"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

events.EventEmitter

1. close
2. error
3. exit

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"exit"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`addListener`](#addlistener)

##### emit()

###### Call Signature

> **emit**(`event`: `string` | `symbol`, ...`args`: `any`\[]): `boolean`

Synchronously calls each of the listeners registered for the event named `eventName`, in the order they were registered, passing the supplied arguments
to each.

```js
import { EventEmitter } from 'events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `string` | `symbol` |
| ...`args` | `any`\[] |

###### Returns

`boolean`

###### Inherited from

[`ChildProcess`](#childprocess).[`emit`](#emit)

###### Call Signature

> **emit**(`event`: `"close"`, `code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `code` | `number` | `null` |
| `signal` | [`Signals`](globals/namespaces/QuickJS.md#signals) | `null` |

###### Returns

`boolean`

###### Inherited from

[`ChildProcess`](#childprocess).[`emit`](#emit)

###### Call Signature

> **emit**(`event`: `"error"`, `err`: `Error`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `err` | `Error` |

###### Returns

`boolean`

###### Inherited from

[`ChildProcess`](#childprocess).[`emit`](#emit)

###### Call Signature

> **emit**(`event`: `"exit"`, `code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"exit"` |
| `code` | `number` | `null` |
| `signal` | [`Signals`](globals/namespaces/QuickJS.md#signals) | `null` |

###### Returns

`boolean`

###### Inherited from

[`ChildProcess`](#childprocess).[`emit`](#emit)

##### eventNames()

> **eventNames**(): [`EventKey`](dom-events.md#eventkey)\[]

Returns an array listing the events for which the emitter has registered
listeners. The values in the array are strings or `Symbol`s.

```js
import { EventEmitter } from 'events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]
```

###### Returns

[`EventKey`](dom-events.md#eventkey)\[]

###### Inherited from

[`ChildProcess`](#childprocess).[`eventNames`](#eventnames)

##### kill()

> **kill**(`signal?`: `number` | [`Signals`](globals/namespaces/QuickJS.md#signals)): `boolean`

The `subprocess.kill()` method sends a signal to the child process. If no
argument is given, the process will be sent the `'SIGTERM'` signal. See [`signal(7)`](http://man7.org/linux/man-pages/man7/signal.7.html) for a list of available signals. This function
returns `true` if [`kill(2)`](http://man7.org/linux/man-pages/man2/kill.2.html) succeeds, and `false` otherwise.

```js
const { spawn } = require('child_process');
const grep = spawn('grep', ['ssh']);

grep.on('close', (code, signal) => {
  console.log(
    `child process terminated due to receipt of signal ${signal}`);
});

// Send SIGHUP to process.
grep.kill('SIGHUP');
```

The `ChildProcess` object may emit an `'error'` event if the signal
cannot be delivered. Sending a signal to a child process that has already exited
is not an error but may have unforeseen consequences. Specifically, if the
process identifier (PID) has been reassigned to another process, the signal will
be delivered to that process instead which can have unexpected results.

While the function is called `kill`, the signal delivered to the child process
may not actually terminate the process.

See [`kill(2)`](http://man7.org/linux/man-pages/man2/kill.2.html) for reference.

On Windows, where POSIX signals do not exist, the `signal` argument will be
ignored, and the process will be killed forcefully and abruptly (similar to `'SIGKILL'`).
See `Signal Events` for more details.

On Linux, child processes of child processes will not be terminated
when attempting to kill their parent. This is likely to happen when running a
new process in a shell or with the use of the `shell` option of `ChildProcess`:

```js
'use strict';
const { spawn } = require('child_process');

const subprocess = spawn(
  'sh',
  [
    '-c',
    `node -e "setInterval(() => {
      console.log(process.pid, 'is alive')
    }, 500);"`,
  ], {
    stdio: ['inherit', 'inherit', 'inherit'],
  },
);

setTimeout(() => {
  subprocess.kill(); // Does not terminate the Node.js process in the shell.
}, 2000);
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `signal?` | `number` | [`Signals`](globals/namespaces/QuickJS.md#signals) |

###### Returns

`boolean`

###### Inherited from

[`ChildProcess`](#childprocess).[`kill`](#kill)

##### off()

> **off**<`K`>(`eventName`: [`EventKey`](dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Alias for `emitter.removeListener()`.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`EventKey`](dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`off`](#off)

##### on()

###### Call Signature

> **on**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the end of the listeners array for the event
named `eventName`. No checks are made to see if the `listener` has already
been added. Multiple calls passing the same combination of `eventName` and
`listener` will result in the `listener` being added, and called, multiple times.

```js
server.on('connection', (stream) => {
  console.log('someone connected!');
});
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | `string` | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`on`](#on)

###### Call Signature

> **on**(`event`: `"close"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`on`](#on)

###### Call Signature

> **on**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`on`](#on)

###### Call Signature

> **on**(`event`: `"exit"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"exit"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`on`](#on)

##### once()

###### Call Signature

> **once**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time** `listener` function for the event named `eventName`. The
next time `eventName` is triggered, this listener is removed and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependOnceListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | `string` | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Since

v0.3.0

###### Inherited from

[`ChildProcess`](#childprocess).[`once`](#once)

###### Call Signature

> **once**(`event`: `"close"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`once`](#once)

###### Call Signature

> **once**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`once`](#once)

###### Call Signature

> **once**(`event`: `"exit"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"exit"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`once`](#once)

##### prependListener()

###### Call Signature

> **prependListener**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the *beginning* of the listeners array for the
event named `eventName`. No checks are made to see if the `listener` has
already been added. Multiple calls passing the same combination of `eventName`
and `listener` will result in the `listener` being added, and called, multiple times.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | `string` | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`prependListener`](#prependlistener)

###### Call Signature

> **prependListener**(`event`: `"close"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`prependListener`](#prependlistener)

###### Call Signature

> **prependListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`prependListener`](#prependlistener)

###### Call Signature

> **prependListener**(`event`: `"exit"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"exit"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`prependListener`](#prependlistener)

##### prependOnceListener()

###### Call Signature

> **prependOnceListener**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time**`listener` function for the event named `eventName` to the *beginning* of the listeners array.
The next time `eventName` is triggered, this listener is removed, and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | `string` | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`prependOnceListener`](#prependoncelistener)

###### Call Signature

> **prependOnceListener**(`event`: `"close"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`prependOnceListener`](#prependoncelistener)

###### Call Signature

> **prependOnceListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`prependOnceListener`](#prependoncelistener)

###### Call Signature

> **prependOnceListener**(`event`: `"exit"`, `listener`: (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"exit"` |
| `listener` | (`code`: `number` | `null`, `signal`: [`Signals`](globals/namespaces/QuickJS.md#signals) | `null`) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`prependOnceListener`](#prependoncelistener)

##### removeListener()

> **removeListener**<`K`>(`eventName`: [`EventKey`](dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Removes the specified `listener` from the listener array for the event named `eventName`.

`removeListener()` will remove, at most, one instance of a listener from the
listener array. If any single listener has been added multiple times to the
listener array for the specified `eventName`, then `removeListener()` must be
called multiple times to remove each instance.

Once an event is emitted, all listeners attached to it at the time of emitting are called in order.
This implies that any `removeListener()` calls *after* emitting and *before* the last listener finishes execution
will not remove them from `emit()` in progress. Subsequent events behave as expected.

```js
import { EventEmitter } from 'events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A
```

Because listeners are managed using an internal array, calling this will
change the position indices of any listener registered *after* the listener
being removed. This will not impact the order in which listeners are called,
but it means that any copies of the listener array as returned by
the `emitter.listeners()` method will need to be recreated.

When a single function has been added as a handler multiple times for a single
event (as in the example below), `removeListener()` will remove the most
recently added instance. In the example the `once('ping')` listener is removed:

```js
import { EventEmitter } from 'events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`EventKey`](dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`ChildProcess`](#childprocess).[`removeListener`](#removelistener)

***

### ProcessEnvOptions

#### Extended by

* [`SpawnOptions`](#spawnoptions)

#### Properties

##### cwd?

> `optional` **cwd**: `string`

##### gid?

> `optional` **gid**: `number`

##### uid?

> `optional` **uid**: `number`

***

### SpawnOptions

#### Extends

* [`ProcessEnvOptions`](#processenvoptions)

#### Extended by

* [`SpawnOptionsWithoutStdio`](#spawnoptionswithoutstdio)
* [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)

#### Properties

##### cwd?

> `optional` **cwd**: `string`

###### Inherited from

[`ProcessEnvOptions`](#processenvoptions).[`cwd`](#cwd)

##### gid?

> `optional` **gid**: `number`

###### Inherited from

[`ProcessEnvOptions`](#processenvoptions).[`gid`](#gid)

##### shell?

> `optional` **shell**: `string` | `boolean`

##### stdio?

> `optional` **stdio**: [`StdioOptions`](#stdiooptions)

Can be set to 'pipe', 'inherit', or 'ignore', or an array of these strings.
If passed as an array, the first element is used for `stdin`, the second for
`stdout`, and the third for `stderr`.

###### Default

```ts
'pipe'
```

##### uid?

> `optional` **uid**: `number`

###### Inherited from

[`ProcessEnvOptions`](#processenvoptions).[`uid`](#uid)

##### windowsVerbatimArguments?

> `optional` **windowsVerbatimArguments**: `boolean`

***

### SpawnOptionsWithoutStdio

#### Extends

* [`SpawnOptions`](#spawnoptions)

#### Properties

##### cwd?

> `optional` **cwd**: `string`

###### Inherited from

[`SpawnOptions`](#spawnoptions).[`cwd`](#cwd-1)

##### gid?

> `optional` **gid**: `number`

###### Inherited from

[`SpawnOptions`](#spawnoptions).[`gid`](#gid-1)

##### shell?

> `optional` **shell**: `string` | `boolean`

###### Inherited from

[`SpawnOptions`](#spawnoptions).[`shell`](#shell)

##### stdio?

> `optional` **stdio**: `"pipe"` | [`StdioPipe`](#stdiopipe)\[]

Can be set to 'pipe', 'inherit', or 'ignore', or an array of these strings.
If passed as an array, the first element is used for `stdin`, the second for
`stdout`, and the third for `stderr`.

###### Default

```ts
'pipe'
```

###### Overrides

[`SpawnOptions`](#spawnoptions).[`stdio`](#stdio)

##### uid?

> `optional` **uid**: `number`

###### Inherited from

[`SpawnOptions`](#spawnoptions).[`uid`](#uid-1)

##### windowsVerbatimArguments?

> `optional` **windowsVerbatimArguments**: `boolean`

###### Inherited from

[`SpawnOptions`](#spawnoptions).[`windowsVerbatimArguments`](#windowsverbatimarguments)

***

### SpawnOptionsWithStdioTuple

#### Extends

* [`SpawnOptions`](#spawnoptions)

#### Type Parameters

| Type Parameter |
| ------ |
| `Stdin` *extends* [`StdioNull`](#stdionull) | [`StdioPipe`](#stdiopipe) |
| `Stdout` *extends* [`StdioNull`](#stdionull) | [`StdioPipe`](#stdiopipe) |
| `Stderr` *extends* [`StdioNull`](#stdionull) | [`StdioPipe`](#stdiopipe) |

#### Properties

##### cwd?

> `optional` **cwd**: `string`

###### Inherited from

[`SpawnOptions`](#spawnoptions).[`cwd`](#cwd-1)

##### gid?

> `optional` **gid**: `number`

###### Inherited from

[`SpawnOptions`](#spawnoptions).[`gid`](#gid-1)

##### shell?

> `optional` **shell**: `string` | `boolean`

###### Inherited from

[`SpawnOptions`](#spawnoptions).[`shell`](#shell)

##### stdio

> **stdio**: \[`Stdin`, `Stdout`, `Stderr`]

Can be set to 'pipe', 'inherit', or 'ignore', or an array of these strings.
If passed as an array, the first element is used for `stdin`, the second for
`stdout`, and the third for `stderr`.

###### Default

```ts
'pipe'
```

###### Overrides

[`SpawnOptions`](#spawnoptions).[`stdio`](#stdio)

##### uid?

> `optional` **uid**: `number`

###### Inherited from

[`SpawnOptions`](#spawnoptions).[`uid`](#uid-1)

##### windowsVerbatimArguments?

> `optional` **windowsVerbatimArguments**: `boolean`

###### Inherited from

[`SpawnOptions`](#spawnoptions).[`windowsVerbatimArguments`](#windowsverbatimarguments)

## Type Aliases

### IOType

> **IOType** = `"pipe"` | `"ignore"` | `"inherit"`

***

### StdioNull

> **StdioNull** = `"inherit"` | `"ignore"`

***

### StdioOptions

> **StdioOptions** = [`IOType`](#iotype) | ([`IOType`](#iotype) | `number` | `null` | `undefined`)\[]

***

### StdioPipe

> **StdioPipe** = `undefined` | `null` | [`StdioPipeNamed`](#stdiopipenamed)

***

### StdioPipeNamed

> **StdioPipeNamed** = `"pipe"`

## Functions

### spawn()

#### Call Signature

> **spawn**(`command`: `string`, `options?`: [`SpawnOptionsWithoutStdio`](#spawnoptionswithoutstdio)): [`ChildProcessWithoutNullStreams`](#childprocesswithoutnullstreams)

The `child_process.spawn()` method spawns a new process using the given `command`, with command-line arguments in `args`.
If omitted, `args` defaults to an empty array.

**If the `shell` option is enabled, do not pass unsanitized user input to this**
**function. Any input containing shell metacharacters may be used to trigger**
**arbitrary command execution.**

A third argument may be used to specify additional options.

Use `cwd` to specify the working directory from which the process is spawned.
If not given, the default is to inherit the current working directory. If given,
but the path does not exist, the child process emits an `ENOENT` error
and exits immediately. `ENOENT` is also emitted when the command
does not exist.

Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the
exit code:

```js
const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});
```

Example: A very elaborate way to run `ps ax | grep ssh`

```js
const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});
```

Example of checking for failed `spawn`:

```js
const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});
```

Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process
title while others (Windows, SunOS) will use `command`.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `command` | `string` | The command to run. |
| `options?` | [`SpawnOptionsWithoutStdio`](#spawnoptionswithoutstdio) | - |

##### Returns

[`ChildProcessWithoutNullStreams`](#childprocesswithoutnullstreams)

#### Call Signature

> **spawn**(`command`: `string`, `options`: [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioPipe`](#stdiopipe), [`StdioPipe`](#stdiopipe), [`StdioPipe`](#stdiopipe)>): [`ChildProcessByStdio`](#childprocessbystdio)<[`DefaultWritableStream`](stream/stream.md#defaultwritablestream), [`DefaultReadableStream`](stream/stream.md#defaultreadablestream), [`DefaultReadableStream`](stream/stream.md#defaultreadablestream)>

The `child_process.spawn()` method spawns a new process using the given `command`, with command-line arguments in `args`.
If omitted, `args` defaults to an empty array.

**If the `shell` option is enabled, do not pass unsanitized user input to this**
**function. Any input containing shell metacharacters may be used to trigger**
**arbitrary command execution.**

A third argument may be used to specify additional options.

Use `cwd` to specify the working directory from which the process is spawned.
If not given, the default is to inherit the current working directory. If given,
but the path does not exist, the child process emits an `ENOENT` error
and exits immediately. `ENOENT` is also emitted when the command
does not exist.

Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the
exit code:

```js
const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});
```

Example: A very elaborate way to run `ps ax | grep ssh`

```js
const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});
```

Example of checking for failed `spawn`:

```js
const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});
```

Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process
title while others (Windows, SunOS) will use `command`.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `command` | `string` | The command to run. |
| `options` | [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioPipe`](#stdiopipe), [`StdioPipe`](#stdiopipe), [`StdioPipe`](#stdiopipe)> | - |

##### Returns

[`ChildProcessByStdio`](#childprocessbystdio)<[`DefaultWritableStream`](stream/stream.md#defaultwritablestream), [`DefaultReadableStream`](stream/stream.md#defaultreadablestream), [`DefaultReadableStream`](stream/stream.md#defaultreadablestream)>

#### Call Signature

> **spawn**(`command`: `string`, `options`: [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioPipe`](#stdiopipe), [`StdioPipe`](#stdiopipe), [`StdioNull`](#stdionull)>): [`ChildProcessByStdio`](#childprocessbystdio)<[`DefaultWritableStream`](stream/stream.md#defaultwritablestream), [`DefaultReadableStream`](stream/stream.md#defaultreadablestream), `null`>

The `child_process.spawn()` method spawns a new process using the given `command`, with command-line arguments in `args`.
If omitted, `args` defaults to an empty array.

**If the `shell` option is enabled, do not pass unsanitized user input to this**
**function. Any input containing shell metacharacters may be used to trigger**
**arbitrary command execution.**

A third argument may be used to specify additional options.

Use `cwd` to specify the working directory from which the process is spawned.
If not given, the default is to inherit the current working directory. If given,
but the path does not exist, the child process emits an `ENOENT` error
and exits immediately. `ENOENT` is also emitted when the command
does not exist.

Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the
exit code:

```js
const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});
```

Example: A very elaborate way to run `ps ax | grep ssh`

```js
const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});
```

Example of checking for failed `spawn`:

```js
const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});
```

Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process
title while others (Windows, SunOS) will use `command`.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `command` | `string` | The command to run. |
| `options` | [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioPipe`](#stdiopipe), [`StdioPipe`](#stdiopipe), [`StdioNull`](#stdionull)> | - |

##### Returns

[`ChildProcessByStdio`](#childprocessbystdio)<[`DefaultWritableStream`](stream/stream.md#defaultwritablestream), [`DefaultReadableStream`](stream/stream.md#defaultreadablestream), `null`>

#### Call Signature

> **spawn**(`command`: `string`, `options`: [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioPipe`](#stdiopipe), [`StdioNull`](#stdionull), [`StdioPipe`](#stdiopipe)>): [`ChildProcessByStdio`](#childprocessbystdio)<[`DefaultWritableStream`](stream/stream.md#defaultwritablestream), `null`, [`DefaultReadableStream`](stream/stream.md#defaultreadablestream)>

The `child_process.spawn()` method spawns a new process using the given `command`, with command-line arguments in `args`.
If omitted, `args` defaults to an empty array.

**If the `shell` option is enabled, do not pass unsanitized user input to this**
**function. Any input containing shell metacharacters may be used to trigger**
**arbitrary command execution.**

A third argument may be used to specify additional options.

Use `cwd` to specify the working directory from which the process is spawned.
If not given, the default is to inherit the current working directory. If given,
but the path does not exist, the child process emits an `ENOENT` error
and exits immediately. `ENOENT` is also emitted when the command
does not exist.

Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the
exit code:

```js
const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});
```

Example: A very elaborate way to run `ps ax | grep ssh`

```js
const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});
```

Example of checking for failed `spawn`:

```js
const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});
```

Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process
title while others (Windows, SunOS) will use `command`.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `command` | `string` | The command to run. |
| `options` | [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioPipe`](#stdiopipe), [`StdioNull`](#stdionull), [`StdioPipe`](#stdiopipe)> | - |

##### Returns

[`ChildProcessByStdio`](#childprocessbystdio)<[`DefaultWritableStream`](stream/stream.md#defaultwritablestream), `null`, [`DefaultReadableStream`](stream/stream.md#defaultreadablestream)>

#### Call Signature

> **spawn**(`command`: `string`, `options`: [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioNull`](#stdionull), [`StdioPipe`](#stdiopipe), [`StdioPipe`](#stdiopipe)>): [`ChildProcessByStdio`](#childprocessbystdio)<`null`, [`DefaultReadableStream`](stream/stream.md#defaultreadablestream), [`DefaultReadableStream`](stream/stream.md#defaultreadablestream)>

The `child_process.spawn()` method spawns a new process using the given `command`, with command-line arguments in `args`.
If omitted, `args` defaults to an empty array.

**If the `shell` option is enabled, do not pass unsanitized user input to this**
**function. Any input containing shell metacharacters may be used to trigger**
**arbitrary command execution.**

A third argument may be used to specify additional options.

Use `cwd` to specify the working directory from which the process is spawned.
If not given, the default is to inherit the current working directory. If given,
but the path does not exist, the child process emits an `ENOENT` error
and exits immediately. `ENOENT` is also emitted when the command
does not exist.

Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the
exit code:

```js
const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});
```

Example: A very elaborate way to run `ps ax | grep ssh`

```js
const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});
```

Example of checking for failed `spawn`:

```js
const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});
```

Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process
title while others (Windows, SunOS) will use `command`.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `command` | `string` | The command to run. |
| `options` | [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioNull`](#stdionull), [`StdioPipe`](#stdiopipe), [`StdioPipe`](#stdiopipe)> | - |

##### Returns

[`ChildProcessByStdio`](#childprocessbystdio)<`null`, [`DefaultReadableStream`](stream/stream.md#defaultreadablestream), [`DefaultReadableStream`](stream/stream.md#defaultreadablestream)>

#### Call Signature

> **spawn**(`command`: `string`, `options`: [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioPipe`](#stdiopipe), [`StdioNull`](#stdionull), [`StdioNull`](#stdionull)>): [`ChildProcessByStdio`](#childprocessbystdio)<[`DefaultWritableStream`](stream/stream.md#defaultwritablestream), `null`, `null`>

The `child_process.spawn()` method spawns a new process using the given `command`, with command-line arguments in `args`.
If omitted, `args` defaults to an empty array.

**If the `shell` option is enabled, do not pass unsanitized user input to this**
**function. Any input containing shell metacharacters may be used to trigger**
**arbitrary command execution.**

A third argument may be used to specify additional options.

Use `cwd` to specify the working directory from which the process is spawned.
If not given, the default is to inherit the current working directory. If given,
but the path does not exist, the child process emits an `ENOENT` error
and exits immediately. `ENOENT` is also emitted when the command
does not exist.

Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the
exit code:

```js
const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});
```

Example: A very elaborate way to run `ps ax | grep ssh`

```js
const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});
```

Example of checking for failed `spawn`:

```js
const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});
```

Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process
title while others (Windows, SunOS) will use `command`.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `command` | `string` | The command to run. |
| `options` | [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioPipe`](#stdiopipe), [`StdioNull`](#stdionull), [`StdioNull`](#stdionull)> | - |

##### Returns

[`ChildProcessByStdio`](#childprocessbystdio)<[`DefaultWritableStream`](stream/stream.md#defaultwritablestream), `null`, `null`>

#### Call Signature

> **spawn**(`command`: `string`, `options`: [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioNull`](#stdionull), [`StdioPipe`](#stdiopipe), [`StdioNull`](#stdionull)>): [`ChildProcessByStdio`](#childprocessbystdio)<`null`, [`DefaultReadableStream`](stream/stream.md#defaultreadablestream), `null`>

The `child_process.spawn()` method spawns a new process using the given `command`, with command-line arguments in `args`.
If omitted, `args` defaults to an empty array.

**If the `shell` option is enabled, do not pass unsanitized user input to this**
**function. Any input containing shell metacharacters may be used to trigger**
**arbitrary command execution.**

A third argument may be used to specify additional options.

Use `cwd` to specify the working directory from which the process is spawned.
If not given, the default is to inherit the current working directory. If given,
but the path does not exist, the child process emits an `ENOENT` error
and exits immediately. `ENOENT` is also emitted when the command
does not exist.

Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the
exit code:

```js
const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});
```

Example: A very elaborate way to run `ps ax | grep ssh`

```js
const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});
```

Example of checking for failed `spawn`:

```js
const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});
```

Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process
title while others (Windows, SunOS) will use `command`.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `command` | `string` | The command to run. |
| `options` | [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioNull`](#stdionull), [`StdioPipe`](#stdiopipe), [`StdioNull`](#stdionull)> | - |

##### Returns

[`ChildProcessByStdio`](#childprocessbystdio)<`null`, [`DefaultReadableStream`](stream/stream.md#defaultreadablestream), `null`>

#### Call Signature

> **spawn**(`command`: `string`, `options`: [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioNull`](#stdionull), [`StdioNull`](#stdionull), [`StdioPipe`](#stdiopipe)>): [`ChildProcessByStdio`](#childprocessbystdio)<`null`, `null`, [`DefaultReadableStream`](stream/stream.md#defaultreadablestream)>

The `child_process.spawn()` method spawns a new process using the given `command`, with command-line arguments in `args`.
If omitted, `args` defaults to an empty array.

**If the `shell` option is enabled, do not pass unsanitized user input to this**
**function. Any input containing shell metacharacters may be used to trigger**
**arbitrary command execution.**

A third argument may be used to specify additional options.

Use `cwd` to specify the working directory from which the process is spawned.
If not given, the default is to inherit the current working directory. If given,
but the path does not exist, the child process emits an `ENOENT` error
and exits immediately. `ENOENT` is also emitted when the command
does not exist.

Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the
exit code:

```js
const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});
```

Example: A very elaborate way to run `ps ax | grep ssh`

```js
const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});
```

Example of checking for failed `spawn`:

```js
const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});
```

Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process
title while others (Windows, SunOS) will use `command`.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `command` | `string` | The command to run. |
| `options` | [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioNull`](#stdionull), [`StdioNull`](#stdionull), [`StdioPipe`](#stdiopipe)> | - |

##### Returns

[`ChildProcessByStdio`](#childprocessbystdio)<`null`, `null`, [`DefaultReadableStream`](stream/stream.md#defaultreadablestream)>

#### Call Signature

> **spawn**(`command`: `string`, `options`: [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioNull`](#stdionull), [`StdioNull`](#stdionull), [`StdioNull`](#stdionull)>): [`ChildProcessByStdio`](#childprocessbystdio)<`null`, `null`, `null`>

The `child_process.spawn()` method spawns a new process using the given `command`, with command-line arguments in `args`.
If omitted, `args` defaults to an empty array.

**If the `shell` option is enabled, do not pass unsanitized user input to this**
**function. Any input containing shell metacharacters may be used to trigger**
**arbitrary command execution.**

A third argument may be used to specify additional options.

Use `cwd` to specify the working directory from which the process is spawned.
If not given, the default is to inherit the current working directory. If given,
but the path does not exist, the child process emits an `ENOENT` error
and exits immediately. `ENOENT` is also emitted when the command
does not exist.

Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the
exit code:

```js
const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});
```

Example: A very elaborate way to run `ps ax | grep ssh`

```js
const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});
```

Example of checking for failed `spawn`:

```js
const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});
```

Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process
title while others (Windows, SunOS) will use `command`.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `command` | `string` | The command to run. |
| `options` | [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioNull`](#stdionull), [`StdioNull`](#stdionull), [`StdioNull`](#stdionull)> | - |

##### Returns

[`ChildProcessByStdio`](#childprocessbystdio)<`null`, `null`, `null`>

#### Call Signature

> **spawn**(`command`: `string`, `options`: [`SpawnOptions`](#spawnoptions)): [`ChildProcess`](#childprocess)

The `child_process.spawn()` method spawns a new process using the given `command`, with command-line arguments in `args`.
If omitted, `args` defaults to an empty array.

**If the `shell` option is enabled, do not pass unsanitized user input to this**
**function. Any input containing shell metacharacters may be used to trigger**
**arbitrary command execution.**

A third argument may be used to specify additional options.

Use `cwd` to specify the working directory from which the process is spawned.
If not given, the default is to inherit the current working directory. If given,
but the path does not exist, the child process emits an `ENOENT` error
and exits immediately. `ENOENT` is also emitted when the command
does not exist.

Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the
exit code:

```js
const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});
```

Example: A very elaborate way to run `ps ax | grep ssh`

```js
const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});
```

Example of checking for failed `spawn`:

```js
const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});
```

Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process
title while others (Windows, SunOS) will use `command`.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `command` | `string` | The command to run. |
| `options` | [`SpawnOptions`](#spawnoptions) | - |

##### Returns

[`ChildProcess`](#childprocess)

#### Call Signature

> **spawn**(`command`: `string`, `args?`: readonly `string`\[], `options?`: [`SpawnOptionsWithoutStdio`](#spawnoptionswithoutstdio)): [`ChildProcessWithoutNullStreams`](#childprocesswithoutnullstreams)

The `child_process.spawn()` method spawns a new process using the given `command`, with command-line arguments in `args`.
If omitted, `args` defaults to an empty array.

**If the `shell` option is enabled, do not pass unsanitized user input to this**
**function. Any input containing shell metacharacters may be used to trigger**
**arbitrary command execution.**

A third argument may be used to specify additional options.

Use `cwd` to specify the working directory from which the process is spawned.
If not given, the default is to inherit the current working directory. If given,
but the path does not exist, the child process emits an `ENOENT` error
and exits immediately. `ENOENT` is also emitted when the command
does not exist.

Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the
exit code:

```js
const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});
```

Example: A very elaborate way to run `ps ax | grep ssh`

```js
const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});
```

Example of checking for failed `spawn`:

```js
const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});
```

Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process
title while others (Windows, SunOS) will use `command`.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `command` | `string` | The command to run. |
| `args?` | readonly `string`\[] | List of string arguments. |
| `options?` | [`SpawnOptionsWithoutStdio`](#spawnoptionswithoutstdio) | - |

##### Returns

[`ChildProcessWithoutNullStreams`](#childprocesswithoutnullstreams)

#### Call Signature

> **spawn**(`command`: `string`, `args`: readonly `string`\[], `options`: [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioPipe`](#stdiopipe), [`StdioPipe`](#stdiopipe), [`StdioPipe`](#stdiopipe)>): [`ChildProcessByStdio`](#childprocessbystdio)<[`DefaultWritableStream`](stream/stream.md#defaultwritablestream), [`DefaultReadableStream`](stream/stream.md#defaultreadablestream), [`DefaultReadableStream`](stream/stream.md#defaultreadablestream)>

The `child_process.spawn()` method spawns a new process using the given `command`, with command-line arguments in `args`.
If omitted, `args` defaults to an empty array.

**If the `shell` option is enabled, do not pass unsanitized user input to this**
**function. Any input containing shell metacharacters may be used to trigger**
**arbitrary command execution.**

A third argument may be used to specify additional options.

Use `cwd` to specify the working directory from which the process is spawned.
If not given, the default is to inherit the current working directory. If given,
but the path does not exist, the child process emits an `ENOENT` error
and exits immediately. `ENOENT` is also emitted when the command
does not exist.

Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the
exit code:

```js
const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});
```

Example: A very elaborate way to run `ps ax | grep ssh`

```js
const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});
```

Example of checking for failed `spawn`:

```js
const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});
```

Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process
title while others (Windows, SunOS) will use `command`.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `command` | `string` | The command to run. |
| `args` | readonly `string`\[] | List of string arguments. |
| `options` | [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioPipe`](#stdiopipe), [`StdioPipe`](#stdiopipe), [`StdioPipe`](#stdiopipe)> | - |

##### Returns

[`ChildProcessByStdio`](#childprocessbystdio)<[`DefaultWritableStream`](stream/stream.md#defaultwritablestream), [`DefaultReadableStream`](stream/stream.md#defaultreadablestream), [`DefaultReadableStream`](stream/stream.md#defaultreadablestream)>

#### Call Signature

> **spawn**(`command`: `string`, `args`: readonly `string`\[], `options`: [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioPipe`](#stdiopipe), [`StdioPipe`](#stdiopipe), [`StdioNull`](#stdionull)>): [`ChildProcessByStdio`](#childprocessbystdio)<[`DefaultWritableStream`](stream/stream.md#defaultwritablestream), [`DefaultReadableStream`](stream/stream.md#defaultreadablestream), `null`>

The `child_process.spawn()` method spawns a new process using the given `command`, with command-line arguments in `args`.
If omitted, `args` defaults to an empty array.

**If the `shell` option is enabled, do not pass unsanitized user input to this**
**function. Any input containing shell metacharacters may be used to trigger**
**arbitrary command execution.**

A third argument may be used to specify additional options.

Use `cwd` to specify the working directory from which the process is spawned.
If not given, the default is to inherit the current working directory. If given,
but the path does not exist, the child process emits an `ENOENT` error
and exits immediately. `ENOENT` is also emitted when the command
does not exist.

Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the
exit code:

```js
const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});
```

Example: A very elaborate way to run `ps ax | grep ssh`

```js
const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});
```

Example of checking for failed `spawn`:

```js
const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});
```

Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process
title while others (Windows, SunOS) will use `command`.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `command` | `string` | The command to run. |
| `args` | readonly `string`\[] | List of string arguments. |
| `options` | [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioPipe`](#stdiopipe), [`StdioPipe`](#stdiopipe), [`StdioNull`](#stdionull)> | - |

##### Returns

[`ChildProcessByStdio`](#childprocessbystdio)<[`DefaultWritableStream`](stream/stream.md#defaultwritablestream), [`DefaultReadableStream`](stream/stream.md#defaultreadablestream), `null`>

#### Call Signature

> **spawn**(`command`: `string`, `args`: readonly `string`\[], `options`: [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioPipe`](#stdiopipe), [`StdioNull`](#stdionull), [`StdioPipe`](#stdiopipe)>): [`ChildProcessByStdio`](#childprocessbystdio)<[`DefaultWritableStream`](stream/stream.md#defaultwritablestream), `null`, [`DefaultReadableStream`](stream/stream.md#defaultreadablestream)>

The `child_process.spawn()` method spawns a new process using the given `command`, with command-line arguments in `args`.
If omitted, `args` defaults to an empty array.

**If the `shell` option is enabled, do not pass unsanitized user input to this**
**function. Any input containing shell metacharacters may be used to trigger**
**arbitrary command execution.**

A third argument may be used to specify additional options.

Use `cwd` to specify the working directory from which the process is spawned.
If not given, the default is to inherit the current working directory. If given,
but the path does not exist, the child process emits an `ENOENT` error
and exits immediately. `ENOENT` is also emitted when the command
does not exist.

Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the
exit code:

```js
const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});
```

Example: A very elaborate way to run `ps ax | grep ssh`

```js
const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});
```

Example of checking for failed `spawn`:

```js
const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});
```

Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process
title while others (Windows, SunOS) will use `command`.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `command` | `string` | The command to run. |
| `args` | readonly `string`\[] | List of string arguments. |
| `options` | [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioPipe`](#stdiopipe), [`StdioNull`](#stdionull), [`StdioPipe`](#stdiopipe)> | - |

##### Returns

[`ChildProcessByStdio`](#childprocessbystdio)<[`DefaultWritableStream`](stream/stream.md#defaultwritablestream), `null`, [`DefaultReadableStream`](stream/stream.md#defaultreadablestream)>

#### Call Signature

> **spawn**(`command`: `string`, `args`: readonly `string`\[], `options`: [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioNull`](#stdionull), [`StdioPipe`](#stdiopipe), [`StdioPipe`](#stdiopipe)>): [`ChildProcessByStdio`](#childprocessbystdio)<`null`, [`DefaultReadableStream`](stream/stream.md#defaultreadablestream), [`DefaultReadableStream`](stream/stream.md#defaultreadablestream)>

The `child_process.spawn()` method spawns a new process using the given `command`, with command-line arguments in `args`.
If omitted, `args` defaults to an empty array.

**If the `shell` option is enabled, do not pass unsanitized user input to this**
**function. Any input containing shell metacharacters may be used to trigger**
**arbitrary command execution.**

A third argument may be used to specify additional options.

Use `cwd` to specify the working directory from which the process is spawned.
If not given, the default is to inherit the current working directory. If given,
but the path does not exist, the child process emits an `ENOENT` error
and exits immediately. `ENOENT` is also emitted when the command
does not exist.

Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the
exit code:

```js
const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});
```

Example: A very elaborate way to run `ps ax | grep ssh`

```js
const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});
```

Example of checking for failed `spawn`:

```js
const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});
```

Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process
title while others (Windows, SunOS) will use `command`.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `command` | `string` | The command to run. |
| `args` | readonly `string`\[] | List of string arguments. |
| `options` | [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioNull`](#stdionull), [`StdioPipe`](#stdiopipe), [`StdioPipe`](#stdiopipe)> | - |

##### Returns

[`ChildProcessByStdio`](#childprocessbystdio)<`null`, [`DefaultReadableStream`](stream/stream.md#defaultreadablestream), [`DefaultReadableStream`](stream/stream.md#defaultreadablestream)>

#### Call Signature

> **spawn**(`command`: `string`, `args`: readonly `string`\[], `options`: [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioPipe`](#stdiopipe), [`StdioNull`](#stdionull), [`StdioNull`](#stdionull)>): [`ChildProcessByStdio`](#childprocessbystdio)<[`DefaultWritableStream`](stream/stream.md#defaultwritablestream), `null`, `null`>

The `child_process.spawn()` method spawns a new process using the given `command`, with command-line arguments in `args`.
If omitted, `args` defaults to an empty array.

**If the `shell` option is enabled, do not pass unsanitized user input to this**
**function. Any input containing shell metacharacters may be used to trigger**
**arbitrary command execution.**

A third argument may be used to specify additional options.

Use `cwd` to specify the working directory from which the process is spawned.
If not given, the default is to inherit the current working directory. If given,
but the path does not exist, the child process emits an `ENOENT` error
and exits immediately. `ENOENT` is also emitted when the command
does not exist.

Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the
exit code:

```js
const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});
```

Example: A very elaborate way to run `ps ax | grep ssh`

```js
const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});
```

Example of checking for failed `spawn`:

```js
const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});
```

Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process
title while others (Windows, SunOS) will use `command`.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `command` | `string` | The command to run. |
| `args` | readonly `string`\[] | List of string arguments. |
| `options` | [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioPipe`](#stdiopipe), [`StdioNull`](#stdionull), [`StdioNull`](#stdionull)> | - |

##### Returns

[`ChildProcessByStdio`](#childprocessbystdio)<[`DefaultWritableStream`](stream/stream.md#defaultwritablestream), `null`, `null`>

#### Call Signature

> **spawn**(`command`: `string`, `args`: readonly `string`\[], `options`: [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioNull`](#stdionull), [`StdioPipe`](#stdiopipe), [`StdioNull`](#stdionull)>): [`ChildProcessByStdio`](#childprocessbystdio)<`null`, [`DefaultReadableStream`](stream/stream.md#defaultreadablestream), `null`>

The `child_process.spawn()` method spawns a new process using the given `command`, with command-line arguments in `args`.
If omitted, `args` defaults to an empty array.

**If the `shell` option is enabled, do not pass unsanitized user input to this**
**function. Any input containing shell metacharacters may be used to trigger**
**arbitrary command execution.**

A third argument may be used to specify additional options.

Use `cwd` to specify the working directory from which the process is spawned.
If not given, the default is to inherit the current working directory. If given,
but the path does not exist, the child process emits an `ENOENT` error
and exits immediately. `ENOENT` is also emitted when the command
does not exist.

Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the
exit code:

```js
const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});
```

Example: A very elaborate way to run `ps ax | grep ssh`

```js
const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});
```

Example of checking for failed `spawn`:

```js
const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});
```

Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process
title while others (Windows, SunOS) will use `command`.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `command` | `string` | The command to run. |
| `args` | readonly `string`\[] | List of string arguments. |
| `options` | [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioNull`](#stdionull), [`StdioPipe`](#stdiopipe), [`StdioNull`](#stdionull)> | - |

##### Returns

[`ChildProcessByStdio`](#childprocessbystdio)<`null`, [`DefaultReadableStream`](stream/stream.md#defaultreadablestream), `null`>

#### Call Signature

> **spawn**(`command`: `string`, `args`: readonly `string`\[], `options`: [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioNull`](#stdionull), [`StdioNull`](#stdionull), [`StdioPipe`](#stdiopipe)>): [`ChildProcessByStdio`](#childprocessbystdio)<`null`, `null`, [`DefaultReadableStream`](stream/stream.md#defaultreadablestream)>

The `child_process.spawn()` method spawns a new process using the given `command`, with command-line arguments in `args`.
If omitted, `args` defaults to an empty array.

**If the `shell` option is enabled, do not pass unsanitized user input to this**
**function. Any input containing shell metacharacters may be used to trigger**
**arbitrary command execution.**

A third argument may be used to specify additional options.

Use `cwd` to specify the working directory from which the process is spawned.
If not given, the default is to inherit the current working directory. If given,
but the path does not exist, the child process emits an `ENOENT` error
and exits immediately. `ENOENT` is also emitted when the command
does not exist.

Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the
exit code:

```js
const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});
```

Example: A very elaborate way to run `ps ax | grep ssh`

```js
const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});
```

Example of checking for failed `spawn`:

```js
const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});
```

Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process
title while others (Windows, SunOS) will use `command`.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `command` | `string` | The command to run. |
| `args` | readonly `string`\[] | List of string arguments. |
| `options` | [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioNull`](#stdionull), [`StdioNull`](#stdionull), [`StdioPipe`](#stdiopipe)> | - |

##### Returns

[`ChildProcessByStdio`](#childprocessbystdio)<`null`, `null`, [`DefaultReadableStream`](stream/stream.md#defaultreadablestream)>

#### Call Signature

> **spawn**(`command`: `string`, `args`: readonly `string`\[], `options`: [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioNull`](#stdionull), [`StdioNull`](#stdionull), [`StdioNull`](#stdionull)>): [`ChildProcessByStdio`](#childprocessbystdio)<`null`, `null`, `null`>

The `child_process.spawn()` method spawns a new process using the given `command`, with command-line arguments in `args`.
If omitted, `args` defaults to an empty array.

**If the `shell` option is enabled, do not pass unsanitized user input to this**
**function. Any input containing shell metacharacters may be used to trigger**
**arbitrary command execution.**

A third argument may be used to specify additional options.

Use `cwd` to specify the working directory from which the process is spawned.
If not given, the default is to inherit the current working directory. If given,
but the path does not exist, the child process emits an `ENOENT` error
and exits immediately. `ENOENT` is also emitted when the command
does not exist.

Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the
exit code:

```js
const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});
```

Example: A very elaborate way to run `ps ax | grep ssh`

```js
const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});
```

Example of checking for failed `spawn`:

```js
const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});
```

Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process
title while others (Windows, SunOS) will use `command`.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `command` | `string` | The command to run. |
| `args` | readonly `string`\[] | List of string arguments. |
| `options` | [`SpawnOptionsWithStdioTuple`](#spawnoptionswithstdiotuple)<[`StdioNull`](#stdionull), [`StdioNull`](#stdionull), [`StdioNull`](#stdionull)> | - |

##### Returns

[`ChildProcessByStdio`](#childprocessbystdio)<`null`, `null`, `null`>

#### Call Signature

> **spawn**(`command`: `string`, `args`: readonly `string`\[], `options`: [`SpawnOptions`](#spawnoptions)): [`ChildProcess`](#childprocess)

The `child_process.spawn()` method spawns a new process using the given `command`, with command-line arguments in `args`.
If omitted, `args` defaults to an empty array.

**If the `shell` option is enabled, do not pass unsanitized user input to this**
**function. Any input containing shell metacharacters may be used to trigger**
**arbitrary command execution.**

A third argument may be used to specify additional options.

Use `cwd` to specify the working directory from which the process is spawned.
If not given, the default is to inherit the current working directory. If given,
but the path does not exist, the child process emits an `ENOENT` error
and exits immediately. `ENOENT` is also emitted when the command
does not exist.

Example of running `ls -lh /usr`, capturing `stdout`, `stderr`, and the
exit code:

```js
const { spawn } = require('child_process');
const ls = spawn('ls', ['-lh', '/usr']);

ls.stdout.on('data', (data) => {
  console.log(`stdout: ${data}`);
});

ls.stderr.on('data', (data) => {
  console.error(`stderr: ${data}`);
});

ls.on('close', (code) => {
  console.log(`child process exited with code ${code}`);
});
```

Example: A very elaborate way to run `ps ax | grep ssh`

```js
const { spawn } = require('child_process');
const ps = spawn('ps', ['ax']);
const grep = spawn('grep', ['ssh']);

ps.stdout.on('data', (data) => {
  grep.stdin.write(data);
});

ps.stderr.on('data', (data) => {
  console.error(`ps stderr: ${data}`);
});

ps.on('close', (code) => {
  if (code !== 0) {
    console.log(`ps process exited with code ${code}`);
  }
  grep.stdin.end();
});

grep.stdout.on('data', (data) => {
  console.log(data.toString());
});

grep.stderr.on('data', (data) => {
  console.error(`grep stderr: ${data}`);
});

grep.on('close', (code) => {
  if (code !== 0) {
    console.log(`grep process exited with code ${code}`);
  }
});
```

Example of checking for failed `spawn`:

```js
const { spawn } = require('child_process');
const subprocess = spawn('bad_command');

subprocess.on('error', (err) => {
  console.error('Failed to start subprocess.');
});
```

Certain platforms (macOS, Linux) will use the value of `argv[0]` for the process
title while others (Windows, SunOS) will use `command`.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `command` | `string` | The command to run. |
| `args` | readonly `string`\[] | List of string arguments. |
| `options` | [`SpawnOptions`](#spawnoptions) | - |

##### Returns

[`ChildProcess`](#childprocess)

---

---
url: /plugins/reference/modules/llrt/dns.md
---
[@caido/quickjs-types](../index.md) / llrt/dns

# llrt/dns

## Interfaces

### LookupAddress

#### Properties

##### address

> **address**: `string`

A string representation of an IPv4 or IPv6 address.

##### family

> **family**: `number`

`4` or `6`, denoting the family of `address`, or `0` if the address is not an IPv4 or IPv6 address. `0` is a likely indicator of a
bug in the name resolution service used by the operating system.

***

### LookupAllOptions

#### Extends

* [`LookupOptions`](#lookupoptions)

#### Properties

##### all

> **all**: `true`

When `true`, the callback returns all resolved addresses in an array. Otherwise, returns a single address.

###### Default

```ts
false
```

###### Overrides

[`LookupOptions`](#lookupoptions).[`all`](#all-2)

##### family?

> `optional` **family**: `number` | `"IPv4"` | `"IPv6"`

The record family. Must be `4`, `6`, or `0`.
The value 0 indicates that either an IPv4 or IPv6 address is returned.

###### Default

```ts
0
```

###### Inherited from

[`LookupOptions`](#lookupoptions).[`family`](#family-3)

##### order?

> `optional` **order**: `"verbatim"` | `"ipv4first"` | `"ipv6first"`

When `verbatim`, the resolved addresses are return unsorted. When `ipv4first`, the resolved addresses are sorted
by placing IPv4 addresses before IPv6 addresses. When `ipv6first`, the resolved addresses are sorted by placing IPv6
addresses before IPv4 addresses. Default value is configurable using
setDefaultResultOrder or [`--dns-result-order`](https://nodejs.org/docs/latest-v20.x/api/cli.html#--dns-result-orderorder).

###### Default

`verbatim` (addresses are not reordered)

###### Inherited from

[`LookupOptions`](#lookupoptions).[`order`](#order-2)

***

### LookupOneOptions

#### Extends

* [`LookupOptions`](#lookupoptions)

#### Properties

##### all?

> `optional` **all**: `false`

When `true`, the callback returns all resolved addresses in an array. Otherwise, returns a single address.

###### Default

```ts
false
```

###### Overrides

[`LookupOptions`](#lookupoptions).[`all`](#all-2)

##### family?

> `optional` **family**: `number` | `"IPv4"` | `"IPv6"`

The record family. Must be `4`, `6`, or `0`.
The value 0 indicates that either an IPv4 or IPv6 address is returned.

###### Default

```ts
0
```

###### Inherited from

[`LookupOptions`](#lookupoptions).[`family`](#family-3)

##### order?

> `optional` **order**: `"verbatim"` | `"ipv4first"` | `"ipv6first"`

When `verbatim`, the resolved addresses are return unsorted. When `ipv4first`, the resolved addresses are sorted
by placing IPv4 addresses before IPv6 addresses. When `ipv6first`, the resolved addresses are sorted by placing IPv6
addresses before IPv4 addresses. Default value is configurable using
setDefaultResultOrder or [`--dns-result-order`](https://nodejs.org/docs/latest-v20.x/api/cli.html#--dns-result-orderorder).

###### Default

`verbatim` (addresses are not reordered)

###### Inherited from

[`LookupOptions`](#lookupoptions).[`order`](#order-2)

***

### LookupOptions

#### Extended by

* [`LookupOneOptions`](#lookuponeoptions)
* [`LookupAllOptions`](#lookupalloptions)

#### Properties

##### all?

> `optional` **all**: `boolean`

When `true`, the callback returns all resolved addresses in an array. Otherwise, returns a single address.

###### Default

```ts
false
```

##### family?

> `optional` **family**: `number` | `"IPv4"` | `"IPv6"`

The record family. Must be `4`, `6`, or `0`.
The value 0 indicates that either an IPv4 or IPv6 address is returned.

###### Default

```ts
0
```

##### order?

> `optional` **order**: `"verbatim"` | `"ipv4first"` | `"ipv6first"`

When `verbatim`, the resolved addresses are return unsorted. When `ipv4first`, the resolved addresses are sorted
by placing IPv4 addresses before IPv6 addresses. When `ipv6first`, the resolved addresses are sorted by placing IPv6
addresses before IPv4 addresses. Default value is configurable using
setDefaultResultOrder or [`--dns-result-order`](https://nodejs.org/docs/latest-v20.x/api/cli.html#--dns-result-orderorder).

###### Default

`verbatim` (addresses are not reordered)

## Functions

### lookup()

#### Call Signature

> **lookup**(`hostname`: `string`, `family`: `number`, `callback`: (`err`: `Error` | `null`, `address`: `string`, `family`: `number`) => `void`): `void`

Resolves a host name (e.g. `'nodejs.org'`) into the first found A (IPv4) or
AAAA (IPv6) record. All `option` properties are optional. If `options` is an
integer, then it must be `4` or `6` – if `options` is `0` or not provided, then
IPv4 and IPv6 addresses are both returned if found.

On error, `err` is an `Error` object, where `err.code` is the error code.
Keep in mind that `err.code` will be set to `'ENOTFOUND'` not only when
the host name does not exist but also when the lookup fails in other ways
such as no available file descriptors.

`dns.lookup()` does not necessarily have anything to do with the DNS protocol.
The implementation uses an operating system facility that can associate names
with addresses and vice versa.

Example usage:

```js
import dns from 'dns';
const options = {
  family: 6,
};
dns.lookup('example.com', options, (err, address, family) =>
  console.log('address: %j family: IPv%s', address, family));
// address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6

```

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `hostname` | `string` |
| `family` | `number` |
| `callback` | (`err`: `Error` | `null`, `address`: `string`, `family`: `number`) => `void` |

##### Returns

`void`

#### Call Signature

> **lookup**(`hostname`: `string`, `options`: [`LookupOneOptions`](#lookuponeoptions), `callback`: (`err`: `Error` | `null`, `address`: `string`, `family`: `number`) => `void`): `void`

Resolves a host name (e.g. `'nodejs.org'`) into the first found A (IPv4) or
AAAA (IPv6) record. All `option` properties are optional. If `options` is an
integer, then it must be `4` or `6` – if `options` is `0` or not provided, then
IPv4 and IPv6 addresses are both returned if found.

On error, `err` is an `Error` object, where `err.code` is the error code.
Keep in mind that `err.code` will be set to `'ENOTFOUND'` not only when
the host name does not exist but also when the lookup fails in other ways
such as no available file descriptors.

`dns.lookup()` does not necessarily have anything to do with the DNS protocol.
The implementation uses an operating system facility that can associate names
with addresses and vice versa.

Example usage:

```js
import dns from 'dns';
const options = {
  family: 6,
};
dns.lookup('example.com', options, (err, address, family) =>
  console.log('address: %j family: IPv%s', address, family));
// address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6

```

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `hostname` | `string` |
| `options` | [`LookupOneOptions`](#lookuponeoptions) |
| `callback` | (`err`: `Error` | `null`, `address`: `string`, `family`: `number`) => `void` |

##### Returns

`void`

#### Call Signature

> **lookup**(`hostname`: `string`, `options`: [`LookupAllOptions`](#lookupalloptions), `callback`: (`err`: `Error` | `null`, `addresses`: [`LookupAddress`](#lookupaddress)\[]) => `void`): `void`

Resolves a host name (e.g. `'nodejs.org'`) into the first found A (IPv4) or
AAAA (IPv6) record. All `option` properties are optional. If `options` is an
integer, then it must be `4` or `6` – if `options` is `0` or not provided, then
IPv4 and IPv6 addresses are both returned if found.

On error, `err` is an `Error` object, where `err.code` is the error code.
Keep in mind that `err.code` will be set to `'ENOTFOUND'` not only when
the host name does not exist but also when the lookup fails in other ways
such as no available file descriptors.

`dns.lookup()` does not necessarily have anything to do with the DNS protocol.
The implementation uses an operating system facility that can associate names
with addresses and vice versa.

Example usage:

```js
import dns from 'dns';
const options = {
  family: 6,
};
dns.lookup('example.com', options, (err, address, family) =>
  console.log('address: %j family: IPv%s', address, family));
// address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6

```

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `hostname` | `string` |
| `options` | [`LookupAllOptions`](#lookupalloptions) |
| `callback` | (`err`: `Error` | `null`, `addresses`: [`LookupAddress`](#lookupaddress)\[]) => `void` |

##### Returns

`void`

#### Call Signature

> **lookup**(`hostname`: `string`, `options`: [`LookupOptions`](#lookupoptions), `callback`: (`err`: `Error` | `null`, `address`: `string` | [`LookupAddress`](#lookupaddress)\[], `family`: `number`) => `void`): `void`

Resolves a host name (e.g. `'nodejs.org'`) into the first found A (IPv4) or
AAAA (IPv6) record. All `option` properties are optional. If `options` is an
integer, then it must be `4` or `6` – if `options` is `0` or not provided, then
IPv4 and IPv6 addresses are both returned if found.

On error, `err` is an `Error` object, where `err.code` is the error code.
Keep in mind that `err.code` will be set to `'ENOTFOUND'` not only when
the host name does not exist but also when the lookup fails in other ways
such as no available file descriptors.

`dns.lookup()` does not necessarily have anything to do with the DNS protocol.
The implementation uses an operating system facility that can associate names
with addresses and vice versa.

Example usage:

```js
import dns from 'dns';
const options = {
  family: 6,
};
dns.lookup('example.com', options, (err, address, family) =>
  console.log('address: %j family: IPv%s', address, family));
// address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6

```

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `hostname` | `string` |
| `options` | [`LookupOptions`](#lookupoptions) |
| `callback` | (`err`: `Error` | `null`, `address`: `string` | [`LookupAddress`](#lookupaddress)\[], `family`: `number`) => `void` |

##### Returns

`void`

#### Call Signature

> **lookup**(`hostname`: `string`, `callback`: (`err`: `Error` | `null`, `address`: `string`, `family`: `number`) => `void`): `void`

Resolves a host name (e.g. `'nodejs.org'`) into the first found A (IPv4) or
AAAA (IPv6) record. All `option` properties are optional. If `options` is an
integer, then it must be `4` or `6` – if `options` is `0` or not provided, then
IPv4 and IPv6 addresses are both returned if found.

On error, `err` is an `Error` object, where `err.code` is the error code.
Keep in mind that `err.code` will be set to `'ENOTFOUND'` not only when
the host name does not exist but also when the lookup fails in other ways
such as no available file descriptors.

`dns.lookup()` does not necessarily have anything to do with the DNS protocol.
The implementation uses an operating system facility that can associate names
with addresses and vice versa.

Example usage:

```js
import dns from 'dns';
const options = {
  family: 6,
};
dns.lookup('example.com', options, (err, address, family) =>
  console.log('address: %j family: IPv%s', address, family));
// address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6

```

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `hostname` | `string` |
| `callback` | (`err`: `Error` | `null`, `address`: `string`, `family`: `number`) => `void` |

##### Returns

`void`

---

---
url: /plugins/reference/modules/llrt/dom-events.md
---
[@caido/quickjs-types](../index.md) / llrt/dom-events

# llrt/dom-events

## Classes

### CustomEvent

An event which takes place in the system.

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `D` | `any` |

#### Implements

* [`Event`](#event)

#### Constructors

##### Constructor

> **new CustomEvent**<`D`>(`type`: `string`, `opts?`: `object`): [`CustomEvent`](#customevent)<`D`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `type` | `string` |
| `opts?` | { `details?`: `D`; } |
| `opts.details?` | `D` |

###### Returns

[`CustomEvent`](#customevent)<`D`>

#### Properties

##### details

> `readonly` **details**: `D` | `null`

##### type

> `readonly` **type**: `string`

Returns the type of event, e.g. "click", "hashchange", or "submit".

###### Implementation of

[`Event`](#event).[`type`](#type-1)

***

### EventTarget

EventTarget is an interface implemented by objects that can
receive events and may have listeners for them.

#### Extended by

* [`AbortSignal`](abort.md#abortsignal)

#### Constructors

##### Constructor

> **new EventTarget**(): [`EventTarget`](#eventtarget)

###### Returns

[`EventTarget`](#eventtarget)

#### Methods

##### addEventListener()

> **addEventListener**(`type`: [`EventKey`](#eventkey), `listener`: [`EventListener`](#eventlistener), `options?`: [`AddEventListenerOptions`](#addeventlisteneroptions)): `void`

Adds a new handler for the `type` event. Any given `listener` is added only once per `type`.

If the `once` option is true, the `listener` is removed after the next time a `type` event is dispatched.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `type` | [`EventKey`](#eventkey) |
| `listener` | [`EventListener`](#eventlistener) |
| `options?` | [`AddEventListenerOptions`](#addeventlisteneroptions) |

###### Returns

`void`

##### dispatchEvent()

> **dispatchEvent**(`event`: [`Event`](#event)): `void`

Dispatches a synthetic event event to target

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | [`Event`](#event) |

###### Returns

`void`

##### removeEventListener()

> **removeEventListener**(`type`: [`EventKey`](#eventkey), `listener`: [`EventListener`](#eventlistener)): `void`

Removes the event listener in target's event listener list with the same type and callback

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `type` | [`EventKey`](#eventkey) |
| `listener` | [`EventListener`](#eventlistener) |

###### Returns

`void`

## Interfaces

### AddEventListenerOptions

#### Properties

##### once?

> `optional` **once**: `boolean`

When `true`, the listener is automatically removed when it is first invoked. Default: `false`.

***

### Event

An event which takes place in the system.

#### Properties

##### type

> `readonly` **type**: [`EventKey`](#eventkey)

Returns the type of event, e.g. "click", "hashchange", or "submit".

***

### EventListener()

> **EventListener**(`evt`: [`Event`](#event)): `void`

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `evt` | [`Event`](#event) |

#### Returns

`void`

## Type Aliases

### EventKey

> **EventKey** = `string` | `symbol`

---

---
url: /plugins/reference/modules/llrt/events.md
---
[@caido/quickjs-types](../index.md) / llrt/events

# llrt/events

## Classes

### EventEmitter

#### Extended by

* [`ChildProcess`](child_process.md#childprocess)
* [`Server`](net.md#server)
* [`ReadableStreamInner`](stream/stream.md#readablestreaminner)
* [`WritableStreamInner`](stream/stream.md#writablestreaminner)
* [`ReadableStream`](globals/namespaces/QuickJS.md#readablestream)
* [`WritableStream`](globals/namespaces/QuickJS.md#writablestream)

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `T` *extends* [`EventMap`](#eventmap)<`T`> | [`DefaultEventMap`](#defaulteventmap) |

#### Constructors

##### Constructor

> **new EventEmitter**<`T`>(): [`EventEmitter`](#eventemitter)<`T`>

###### Returns

[`EventEmitter`](#eventemitter)<`T`>

#### Methods

##### addListener()

> **addListener**<`K`>(`eventName`: [`Key`](#key)<`K`, `T`>, `listener`: [`Listener`](#listener)<`K`, `T`>): `this`

Alias for `emitter.on(eventName, listener)`.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`Key`](#key)<`K`, `T`> |
| `listener` | [`Listener`](#listener)<`K`, `T`> |

###### Returns

`this`

##### emit()

> **emit**<`K`>(`eventName`: [`Key`](#key)<`K`, `T`>, ...`args`: [`Args`](#args)<`K`, `T`>): `void`

Synchronously calls each of the listeners registered for the event named `eventName`, in the order they were registered, passing the supplied arguments
to each.

```js
import { EventEmitter } from 'events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener
```

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`Key`](#key)<`K`, `T`> |
| ...`args` | [`Args`](#args)<`K`, `T`> |

###### Returns

`void`

##### eventNames()

> **eventNames**(): [`EventKey`](dom-events.md#eventkey) & [`Key2`](#key2)<`unknown`, `T`>\[]

Returns an array listing the events for which the emitter has registered
listeners. The values in the array are strings or `Symbol`s.

```js
import { EventEmitter } from 'events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]
```

###### Returns

[`EventKey`](dom-events.md#eventkey) & [`Key2`](#key2)<`unknown`, `T`>\[]

##### off()

> **off**<`K`>(`eventName`: [`Key`](#key)<`K`, `T`>, `listener`: [`Listener`](#listener)<`K`, `T`>): `this`

Alias for `emitter.removeListener()`.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`Key`](#key)<`K`, `T`> |
| `listener` | [`Listener`](#listener)<`K`, `T`> |

###### Returns

`this`

##### on()

> **on**<`K`>(`eventName`: [`Key`](#key)<`K`, `T`>, `listener`: [`Listener`](#listener)<`K`, `T`>): `this`

Adds the `listener` function to the end of the listeners array for the event
named `eventName`. No checks are made to see if the `listener` has already
been added. Multiple calls passing the same combination of `eventName` and
`listener` will result in the `listener` being added, and called, multiple times.

```js
server.on('connection', (stream) => {
  console.log('someone connected!');
});
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `eventName` | [`Key`](#key)<`K`, `T`> | The name of the event. |
| `listener` | [`Listener`](#listener)<`K`, `T`> | The callback function |

###### Returns

`this`

##### once()

> **once**<`K`>(`eventName`: [`Key`](#key)<`K`, `T`>, `listener`: [`Listener`](#listener)<`K`, `T`>): `this`

Adds a **one-time** `listener` function for the event named `eventName`. The
next time `eventName` is triggered, this listener is removed and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependOnceListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `eventName` | [`Key`](#key)<`K`, `T`> | The name of the event. |
| `listener` | [`Listener`](#listener)<`K`, `T`> | The callback function |

###### Returns

`this`

###### Since

v0.3.0

##### prependListener()

> **prependListener**<`K`>(`eventName`: [`Key`](#key)<`K`, `T`>, `listener`: [`Listener`](#listener)<`K`, `T`>): `this`

Adds the `listener` function to the *beginning* of the listeners array for the
event named `eventName`. No checks are made to see if the `listener` has
already been added. Multiple calls passing the same combination of `eventName`
and `listener` will result in the `listener` being added, and called, multiple times.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `eventName` | [`Key`](#key)<`K`, `T`> | The name of the event. |
| `listener` | [`Listener`](#listener)<`K`, `T`> | The callback function |

###### Returns

`this`

##### prependOnceListener()

> **prependOnceListener**<`K`>(`eventName`: [`Key`](#key)<`K`, `T`>, `listener`: [`Listener`](#listener)<`K`, `T`>): `this`

Adds a **one-time**`listener` function for the event named `eventName` to the *beginning* of the listeners array.
The next time `eventName` is triggered, this listener is removed, and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `eventName` | [`Key`](#key)<`K`, `T`> | The name of the event. |
| `listener` | [`Listener`](#listener)<`K`, `T`> | The callback function |

###### Returns

`this`

##### removeListener()

> **removeListener**<`K`>(`eventName`: [`Key`](#key)<`K`, `T`>, `listener`: [`Listener`](#listener)<`K`, `T`>): `this`

Removes the specified `listener` from the listener array for the event named `eventName`.

`removeListener()` will remove, at most, one instance of a listener from the
listener array. If any single listener has been added multiple times to the
listener array for the specified `eventName`, then `removeListener()` must be
called multiple times to remove each instance.

Once an event is emitted, all listeners attached to it at the time of emitting are called in order.
This implies that any `removeListener()` calls *after* emitting and *before* the last listener finishes execution
will not remove them from `emit()` in progress. Subsequent events behave as expected.

```js
import { EventEmitter } from 'events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A
```

Because listeners are managed using an internal array, calling this will
change the position indices of any listener registered *after* the listener
being removed. This will not impact the order in which listeners are called,
but it means that any copies of the listener array as returned by
the `emitter.listeners()` method will need to be recreated.

When a single function has been added as a handler multiple times for a single
event (as in the example below), `removeListener()` will remove the most
recently added instance. In the example the `once('ping')` listener is removed:

```js
import { EventEmitter } from 'events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`Key`](#key)<`K`, `T`> |
| `listener` | [`Listener`](#listener)<`K`, `T`> |

###### Returns

`this`

## Type Aliases

### AnyRest

> **AnyRest** = \[`any`\[]]

***

### Args

> **Args**<`K`, `T`> = `T` *extends* [`DefaultEventMap`](#defaulteventmap) ? [`AnyRest`](#anyrest) : `K` *extends* keyof `T` ? `T`\[`K`] : `never`

#### Type Parameters

| Type Parameter |
| ------ |
| `K` |
| `T` |

***

### DefaultEventMap

> **DefaultEventMap** = \[`never`]

***

### EventMap

> **EventMap**<`T`> = `Record`\<keyof `T`, `any`\[]> | [`DefaultEventMap`](#defaulteventmap)

#### Type Parameters

| Type Parameter |
| ------ |
| `T` |

***

### Key

> **Key**<`K`, `T`> = `T` *extends* [`DefaultEventMap`](#defaulteventmap) ? [`EventKey`](dom-events.md#eventkey) : `K` | keyof `T`

#### Type Parameters

| Type Parameter |
| ------ |
| `K` |
| `T` |

***

### Key2

> **Key2**<`K`, `T`> = `T` *extends* [`DefaultEventMap`](#defaulteventmap) ? [`EventKey`](dom-events.md#eventkey) : `K` & keyof `T`

#### Type Parameters

| Type Parameter |
| ------ |
| `K` |
| `T` |

***

### Listener

> **Listener**<`K`, `T`, `F`> = `T` *extends* [`DefaultEventMap`](#defaulteventmap) ? `F` : `K` *extends* keyof `T` ? `T`\[`K`] *extends* `unknown`\[] ? (...`args`: `T`\[`K`]) => `void` : `never` : `never`

#### Type Parameters

| Type Parameter |
| ------ |
| `K` |
| `T` |
| `F` |

## References

### default

Renames and re-exports [EventEmitter](#eventemitter)

---

---
url: /plugins/reference/modules/llrt/fs.md
---
[@caido/quickjs-types](../../index.md) / llrt/fs

# llrt/fs

## Namespaces

| Namespace | Description |
| ------ | ------ |
| [constants](namespaces/constants.md) | - |

## Classes

### Dirent

A representation of a directory entry, which can be a file or a subdirectory
within the directory. A directory entry is a combination of the file name and file type pairs.

Additionally, when [promises.readdir](promises.md#readdir) or [readdirSync](#readdirsync) is called with
the `withFileTypes` option set to `true`, the resulting array is filled with `fs.Dirent` objects, rather than strings.

#### Constructors

##### Constructor

> **new Dirent**(): [`Dirent`](#dirent)

###### Returns

[`Dirent`](#dirent)

#### Properties

##### name

> **name**: `string`

The file name that this `fs.Dirent` object refers to.

##### parentPath

> **parentPath**: `string`

The base path that this `fs.Dirent` object refers to.

#### Methods

##### isBlockDevice()

> **isBlockDevice**(): `boolean`

Returns `true` if the `fs.Dirent` object describes a block device.

###### Returns

`boolean`

##### isCharacterDevice()

> **isCharacterDevice**(): `boolean`

Returns `true` if the `fs.Dirent` object describes a character device.

###### Returns

`boolean`

##### isDirectory()

> **isDirectory**(): `boolean`

Returns `true` if the `fs.Dirent` object describes a file system
directory.

###### Returns

`boolean`

##### isFIFO()

> **isFIFO**(): `boolean`

Returns `true` if the `fs.Dirent` object describes a first-in-first-out
(FIFO) pipe.

###### Returns

`boolean`

##### isFile()

> **isFile**(): `boolean`

Returns `true` if the `fs.Dirent` object describes a regular file.

###### Returns

`boolean`

##### isSocket()

> **isSocket**(): `boolean`

Returns `true` if the `fs.Dirent` object describes a socket.

###### Returns

`boolean`

##### isSymbolicLink()

> **isSymbolicLink**(): `boolean`

Returns `true` if the `fs.Dirent` object describes a symbolic link.

###### Returns

`boolean`

***

### Stats

A `fs.Stats` object provides information about a file.

`Stat` objects are not to be created directly using the `new` keyword.

```console
Stats {
  dev: 2114,
  ino: 48064969,
  mode: 33188,
  nlink: 1,
  uid: 85,
  gid: 100,
  rdev: 0,
  size: 527,
  blksize: 4096,
  blocks: 8,
  atimeMs: 1318289051000.1,
  mtimeMs: 1318289051000.1,
  ctimeMs: 1318289051000.1,
  birthtimeMs: 1318289051000.1,
  atime: Mon, 10 Oct 2011 23:24:11 GMT,
  mtime: Mon, 10 Oct 2011 23:24:11 GMT,
  ctime: Mon, 10 Oct 2011 23:24:11 GMT,
  birthtime: Mon, 10 Oct 2011 23:24:11 GMT }
```

#### Extends

* [`StatsBase`](#statsbase)<`number`>

#### Constructors

##### Constructor

> **new Stats**(): [`Stats`](#stats)

###### Returns

[`Stats`](#stats)

###### Inherited from

`StatsBase<number>.constructor`

#### Properties

##### atime

> **atime**: `Date`

###### Inherited from

[`StatsBase`](#statsbase).[`atime`](#atime-1)

##### atimeMs

> **atimeMs**: `number`

###### Inherited from

[`StatsBase`](#statsbase).[`atimeMs`](#atimems-1)

##### birthtime

> **birthtime**: `Date`

###### Inherited from

[`StatsBase`](#statsbase).[`birthtime`](#birthtime-1)

##### birthtimeMs

> **birthtimeMs**: `number`

###### Inherited from

[`StatsBase`](#statsbase).[`birthtimeMs`](#birthtimems-1)

##### blksize

> **blksize**: `number`

###### Inherited from

[`StatsBase`](#statsbase).[`blksize`](#blksize-1)

##### blocks

> **blocks**: `number`

###### Inherited from

[`StatsBase`](#statsbase).[`blocks`](#blocks-1)

##### ctime

> **ctime**: `Date`

###### Inherited from

[`StatsBase`](#statsbase).[`ctime`](#ctime-1)

##### ctimeMs

> **ctimeMs**: `number`

###### Inherited from

[`StatsBase`](#statsbase).[`ctimeMs`](#ctimems-1)

##### dev

> **dev**: `number`

###### Inherited from

[`StatsBase`](#statsbase).[`dev`](#dev-1)

##### gid

> **gid**: `number`

###### Inherited from

[`StatsBase`](#statsbase).[`gid`](#gid-1)

##### ino

> **ino**: `number`

###### Inherited from

[`StatsBase`](#statsbase).[`ino`](#ino-1)

##### mode

> **mode**: `number`

###### Inherited from

[`StatsBase`](#statsbase).[`mode`](#mode-2)

##### mtime

> **mtime**: `Date`

###### Inherited from

[`StatsBase`](#statsbase).[`mtime`](#mtime-1)

##### mtimeMs

> **mtimeMs**: `number`

###### Inherited from

[`StatsBase`](#statsbase).[`mtimeMs`](#mtimems-1)

##### nlink

> **nlink**: `number`

###### Inherited from

[`StatsBase`](#statsbase).[`nlink`](#nlink-1)

##### rdev

> **rdev**: `number`

###### Inherited from

[`StatsBase`](#statsbase).[`rdev`](#rdev-1)

##### size

> **size**: `number`

###### Inherited from

[`StatsBase`](#statsbase).[`size`](#size-1)

##### uid

> **uid**: `number`

###### Inherited from

[`StatsBase`](#statsbase).[`uid`](#uid-1)

#### Methods

##### isBlockDevice()

> **isBlockDevice**(): `boolean`

###### Returns

`boolean`

###### Inherited from

[`StatsBase`](#statsbase).[`isBlockDevice`](#isblockdevice-4)

##### isCharacterDevice()

> **isCharacterDevice**(): `boolean`

###### Returns

`boolean`

###### Inherited from

[`StatsBase`](#statsbase).[`isCharacterDevice`](#ischaracterdevice-4)

##### isDirectory()

> **isDirectory**(): `boolean`

###### Returns

`boolean`

###### Inherited from

[`StatsBase`](#statsbase).[`isDirectory`](#isdirectory-4)

##### isFIFO()

> **isFIFO**(): `boolean`

###### Returns

`boolean`

###### Inherited from

[`StatsBase`](#statsbase).[`isFIFO`](#isfifo-4)

##### isFile()

> **isFile**(): `boolean`

###### Returns

`boolean`

###### Inherited from

[`StatsBase`](#statsbase).[`isFile`](#isfile-4)

##### isSocket()

> **isSocket**(): `boolean`

###### Returns

`boolean`

###### Inherited from

[`StatsBase`](#statsbase).[`isSocket`](#issocket-4)

##### isSymbolicLink()

> **isSymbolicLink**(): `boolean`

###### Returns

`boolean`

###### Inherited from

[`StatsBase`](#statsbase).[`isSymbolicLink`](#issymboliclink-4)

## Interfaces

### MakeDirectoryOptions

#### Properties

##### mode?

> `optional` **mode**: `number`

A file mode. If not specified

###### Default

```ts
0o777
```

##### recursive?

> `optional` **recursive**: `boolean`

Indicates whether parent folders should be created.
If a folder was created, the path to the first created folder will be returned.

###### Default

```ts
false
```

***

### RmDirOptions

#### Properties

##### ~~recursive?~~

> `optional` **recursive**: `boolean`

###### Deprecated

Use `fs.rm(path, { recursive: true, force: true })` instead.

If `true`, perform a recursive directory removal. In
recursive mode, operations are retried on failure.

###### Default

```ts
false
```

***

### RmOptions

#### Properties

##### force?

> `optional` **force**: `boolean`

When `true`, exceptions will be ignored if `path` does not exist.

###### Default

```ts
false
```

##### recursive?

> `optional` **recursive**: `boolean`

If `true`, perform a recursive directory removal. In
recursive mode, operations are retried on failure.

###### Default

```ts
false
```

***

### StatsBase

#### Extended by

* [`Stats`](#stats)

#### Type Parameters

| Type Parameter |
| ------ |
| `T` |

#### Properties

##### atime

> **atime**: `Date`

##### atimeMs

> **atimeMs**: `T`

##### birthtime

> **birthtime**: `Date`

##### birthtimeMs

> **birthtimeMs**: `T`

##### blksize

> **blksize**: `T`

##### blocks

> **blocks**: `T`

##### ctime

> **ctime**: `Date`

##### ctimeMs

> **ctimeMs**: `T`

##### dev

> **dev**: `T`

##### gid

> **gid**: `T`

##### ino

> **ino**: `T`

##### mode

> **mode**: `T`

##### mtime

> **mtime**: `Date`

##### mtimeMs

> **mtimeMs**: `T`

##### nlink

> **nlink**: `T`

##### rdev

> **rdev**: `T`

##### size

> **size**: `T`

##### uid

> **uid**: `T`

#### Methods

##### isBlockDevice()

> **isBlockDevice**(): `boolean`

###### Returns

`boolean`

##### isCharacterDevice()

> **isCharacterDevice**(): `boolean`

###### Returns

`boolean`

##### isDirectory()

> **isDirectory**(): `boolean`

###### Returns

`boolean`

##### isFIFO()

> **isFIFO**(): `boolean`

###### Returns

`boolean`

##### isFile()

> **isFile**(): `boolean`

###### Returns

`boolean`

##### isSocket()

> **isSocket**(): `boolean`

###### Returns

`boolean`

##### isSymbolicLink()

> **isSymbolicLink**(): `boolean`

###### Returns

`boolean`

***

### StatSyncFn()

#### Extends

* `Function`

> **StatSyncFn**(`path`: `string`): [`Stats`](#stats)

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `path` | `string` |

#### Returns

[`Stats`](#stats)

## Type Aliases

### Mode

> **Mode** = `number`

***

### PathLike

> **PathLike** = `string`

Valid types for path values in "fs".

## Variables

### statSync

> `const` **statSync**: [`StatSyncFn`](#statsyncfn)

Synchronous stat - Get file status.

#### Param

A path to a file.

## Functions

### accessSync()

> **accessSync**(`path`: `string`, `mode?`: `number`): `void`

Synchronously tests a user's permissions for the file or directory specified
by `path`. The `mode` argument is an optional integer that specifies the
accessibility checks to be performed. `mode` should be either the value `fs.constants.F_OK` or a mask consisting of the bitwise OR of any of `fs.constants.R_OK`, `fs.constants.W_OK`, and
`fs.constants.X_OK` (e.g.`fs.constants.W_OK | fs.constants.R_OK`). Check `File access constants` for
possible values of `mode`.

If any of the accessibility checks fail, an `Error` will be thrown. Otherwise,
the method will return `undefined`.

```js
import { accessSync, constants } from 'fs';

try {
  accessSync('etc/passwd', constants.R_OK | constants.W_OK);
  console.log('can read/write');
} catch (err) {
  console.error('no access!');
}
```

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `path` | `string` | - |
| `mode?` | `number` |  |

#### Returns

`void`

***

### chmodSync()

> **chmodSync**(`path`: `string`, `mode`: `number`): `void`

For detailed information, see the documentation of the asynchronous version of
this API: chmod.

See the POSIX [`chmod(2)`](http://man7.org/linux/man-pages/man2/chmod.2.html) documentation for more detail.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `path` | `string` |
| `mode` | `number` |

#### Returns

`void`

***

### mkdirSync()

> **mkdirSync**(`path`: `string`, `options?`: [`MakeDirectoryOptions`](#makedirectoryoptions)): `string`

Synchronously creates a directory. Returns the `path`.

See the POSIX [`mkdir(2)`](http://man7.org/linux/man-pages/man2/mkdir.2.html) documentation for more details.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `path` | `string` |
| `options?` | [`MakeDirectoryOptions`](#makedirectoryoptions) |

#### Returns

`string`

***

### mkdtempSync()

> **mkdtempSync**(`prefix`: `string`): `string`

Returns the created directory path.

For detailed information, see the documentation of the asynchronous version of
this API: [promises.mkdtemp](promises.md#mkdtemp).

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `prefix` | `string` |

#### Returns

`string`

***

### readdirSync()

#### Call Signature

> **readdirSync**(`path`: `string`, `options?`: `object`): `string`\[]

Reads the contents of the directory.

See the POSIX [`readdir(3)`](http://man7.org/linux/man-pages/man3/readdir.3.html) documentation for more details.

If `options.withFileTypes` is set to `true`, the result will contain `fs.Dirent` objects.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `path` | `string` |
| `options?` | { `recursive?`: `boolean`; `withFileTypes?`: `false`; } |
| `options.recursive?` | `boolean` |
| `options.withFileTypes?` | `false` |

##### Returns

`string`\[]

#### Call Signature

> **readdirSync**(`path`: `string`, `options`: `object`): [`Dirent`](#dirent)\[]

Synchronous readdir (2) - read a directory.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `path` | `string` | A path to a file. If a URL is provided, it must use the `file:` protocol. |
| `options` | { `recursive?`: `boolean`; `withFileTypes`: `true`; } | If called with `withFileTypes: true` the result data will be an array of Dirent. |
| `options.recursive?` | `boolean` | - |
| `options.withFileTypes` | `true` | - |

##### Returns

[`Dirent`](#dirent)\[]

***

### readFileSync()

#### Call Signature

> **readFileSync**(`path`: `string`, `options?`: { `encoding?`: `null`; } | `null`): [`Buffer`](../buffer.md#buffer)

Returns the contents of the `path`.

For detailed information, see the documentation of the asynchronous version of
this API: [promises.readFile](promises.md#readfile-3).

If the `encoding` option is specified then this function returns a
string. Otherwise it returns a buffer.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `path` | `string` | A path to a file. |
| `options?` | { `encoding?`: `null`; } | `null` | - |

##### Returns

[`Buffer`](../buffer.md#buffer)

#### Call Signature

> **readFileSync**(`path`: `string`, `options`: [`BufferEncoding`](../buffer.md#bufferencoding) | { `encoding`: [`BufferEncoding`](../buffer.md#bufferencoding); }): `string`

Synchronously reads the entire contents of a file.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `path` | `string` | A path to a file. |
| `options` | [`BufferEncoding`](../buffer.md#bufferencoding) | { `encoding`: [`BufferEncoding`](../buffer.md#bufferencoding); } | Either the encoding for the result, or an object that contains the encoding. |

##### Returns

`string`

***

### renameSync()

> **renameSync**(`oldPath`: `string`, `newPath`: `string`): `void`

Synchronously renames a file or directory from `oldPath` to `newPath`.

For detailed information, see the documentation of the asynchronous version of
this API: [promises.rename](promises.md#rename).

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `oldPath` | `string` |
| `newPath` | `string` |

#### Returns

`void`

***

### rmdirSync()

> **rmdirSync**(`path`: `string`, `options?`: [`RmDirOptions`](#rmdiroptions)): `void`

Synchronous [`rmdir(2)`](http://man7.org/linux/man-pages/man2/rmdir.2.html). Returns `undefined`.

Using `fs.rmdirSync()` on a file (not a directory) results in an `ENOENT` error
on Windows and an `ENOTDIR` error on POSIX.

To get a behavior similar to the `rm -rf` Unix command, use [rmSync](#rmsync) with options `{ recursive: true, force: true }`.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `path` | `string` |
| `options?` | [`RmDirOptions`](#rmdiroptions) |

#### Returns

`void`

***

### rmSync()

> **rmSync**(`path`: `string`, `options?`: [`RmOptions`](#rmoptions)): `void`

Synchronously removes files and directories (modeled on the standard POSIX `rm` utility). Returns `undefined`.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `path` | `string` |
| `options?` | [`RmOptions`](#rmoptions) |

#### Returns

`void`

***

### symlinkSync()

> **symlinkSync**(`target`: `string`, `path`: `string`, `type?`: `"dir"` | `"file"` | `"junction"` | `null`): `void`

Synchronous symlink(2) - Create a new symbolic link to an existing file.

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `target` | `string` | A path to an existing file. If a URL is provided, it must use the `file:` protocol. |
| `path` | `string` | A path to the new symlink. If a URL is provided, it must use the `file:` protocol. |
| `type?` | `"dir"` | `"file"` | `"junction"` | `null` |  |

#### Returns

`void`

***

### writeFileSync()

> **writeFileSync**(`file`: `string`, `data`: `string` | [`ArrayBufferView`](../globals/namespaces/QuickJS.md#arraybufferview) | [`Buffer`](../buffer.md#buffer) | `ArrayBuffer` | `SharedArrayBuffer`, `options?`: `object`): `void`

Returns `undefined`.

For detailed information, see the documentation of the asynchronous version of
this API: [promises.writeFile](promises.md#writefile-2).

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `file` | `string` | A path to a file. |
| `data` | `string` | [`ArrayBufferView`](../globals/namespaces/QuickJS.md#arraybufferview) | [`Buffer`](../buffer.md#buffer) | `ArrayBuffer` | `SharedArrayBuffer` | - |
| `options?` | { `mode?`: `number`; } | - |
| `options.mode?` | `number` | - |

#### Returns

`void`

## References

### promises

Renames and re-exports [llrt/fs/promises](promises.md)

---

---
url: /plugins/reference/modules/llrt/fs/promises.md
---
[@caido/quickjs-types](../../index.md) / llrt/fs/promises

# llrt/fs/promises

## Classes

### FileHandle

#### Constructors

##### Constructor

> **new FileHandle**(): [`FileHandle`](#filehandle)

###### Returns

[`FileHandle`](#filehandle)

#### Properties

##### fd

> `readonly` **fd**: `number`

The numeric file descriptor managed by the {FileHandle} object.

#### Methods

##### chmod()

> **chmod**(`mode`: `number`): `Promise`<`void`>

Modifies the permissions on the file. See [`chmod(2)`](http://man7.org/linux/man-pages/man2/chmod.2.html).

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `mode` | `number` | the file mode bit mask. |

###### Returns

`Promise`<`void`>

Fulfills with `undefined` upon success.

##### chown()

> **chown**(`uid`: `number`, `gid`: `number`): `Promise`<`void`>

Changes the ownership of the file. A wrapper for [`chown(2)`](http://man7.org/linux/man-pages/man2/chown.2.html).

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `uid` | `number` | The file's new owner's user id. |
| `gid` | `number` | The file's new group's group id. |

###### Returns

`Promise`<`void`>

Fulfills with `undefined` upon success.

##### close()

> **close**(): `Promise`<`void`>

Closes the file handle after waiting for any pending operation on the handle to
complete.

```js
import { open } from 'fs/promises';

let filehandle;
try {
  filehandle = await open('thefile.txt', 'r');
} finally {
  await filehandle?.close();
}
```

###### Returns

`Promise`<`void`>

Fulfills with `undefined` upon success.

##### datasync()

> **datasync**(): `Promise`<`void`>

Forces all currently queued I/O operations associated with the file to the
operating system's synchronized I/O completion state. Refer to the POSIX [`fdatasync(2)`](http://man7.org/linux/man-pages/man2/fdatasync.2.html) documentation for details.

Unlike `filehandle.sync` this method does not flush modified metadata.

###### Returns

`Promise`<`void`>

Fulfills with `undefined` upon success.

##### read()

###### Call Signature

> **read**<`T`>(`buffer`: `T`, `offset?`: `number` | `null`, `length?`: `number` | `null`, `position?`: `number` | `null`): `Promise`<[`FileReadResult`](#filereadresult)<`T`>>

Reads data from the file and stores that in the given buffer.

If the file is not modified concurrently, the end-of-file is reached when the
number of bytes read is zero.

###### Type Parameters

| Type Parameter |
| ------ |
| `T` *extends* [`ArrayBufferView`](../globals/namespaces/QuickJS.md#arraybufferview) |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `buffer` | `T` | A buffer that will be filled with the file data read. |
| `offset?` | `number` | `null` | The location in the buffer at which to start filling. |
| `length?` | `number` | `null` | The number of bytes to read. |
| `position?` | `number` | `null` | The location where to begin reading data from the file. If `null`, data will be read from the current file position, and the position will be updated. If `position` is an integer, the current file position will remain unchanged. |

###### Returns

`Promise`<[`FileReadResult`](#filereadresult)<`T`>>

Fulfills upon success with an object with two properties: bytesRead and buffer

###### Call Signature

> **read**<`T`>(`buffer`: `T`, `options?`: [`FileReadOptions`](#filereadoptions)<`T`>): `Promise`<[`FileReadResult`](#filereadresult)<`T`>>

Reads data from the file and stores that in the given buffer.

If the file is not modified concurrently, the end-of-file is reached when the
number of bytes read is zero.

###### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `T` *extends* [`ArrayBufferView`](../globals/namespaces/QuickJS.md#arraybufferview) | [`Buffer`](../buffer.md#buffer) |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `buffer` | `T` | A buffer that will be filled with the file data read. |
| `options?` | [`FileReadOptions`](#filereadoptions)<`T`> | - |

###### Returns

`Promise`<[`FileReadResult`](#filereadresult)<`T`>>

Fulfills upon success with an object with two properties: bytesRead and buffer

###### Call Signature

> **read**<`T`>(`options?`: [`FileReadOptions`](#filereadoptions)<`T`>): `Promise`<[`FileReadResult`](#filereadresult)<`T`>>

Reads data from the file and stores that in the given buffer.

If the file is not modified concurrently, the end-of-file is reached when the
number of bytes read is zero.

###### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `T` *extends* [`ArrayBufferView`](../globals/namespaces/QuickJS.md#arraybufferview) | [`Buffer`](../buffer.md#buffer) |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `options?` | [`FileReadOptions`](#filereadoptions)<`T`> |

###### Returns

`Promise`<[`FileReadResult`](#filereadresult)<`T`>>

Fulfills upon success with an object with two properties: bytesRead and buffer

##### readFile()

###### Call Signature

> **readFile**(`options?`: { `encoding?`: `null`; } | `null`): `Promise`<[`Buffer`](../buffer.md#buffer)>

Asynchronously reads the entire contents of a file.

If `options` is a string, then it specifies the `encoding`.

The `FileHandle` has to support reading.

If one or more `filehandle.read()` calls are made on a file handle and then a `filehandle.readFile()` call is made, the data will be read from the current
position till the end of the file. It doesn't always read from the beginning
of the file.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `options?` | { `encoding?`: `null`; } | `null` |

###### Returns

`Promise`<[`Buffer`](../buffer.md#buffer)>

Fulfills upon a successful read with the contents of the file. If no encoding is specified (using `options.encoding`), the data is returned as a {Buffer} object. Otherwise, the
data will be a string.

###### Call Signature

> **readFile**(`options`: [`BufferEncoding`](../buffer.md#bufferencoding) | { `encoding`: [`BufferEncoding`](../buffer.md#bufferencoding); }): `Promise`<`string`>

Asynchronously reads the entire contents of a file.

If `options` is a string, then it specifies the `encoding`.

The `FileHandle` has to support reading.

If one or more `filehandle.read()` calls are made on a file handle and then a `filehandle.readFile()` call is made, the data will be read from the current
position till the end of the file. It doesn't always read from the beginning
of the file.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | [`BufferEncoding`](../buffer.md#bufferencoding) | { `encoding`: [`BufferEncoding`](../buffer.md#bufferencoding); } |

###### Returns

`Promise`<`string`>

Fulfills upon a successful read with the contents of the file. If no encoding is specified (using `options.encoding`), the data is returned as a {Buffer} object. Otherwise, the
data will be a string.

##### stat()

> **stat**(): `Promise`<[`Stats`](index.md#stats)>

Get {FileHandle} status.

###### Returns

`Promise`<[`Stats`](index.md#stats)>

Fulfills with the {fs.Stats} object.

##### sync()

> **sync**(): `Promise`<`void`>

Request that all data for the open file descriptor is flushed to the storage
device. The specific implementation is operating system and device specific.
Refer to the POSIX [`fsync(2)`](http://man7.org/linux/man-pages/man2/fsync.2.html) documentation for more detail.

###### Returns

`Promise`<`void`>

Fulfills with `undefined` upon success.

##### truncate()

> **truncate**(`len?`: `number`): `Promise`<`void`>

Truncates the file.

If the file was larger than `len` bytes, only the first `len` bytes will be
retained in the file.

The following example retains only the first four bytes of the file:

```js
import { open } from 'fs/promises';

let filehandle = null;
try {
  filehandle = await open('temp.txt', 'r+');
  await filehandle.truncate(4);
} finally {
  await filehandle?.close();
}
```

If the file previously was shorter than `len` bytes, it is extended, and the
extended part is filled with null bytes (`'\0'`):

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `len?` | `number` |  |

###### Returns

`Promise`<`void`>

Fulfills with `undefined` upon success.

##### write()

###### Call Signature

> **write**<`TBuffer`>(`buffer`: `TBuffer`, `offset?`: `number` | `null`, `length?`: `number` | `null`, `position?`: `number` | `null`): `Promise`<{ `buffer`: `TBuffer`; `bytesWritten`: `number`; }>

Write `buffer` to the file.

The promise is fulfilled with an object containing two properties:

It is unsafe to use `filehandle.write()` multiple times on the same file
without waiting for the promise to be fulfilled (or rejected). For this
scenario, use `filehandle.createWriteStream()`.

On Linux, positional writes do not work when the file is opened in append mode.
The kernel ignores the position argument and always appends the data to
the end of the file.

###### Type Parameters

| Type Parameter |
| ------ |
| `TBuffer` *extends* [`ArrayBufferView`](../globals/namespaces/QuickJS.md#arraybufferview) |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `buffer` | `TBuffer` | - |
| `offset?` | `number` | `null` | The start position from within `buffer` where the data to write begins. |
| `length?` | `number` | `null` | The number of bytes from `buffer` to write. |
| `position?` | `number` | `null` | The offset from the beginning of the file where the data from `buffer` should be written. If `position` is not a `number`, the data will be written at the current position. See the POSIX pwrite(2) documentation for more detail. |

###### Returns

`Promise`<{ `buffer`: `TBuffer`; `bytesWritten`: `number`; }>

###### Call Signature

> **write**<`TBuffer`>(`buffer`: `TBuffer`, `options?`: { `length?`: `number` | `null`; `offset?`: `number` | `null`; `position?`: `number` | `null`; } | `null`): `Promise`<{ `buffer`: `TBuffer`; `bytesWritten`: `number`; }>

Write `buffer` to the file.

The promise is fulfilled with an object containing two properties:

It is unsafe to use `filehandle.write()` multiple times on the same file
without waiting for the promise to be fulfilled (or rejected). For this
scenario, use `filehandle.createWriteStream()`.

On Linux, positional writes do not work when the file is opened in append mode.
The kernel ignores the position argument and always appends the data to
the end of the file.

###### Type Parameters

| Type Parameter |
| ------ |
| `TBuffer` *extends* [`ArrayBufferView`](../globals/namespaces/QuickJS.md#arraybufferview) |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `buffer` | `TBuffer` |
| `options?` | { `length?`: `number` | `null`; `offset?`: `number` | `null`; `position?`: `number` | `null`; } | `null` |

###### Returns

`Promise`<{ `buffer`: `TBuffer`; `bytesWritten`: `number`; }>

###### Call Signature

> **write**(`data`: `string`, `position?`: `number` | `null`, `encoding?`: [`BufferEncoding`](../buffer.md#bufferencoding) | `null`): `Promise`<{ `buffer`: `string`; `bytesWritten`: `number`; }>

Write `buffer` to the file.

The promise is fulfilled with an object containing two properties:

It is unsafe to use `filehandle.write()` multiple times on the same file
without waiting for the promise to be fulfilled (or rejected). For this
scenario, use `filehandle.createWriteStream()`.

On Linux, positional writes do not work when the file is opened in append mode.
The kernel ignores the position argument and always appends the data to
the end of the file.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `data` | `string` | - |
| `position?` | `number` | `null` | The offset from the beginning of the file where the data from `buffer` should be written. If `position` is not a `number`, the data will be written at the current position. See the POSIX pwrite(2) documentation for more detail. |
| `encoding?` | [`BufferEncoding`](../buffer.md#bufferencoding) | `null` | - |

###### Returns

`Promise`<{ `buffer`: `string`; `bytesWritten`: `number`; }>

##### writeFile()

> **writeFile**(`data`: `string` | [`ArrayBufferView`](../globals/namespaces/QuickJS.md#arraybufferview), `options?`: [`BufferEncoding`](../buffer.md#bufferencoding) | { `encoding?`: BufferEncoding | null | undefined; } | `null`): `Promise`<`void`>

Asynchronously writes data to a file, replacing the file if it already exists.

If `options` is a string, then it specifies the `encoding`.

The `FileHandle` has to support writing.

It is unsafe to use `filehandle.writeFile()` multiple times on the same file
without waiting for the promise to be fulfilled (or rejected).

If one or more `filehandle.write()` calls are made on a file handle and then a`filehandle.writeFile()` call is made, the data will be written from the
current position till the end of the file. It doesn't always write from the beginning of the file.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `data` | `string` | [`ArrayBufferView`](../globals/namespaces/QuickJS.md#arraybufferview) |
| `options?` | [`BufferEncoding`](../buffer.md#bufferencoding) | { `encoding?`: BufferEncoding | null | undefined; } | `null` |

###### Returns

`Promise`<`void`>

## Interfaces

### FileReadOptions

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `T` *extends* [`ArrayBufferView`](../globals/namespaces/QuickJS.md#arraybufferview) | [`Buffer`](../buffer.md#buffer) |

#### Properties

##### buffer?

> `optional` **buffer**: `T`

###### Default

`Buffer.alloc(16384)`

##### length?

> `optional` **length**: `number` | `null`

###### Default

`buffer.byteLength - offset`

##### offset?

> `optional` **offset**: `number` | `null`

###### Default

```ts
0
```

##### position?

> `optional` **position**: `number` | `null`

***

### FileReadResult

#### Type Parameters

| Type Parameter |
| ------ |
| `T` *extends* [`ArrayBufferView`](../globals/namespaces/QuickJS.md#arraybufferview) |

#### Properties

##### buffer

> **buffer**: `T`

##### bytesRead

> **bytesRead**: `number`

## Type Aliases

### FileSystemFlags

> **FileSystemFlags** = `"a"` | `"ax"` | `"a+"` | `"r"` | `"r+"` | `"w"` | `"wx"` | `"w+"` | `"wx+"`

## Variables

### constants

> `const` **constants**: *typeof* [`constants`](namespaces/constants.md)

## Functions

### access()

> **access**(`path`: `string`, `mode?`: `number`): `Promise`<`void`>

Tests a user's permissions for the file or directory specified by `path`.
The `mode` argument is an optional integer that specifies the accessibility
checks to be performed. `mode` should be either the value `fs.constants.F_OK` or a mask consisting of the bitwise OR of any of `fs.constants.R_OK`, `fs.constants.W_OK`, and `fs.constants.X_OK`
(e.g.`fs.constants.W_OK | fs.constants.R_OK`). Check `File access constants` for
possible values of `mode`.

If the accessibility check is successful, the promise is fulfilled with no
value. If any of the accessibility checks fail, the promise is rejected
with an [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) object. The following example checks if the file`/etc/passwd` can be read and
written by the current process.

```js
import { access, constants } from 'fs/promises';

try {
  await access('/etc/passwd', constants.R_OK | constants.W_OK);
  console.log('can access');
} catch {
  console.error('cannot access');
}
```

Using `fsPromises.access()` to check for the accessibility of a file before
calling `fsPromises.open()` is not recommended. Doing so introduces a race
condition, since other processes may change the file's state between the two
calls. Instead, user code should open/read/write the file directly and handle
the error raised if the file is not accessible.

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `path` | `string` | - |
| `mode?` | `number` |  |

#### Returns

`Promise`<`void`>

Fulfills with `undefined` upon success.

***

### chmod()

> **chmod**(`path`: `string`, `mode`: `number`): `Promise`<`void`>

Changes the permissions of a file.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `path` | `string` |
| `mode` | `number` |

#### Returns

`Promise`<`void`>

Fulfills with `undefined` upon success.

***

### mkdir()

> **mkdir**(`path`: `string`, `options?`: [`MakeDirectoryOptions`](index.md#makedirectoryoptions)): `Promise`<`string`>

Asynchronously creates a directory.

The optional `options` argument can be an object with a `mode` property and a `recursive` property indicating whether parent directories should be created.
Calling `fsPromises.mkdir()` when `path` is a directory that exists results in a rejection only when `recursive` is false.

```js
import { mkdir } from 'fs/promises';

try {
  const projectFolder = './test/project/123';
  const createDir = await mkdir(projectFolder, { recursive: true });

  console.log(`created ${createDir}`);
} catch (err) {
  console.error(err.message);
}
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `path` | `string` |
| `options?` | [`MakeDirectoryOptions`](index.md#makedirectoryoptions) |

#### Returns

`Promise`<`string`>

Upon success, fulfills with `undefined` if `recursive` is `false`, or the first directory path created if `recursive` is `true`.

***

### mkdtemp()

> **mkdtemp**(`prefix`: `string`): `Promise`<`string`>

Creates a unique temporary directory. A unique directory name is generated by
appending six random characters to the end of the provided `prefix`. Due to
platform inconsistencies, avoid trailing `X` characters in `prefix`. Some
platforms, notably the BSDs, can return more than six random characters, and
replace trailing `X` characters in `prefix` with random characters.

```js
import { mkdtemp } from 'fs/promises';
import { join } from 'path';
import { tmpdir } from 'os';

try {
  await mkdtemp(join(tmpdir(), 'foo-'));
} catch (err) {
  console.error(err);
}
```

The `fsPromises.mkdtemp()` method will append the six randomly selected
characters directly to the `prefix` string. For instance, given a directory `/tmp`, if the intention is to create a temporary directory *within* `/tmp`, the `prefix` must end with a trailing
platform-specific path separator
(`require('path').sep`).

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `prefix` | `string` |

#### Returns

`Promise`<`string`>

Fulfills with a string containing the file system path of the newly created temporary directory.

***

### open()

> **open**(`path`: `string`, `flags?`: [`FileSystemFlags`](#filesystemflags), `mode?`: `number`): `Promise`<[`FileHandle`](#filehandle)>

Opens a `FileHandle`.

Refer to the POSIX [`open(2)`](http://man7.org/linux/man-pages/man2/open.2.html) documentation for more detail.

Some characters (`< > : " / \ | ? *`) are reserved under Windows as documented
by [Naming Files, Paths, and Namespaces](https://docs.microsoft.com/en-us/windows/desktop/FileIO/naming-a-file).

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `path` | `string` | - |
| `flags?` | [`FileSystemFlags`](#filesystemflags) | See {FileSystemFlags}. |
| `mode?` | `number` | Sets the file mode if the file is created (UNIX). |

#### Returns

`Promise`<[`FileHandle`](#filehandle)>

Fulfills with a {FileHandle} object.

***

### readdir()

#### Call Signature

> **readdir**(`path`: `string`, `options?`: `object`): `Promise`<`string`\[]>

Reads the contents of a directory.

If `options.withFileTypes` is set to `true`, the returned array will contain `fs.Dirent` objects.

```js
import { readdir } from 'fs/promises';

try {
  const files = await readdir(path);
  for (const file of files)
    console.log(file);
} catch (err) {
  console.error(err);
}
```

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `path` | `string` |
| `options?` | { `recursive?`: `boolean`; `withFileTypes?`: `false`; } |
| `options.recursive?` | `boolean` |
| `options.withFileTypes?` | `false` |

##### Returns

`Promise`<`string`\[]>

Fulfills with an array of the names of the files in the directory excluding `'.'` and `'..'`.

#### Call Signature

> **readdir**(`path`: `string`, `options`: `object`): `Promise`<[`Dirent`](index.md#dirent)\[]>

Asynchronous readdir(2) - read a directory.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `path` | `string` | A path to a file. If a URL is provided, it must use the `file:` protocol. |
| `options` | { `recursive?`: `boolean`; `withFileTypes`: `true`; } | If called with `withFileTypes: true` the result data will be an array of Dirent. |
| `options.recursive?` | `boolean` | - |
| `options.withFileTypes` | `true` | - |

##### Returns

`Promise`<[`Dirent`](index.md#dirent)\[]>

***

### readFile()

#### Call Signature

> **readFile**(`path`: `string`, `options?`: { `encoding?`: `null`; } | `null`): `Promise`<[`Buffer`](../buffer.md#buffer)>

Asynchronously reads the entire contents of a file.

If no encoding is specified (using `options.encoding`), the data is returned
as a `Buffer` object. Otherwise, the data will be a string.

If `options` is a string, then it specifies the encoding.

When the `path` is a directory, the behavior of `fsPromises.readFile()` is
platform-specific. On macOS, Linux, and Windows, the promise will be rejected
with an error. On FreeBSD, a representation of the directory's contents will be
returned.

An example of reading a `package.json` file.

```js
import { readFile } from 'fs/promises';
try {
  const filePath = './package.json';
  const contents = await readFile(filePath, { encoding: 'utf8' });
  console.log(contents);
} catch (err) {
  console.error(err.message);
}
```

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `path` | `string` | filename or `FileHandle` |
| `options?` | { `encoding?`: `null`; } | `null` | - |

##### Returns

`Promise`<[`Buffer`](../buffer.md#buffer)>

Fulfills with the contents of the file.

#### Call Signature

> **readFile**(`path`: `string`, `options`: { `encoding`: [`BufferEncoding`](../buffer.md#bufferencoding); } | [`BufferEncoding`](../buffer.md#bufferencoding)): `Promise`<`string`>

Asynchronously reads the entire contents of a file.

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `path` | `string` | A path to a file. If a URL is provided, it must use the `file:` protocol. If a `FileHandle` is provided, the underlying file will *not* be closed automatically. |
| `options` | { `encoding`: [`BufferEncoding`](../buffer.md#bufferencoding); } | [`BufferEncoding`](../buffer.md#bufferencoding) | An object that may contain an optional flag. If a flag is not provided, it defaults to `'r'`. |

##### Returns

`Promise`<`string`>

***

### rename()

> **rename**(`oldPath`: `string`, `newPath`: `string`): `Promise`<`void`>

Asynchronously renames a file or directory from `oldPath` to `newPath`.

```js
import { rename } from 'fs/promises';

try {
  await rename('oldfile.txt', 'newfile.txt');
  console.log('Rename complete!');
} catch (err) {
  console.error(err);
}
```

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `oldPath` | `string` | A path to a file or directory. |
| `newPath` | `string` | The new path for the file or directory. |

#### Returns

`Promise`<`void`>

Fulfills with `undefined` upon success.

***

### rm()

> **rm**(`path`: `string`, `options?`: [`RmOptions`](index.md#rmoptions)): `Promise`<`void`>

Removes files and directories (modeled on the standard POSIX `rm` utility).

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `path` | `string` |
| `options?` | [`RmOptions`](index.md#rmoptions) |

#### Returns

`Promise`<`void`>

Fulfills with `undefined` upon success.

***

### rmdir()

> **rmdir**(`path`: `string`, `options?`: [`RmDirOptions`](index.md#rmdiroptions)): `Promise`<`void`>

Removes the directory identified by `path`.

Using `fsPromises.rmdir()` on a file (not a directory) results in the
promise being rejected with an `ENOENT` error on Windows and an `ENOTDIR` error on POSIX.

To get a behavior similar to the `rm -rf` Unix command, use `fsPromises.rm()` with options `{ recursive: true, force: true }`.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `path` | `string` |
| `options?` | [`RmDirOptions`](index.md#rmdiroptions) |

#### Returns

`Promise`<`void`>

Fulfills with `undefined` upon success.

***

### stat()

> **stat**(`path`: `string`): `Promise`<[`Stats`](index.md#stats)>

Asynchronous stat - Get file status.

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `path` | `string` | A path to a file. |

#### Returns

`Promise`<[`Stats`](index.md#stats)>

Fulfills with the {fs.Stats} object for the given `path`.

***

### symlink()

> **symlink**(`target`: `string`, `path`: `string`, `type?`: `"dir"` | `"file"` | `"junction"` | `null`): `Promise`<`void`>

Creates a symbolic link.

The `type` argument is only used on Windows platforms and can be one of `'dir'`, `'file'`, or `'junction'`. If the `type` argument is not a string, LLRT will
autodetect `target` type and use `'file'` or `'dir'`. If the `target` does not
exist, `'file'` will be used. Windows junction points require the destination
path to be absolute. When using `'junction'`, the `target` argument will
automatically be normalized to absolute path. Junction points on NTFS volumes
can only point to directories.

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `target` | `string` | - |
| `path` | `string` | - |
| `type?` | `"dir"` | `"file"` | `"junction"` | `null` |  |

#### Returns

`Promise`<`void`>

Fulfills with `undefined` upon success.

***

### writeFile()

> **writeFile**(`file`: `string`, `data`: `string` | [`ArrayBufferView`](../globals/namespaces/QuickJS.md#arraybufferview) | [`Buffer`](../buffer.md#buffer) | `ArrayBuffer` | `SharedArrayBuffer`, `options?`: `object`): `Promise`<`void`>

Asynchronously writes data to a file, replacing the file if it already exists.

The `encoding` option is ignored if `data` is a buffer.

It is unsafe to use `fsPromises.writeFile()` multiple times on the same file
without waiting for the promise to be settled.

Similarly to `fsPromises.readFile` - `fsPromises.writeFile` is a convenience
method that performs multiple `write` calls internally to write the buffer
passed to it.

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `file` | `string` | filename or `FileHandle` |
| `data` | `string` | [`ArrayBufferView`](../globals/namespaces/QuickJS.md#arraybufferview) | [`Buffer`](../buffer.md#buffer) | `ArrayBuffer` | `SharedArrayBuffer` | - |
| `options?` | { `mode?`: `number`; } | - |
| `options.mode?` | `number` | - |

#### Returns

`Promise`<`void`>

Fulfills with `undefined` upon success.

---

---
url: /plugins/reference/modules/llrt/globals.md
---
[@caido/quickjs-types](../../index.md) / llrt/globals

# llrt/globals

## Namespaces

| Namespace | Description |
| ------ | ------ |
| [QuickJS](namespaces/QuickJS.md) | - |

## Interfaces

### SymbolConstructor()

> **SymbolConstructor**(`description?`: `string` | `number`): `symbol`

Returns a new unique Symbol value.

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `description?` | `string` | `number` | Description of the new Symbol object. |

#### Returns

`symbol`

#### Properties

##### dispose

> `readonly` **dispose**: *typeof* [`dispose`](#dispose)

A method that is used to release resources held by an object. Called by the semantics of the `using` statement.

---

---
url: /plugins/reference/modules/llrt/https.md
---
[@caido/quickjs-types](../index.md) / llrt/https

# llrt/https

## Classes

### Agent

An `Agent` is responsible for managing connection persistence
and reuse for HTTP clients. Currently only a small subset of the options
are supported.

#### Constructors

##### Constructor

> **new Agent**(`opts?`: [`AgentOptions`](#agentoptions)): [`Agent`](#agent)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `opts?` | [`AgentOptions`](#agentoptions) |

###### Returns

[`Agent`](#agent)

## Interfaces

### AgentOptions

#### Properties

##### ca?

> `optional` **ca**: `string` | [`Buffer`](buffer.md#buffer) | (`string` | [`Buffer`](buffer.md#buffer))\[]

Optionally override the trusted CA certificates. Default is to trust
the well-known CAs curated by Mozilla. Mozilla's CAs are completely
replaced when CAs are explicitly specified using this option.

##### rejectUnauthorized?

> `optional` **rejectUnauthorized**: `boolean`

Whether to reject unauthorized certificates. Default is `true`.

---

---
url: /plugins/reference/modules/llrt/net.md
---
[@caido/quickjs-types](../index.md) / llrt/net

# llrt/net

## Classes

### Server

This class is used to create a TCP or `IPC` server.

#### Extends

* [`EventEmitter`](events.md#eventemitter)

#### Constructors

##### Constructor

> **new Server**(`connectionListener?`: (`socket`: [`Socket`](#socket)) => `void`): [`Server`](#server)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `connectionListener?` | (`socket`: [`Socket`](#socket)) => `void` |

###### Returns

[`Server`](#server)

###### Overrides

[`EventEmitter`](events.md#eventemitter).[`constructor`](events.md#constructor)

##### Constructor

> **new Server**(`options?`: [`ServerOpts`](#serveropts), `connectionListener?`: (`socket`: [`Socket`](#socket)) => `void`): [`Server`](#server)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `options?` | [`ServerOpts`](#serveropts) |
| `connectionListener?` | (`socket`: [`Socket`](#socket)) => `void` |

###### Returns

[`Server`](#server)

###### Overrides

`EventEmitter.constructor`

#### Methods

##### addListener()

###### Call Signature

> **addListener**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

events.EventEmitter

1. close
2. connection
3. error
4. listening

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `string` |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Overrides

[`EventEmitter`](events.md#eventemitter).[`addListener`](events.md#addlistener)

###### Call Signature

> **addListener**(`event`: `"close"`, `listener`: () => `void`): `this`

events.EventEmitter

1. close
2. connection
3. error
4. listening

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.addListener`

###### Call Signature

> **addListener**(`event`: `"connection"`, `listener`: (`socket`: [`Socket`](#socket)) => `void`): `this`

events.EventEmitter

1. close
2. connection
3. error
4. listening

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"connection"` |
| `listener` | (`socket`: [`Socket`](#socket)) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.addListener`

###### Call Signature

> **addListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

events.EventEmitter

1. close
2. connection
3. error
4. listening

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.addListener`

###### Call Signature

> **addListener**(`event`: `"listening"`, `listener`: () => `void`): `this`

events.EventEmitter

1. close
2. connection
3. error
4. listening

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"listening"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.addListener`

##### address()

> **address**(): `string` | [`AddressInfo`](#addressinfo) | `null`

Returns the bound `address`, the address `family` name, and `port` of the server
as reported by the operating system if listening on an IP socket
(useful to find which port was assigned when getting an OS-assigned address):`{ port: 12346, family: 'IPv4', address: '127.0.0.1' }`.

For a server listening on a pipe or Unix domain socket, the name is returned
as a string.

```js
const server = net.createServer((socket) => {
  socket.end('goodbye\n');
}).on('error', (err) => {
  // Handle errors here.
  throw err;
});

// Grab an arbitrary unused port.
server.listen(() => {
  console.log('opened server on', server.address());
});
```

`server.address()` returns `null` before the `'listening'` event has been
emitted or after calling `server.close()`.

###### Returns

`string` | [`AddressInfo`](#addressinfo) | `null`

##### close()

> **close**(`callback?`: (`err?`: `Error`) => `void`): `this`

Stops the server from accepting new connections and keeps existing
connections. This function is asynchronous, the server is finally closed
when all connections are ended and the server emits a `'close'` event.
The optional `callback` will be called once the `'close'` event occurs. Unlike
that event, it will be called with an `Error` as its only argument if the server
was not open when it was closed.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `callback?` | (`err?`: `Error`) => `void` | Called when the server is closed. |

###### Returns

`this`

##### emit()

###### Call Signature

> **emit**(`event`: `string` | `symbol`, ...`args`: `any`\[]): `boolean`

Synchronously calls each of the listeners registered for the event named `eventName`, in the order they were registered, passing the supplied arguments
to each.

```js
import { EventEmitter } from 'events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `string` | `symbol` |
| ...`args` | `any`\[] |

###### Returns

`boolean`

###### Overrides

[`EventEmitter`](events.md#eventemitter).[`emit`](events.md#emit)

###### Call Signature

> **emit**(`event`: `"close"`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |

###### Returns

`boolean`

###### Overrides

`EventEmitter.emit`

###### Call Signature

> **emit**(`event`: `"connection"`, `socket`: [`Socket`](#socket)): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"connection"` |
| `socket` | [`Socket`](#socket) |

###### Returns

`boolean`

###### Overrides

`EventEmitter.emit`

###### Call Signature

> **emit**(`event`: `"error"`, `err`: `Error`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `err` | `Error` |

###### Returns

`boolean`

###### Overrides

`EventEmitter.emit`

###### Call Signature

> **emit**(`event`: `"listening"`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"listening"` |

###### Returns

`boolean`

###### Overrides

`EventEmitter.emit`

##### eventNames()

> **eventNames**(): [`EventKey`](dom-events.md#eventkey)\[]

Returns an array listing the events for which the emitter has registered
listeners. The values in the array are strings or `Symbol`s.

```js
import { EventEmitter } from 'events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]
```

###### Returns

[`EventKey`](dom-events.md#eventkey)\[]

###### Inherited from

[`EventEmitter`](events.md#eventemitter).[`eventNames`](events.md#eventnames)

##### listen()

###### Call Signature

> **listen**(`listeningListener?`: () => `void`): `void`

Start a server listening for connections. A `net.Server` can be a TCP or
an `IPC` server depending on what it listens to.

Possible signatures:

* `server.listen(options[, callback])`
* `server.listen(path[, backlog][, callback])` for `IPC` servers
* `server.listen([port[, host[, backlog]]][, callback])` for TCP servers

This function is asynchronous. When the server starts listening, the `'listening'` event will be emitted. The last parameter `callback`will be added as a listener for the `'listening'`
event.

All `listen()` methods can take a `backlog` parameter to specify the maximum length of the queue of pending connections.
Currently this parameter is IGNORED, support will be added in the future.

All [Socket](#socket) are set to `SO_REUSEADDR` (see [`socket(7)`](https://man7.org/linux/man-pages/man7/socket.7.html) for details).

The `server.listen()` method can be called again if and only if there was an error during the first `server.listen()`
call or `server.close()` has been called. Otherwise, an error will be thrown.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `listeningListener?` | () => `void` |

###### Returns

`void`

###### Call Signature

> **listen**(`port?`: `number`, `hostname?`: `string`, `backlog?`: `number`, `listeningListener?`: () => `void`): `void`

Start a server listening for connections. A `net.Server` can be a TCP or
an `IPC` server depending on what it listens to.

Possible signatures:

* `server.listen(options[, callback])`
* `server.listen(path[, backlog][, callback])` for `IPC` servers
* `server.listen([port[, host[, backlog]]][, callback])` for TCP servers

This function is asynchronous. When the server starts listening, the `'listening'` event will be emitted. The last parameter `callback`will be added as a listener for the `'listening'`
event.

All `listen()` methods can take a `backlog` parameter to specify the maximum length of the queue of pending connections.
Currently this parameter is IGNORED, support will be added in the future.

All [Socket](#socket) are set to `SO_REUSEADDR` (see [`socket(7)`](https://man7.org/linux/man-pages/man7/socket.7.html) for details).

The `server.listen()` method can be called again if and only if there was an error during the first `server.listen()`
call or `server.close()` has been called. Otherwise, an error will be thrown.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `port?` | `number` |
| `hostname?` | `string` |
| `backlog?` | `number` |
| `listeningListener?` | () => `void` |

###### Returns

`void`

###### Call Signature

> **listen**(`port?`: `number`, `hostname?`: `string`, `listeningListener?`: () => `void`): `void`

Start a server listening for connections. A `net.Server` can be a TCP or
an `IPC` server depending on what it listens to.

Possible signatures:

* `server.listen(options[, callback])`
* `server.listen(path[, backlog][, callback])` for `IPC` servers
* `server.listen([port[, host[, backlog]]][, callback])` for TCP servers

This function is asynchronous. When the server starts listening, the `'listening'` event will be emitted. The last parameter `callback`will be added as a listener for the `'listening'`
event.

All `listen()` methods can take a `backlog` parameter to specify the maximum length of the queue of pending connections.
Currently this parameter is IGNORED, support will be added in the future.

All [Socket](#socket) are set to `SO_REUSEADDR` (see [`socket(7)`](https://man7.org/linux/man-pages/man7/socket.7.html) for details).

The `server.listen()` method can be called again if and only if there was an error during the first `server.listen()`
call or `server.close()` has been called. Otherwise, an error will be thrown.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `port?` | `number` |
| `hostname?` | `string` |
| `listeningListener?` | () => `void` |

###### Returns

`void`

###### Call Signature

> **listen**(`port?`: `number`, `backlog?`: `number`, `listeningListener?`: () => `void`): `void`

Start a server listening for connections. A `net.Server` can be a TCP or
an `IPC` server depending on what it listens to.

Possible signatures:

* `server.listen(options[, callback])`
* `server.listen(path[, backlog][, callback])` for `IPC` servers
* `server.listen([port[, host[, backlog]]][, callback])` for TCP servers

This function is asynchronous. When the server starts listening, the `'listening'` event will be emitted. The last parameter `callback`will be added as a listener for the `'listening'`
event.

All `listen()` methods can take a `backlog` parameter to specify the maximum length of the queue of pending connections.
Currently this parameter is IGNORED, support will be added in the future.

All [Socket](#socket) are set to `SO_REUSEADDR` (see [`socket(7)`](https://man7.org/linux/man-pages/man7/socket.7.html) for details).

The `server.listen()` method can be called again if and only if there was an error during the first `server.listen()`
call or `server.close()` has been called. Otherwise, an error will be thrown.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `port?` | `number` |
| `backlog?` | `number` |
| `listeningListener?` | () => `void` |

###### Returns

`void`

###### Call Signature

> **listen**(`port?`: `number`, `listeningListener?`: () => `void`): `void`

Start a server listening for connections. A `net.Server` can be a TCP or
an `IPC` server depending on what it listens to.

Possible signatures:

* `server.listen(options[, callback])`
* `server.listen(path[, backlog][, callback])` for `IPC` servers
* `server.listen([port[, host[, backlog]]][, callback])` for TCP servers

This function is asynchronous. When the server starts listening, the `'listening'` event will be emitted. The last parameter `callback`will be added as a listener for the `'listening'`
event.

All `listen()` methods can take a `backlog` parameter to specify the maximum length of the queue of pending connections.
Currently this parameter is IGNORED, support will be added in the future.

All [Socket](#socket) are set to `SO_REUSEADDR` (see [`socket(7)`](https://man7.org/linux/man-pages/man7/socket.7.html) for details).

The `server.listen()` method can be called again if and only if there was an error during the first `server.listen()`
call or `server.close()` has been called. Otherwise, an error will be thrown.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `port?` | `number` |
| `listeningListener?` | () => `void` |

###### Returns

`void`

###### Call Signature

> **listen**(`path`: `string`, `backlog?`: `number`, `listeningListener?`: () => `void`): `void`

Start a server listening for connections. A `net.Server` can be a TCP or
an `IPC` server depending on what it listens to.

Possible signatures:

* `server.listen(options[, callback])`
* `server.listen(path[, backlog][, callback])` for `IPC` servers
* `server.listen([port[, host[, backlog]]][, callback])` for TCP servers

This function is asynchronous. When the server starts listening, the `'listening'` event will be emitted. The last parameter `callback`will be added as a listener for the `'listening'`
event.

All `listen()` methods can take a `backlog` parameter to specify the maximum length of the queue of pending connections.
Currently this parameter is IGNORED, support will be added in the future.

All [Socket](#socket) are set to `SO_REUSEADDR` (see [`socket(7)`](https://man7.org/linux/man-pages/man7/socket.7.html) for details).

The `server.listen()` method can be called again if and only if there was an error during the first `server.listen()`
call or `server.close()` has been called. Otherwise, an error will be thrown.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `path` | `string` |
| `backlog?` | `number` |
| `listeningListener?` | () => `void` |

###### Returns

`void`

###### Call Signature

> **listen**(`path`: `string`, `listeningListener?`: () => `void`): `void`

Start a server listening for connections. A `net.Server` can be a TCP or
an `IPC` server depending on what it listens to.

Possible signatures:

* `server.listen(options[, callback])`
* `server.listen(path[, backlog][, callback])` for `IPC` servers
* `server.listen([port[, host[, backlog]]][, callback])` for TCP servers

This function is asynchronous. When the server starts listening, the `'listening'` event will be emitted. The last parameter `callback`will be added as a listener for the `'listening'`
event.

All `listen()` methods can take a `backlog` parameter to specify the maximum length of the queue of pending connections.
Currently this parameter is IGNORED, support will be added in the future.

All [Socket](#socket) are set to `SO_REUSEADDR` (see [`socket(7)`](https://man7.org/linux/man-pages/man7/socket.7.html) for details).

The `server.listen()` method can be called again if and only if there was an error during the first `server.listen()`
call or `server.close()` has been called. Otherwise, an error will be thrown.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `path` | `string` |
| `listeningListener?` | () => `void` |

###### Returns

`void`

###### Call Signature

> **listen**(`options`: [`ListenOptions`](#listenoptions), `listeningListener?`: () => `void`): `void`

Start a server listening for connections. A `net.Server` can be a TCP or
an `IPC` server depending on what it listens to.

Possible signatures:

* `server.listen(options[, callback])`
* `server.listen(path[, backlog][, callback])` for `IPC` servers
* `server.listen([port[, host[, backlog]]][, callback])` for TCP servers

This function is asynchronous. When the server starts listening, the `'listening'` event will be emitted. The last parameter `callback`will be added as a listener for the `'listening'`
event.

All `listen()` methods can take a `backlog` parameter to specify the maximum length of the queue of pending connections.
Currently this parameter is IGNORED, support will be added in the future.

All [Socket](#socket) are set to `SO_REUSEADDR` (see [`socket(7)`](https://man7.org/linux/man-pages/man7/socket.7.html) for details).

The `server.listen()` method can be called again if and only if there was an error during the first `server.listen()`
call or `server.close()` has been called. Otherwise, an error will be thrown.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | [`ListenOptions`](#listenoptions) |
| `listeningListener?` | () => `void` |

###### Returns

`void`

##### off()

> **off**<`K`>(`eventName`: [`EventKey`](dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Alias for `emitter.removeListener()`.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`EventKey`](dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`EventEmitter`](events.md#eventemitter).[`off`](events.md#off)

##### on()

###### Call Signature

> **on**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the end of the listeners array for the event
named `eventName`. No checks are made to see if the `listener` has already
been added. Multiple calls passing the same combination of `eventName` and
`listener` will result in the `listener` being added, and called, multiple times.

```js
server.on('connection', (stream) => {
  console.log('someone connected!');
});
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | `string` | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Overrides

[`EventEmitter`](events.md#eventemitter).[`on`](events.md#on)

###### Call Signature

> **on**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.on`

###### Call Signature

> **on**(`event`: `"connection"`, `listener`: (`socket`: [`Socket`](#socket)) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"connection"` |
| `listener` | (`socket`: [`Socket`](#socket)) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.on`

###### Call Signature

> **on**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.on`

###### Call Signature

> **on**(`event`: `"listening"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"listening"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.on`

##### once()

###### Call Signature

> **once**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time** `listener` function for the event named `eventName`. The
next time `eventName` is triggered, this listener is removed and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependOnceListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | `string` | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Since

v0.3.0

###### Overrides

[`EventEmitter`](events.md#eventemitter).[`once`](events.md#once)

###### Call Signature

> **once**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.once`

###### Call Signature

> **once**(`event`: `"connection"`, `listener`: (`socket`: [`Socket`](#socket)) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"connection"` |
| `listener` | (`socket`: [`Socket`](#socket)) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.once`

###### Call Signature

> **once**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.once`

###### Call Signature

> **once**(`event`: `"listening"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"listening"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.once`

##### prependListener()

###### Call Signature

> **prependListener**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the *beginning* of the listeners array for the
event named `eventName`. No checks are made to see if the `listener` has
already been added. Multiple calls passing the same combination of `eventName`
and `listener` will result in the `listener` being added, and called, multiple times.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | `string` | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Overrides

[`EventEmitter`](events.md#eventemitter).[`prependListener`](events.md#prependlistener)

###### Call Signature

> **prependListener**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.prependListener`

###### Call Signature

> **prependListener**(`event`: `"connection"`, `listener`: (`socket`: [`Socket`](#socket)) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"connection"` |
| `listener` | (`socket`: [`Socket`](#socket)) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.prependListener`

###### Call Signature

> **prependListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.prependListener`

###### Call Signature

> **prependListener**(`event`: `"listening"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"listening"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.prependListener`

##### prependOnceListener()

###### Call Signature

> **prependOnceListener**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time**`listener` function for the event named `eventName` to the *beginning* of the listeners array.
The next time `eventName` is triggered, this listener is removed, and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | `string` | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Overrides

[`EventEmitter`](events.md#eventemitter).[`prependOnceListener`](events.md#prependoncelistener)

###### Call Signature

> **prependOnceListener**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.prependOnceListener`

###### Call Signature

> **prependOnceListener**(`event`: `"connection"`, `listener`: (`socket`: [`Socket`](#socket)) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"connection"` |
| `listener` | (`socket`: [`Socket`](#socket)) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.prependOnceListener`

###### Call Signature

> **prependOnceListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.prependOnceListener`

###### Call Signature

> **prependOnceListener**(`event`: `"listening"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"listening"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Overrides

`EventEmitter.prependOnceListener`

##### removeListener()

> **removeListener**<`K`>(`eventName`: [`EventKey`](dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Removes the specified `listener` from the listener array for the event named `eventName`.

`removeListener()` will remove, at most, one instance of a listener from the
listener array. If any single listener has been added multiple times to the
listener array for the specified `eventName`, then `removeListener()` must be
called multiple times to remove each instance.

Once an event is emitted, all listeners attached to it at the time of emitting are called in order.
This implies that any `removeListener()` calls *after* emitting and *before* the last listener finishes execution
will not remove them from `emit()` in progress. Subsequent events behave as expected.

```js
import { EventEmitter } from 'events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A
```

Because listeners are managed using an internal array, calling this will
change the position indices of any listener registered *after* the listener
being removed. This will not impact the order in which listeners are called,
but it means that any copies of the listener array as returned by
the `emitter.listeners()` method will need to be recreated.

When a single function has been added as a handler multiple times for a single
event (as in the example below), `removeListener()` will remove the most
recently added instance. In the example the `once('ping')` listener is removed:

```js
import { EventEmitter } from 'events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`EventKey`](dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`EventEmitter`](events.md#eventemitter).[`removeListener`](events.md#removelistener)

***

### Socket

This class is an abstraction of a TCP socket or a streaming `IPC` endpoint (only available on Unix with domain sockets).
It is also an `EventEmitter`.

A `net.Socket` can be created by the user and used directly to interact with a server. For example, it is returned by [createConnection](#createconnection),
so the user can use it to talk to the server.

It can also be created by LLRT and passed to the user when a connection is received.
For example, it is passed to the listeners of a `'connection'` event emitted on a [Server](#server), so the user can use it to interact with the client.

#### Extends

* [`DefaultDuplexStream`](stream/stream.md#defaultduplexstream)

#### Constructors

##### Constructor

> **new Socket**(`options?`: [`SocketConstructorOpts`](#socketconstructoropts)): [`Socket`](#socket)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `options?` | [`SocketConstructorOpts`](#socketconstructoropts) |

###### Returns

[`Socket`](#socket)

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`constructor`](stream/stream.md#constructor)

#### Properties

##### connecting

> `readonly` **connecting**: `boolean`

If `true`, `socket.connect(options[, connectListener])` was
called and has not yet finished. It will stay `true` until the socket becomes
connected, then it is set to `false` and the `'connect'` event is emitted. Note
that the `socket.connect(options[, connectListener])` callback is a listener for the `'connect'` event.

##### localAddress?

> `readonly` `optional` **localAddress**: `string`

The string representation of the local IP address the remote client is
connecting on. For example, in a server listening on `'0.0.0.0'`, if a client
connects on `'192.168.1.1'`, the value of `socket.localAddress` would be`'192.168.1.1'`.

##### localFamily?

> `readonly` `optional` **localFamily**: `string`

The string representation of the local IP family. `'IPv4'` or `'IPv6'`.

##### localPort?

> `readonly` `optional` **localPort**: `number`

The numeric representation of the local port. For example, `80` or `21`.

##### pending

> `readonly` **pending**: `boolean`

This is `true` if the socket is not connected yet, either because `.connect()`has not yet been called or because it is still in the process of connecting
(see `socket.connecting`).

##### readyState

> `readonly` **readyState**: [`SocketReadyState`](#socketreadystate-1)

This property represents the state of the connection as a string.

* If the stream is connecting `socket.readyState` is `opening`.
* If the stream is readable and writable, it is `open`.
* If the stream is readable and not writable, it is `readOnly`.
* If the stream is not readable and writable, it is `writeOnly`.

##### remoteAddress?

> `readonly` `optional` **remoteAddress**: `string`

The string representation of the remote IP address. For example,`'74.125.127.100'` or `'2001:4860:a005::68'`. Value may be `undefined` if
the socket is destroyed (for example, if the client disconnected).

##### remoteFamily?

> `readonly` `optional` **remoteFamily**: `string`

The string representation of the remote IP family. `'IPv4'` or `'IPv6'`. Value may be `undefined` if
the socket is destroyed (for example, if the client disconnected).

##### remotePort?

> `readonly` `optional` **remotePort**: `number`

The numeric representation of the remote port. For example, `80` or `21`. Value may be `undefined` if
the socket is destroyed (for example, if the client disconnected).

#### Methods

##### \[dispose]\()

> **\[dispose]**(): `void`

Calls `readable.destroy()`.

###### Returns

`void`

###### Inherited from

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`[dispose]`](stream/stream.md#dispose)

##### addListener()

###### Call Signature

> **addListener**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

events.EventEmitter

1. close
2. connect
3. data
4. end
5. error

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `string` |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`addListener`](stream/stream.md#addlistener)

###### Call Signature

> **addListener**(`event`: `"close"`, `listener`: (`hadError`: `boolean`) => `void`): `this`

events.EventEmitter

1. close
2. connect
3. data
4. end
5. error

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | (`hadError`: `boolean`) => `void` |

###### Returns

`this`

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`addListener`](stream/stream.md#addlistener)

###### Call Signature

> **addListener**(`event`: `"connect"`, `listener`: () => `void`): `this`

events.EventEmitter

1. close
2. connect
3. data
4. end
5. error

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"connect"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`addListener`](stream/stream.md#addlistener)

###### Call Signature

> **addListener**(`event`: `"data"`, `listener`: (`data`: [`Buffer`](buffer.md#buffer)) => `void`): `this`

events.EventEmitter

1. close
2. connect
3. data
4. end
5. error

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"data"` |
| `listener` | (`data`: [`Buffer`](buffer.md#buffer)) => `void` |

###### Returns

`this`

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`addListener`](stream/stream.md#addlistener)

###### Call Signature

> **addListener**(`event`: `"drain"`, `listener`: () => `void`): `this`

events.EventEmitter

1. close
2. connect
3. data
4. end
5. error

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"drain"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Overrides

`Duplex.addListener`

###### Call Signature

> **addListener**(`event`: `"end"`, `listener`: () => `void`): `this`

events.EventEmitter

1. close
2. connect
3. data
4. end
5. error

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"end"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Overrides

`Duplex.addListener`

###### Call Signature

> **addListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

events.EventEmitter

1. close
2. connect
3. data
4. end
5. error

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Overrides

`Duplex.addListener`

##### address()

> **address**(): { } | [`AddressInfo`](#addressinfo)

Returns the bound `address`, the address `family` name and `port` of the
socket as reported by the operating system:`{ port: 12346, family: 'IPv4', address: '127.0.0.1' }`

###### Returns

{ } | [`AddressInfo`](#addressinfo)

###### Since

v0.1.90

##### connect()

###### Call Signature

> **connect**(`options`: [`SocketConnectOpts`](#socketconnectopts), `connectionListener?`: () => `void`): `this`

Initiate a connection on a given socket.

Possible signatures:

* `socket.connect(options[, connectListener])`
* `socket.connect(path[, connectListener])` for `IPC` connections.
* `socket.connect(port[, host][, connectListener])` for TCP connections.
* Returns: `net.Socket` The socket itself.

This function is asynchronous. When the connection is established, the `'connect'` event will be emitted. If there is a problem connecting,
instead of a `'connect'` event, an `'error'` event will be emitted with
the error passed to the `'error'` listener.
The last parameter `connectListener`, if supplied, will be added as a listener
for the `'connect'` event **once**.

This function should only be used for reconnecting a socket after`'close'` has been emitted or otherwise it may lead to undefined
behavior.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | [`SocketConnectOpts`](#socketconnectopts) |
| `connectionListener?` | () => `void` |

###### Returns

`this`

###### Call Signature

> **connect**(`port`: `number`, `host`: `string`, `connectionListener?`: () => `void`): `this`

Initiate a connection on a given socket.

Possible signatures:

* `socket.connect(options[, connectListener])`
* `socket.connect(path[, connectListener])` for `IPC` connections.
* `socket.connect(port[, host][, connectListener])` for TCP connections.
* Returns: `net.Socket` The socket itself.

This function is asynchronous. When the connection is established, the `'connect'` event will be emitted. If there is a problem connecting,
instead of a `'connect'` event, an `'error'` event will be emitted with
the error passed to the `'error'` listener.
The last parameter `connectListener`, if supplied, will be added as a listener
for the `'connect'` event **once**.

This function should only be used for reconnecting a socket after`'close'` has been emitted or otherwise it may lead to undefined
behavior.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `port` | `number` |
| `host` | `string` |
| `connectionListener?` | () => `void` |

###### Returns

`this`

###### Call Signature

> **connect**(`port`: `number`, `connectionListener?`: () => `void`): `this`

Initiate a connection on a given socket.

Possible signatures:

* `socket.connect(options[, connectListener])`
* `socket.connect(path[, connectListener])` for `IPC` connections.
* `socket.connect(port[, host][, connectListener])` for TCP connections.
* Returns: `net.Socket` The socket itself.

This function is asynchronous. When the connection is established, the `'connect'` event will be emitted. If there is a problem connecting,
instead of a `'connect'` event, an `'error'` event will be emitted with
the error passed to the `'error'` listener.
The last parameter `connectListener`, if supplied, will be added as a listener
for the `'connect'` event **once**.

This function should only be used for reconnecting a socket after`'close'` has been emitted or otherwise it may lead to undefined
behavior.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `port` | `number` |
| `connectionListener?` | () => `void` |

###### Returns

`this`

###### Call Signature

> **connect**(`path`: `string`, `connectionListener?`: () => `void`): `this`

Initiate a connection on a given socket.

Possible signatures:

* `socket.connect(options[, connectListener])`
* `socket.connect(path[, connectListener])` for `IPC` connections.
* `socket.connect(port[, host][, connectListener])` for TCP connections.
* Returns: `net.Socket` The socket itself.

This function is asynchronous. When the connection is established, the `'connect'` event will be emitted. If there is a problem connecting,
instead of a `'connect'` event, an `'error'` event will be emitted with
the error passed to the `'error'` listener.
The last parameter `connectListener`, if supplied, will be added as a listener
for the `'connect'` event **once**.

This function should only be used for reconnecting a socket after`'close'` has been emitted or otherwise it may lead to undefined
behavior.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `path` | `string` |
| `connectionListener?` | () => `void` |

###### Returns

`this`

##### destroy()

> **destroy**(`error?`: `Error`): `this`

Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'` event. After this call, the readable
stream will release any internal resources and subsequent calls to `push()` will be ignored.

Once `destroy()` has been called any further calls will be a no-op and no
further errors except from `_destroy()` may be emitted as `'error'`.

Implementors should not override this method, but instead implement `readable._destroy()`.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `error?` | `Error` | Error which will be passed as payload in `'error'` event |

###### Returns

`this`

###### Inherited from

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`destroy`](stream/stream.md#destroy)

##### emit()

###### Call Signature

> **emit**(`event`: `string` | `symbol`, ...`args`: `any`\[]): `boolean`

Synchronously calls each of the listeners registered for the event named `eventName`, in the order they were registered, passing the supplied arguments
to each.

```js
import { EventEmitter } from 'events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `string` | `symbol` |
| ...`args` | `any`\[] |

###### Returns

`boolean`

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`emit`](stream/stream.md#emit)

###### Call Signature

> **emit**(`event`: `"close"`, `hadError`: `boolean`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `hadError` | `boolean` |

###### Returns

`boolean`

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`emit`](stream/stream.md#emit)

###### Call Signature

> **emit**(`event`: `"connect"`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"connect"` |

###### Returns

`boolean`

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`emit`](stream/stream.md#emit)

###### Call Signature

> **emit**(`event`: `"data"`, `data`: [`Buffer`](buffer.md#buffer)): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"data"` |
| `data` | [`Buffer`](buffer.md#buffer) |

###### Returns

`boolean`

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`emit`](stream/stream.md#emit)

###### Call Signature

> **emit**(`event`: `"end"`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"end"` |

###### Returns

`boolean`

###### Overrides

`Duplex.emit`

###### Call Signature

> **emit**(`event`: `"error"`, `err`: `Error`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `err` | `Error` |

###### Returns

`boolean`

###### Overrides

`Duplex.emit`

##### end()

> **end**(`callback?`: () => `void`): `this`

Half-closes the socket. i.e., it sends a FIN packet. It is possible the server will still send some data.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `callback?` | () => `void` | Optional callback for when the socket is finished. |

###### Returns

`this`

The socket itself.

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`end`](stream/stream.md#end)

##### eventNames()

> **eventNames**(): [`EventKey`](dom-events.md#eventkey)\[]

Returns an array listing the events for which the emitter has registered
listeners. The values in the array are strings or `Symbol`s.

```js
import { EventEmitter } from 'events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]
```

###### Returns

[`EventKey`](dom-events.md#eventkey)\[]

###### Inherited from

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`eventNames`](stream/stream.md#eventnames)

##### off()

> **off**<`K`>(`eventName`: [`EventKey`](dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Alias for `emitter.removeListener()`.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`EventKey`](dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`off`](stream/stream.md#off)

##### on()

###### Call Signature

> **on**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the end of the listeners array for the event
named `eventName`. No checks are made to see if the `listener` has already
been added. Multiple calls passing the same combination of `eventName` and
`listener` will result in the `listener` being added, and called, multiple times.

```js
server.on('connection', (stream) => {
  console.log('someone connected!');
});
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | `string` | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`on`](stream/stream.md#on)

###### Call Signature

> **on**(`event`: `"close"`, `listener`: (`hadError`: `boolean`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | (`hadError`: `boolean`) => `void` |

###### Returns

`this`

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`on`](stream/stream.md#on)

###### Call Signature

> **on**(`event`: `"connect"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"connect"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`on`](stream/stream.md#on)

###### Call Signature

> **on**(`event`: `"data"`, `listener`: (`data`: [`Buffer`](buffer.md#buffer)) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"data"` |
| `listener` | (`data`: [`Buffer`](buffer.md#buffer)) => `void` |

###### Returns

`this`

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`on`](stream/stream.md#on)

###### Call Signature

> **on**(`event`: `"end"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"end"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Overrides

`Duplex.on`

###### Call Signature

> **on**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Overrides

`Duplex.on`

##### once()

###### Call Signature

> **once**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time** `listener` function for the event named `eventName`. The
next time `eventName` is triggered, this listener is removed and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependOnceListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | `string` | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Since

v0.3.0

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`once`](stream/stream.md#once)

###### Call Signature

> **once**(`event`: `"close"`, `listener`: (`hadError`: `boolean`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | (`hadError`: `boolean`) => `void` |

###### Returns

`this`

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`once`](stream/stream.md#once)

###### Call Signature

> **once**(`event`: `"connect"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"connect"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`once`](stream/stream.md#once)

###### Call Signature

> **once**(`event`: `"data"`, `listener`: (`data`: [`Buffer`](buffer.md#buffer)) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"data"` |
| `listener` | (`data`: [`Buffer`](buffer.md#buffer)) => `void` |

###### Returns

`this`

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`once`](stream/stream.md#once)

###### Call Signature

> **once**(`event`: `"end"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"end"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Overrides

`Duplex.once`

###### Call Signature

> **once**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Overrides

`Duplex.once`

##### prependListener()

###### Call Signature

> **prependListener**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the *beginning* of the listeners array for the
event named `eventName`. No checks are made to see if the `listener` has
already been added. Multiple calls passing the same combination of `eventName`
and `listener` will result in the `listener` being added, and called, multiple times.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | `string` | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`prependListener`](stream/stream.md#prependlistener)

###### Call Signature

> **prependListener**(`event`: `"close"`, `listener`: (`hadError`: `boolean`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | (`hadError`: `boolean`) => `void` |

###### Returns

`this`

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`prependListener`](stream/stream.md#prependlistener)

###### Call Signature

> **prependListener**(`event`: `"connect"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"connect"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`prependListener`](stream/stream.md#prependlistener)

###### Call Signature

> **prependListener**(`event`: `"data"`, `listener`: (`data`: [`Buffer`](buffer.md#buffer)) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"data"` |
| `listener` | (`data`: [`Buffer`](buffer.md#buffer)) => `void` |

###### Returns

`this`

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`prependListener`](stream/stream.md#prependlistener)

###### Call Signature

> **prependListener**(`event`: `"end"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"end"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Overrides

`Duplex.prependListener`

###### Call Signature

> **prependListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Overrides

`Duplex.prependListener`

##### prependOnceListener()

###### Call Signature

> **prependOnceListener**(`event`: `string`, `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time**`listener` function for the event named `eventName` to the *beginning* of the listeners array.
The next time `eventName` is triggered, this listener is removed, and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | `string` | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`prependOnceListener`](stream/stream.md#prependoncelistener)

###### Call Signature

> **prependOnceListener**(`event`: `"close"`, `listener`: (`hadError`: `boolean`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | (`hadError`: `boolean`) => `void` |

###### Returns

`this`

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`prependOnceListener`](stream/stream.md#prependoncelistener)

###### Call Signature

> **prependOnceListener**(`event`: `"connect"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"connect"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`prependOnceListener`](stream/stream.md#prependoncelistener)

###### Call Signature

> **prependOnceListener**(`event`: `"data"`, `listener`: (`data`: [`Buffer`](buffer.md#buffer)) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"data"` |
| `listener` | (`data`: [`Buffer`](buffer.md#buffer)) => `void` |

###### Returns

`this`

###### Overrides

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`prependOnceListener`](stream/stream.md#prependoncelistener)

###### Call Signature

> **prependOnceListener**(`event`: `"end"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"end"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Overrides

`Duplex.prependOnceListener`

###### Call Signature

> **prependOnceListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Overrides

`Duplex.prependOnceListener`

##### read()

> **read**(`size?`: `number`): [`Buffer`](buffer.md#buffer) | `null`

The `readable.read()` method reads data out of the internal buffer and
returns it. If no data is available to be read, `null` is returned. By default,
the data is returned as a `Buffer` object unless an encoding has been
specified using the `readable.setEncoding()` method or the stream is operating
in object mode.

The optional `size` argument specifies a specific number of bytes to read. If
`size` bytes are not available to be read, `null` will be returned *unless* the
stream has ended, in which case all of the data remaining in the internal buffer
will be returned.

If the `size` argument is not specified, all of the data contained in the
internal buffer will be returned.

The `size` argument must be less than or equal to 1 GiB.

The `readable.read()` method should only be called on `Readable` streams
operating in paused mode. In flowing mode, `readable.read()` is called
automatically until the internal buffer is fully drained.

```js
const readable = getReadableStreamSomehow();

// 'readable' may be triggered multiple times as data is buffered in
readable.on('readable', () => {
  let chunk;
  console.log('Stream is readable (new data received in buffer)');
  // Use a loop to make sure we read all currently available data
  while (null !== (chunk = readable.read())) {
    console.log(`Read ${chunk.length} bytes of data...`);
  }
});

// 'end' will be triggered once when there is no more data available
readable.on('end', () => {
  console.log('Reached end of stream.');
});
```

Each call to `readable.read()` returns a chunk of data, or `null`. The chunks
are not concatenated. A `while` loop is necessary to consume all data
currently in the buffer. When reading a large file `.read()` may return `null`,
having consumed all buffered content so far, but there is still more data to
come not yet buffered. In this case a new `'readable'` event will be emitted
when there is more data in the buffer. Finally the `'end'` event will be
emitted when there is no more data to come.

Therefore to read a file's whole contents from a `readable`, it is necessary
to collect chunks across multiple `'readable'` events:

```js
const chunks = [];

readable.on('readable', () => {
  let chunk;
  while (null !== (chunk = readable.read())) {
    chunks.push(chunk);
  }
});

readable.on('end', () => {
  const content = chunks.join('');
});
```

A `Readable` stream in object mode will always return a single item from
a call to `readable.read(size)`, regardless of the value of the `size` argument.

If the `readable.read()` method returns a chunk of data, a `'data'` event will
also be emitted.

Calling [read](stream/stream.md#read-4) after the `'end'` event has
been emitted will return `null`. No runtime error will be raised.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `size?` | `number` | Optional argument to specify how much data to read. |

###### Returns

[`Buffer`](buffer.md#buffer) | `null`

###### Inherited from

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`read`](stream/stream.md#read)

##### removeListener()

###### Call Signature

> **removeListener**(`event`: [`EventKey`](dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Removes the specified `listener` from the listener array for the event named `eventName`.

`removeListener()` will remove, at most, one instance of a listener from the
listener array. If any single listener has been added multiple times to the
listener array for the specified `eventName`, then `removeListener()` must be
called multiple times to remove each instance.

Once an event is emitted, all listeners attached to it at the time of emitting are called in order.
This implies that any `removeListener()` calls *after* emitting and *before* the last listener finishes execution
will not remove them from `emit()` in progress. Subsequent events behave as expected.

```js
import { EventEmitter } from 'events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A
```

Because listeners are managed using an internal array, calling this will
change the position indices of any listener registered *after* the listener
being removed. This will not impact the order in which listeners are called,
but it means that any copies of the listener array as returned by
the `emitter.listeners()` method will need to be recreated.

When a single function has been added as a handler multiple times for a single
event (as in the example below), `removeListener()` will remove the most
recently added instance. In the example the `once('ping')` listener is removed:

```js
import { EventEmitter } from 'events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | [`EventKey`](dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`removeListener`](stream/stream.md#removelistener)

###### Call Signature

> **removeListener**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`removeListener`](stream/stream.md#removelistener)

###### Call Signature

> **removeListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Inherited from

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`removeListener`](stream/stream.md#removelistener)

###### Call Signature

> **removeListener**(`event`: `"finish"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"finish"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`removeListener`](stream/stream.md#removelistener)

##### write()

> **write**(`chunk`: `string` | [`ArrayBufferView`](globals/namespaces/QuickJS.md#arraybufferview) | [`Buffer`](buffer.md#buffer) | `ArrayBuffer` | `SharedArrayBuffer`, `callback?`: (`error?`: `Error` | `null`) => `void`): `void`

The `writable.write()` method writes some data to the stream, and calls the
supplied `callback` once the data has been fully handled. If an error
occurs, the `callback` will be called with the error as its
first argument. The `callback` is usually called asynchronously and before `'error'`
is emitted.

```js
function write(data, cb) {
  if (!stream.write(data)) {
    stream.once('drain', cb);
  } else {
    process.nextTick(cb);
  }
}

// Wait for cb to be called before doing any other write.
write('hello', () => {
  console.log('Write completed, do more writes now.');
});
```

A `Writable` stream in object mode will always ignore the `encoding` argument.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `chunk` | `string` | [`ArrayBufferView`](globals/namespaces/QuickJS.md#arraybufferview) | [`Buffer`](buffer.md#buffer) | `ArrayBuffer` | `SharedArrayBuffer` | Optional data to write. `chunk` must be a {string}, {Buffer}, {TypedArray} or {DataView}. |
| `callback?` | (`error?`: `Error` | `null`) => `void` | Callback for when this chunk of data is flushed. |

###### Returns

`void`

`false` if the stream wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`.

###### Since

v0.9.4

###### Inherited from

[`DefaultDuplexStream`](stream/stream.md#defaultduplexstream).[`write`](stream/stream.md#write)

## Interfaces

### AddressInfo

#### Properties

##### address

> **address**: `string`

##### family

> **family**: `string`

##### port

> **port**: `number`

***

### IpcSocketConnectOpts

#### Properties

##### path

> **path**: `string`

***

### ListenOptions

#### Properties

##### backlog?

> `optional` **backlog**: `number`

##### host?

> `optional` **host**: `string`

##### path?

> `optional` **path**: `string`

##### port?

> `optional` **port**: `number`

***

### ServerOpts

#### Properties

##### allowHalfOpen?

> `optional` **allowHalfOpen**: `boolean`

Indicates whether half-opened TCP connections are allowed.

###### Default

```ts
false
```

***

### SocketConstructorOpts

#### Properties

##### allowHalfOpen?

> `optional` **allowHalfOpen**: `boolean`

***

### TcpSocketConnectOpts

#### Properties

##### host?

> `optional` **host**: `string`

##### port

> **port**: `number`

## Type Aliases

### NetConnectOpts

> **NetConnectOpts** = [`TcpSocketConnectOpts`](#tcpsocketconnectopts) | [`IpcSocketConnectOpts`](#ipcsocketconnectopts)

***

### SocketConnectOpts

> **SocketConnectOpts** = [`TcpSocketConnectOpts`](#tcpsocketconnectopts) | [`IpcSocketConnectOpts`](#ipcsocketconnectopts)

***

### SocketReadyState

> **SocketReadyState** = `"opening"` | `"open"` | `"readOnly"` | `"writeOnly"` | `"closed"`

## Functions

### connect()

#### Call Signature

> **connect**(`options`: [`NetConnectOpts`](#netconnectopts), `connectionListener?`: () => `void`): [`Socket`](#socket)

Aliases to [createConnection](#createconnection).

Possible signatures:

* [connect](#connect-5)
* [connect](#connect-5) for `IPC` connections.
* [connect](#connect-5) for TCP connections.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | [`NetConnectOpts`](#netconnectopts) |
| `connectionListener?` | () => `void` |

##### Returns

[`Socket`](#socket)

#### Call Signature

> **connect**(`port`: `number`, `host`: `string`, `connectionListener?`: () => `void`): [`Socket`](#socket)

Aliases to [createConnection](#createconnection).

Possible signatures:

* [connect](#connect-5)
* [connect](#connect-5) for `IPC` connections.
* [connect](#connect-5) for TCP connections.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `port` | `number` |
| `host` | `string` |
| `connectionListener?` | () => `void` |

##### Returns

[`Socket`](#socket)

#### Call Signature

> **connect**(`port`: `number`, `connectionListener?`: () => `void`): [`Socket`](#socket)

Aliases to [createConnection](#createconnection).

Possible signatures:

* [connect](#connect-5)
* [connect](#connect-5) for `IPC` connections.
* [connect](#connect-5) for TCP connections.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `port` | `number` |
| `connectionListener?` | () => `void` |

##### Returns

[`Socket`](#socket)

#### Call Signature

> **connect**(`path`: `string`, `connectionListener?`: () => `void`): [`Socket`](#socket)

Aliases to [createConnection](#createconnection).

Possible signatures:

* [connect](#connect-5)
* [connect](#connect-5) for `IPC` connections.
* [connect](#connect-5) for TCP connections.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `path` | `string` |
| `connectionListener?` | () => `void` |

##### Returns

[`Socket`](#socket)

***

### createConnection()

#### Call Signature

> **createConnection**(`options`: [`NetConnectOpts`](#netconnectopts), `connectionListener?`: () => `void`): [`Socket`](#socket)

A factory function, which creates a new [Socket](#socket),
immediately initiates connection with `socket.connect()`,
then returns the `net.Socket` that starts the connection.

When the connection is established, a `'connect'` event will be emitted
on the returned socket. The last parameter `connectListener`, if supplied,
will be added as a listener for the `'connect'` event **once**.

Possible signatures:

* [createConnection](#createconnection)
* [createConnection](#createconnection) for `IPC` connections.
* [createConnection](#createconnection) for TCP connections.

The [connect](#connect-5) function is an alias to this function.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | [`NetConnectOpts`](#netconnectopts) |
| `connectionListener?` | () => `void` |

##### Returns

[`Socket`](#socket)

#### Call Signature

> **createConnection**(`port`: `number`, `host`: `string`, `connectionListener?`: () => `void`): [`Socket`](#socket)

A factory function, which creates a new [Socket](#socket),
immediately initiates connection with `socket.connect()`,
then returns the `net.Socket` that starts the connection.

When the connection is established, a `'connect'` event will be emitted
on the returned socket. The last parameter `connectListener`, if supplied,
will be added as a listener for the `'connect'` event **once**.

Possible signatures:

* [createConnection](#createconnection)
* [createConnection](#createconnection) for `IPC` connections.
* [createConnection](#createconnection) for TCP connections.

The [connect](#connect-5) function is an alias to this function.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `port` | `number` |
| `host` | `string` |
| `connectionListener?` | () => `void` |

##### Returns

[`Socket`](#socket)

#### Call Signature

> **createConnection**(`port`: `number`, `connectionListener?`: () => `void`): [`Socket`](#socket)

A factory function, which creates a new [Socket](#socket),
immediately initiates connection with `socket.connect()`,
then returns the `net.Socket` that starts the connection.

When the connection is established, a `'connect'` event will be emitted
on the returned socket. The last parameter `connectListener`, if supplied,
will be added as a listener for the `'connect'` event **once**.

Possible signatures:

* [createConnection](#createconnection)
* [createConnection](#createconnection) for `IPC` connections.
* [createConnection](#createconnection) for TCP connections.

The [connect](#connect-5) function is an alias to this function.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `port` | `number` |
| `connectionListener?` | () => `void` |

##### Returns

[`Socket`](#socket)

#### Call Signature

> **createConnection**(`path`: `string`, `connectionListener?`: () => `void`): [`Socket`](#socket)

A factory function, which creates a new [Socket](#socket),
immediately initiates connection with `socket.connect()`,
then returns the `net.Socket` that starts the connection.

When the connection is established, a `'connect'` event will be emitted
on the returned socket. The last parameter `connectListener`, if supplied,
will be added as a listener for the `'connect'` event **once**.

Possible signatures:

* [createConnection](#createconnection)
* [createConnection](#createconnection) for `IPC` connections.
* [createConnection](#createconnection) for TCP connections.

The [connect](#connect-5) function is an alias to this function.

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `path` | `string` |
| `connectionListener?` | () => `void` |

##### Returns

[`Socket`](#socket)

***

### createServer()

#### Call Signature

> **createServer**(`connectionListener?`: (`socket`: [`Socket`](#socket)) => `void`): [`Server`](#server)

Creates a new TCP or `IPC` server.

If `allowHalfOpen` is set to `true`, when the other end of the socket
signals the end of transmission, the server will only send back the end of
transmission when `socket.end()` is explicitly called. For example, in the
context of TCP, when a FIN packed is received, a FIN packed is sent
back only when `socket.end()` is explicitly called. Until then the
connection is half-closed (non-readable but still writable). See `'end'` event and [RFC 1122](https://tools.ietf.org/html/rfc1122) (section 4.2.2.13) for more information.

If `pauseOnConnect` is set to `true`, then the socket associated with each
incoming connection will be paused, and no data will be read from its handle.
This allows connections to be passed between processes without any data being
read by the original process. To begin reading data from a paused socket, call `socket.resume()`.

The server can be a TCP server or an `IPC` server, depending on what it `listen()` to.

Here is an example of a TCP echo server which listens for connections
on port 8124:

```js
import * as net from 'net';
const server = net.createServer((c) => {
  // 'connection' listener.
  console.log('client connected');
  c.on('end', () => {
    console.log('client disconnected');
  });
  c.write('hello\r\n');

});
server.on('error', (err) => {
  throw err;
});
server.listen(8124, () => {
  console.log('server bound');
});
```

Test this by using `telnet`:

```bash
telnet localhost 8124
```

To listen on the socket `/tmp/echo.sock`:

```js
server.listen('/tmp/echo.sock', () => {
  console.log('server bound');
});
```

Use `nc` to connect to a Unix domain socket server:

```bash
nc -U /tmp/echo.sock
```

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `connectionListener?` | (`socket`: [`Socket`](#socket)) => `void` | Automatically set as a listener for the 'connection' event. |

##### Returns

[`Server`](#server)

#### Call Signature

> **createServer**(`options?`: [`ServerOpts`](#serveropts), `connectionListener?`: (`socket`: [`Socket`](#socket)) => `void`): [`Server`](#server)

Creates a new TCP or `IPC` server.

If `allowHalfOpen` is set to `true`, when the other end of the socket
signals the end of transmission, the server will only send back the end of
transmission when `socket.end()` is explicitly called. For example, in the
context of TCP, when a FIN packed is received, a FIN packed is sent
back only when `socket.end()` is explicitly called. Until then the
connection is half-closed (non-readable but still writable). See `'end'` event and [RFC 1122](https://tools.ietf.org/html/rfc1122) (section 4.2.2.13) for more information.

If `pauseOnConnect` is set to `true`, then the socket associated with each
incoming connection will be paused, and no data will be read from its handle.
This allows connections to be passed between processes without any data being
read by the original process. To begin reading data from a paused socket, call `socket.resume()`.

The server can be a TCP server or an `IPC` server, depending on what it `listen()` to.

Here is an example of a TCP echo server which listens for connections
on port 8124:

```js
import * as net from 'net';
const server = net.createServer((c) => {
  // 'connection' listener.
  console.log('client connected');
  c.on('end', () => {
    console.log('client disconnected');
  });
  c.write('hello\r\n');

});
server.on('error', (err) => {
  throw err;
});
server.listen(8124, () => {
  console.log('server bound');
});
```

Test this by using `telnet`:

```bash
telnet localhost 8124
```

To listen on the socket `/tmp/echo.sock`:

```js
server.listen('/tmp/echo.sock', () => {
  console.log('server bound');
});
```

Use `nc` to connect to a Unix domain socket server:

```bash
nc -U /tmp/echo.sock
```

##### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options?` | [`ServerOpts`](#serveropts) | - |
| `connectionListener?` | (`socket`: [`Socket`](#socket)) => `void` | Automatically set as a listener for the 'connection' event. |

##### Returns

[`Server`](#server)

---

---
url: /plugins/reference/modules/llrt/path.md
---
[@caido/quickjs-types](../../index.md) / llrt/path

# llrt/path

## Namespaces

| Namespace | Description |
| ------ | ------ |
| [export=](namespaces/export=.md) | - |

## Interfaces

### FormatInputPathObject

#### Properties

##### base?

> `optional` **base**: `string`

The file name including extension (if any) such as 'index.html'

##### dir?

> `optional` **dir**: `string`

The full directory path such as '/home/user/dir' or 'c:\path\dir'

##### ext?

> `optional` **ext**: `string`

The file extension (if any) such as '.html'

##### name?

> `optional` **name**: `string`

The file name without extension (if any) such as 'index'

##### root?

> `optional` **root**: `string`

The root of the path such as '/' or 'c:'

***

### ParsedPath

A parsed path object generated by path.parse() or consumed by path.format().

#### Properties

##### base

> **base**: `string`

The file name including extension (if any) such as 'index.html'

##### dir

> **dir**: `string`

The full directory path such as '/home/user/dir' or 'c:\path\dir'

##### ext

> **ext**: `string`

The file extension (if any) such as '.html'

##### name

> **name**: `string`

The file name without extension (if any) such as 'index'

##### root

> **root**: `string`

The root of the path such as '/' or 'c:'

***

### PlatformPath

#### Properties

##### delimiter

> `readonly` **delimiter**: `";"` | `":"`

The platform-specific file delimiter. ';' or ':'.

##### sep

> `readonly` **sep**: "\\" | `"/"`

The platform-specific file separator. '\\' or '/'.

#### Methods

##### basename()

> **basename**(`path`: `string`, `suffix?`: `string`): `string`

Return the last portion of a path. Similar to the Unix basename command.
Often used to extract the file name from a fully qualified path.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `path` | `string` | the path to evaluate. |
| `suffix?` | `string` | optionally, an extension to remove from the result. |

###### Returns

`string`

##### dirname()

> **dirname**(`path`: `string`): `string`

Return the directory name of a path. Similar to the Unix dirname command.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `path` | `string` | the path to evaluate. |

###### Returns

`string`

##### extname()

> **extname**(`path`: `string`): `string`

Return the extension of the path, from the last '.' to end of string in the last portion of the path.
If there is no '.' in the last portion of the path or the first character of it is '.', then it returns an empty string.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `path` | `string` | the path to evaluate. |

###### Returns

`string`

##### format()

> **format**(`pathObject`: [`FormatInputPathObject`](#formatinputpathobject)): `string`

Returns a path string from an object - the opposite of parse().

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `pathObject` | [`FormatInputPathObject`](#formatinputpathobject) | path to evaluate. |

###### Returns

`string`

##### isAbsolute()

> **isAbsolute**(`path`: `string`): `boolean`

Determines whether {path} is an absolute path. An absolute path will always resolve to the same location, regardless of the working directory.

If the given {path} is a zero-length string, `false` will be returned.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `path` | `string` | path to test. |

###### Returns

`boolean`

##### join()

> **join**(...`paths`: `string`\[]): `string`

Join all arguments together and normalize the resulting path.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| ...`paths` | `string`\[] | paths to join. |

###### Returns

`string`

###### Throws

if any of the path segments is not a string.

##### normalize()

> **normalize**(`path`: `string`): `string`

Normalize a string path, reducing '..' and '.' parts.
When multiple slashes are found, they're replaced by a single one; when the path contains a trailing slash, it is preserved. On Windows backslashes are used.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `path` | `string` | string path to normalize. |

###### Returns

`string`

###### Throws

if `path` is not a string.

##### parse()

> **parse**(`path`: `string`): [`ParsedPath`](#parsedpath)

Returns an object from a path string - the opposite of format().

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `path` | `string` | path to evaluate. |

###### Returns

[`ParsedPath`](#parsedpath)

###### Throws

if `path` is not a string.

##### resolve()

> **resolve**(...`paths`: `string`\[]): `string`

The right-most parameter is considered {to}. Other parameters are considered an array of {from}.

Starting from leftmost {from} parameter, resolves {to} to an absolute path.

If {to} isn't already absolute, {from} arguments are prepended in right to left order,
until an absolute path is found. If after using all {from} paths still no absolute path is found,
the current working directory is used as well. The resulting path is normalized,
and trailing slashes are removed unless the path gets resolved to the root directory.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| ...`paths` | `string`\[] | A sequence of paths or path segments. |

###### Returns

`string`

###### Throws

if any of the arguments is not a string.

## Variables

### export=

> **export=**: [`PlatformPath`](#platformpath)

---

---
url: /plugins/reference/modules/llrt/process.md
---
[@caido/quickjs-types](../../index.md) / llrt/process

# llrt/process

## Modules

| Module | Description |
| ------ | ------ |
| [process](process.md) | - |

## References

### QuickJS

Re-exports [QuickJS](../globals/namespaces/QuickJS.md)

---

---
url: /plugins/reference/modules/llrt/stream.md
---
[@caido/quickjs-types](../../index.md) / llrt/stream

# llrt/stream

## Modules

| Module | Description |
| ------ | ------ |
| [stream](stream.md) | - |

## References

### QuickJS

Re-exports [QuickJS](../globals/namespaces/QuickJS.md)

---

---
url: /plugins/reference/modules/llrt/stream/web.md
---
[@caido/quickjs-types](../../../index.md) / llrt/stream/web

# llrt/stream/web

## Modules

| Module | Description |
| ------ | ------ |
| [stream/web](stream/web.md) | - |

## Interfaces

### ByteLengthQueuingStrategy

#### Extends

* [`_ByteLengthQueuingStrategy`](#_bytelengthqueuingstrategy)

#### Properties

##### highWaterMark

> `readonly` **highWaterMark**: `number`

###### Inherited from

`_ByteLengthQueuingStrategy.highWaterMark`

##### size

> `readonly` **size**: [`QueuingStrategySize`](stream/web.md#queuingstrategysize-1)<`ArrayBufferView`>

###### Inherited from

`_ByteLengthQueuingStrategy.size`

***

### CountQueuingStrategy

#### Extends

* [`_CountQueuingStrategy`](#_countqueuingstrategy)

#### Properties

##### highWaterMark

> `readonly` **highWaterMark**: `number`

###### Inherited from

`_CountQueuingStrategy.highWaterMark`

##### size

> `readonly` **size**: [`QueuingStrategySize`](stream/web.md#queuingstrategysize-1)

###### Inherited from

`_CountQueuingStrategy.size`

***

### ReadableByteStreamController

#### Extends

* [`_ReadableByteStreamController`](#_readablebytestreamcontroller)

#### Properties

##### byobRequest

> `readonly` **byobRequest**: `undefined`

###### Inherited from

`_ReadableByteStreamController.byobRequest`

##### desiredSize

> `readonly` **desiredSize**: `number` | `null`

###### Inherited from

`_ReadableByteStreamController.desiredSize`

#### Methods

##### close()

> **close**(): `void`

###### Returns

`void`

###### Inherited from

`_ReadableByteStreamController.close`

##### enqueue()

> **enqueue**(`chunk`: `ArrayBufferView`): `void`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `chunk` | `ArrayBufferView` |

###### Returns

`void`

###### Inherited from

`_ReadableByteStreamController.enqueue`

##### error()

> **error**(`error?`: `any`): `void`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `error?` | `any` |

###### Returns

`void`

###### Inherited from

`_ReadableByteStreamController.error`

***

### ReadableStream

#### Extends

* [`_ReadableStream`](#_readablestream)<`R`>

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `R` | `any` |

#### Properties

##### locked

> `readonly` **locked**: `boolean`

###### Inherited from

`_ReadableStream.locked`

#### Methods

##### \[asyncIterator]\()

> **\[asyncIterator]**(): [`ReadableStreamAsyncIterator`](stream/web.md#readablestreamasynciterator-2)<`R`>

###### Returns

[`ReadableStreamAsyncIterator`](stream/web.md#readablestreamasynciterator-2)<`R`>

###### Inherited from

`_ReadableStream.[asyncIterator]`

##### cancel()

> **cancel**(`reason?`: `any`): `Promise`<`void`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `reason?` | `any` |

###### Returns

`Promise`<`void`>

###### Inherited from

`_ReadableStream.cancel`

##### getReader()

###### Call Signature

> **getReader**(`options`: `object`): [`ReadableStreamBYOBReader`](stream/web.md#readablestreambyobreader)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | { `mode`: `"byob"`; } |
| `options.mode` | `"byob"` |

###### Returns

[`ReadableStreamBYOBReader`](stream/web.md#readablestreambyobreader)

###### Inherited from

`_ReadableStream.getReader`

###### Call Signature

> **getReader**(): [`ReadableStreamDefaultReader`](stream/web.md#readablestreamdefaultreader)<`R`>

###### Returns

[`ReadableStreamDefaultReader`](stream/web.md#readablestreamdefaultreader)<`R`>

###### Inherited from

`_ReadableStream.getReader`

###### Call Signature

> **getReader**(`options?`: [`ReadableStreamGetReaderOptions`](stream/web.md#readablestreamgetreaderoptions)): [`ReadableStreamReader`](stream/web.md#readablestreamreader)<`R`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `options?` | [`ReadableStreamGetReaderOptions`](stream/web.md#readablestreamgetreaderoptions) |

###### Returns

[`ReadableStreamReader`](stream/web.md#readablestreamreader)<`R`>

###### Inherited from

`_ReadableStream.getReader`

##### pipeThrough()

> **pipeThrough**<`T`>(`transform`: [`ReadableWritablePair`](stream/web.md#readablewritablepair)<`T`, `R`>, `options?`: [`StreamPipeOptions`](stream/web.md#streampipeoptions)): [`ReadableStream`](stream/web.md#readablestream)<`T`>

###### Type Parameters

| Type Parameter |
| ------ |
| `T` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `transform` | [`ReadableWritablePair`](stream/web.md#readablewritablepair)<`T`, `R`> |
| `options?` | [`StreamPipeOptions`](stream/web.md#streampipeoptions) |

###### Returns

[`ReadableStream`](stream/web.md#readablestream)<`T`>

###### Inherited from

`_ReadableStream.pipeThrough`

##### pipeTo()

> **pipeTo**(`destination`: [`WritableStream`](stream/web.md#writablestream)<`R`>, `options?`: [`StreamPipeOptions`](stream/web.md#streampipeoptions)): `Promise`<`void`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `destination` | [`WritableStream`](stream/web.md#writablestream)<`R`> |
| `options?` | [`StreamPipeOptions`](stream/web.md#streampipeoptions) |

###### Returns

`Promise`<`void`>

###### Inherited from

`_ReadableStream.pipeTo`

##### tee()

> **tee**(): \[[`ReadableStream`](stream/web.md#readablestream)<`R`>, [`ReadableStream`](stream/web.md#readablestream)<`R`>]

###### Returns

\[[`ReadableStream`](stream/web.md#readablestream)<`R`>, [`ReadableStream`](stream/web.md#readablestream)<`R`>]

###### Inherited from

`_ReadableStream.tee`

##### values()

> **values**(`options?`: `object`): [`ReadableStreamAsyncIterator`](stream/web.md#readablestreamasynciterator-2)<`R`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `options?` | { `preventCancel?`: `boolean`; } |
| `options.preventCancel?` | `boolean` |

###### Returns

[`ReadableStreamAsyncIterator`](stream/web.md#readablestreamasynciterator-2)<`R`>

###### Inherited from

`_ReadableStream.values`

***

### ReadableStreamBYOBReader

#### Extends

* [`_ReadableStreamBYOBReader`](#_readablestreambyobreader)

#### Properties

##### closed

> `readonly` **closed**: `Promise`<`undefined`>

###### Inherited from

`_ReadableStreamBYOBReader.closed`

#### Methods

##### cancel()

> **cancel**(`reason?`: `any`): `Promise`<`void`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `reason?` | `any` |

###### Returns

`Promise`<`void`>

###### Inherited from

`_ReadableStreamBYOBReader.cancel`

##### read()

> **read**<`T`>(`view`: `T`): `Promise`<[`ReadableStreamReadResult`](stream/web.md#readablestreamreadresult)<`T`>>

[MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBReader/read)

###### Type Parameters

| Type Parameter |
| ------ |
| `T` *extends* `ArrayBufferView` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `view` | `T` |

###### Returns

`Promise`<[`ReadableStreamReadResult`](stream/web.md#readablestreamreadresult)<`T`>>

###### Inherited from

`_ReadableStreamBYOBReader.read`

##### releaseLock()

> **releaseLock**(): `void`

[MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBReader/releaseLock)

###### Returns

`void`

###### Inherited from

`_ReadableStreamBYOBReader.releaseLock`

***

### ReadableStreamBYOBRequest

#### Extends

* [`_ReadableStreamBYOBRequest`](#_readablestreambyobrequest)

#### Properties

##### view

> `readonly` **view**: `ArrayBufferView` | `null`

[MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBRequest/view)

###### Inherited from

`_ReadableStreamBYOBRequest.view`

#### Methods

##### respond()

> **respond**(`bytesWritten`: `number`): `void`

[MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBRequest/respond)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `bytesWritten` | `number` |

###### Returns

`void`

###### Inherited from

`_ReadableStreamBYOBRequest.respond`

##### respondWithNewView()

> **respondWithNewView**(`view`: `ArrayBufferView`): `void`

[MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBRequest/respondWithNewView)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `view` | `ArrayBufferView` |

###### Returns

`void`

###### Inherited from

`_ReadableStreamBYOBRequest.respondWithNewView`

***

### ReadableStreamDefaultController

#### Extends

* [`_ReadableStreamDefaultController`](#_readablestreamdefaultcontroller)<`R`>

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `R` | `any` |

#### Properties

##### desiredSize

> `readonly` **desiredSize**: `number` | `null`

###### Inherited from

`_ReadableStreamDefaultController.desiredSize`

#### Methods

##### close()

> **close**(): `void`

###### Returns

`void`

###### Inherited from

`_ReadableStreamDefaultController.close`

##### enqueue()

> **enqueue**(`chunk?`: `R`): `void`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `chunk?` | `R` |

###### Returns

`void`

###### Inherited from

`_ReadableStreamDefaultController.enqueue`

##### error()

> **error**(`e?`: `any`): `void`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `e?` | `any` |

###### Returns

`void`

###### Inherited from

`_ReadableStreamDefaultController.error`

***

### ReadableStreamDefaultReader

#### Extends

* [`_ReadableStreamDefaultReader`](#_readablestreamdefaultreader)<`R`>

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `R` | `any` |

#### Properties

##### closed

> `readonly` **closed**: `Promise`<`undefined`>

###### Inherited from

`_ReadableStreamDefaultReader.closed`

#### Methods

##### cancel()

> **cancel**(`reason?`: `any`): `Promise`<`void`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `reason?` | `any` |

###### Returns

`Promise`<`void`>

###### Inherited from

`_ReadableStreamDefaultReader.cancel`

##### read()

> **read**(): `Promise`<[`ReadableStreamReadResult`](stream/web.md#readablestreamreadresult)<`R`>>

###### Returns

`Promise`<[`ReadableStreamReadResult`](stream/web.md#readablestreamreadresult)<`R`>>

###### Inherited from

`_ReadableStreamDefaultReader.read`

##### releaseLock()

> **releaseLock**(): `void`

###### Returns

`void`

###### Inherited from

`_ReadableStreamDefaultReader.releaseLock`

***

### WritableStream

#### Extends

* [`_WritableStream`](#_writablestream)<`W`>

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `W` | `any` |

#### Properties

##### locked

> `readonly` **locked**: `boolean`

###### Inherited from

`_WritableStream.locked`

#### Methods

##### abort()

> **abort**(`reason?`: `any`): `Promise`<`void`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `reason?` | `any` |

###### Returns

`Promise`<`void`>

###### Inherited from

`_WritableStream.abort`

##### close()

> **close**(): `Promise`<`void`>

###### Returns

`Promise`<`void`>

###### Inherited from

`_WritableStream.close`

##### getWriter()

> **getWriter**(): [`WritableStreamDefaultWriter`](stream/web.md#writablestreamdefaultwriter)<`W`>

###### Returns

[`WritableStreamDefaultWriter`](stream/web.md#writablestreamdefaultwriter)<`W`>

###### Inherited from

`_WritableStream.getWriter`

***

### WritableStreamDefaultController

#### Extends

* [`_WritableStreamDefaultController`](#_writablestreamdefaultcontroller)

#### Methods

##### error()

> **error**(`e?`: `any`): `void`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `e?` | `any` |

###### Returns

`void`

###### Inherited from

`_WritableStreamDefaultController.error`

***

### WritableStreamDefaultWriter

#### Extends

* [`_WritableStreamDefaultWriter`](#_writablestreamdefaultwriter)<`W`>

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `W` | `any` |

#### Properties

##### closed

> `readonly` **closed**: `Promise`<`undefined`>

###### Inherited from

`_WritableStreamDefaultWriter.closed`

##### desiredSize

> `readonly` **desiredSize**: `number` | `null`

###### Inherited from

`_WritableStreamDefaultWriter.desiredSize`

##### ready

> `readonly` **ready**: `Promise`<`undefined`>

###### Inherited from

`_WritableStreamDefaultWriter.ready`

#### Methods

##### abort()

> **abort**(`reason?`: `any`): `Promise`<`void`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `reason?` | `any` |

###### Returns

`Promise`<`void`>

###### Inherited from

`_WritableStreamDefaultWriter.abort`

##### close()

> **close**(): `Promise`<`void`>

###### Returns

`Promise`<`void`>

###### Inherited from

`_WritableStreamDefaultWriter.close`

##### releaseLock()

> **releaseLock**(): `void`

###### Returns

`void`

###### Inherited from

`_WritableStreamDefaultWriter.releaseLock`

##### write()

> **write**(`chunk?`: `W`): `Promise`<`void`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `chunk?` | `W` |

###### Returns

`Promise`<`void`>

###### Inherited from

`_WritableStreamDefaultWriter.write`

## Type Aliases

### \_ByteLengthQueuingStrategy

> **\_ByteLengthQueuingStrategy** = *typeof* `globalThis` *extends* `object` ? `object` : [`ByteLengthQueuingStrategy`](stream/web.md#bytelengthqueuingstrategy)

***

### \_CountQueuingStrategy

> **\_CountQueuingStrategy** = *typeof* `globalThis` *extends* `object` ? `object` : [`CountQueuingStrategy`](stream/web.md#countqueuingstrategy)

***

### \_ReadableByteStreamController

> **\_ReadableByteStreamController** = *typeof* `globalThis` *extends* `object` ? `object` : [`ReadableByteStreamController`](stream/web.md#readablebytestreamcontroller)

***

### \_ReadableStream

> **\_ReadableStream**<`R`> = *typeof* `globalThis` *extends* `object` ? `object` : [`ReadableStream`](stream/web.md#readablestream)

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `R` | `any` |

***

### \_ReadableStreamBYOBReader

> **\_ReadableStreamBYOBReader** = *typeof* `globalThis` *extends* `object` ? `object` : [`ReadableStreamBYOBReader`](stream/web.md#readablestreambyobreader)

***

### \_ReadableStreamBYOBRequest

> **\_ReadableStreamBYOBRequest** = *typeof* `globalThis` *extends* `object` ? `object` : [`ReadableStreamBYOBRequest`](stream/web.md#readablestreambyobrequest)

***

### \_ReadableStreamDefaultController

> **\_ReadableStreamDefaultController**<`R`> = *typeof* `globalThis` *extends* `object` ? `object` : [`ReadableStreamDefaultController`](stream/web.md#readablestreamdefaultcontroller)

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `R` | `any` |

***

### \_ReadableStreamDefaultReader

> **\_ReadableStreamDefaultReader**<`R`> = *typeof* `globalThis` *extends* `object` ? `object` : [`ReadableStreamDefaultReader`](stream/web.md#readablestreamdefaultreader)

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `R` | `any` |

***

### \_WritableStream

> **\_WritableStream**<`W`> = *typeof* `globalThis` *extends* `object` ? `object` : [`WritableStream`](stream/web.md#writablestream)

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `W` | `any` |

***

### \_WritableStreamDefaultController

> **\_WritableStreamDefaultController** = *typeof* `globalThis` *extends* `object` ? `object` : [`WritableStreamDefaultController`](stream/web.md#writablestreamdefaultcontroller)

***

### \_WritableStreamDefaultWriter

> **\_WritableStreamDefaultWriter**<`W`> = *typeof* `globalThis` *extends* `object` ? `object` : [`WritableStreamDefaultWriter`](stream/web.md#writablestreamdefaultwriter)

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `W` | `any` |

## Variables

### ByteLengthQueuingStrategy

> **ByteLengthQueuingStrategy**: {(`init`: [`QueuingStrategyInit`](stream/web.md#queuingstrategyinit)): [`ByteLengthQueuingStrategy`](stream/web.md#bytelengthqueuingstrategy); `prototype`: [`ByteLengthQueuingStrategy`](stream/web.md#bytelengthqueuingstrategy); }

`ByteLengthQueuingStrategy` class is a global reference for `import { ByteLengthQueuingStrategy } from 'stream/web'`.
https://nodejs.org/api/globals.html#class-bytelengthqueuingstrategy

#### Type Declaration

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `init` | [`QueuingStrategyInit`](stream/web.md#queuingstrategyinit) |

#### Returns

[`ByteLengthQueuingStrategy`](stream/web.md#bytelengthqueuingstrategy)

##### prototype

> **prototype**: [`ByteLengthQueuingStrategy`](stream/web.md#bytelengthqueuingstrategy)

#### Since

v18.0.0

***

### CountQueuingStrategy

> **CountQueuingStrategy**: {(`init`: [`QueuingStrategyInit`](stream/web.md#queuingstrategyinit)): [`CountQueuingStrategy`](stream/web.md#countqueuingstrategy); `prototype`: [`CountQueuingStrategy`](stream/web.md#countqueuingstrategy); }

`CountQueuingStrategy` class is a global reference for `import { CountQueuingStrategy } from 'stream/web'`.
https://nodejs.org/api/globals.html#class-countqueuingstrategy

#### Type Declaration

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `init` | [`QueuingStrategyInit`](stream/web.md#queuingstrategyinit) |

#### Returns

[`CountQueuingStrategy`](stream/web.md#countqueuingstrategy)

##### prototype

> **prototype**: [`CountQueuingStrategy`](stream/web.md#countqueuingstrategy)

#### Since

v18.0.0

***

### ReadableByteStreamController

> **ReadableByteStreamController**: {(): [`ReadableByteStreamController`](stream/web.md#readablebytestreamcontroller); `prototype`: [`ReadableByteStreamController`](stream/web.md#readablebytestreamcontroller); }

`ReadableByteStreamController` class is a global reference for `import { ReadableByteStreamController } from 'stream/web'`.
https://nodejs.org/api/globals.html#class-readablebytestreamcontroller

#### Type Declaration

#### Returns

[`ReadableByteStreamController`](stream/web.md#readablebytestreamcontroller)

##### prototype

> **prototype**: [`ReadableByteStreamController`](stream/web.md#readablebytestreamcontroller)

#### Since

v18.0.0

***

### ReadableStream

> **ReadableStream**: {(`underlyingSource`: [`UnderlyingByteSource`](stream/web.md#underlyingbytesource), `strategy?`: [`QueuingStrategy`](stream/web.md#queuingstrategy)<`Uint8Array`>): [`ReadableStream`](stream/web.md#readablestream)<`Uint8Array`>; <`R`>(`underlyingSource?`: [`UnderlyingSource`](stream/web.md#underlyingsource)<`R`>, `strategy?`: [`QueuingStrategy`](stream/web.md#queuingstrategy)<`R`>): [`ReadableStream`](stream/web.md#readablestream)<`R`>; `prototype`: [`ReadableStream`](stream/web.md#readablestream); `from`: [`ReadableStream`](stream/web.md#readablestream)<`T`>; }

`ReadableStream` class is a global reference for `import { ReadableStream } from 'stream/web'`.
https://nodejs.org/api/globals.html#class-readablestream

#### Type Declaration

#### Call Signature

> **new ReadableStream**(`underlyingSource`: [`UnderlyingByteSource`](stream/web.md#underlyingbytesource), `strategy?`: [`QueuingStrategy`](stream/web.md#queuingstrategy)<`Uint8Array`>): [`ReadableStream`](stream/web.md#readablestream)<`Uint8Array`>

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `underlyingSource` | [`UnderlyingByteSource`](stream/web.md#underlyingbytesource) |
| `strategy?` | [`QueuingStrategy`](stream/web.md#queuingstrategy)<`Uint8Array`> |

##### Returns

[`ReadableStream`](stream/web.md#readablestream)<`Uint8Array`>

#### Call Signature

> **new ReadableStream**<`R`>(`underlyingSource?`: [`UnderlyingSource`](stream/web.md#underlyingsource)<`R`>, `strategy?`: [`QueuingStrategy`](stream/web.md#queuingstrategy)<`R`>): [`ReadableStream`](stream/web.md#readablestream)<`R`>

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `underlyingSource?` | [`UnderlyingSource`](stream/web.md#underlyingsource)<`R`> |
| `strategy?` | [`QueuingStrategy`](stream/web.md#queuingstrategy)<`R`> |

##### Returns

[`ReadableStream`](stream/web.md#readablestream)<`R`>

##### prototype

> **prototype**: [`ReadableStream`](stream/web.md#readablestream)

##### from()

> **from**<`T`>(`iterable`: `Iterable`<`T`, `any`, `any`> | `AsyncIterable`<`T`, `any`, `any`>): [`ReadableStream`](stream/web.md#readablestream)<`T`>

###### Type Parameters

| Type Parameter |
| ------ |
| `T` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `iterable` | `Iterable`<`T`, `any`, `any`> | `AsyncIterable`<`T`, `any`, `any`> |

###### Returns

[`ReadableStream`](stream/web.md#readablestream)<`T`>

#### Since

v18.0.0

***

### ReadableStreamBYOBReader

> **ReadableStreamBYOBReader**: {(`stream`: [`ReadableStream`](stream/web.md#readablestream)): [`ReadableStreamBYOBReader`](stream/web.md#readablestreambyobreader); `prototype`: [`ReadableStreamBYOBReader`](stream/web.md#readablestreambyobreader); }

`ReadableStreamBYOBReader` class is a global reference for `import { ReadableStreamBYOBReader } from 'stream/web'`.
https://nodejs.org/api/globals.html#class-readablestreambyobreader

#### Type Declaration

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `stream` | [`ReadableStream`](stream/web.md#readablestream) |

#### Returns

[`ReadableStreamBYOBReader`](stream/web.md#readablestreambyobreader)

##### prototype

> **prototype**: [`ReadableStreamBYOBReader`](stream/web.md#readablestreambyobreader)

#### Since

v18.0.0

***

### ReadableStreamBYOBRequest

> **ReadableStreamBYOBRequest**: {(): [`ReadableStreamBYOBRequest`](stream/web.md#readablestreambyobrequest); `prototype`: [`ReadableStreamBYOBRequest`](stream/web.md#readablestreambyobrequest); }

`ReadableStreamBYOBRequest` class is a global reference for `import { ReadableStreamBYOBRequest } from 'stream/web'`.
https://nodejs.org/api/globals.html#class-readablestreambyobrequest

#### Type Declaration

#### Returns

[`ReadableStreamBYOBRequest`](stream/web.md#readablestreambyobrequest)

##### prototype

> **prototype**: [`ReadableStreamBYOBRequest`](stream/web.md#readablestreambyobrequest)

#### Since

v18.0.0

***

### ReadableStreamDefaultController

> **ReadableStreamDefaultController**: {(): [`ReadableStreamDefaultController`](stream/web.md#readablestreamdefaultcontroller); `prototype`: [`ReadableStreamDefaultController`](stream/web.md#readablestreamdefaultcontroller); }

`ReadableStreamDefaultController` class is a global reference for `import { ReadableStreamDefaultController } from 'stream/web'`.
https://nodejs.org/api/globals.html#class-readablestreamdefaultcontroller

#### Type Declaration

#### Returns

[`ReadableStreamDefaultController`](stream/web.md#readablestreamdefaultcontroller)

##### prototype

> **prototype**: [`ReadableStreamDefaultController`](stream/web.md#readablestreamdefaultcontroller)

#### Since

v18.0.0

***

### ReadableStreamDefaultReader

> **ReadableStreamDefaultReader**: {<`R`>(`stream`: [`ReadableStream`](stream/web.md#readablestream)<`R`>): [`ReadableStreamDefaultReader`](stream/web.md#readablestreamdefaultreader)<`R`>; `prototype`: [`ReadableStreamDefaultReader`](stream/web.md#readablestreamdefaultreader); }

`ReadableStreamDefaultReader` class is a global reference for `import { ReadableStreamDefaultReader } from 'stream/web'`.
https://nodejs.org/api/globals.html#class-readablestreamdefaultreader

#### Type Declaration

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `stream` | [`ReadableStream`](stream/web.md#readablestream)<`R`> |

#### Returns

[`ReadableStreamDefaultReader`](stream/web.md#readablestreamdefaultreader)<`R`>

##### prototype

> **prototype**: [`ReadableStreamDefaultReader`](stream/web.md#readablestreamdefaultreader)

#### Since

v18.0.0

***

### WritableStream

> **WritableStream**: {<`W`>(`underlyingSink?`: [`UnderlyingSink`](stream/web.md#underlyingsink)<`W`>, `strategy?`: [`QueuingStrategy`](stream/web.md#queuingstrategy)<`W`>): [`WritableStream`](stream/web.md#writablestream)<`W`>; `prototype`: [`WritableStream`](stream/web.md#writablestream); }

`WritableStream` class is a global reference for `import { WritableStream } from 'stream/web'`.
https://nodejs.org/api/globals.html#class-writablestream

#### Type Declaration

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `underlyingSink?` | [`UnderlyingSink`](stream/web.md#underlyingsink)<`W`> |
| `strategy?` | [`QueuingStrategy`](stream/web.md#queuingstrategy)<`W`> |

#### Returns

[`WritableStream`](stream/web.md#writablestream)<`W`>

##### prototype

> **prototype**: [`WritableStream`](stream/web.md#writablestream)

#### Since

v18.0.0

***

### WritableStreamDefaultController

> **WritableStreamDefaultController**: {(): [`WritableStreamDefaultController`](stream/web.md#writablestreamdefaultcontroller); `prototype`: [`WritableStreamDefaultController`](stream/web.md#writablestreamdefaultcontroller); }

`WritableStreamDefaultController` class is a global reference for `import { WritableStreamDefaultController } from 'stream/web'`.
https://nodejs.org/api/globals.html#class-writablestreamdefaultcontroller

#### Type Declaration

#### Returns

[`WritableStreamDefaultController`](stream/web.md#writablestreamdefaultcontroller)

##### prototype

> **prototype**: [`WritableStreamDefaultController`](stream/web.md#writablestreamdefaultcontroller)

#### Since

v18.0.0

***

### WritableStreamDefaultWriter

> **WritableStreamDefaultWriter**: {<`W`>(`stream`: [`WritableStream`](stream/web.md#writablestream)<`W`>): [`WritableStreamDefaultWriter`](stream/web.md#writablestreamdefaultwriter)<`W`>; `prototype`: [`WritableStreamDefaultWriter`](stream/web.md#writablestreamdefaultwriter); }

`WritableStreamDefaultWriter` class is a global reference for `import { WritableStreamDefaultWriter } from 'stream/web'`.
https://nodejs.org/api/globals.html#class-writablestreamdefaultwriter

#### Type Declaration

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `stream` | [`WritableStream`](stream/web.md#writablestream)<`W`> |

#### Returns

[`WritableStreamDefaultWriter`](stream/web.md#writablestreamdefaultwriter)<`W`>

##### prototype

> **prototype**: [`WritableStreamDefaultWriter`](stream/web.md#writablestreamdefaultwriter)

#### Since

v18.0.0

---

---
url: /plugins/reference/modules/llrt/string_decoder.md
---
[@caido/quickjs-types](../index.md) / llrt/string\_decoder

# llrt/string\_decoder

## Classes

### StringDecoder

#### Constructors

##### Constructor

> **new StringDecoder**(`encoding?`: [`BufferEncoding`](buffer.md#bufferencoding)): [`StringDecoder`](#stringdecoder)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `encoding?` | [`BufferEncoding`](buffer.md#bufferencoding) |

###### Returns

[`StringDecoder`](#stringdecoder)

#### Methods

##### end()

> **end**(`buffer?`: `string` | [`ArrayBufferView`](globals/namespaces/QuickJS.md#arraybufferview) | [`Buffer`](buffer.md#buffer)): `string`

Returns any remaining input stored in the internal buffer as a string. Bytes
representing incomplete UTF-8 and UTF-16 characters will be replaced with
substitution characters appropriate for the character encoding.

If the `buffer` argument is provided, one final call to `stringDecoder.write()` is performed before returning the remaining input.
After `end()` is called, the `stringDecoder` object can be reused for new input.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `buffer?` | `string` | [`ArrayBufferView`](globals/namespaces/QuickJS.md#arraybufferview) | [`Buffer`](buffer.md#buffer) | The bytes to decode. |

###### Returns

`string`

##### write()

> **write**(`buffer`: `string` | [`ArrayBufferView`](globals/namespaces/QuickJS.md#arraybufferview) | [`Buffer`](buffer.md#buffer)): `string`

Returns a decoded string, ensuring that any incomplete multibyte characters at
the end of the `Buffer`, or `TypedArray`, or `DataView` are omitted from the
returned string and stored in an internal buffer for the next call to `stringDecoder.write()` or `stringDecoder.end()`.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `buffer` | `string` | [`ArrayBufferView`](globals/namespaces/QuickJS.md#arraybufferview) | [`Buffer`](buffer.md#buffer) | The bytes to decode. |

###### Returns

`string`

---

---
url: /plugins/reference/modules/llrt/url.md
---
[@caido/quickjs-types](../../index.md) / llrt/url

# llrt/url

## Modules

| Module | Description |
| ------ | ------ |
| [url](url.md) | - |

## Interfaces

### Global

#### Properties

##### URL

> **URL**: *typeof* [`URL`](url.md#url)

##### URLSearchParams

> **URLSearchParams**: *typeof* [`URLSearchParams`](url.md#urlsearchparams-1)

***

### URL

Browser-compatible `URL` class, implemented by following the WHATWG URL
Standard. [Examples of parsed URLs](https://url.spec.whatwg.org/#example-url-parsing) may be found in the Standard itself.
The `URL` class is also available on the global object.

In accordance with browser conventions, all properties of `URL` objects
are implemented as getters and setters on the class prototype, rather than as
data properties on the object itself. Thus, unlike `legacy urlObject`s,
using the `delete` keyword on any properties of `URL` objects (e.g. `delete myURL.protocol`, `delete myURL.pathname`, etc) has no effect but will still
return `true`.

#### Extends

* [`URL`](url.md#url)

#### Properties

##### hash

> **hash**: `string`

Gets and sets the fragment portion of the URL.

```js
const myURL = new URL('https://example.org/foo#bar');
console.log(myURL.hash);
// Prints #bar

myURL.hash = 'baz';
console.log(myURL.href);
// Prints https://example.org/foo#baz
```

Invalid URL characters included in the value assigned to the `hash` property
are `percent-encoded`. The selection of which characters to
percent-encode may vary somewhat from what the [parse](url.md#parse-2) and [format](url.md#format) methods would produce.

###### Inherited from

[`URL`](url.md#url).[`hash`](url.md#hash)

##### host

> **host**: `string`

Gets and sets the host portion of the URL.

```js
const myURL = new URL('https://example.org:81/foo');
console.log(myURL.host);
// Prints example.org:81

myURL.host = 'example.com:82';
console.log(myURL.href);
// Prints https://example.com:82/foo
```

Invalid host values assigned to the `host` property are ignored.

###### Inherited from

[`URL`](url.md#url).[`host`](url.md#host)

##### hostname

> **hostname**: `string`

Gets and sets the host name portion of the URL. The key difference between`url.host` and `url.hostname` is that `url.hostname` does *not* include the
port.

```js
const myURL = new URL('https://example.org:81/foo');
console.log(myURL.hostname);
// Prints example.org

// Setting the hostname does not change the port
myURL.hostname = 'example.com';
console.log(myURL.href);
// Prints https://example.com:81/foo

// Use myURL.host to change the hostname and port
myURL.host = 'example.org:82';
console.log(myURL.href);
// Prints https://example.org:82/foo
```

Invalid host name values assigned to the `hostname` property are ignored.

###### Inherited from

[`URL`](url.md#url).[`hostname`](url.md#hostname)

##### href

> **href**: `string`

Gets and sets the serialized URL.

```js
const myURL = new URL('https://example.org/foo');
console.log(myURL.href);
// Prints https://example.org/foo

myURL.href = 'https://example.com/bar';
console.log(myURL.href);
// Prints https://example.com/bar
```

Getting the value of the `href` property is equivalent to calling [toString](url.md#tostring).

Setting the value of this property to a new value is equivalent to creating a
new `URL` object using `new URL(value)`. Each of the `URL` object's properties will be modified.

If the value assigned to the `href` property is not a valid URL, a `TypeError` will be thrown.

###### Inherited from

[`URL`](url.md#url).[`href`](url.md#href)

##### origin

> `readonly` **origin**: `string`

Gets the read-only serialization of the URL's origin.

```js
const myURL = new URL('https://example.org/foo/bar?baz');
console.log(myURL.origin);
// Prints https://example.org
```

```js
const idnURL = new URL('https://測試');
console.log(idnURL.origin);
// Prints https://xn--g6w251d

console.log(idnURL.hostname);
// Prints xn--g6w251d
```

###### Inherited from

[`URL`](url.md#url).[`origin`](url.md#origin)

##### password

> **password**: `string`

Gets and sets the password portion of the URL.

```js
const myURL = new URL('https://abc:xyz@example.com');
console.log(myURL.password);
// Prints xyz

myURL.password = '123';
console.log(myURL.href);
// Prints https://abc:123@example.com/
```

Invalid URL characters included in the value assigned to the `password` property
are `percent-encoded`. The selection of which characters to
percent-encode may vary somewhat from what the [parse](url.md#parse-2) and [format](url.md#format) methods would produce.

###### Inherited from

[`URL`](url.md#url).[`password`](url.md#password)

##### pathname

> **pathname**: `string`

Gets and sets the path portion of the URL.

```js
const myURL = new URL('https://example.org/abc/xyz?123');
console.log(myURL.pathname);
// Prints /abc/xyz

myURL.pathname = '/abcdef';
console.log(myURL.href);
// Prints https://example.org/abcdef?123
```

Invalid URL characters included in the value assigned to the `pathname` property are `percent-encoded`. The selection of which characters
to percent-encode may vary somewhat from what the [parse](url.md#parse-2) and [format](url.md#format) methods would produce.

###### Inherited from

[`URL`](url.md#url).[`pathname`](url.md#pathname)

##### port

> **port**: `string`

Gets and sets the port portion of the URL.

The port value may be a number or a string containing a number in the range `0` to `65535` (inclusive). Setting the value to the default port of the `URL` objects given `protocol` will
result in the `port` value becoming
the empty string (`''`).

The port value can be an empty string in which case the port depends on
the protocol/scheme.

Upon assigning a value to the port, the value will first be converted to a
string using `.toString()`.

If that string is invalid but it begins with a number, the leading number is
assigned to `port`.
If the number lies outside the range denoted above, it is ignored.

```js
const myURL = new URL('https://example.org:8888');
console.log(myURL.port);
// Prints 8888

// Default ports are automatically transformed to the empty string
// (HTTPS protocol's default port is 443)
myURL.port = '443';
console.log(myURL.port);
// Prints the empty string
console.log(myURL.href);
// Prints https://example.org/

myURL.port = 1234;
console.log(myURL.port);
// Prints 1234
console.log(myURL.href);
// Prints https://example.org:1234/

// Completely invalid port strings are ignored
myURL.port = 'abcd';
console.log(myURL.port);
// Prints 1234

// Leading numbers are treated as a port number
myURL.port = '5678abcd';
console.log(myURL.port);
// Prints 5678

// Non-integers are truncated
myURL.port = 1234.5678;
console.log(myURL.port);
// Prints 1234

// Out-of-range numbers which are not represented in scientific notation
// will be ignored.
myURL.port = 1e10; // 10000000000, will be range-checked as described below
console.log(myURL.port);
// Prints 1234
```

Numbers which contain a decimal point,
such as floating-point numbers or numbers in scientific notation,
are not an exception to this rule.
Leading numbers up to the decimal point will be set as the URL's port,
assuming they are valid:

```js
myURL.port = 4.567e21;
console.log(myURL.port);
// Prints 4 (because it is the leading number in the string '4.567e21')
```

###### Inherited from

[`URL`](url.md#url).[`port`](url.md#port)

##### protocol

> **protocol**: `string`

Gets and sets the protocol portion of the URL.

```js
const myURL = new URL('https://example.org');
console.log(myURL.protocol);
// Prints https:

myURL.protocol = 'ftp';
console.log(myURL.href);
// Prints ftp://example.org/
```

Invalid URL protocol values assigned to the `protocol` property are ignored.

###### Inherited from

[`URL`](url.md#url).[`protocol`](url.md#protocol)

##### search

> **search**: `string`

Gets and sets the serialized query portion of the URL.

```js
const myURL = new URL('https://example.org/abc?123');
console.log(myURL.search);
// Prints ?123

myURL.search = 'abc=xyz';
console.log(myURL.href);
// Prints https://example.org/abc?abc=xyz
```

Any invalid URL characters appearing in the value assigned the `search` property will be `percent-encoded`. The selection of which
characters to percent-encode may vary somewhat from what the [parse](url.md#parse-2) and [format](url.md#format) methods would produce.

###### Inherited from

[`URL`](url.md#url).[`search`](url.md#search)

##### searchParams

> `readonly` **searchParams**: [`URLSearchParams`](url.md#urlsearchparams-1)

Gets the `URLSearchParams` object representing the query parameters of the
URL. This property is read-only but the `URLSearchParams` object it provides
can be used to mutate the URL instance; to replace the entirety of query
parameters of the URL, use the [search](url.md#search) setter. See `URLSearchParams` documentation for details.

Use care when using `.searchParams` to modify the `URL` because,
per the WHATWG specification, the `URLSearchParams` object uses
different rules to determine which characters to percent-encode. For
instance, the `URL` object will not percent encode the ASCII tilde (`~`)
character, while `URLSearchParams` will always encode it:

```js
const myURL = new URL('https://example.org/abc?foo=~bar');

console.log(myURL.search);  // prints ?foo=~bar

// Modify the URL via searchParams...
myURL.searchParams.sort();

console.log(myURL.search);  // prints ?foo=%7Ebar
```

###### Inherited from

[`URL`](url.md#url).[`searchParams`](url.md#searchparams)

##### username

> **username**: `string`

Gets and sets the username portion of the URL.

```js
const myURL = new URL('https://abc:xyz@example.com');
console.log(myURL.username);
// Prints abc

myURL.username = '123';
console.log(myURL.href);
// Prints https://123:xyz@example.com/
```

Any invalid URL characters appearing in the value assigned the `username` property will be `percent-encoded`. The selection of which
characters to percent-encode may vary somewhat from what the [parse](url.md#parse-2) and [format](url.md#format) methods would produce.

###### Inherited from

[`URL`](url.md#url).[`username`](url.md#username)

#### Methods

##### toJSON()

> **toJSON**(): `string`

The `toJSON()` method on the `URL` object returns the serialized URL. The
value returned is equivalent to that of [href](url.md#href) and [toString](url.md#tostring).

This method is automatically called when an `URL` object is serialized
with [`JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify).

```js
const myURLs = [
  new URL('https://www.example.com'),
  new URL('https://test.example.org'),
];
console.log(JSON.stringify(myURLs));
// Prints ["https://www.example.com/","https://test.example.org/"]
```

###### Returns

`string`

###### Inherited from

[`URL`](url.md#url).[`toJSON`](url.md#tojson)

##### toString()

> **toString**(): `string`

The `toString()` method on the `URL` object returns the serialized URL. The
value returned is equivalent to that of [href](url.md#href) and [toJSON](url.md#tojson).

###### Returns

`string`

###### Inherited from

[`URL`](url.md#url).[`toString`](url.md#tostring)

***

### URLSearchParams

The `URLSearchParams` API provides read and write access to the query of a `URL`. The `URLSearchParams` class can also be used standalone with one of the
four following constructors.
The `URLSearchParams` class is also available on the global object.

The WHATWG `URLSearchParams` interface and the `querystring` module have
similar purpose, but the purpose of the `querystring` module is more
general, as it allows the customization of delimiter characters (`&#x26;` and `=`).
On the other hand, this API is designed purely for URL query strings.

```js
const myURL = new URL('https://example.org/?abc=123');
console.log(myURL.searchParams.get('abc'));
// Prints 123

myURL.searchParams.append('abc', 'xyz');
console.log(myURL.href);
// Prints https://example.org/?abc=123&#x26;abc=xyz

myURL.searchParams.delete('abc');
myURL.searchParams.set('a', 'b');
console.log(myURL.href);
// Prints https://example.org/?a=b

const newSearchParams = new URLSearchParams(myURL.searchParams);
// The above is equivalent to
// const newSearchParams = new URLSearchParams(myURL.search);

newSearchParams.append('a', 'c');
console.log(myURL.href);
// Prints https://example.org/?a=b
console.log(newSearchParams.toString());
// Prints a=b&#x26;a=c

// newSearchParams.toString() is implicitly called
myURL.search = newSearchParams;
console.log(myURL.href);
// Prints https://example.org/?a=b&#x26;a=c
newSearchParams.delete('a');
console.log(myURL.href);
// Prints https://example.org/?a=b&#x26;a=c
```

#### Extends

* [`URLSearchParams`](url.md#urlsearchparams-1)

#### Methods

##### \[iterator]\()

> **\[iterator]**(): `IterableIterator`<\[`string`, `string`]>

###### Returns

`IterableIterator`<\[`string`, `string`]>

###### Inherited from

[`URLSearchParams`](url.md#urlsearchparams-1).[`[iterator]`](url.md#iterator)

##### append()

> **append**(`name`: `string`, `value`: `string`): `void`

Append a new name-value pair to the query string.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |
| `value` | `string` |

###### Returns

`void`

###### Inherited from

[`URLSearchParams`](url.md#urlsearchparams-1).[`append`](url.md#append)

##### delete()

> **delete**(`name`: `string`, `value?`: `string`): `void`

If `value` is provided, removes all name-value pairs
where name is `name` and value is `value`.

If `value` is not provided, removes all name-value pairs whose name is `name`.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |
| `value?` | `string` |

###### Returns

`void`

###### Inherited from

[`URLSearchParams`](url.md#urlsearchparams-1).[`delete`](url.md#delete)

##### entries()

> **entries**(): `IterableIterator`<\[`string`, `string`]>

Returns an ES6 `Iterator` over each of the name-value pairs in the query.
Each item of the iterator is a JavaScript `Array`. The first item of the `Array` is the `name`, the second item of the `Array` is the `value`.

Alias for `urlSearchParams[@@iterator]()`.

###### Returns

`IterableIterator`<\[`string`, `string`]>

###### Inherited from

[`URLSearchParams`](url.md#urlsearchparams-1).[`entries`](url.md#entries)

##### forEach()

> **forEach**<`TThis`>(`fn`: (`this`: `TThis`, `value`: `string`, `name`: `string`, `searchParams`: [`URLSearchParams`](url.md#urlsearchparams-1)) => `void`, `thisArg?`: `TThis`): `void`

Iterates over each name-value pair in the query and invokes the given function.

```js
const myURL = new URL('https://example.org/?a=b&#x26;c=d');
myURL.searchParams.forEach((value, name, searchParams) => {
  console.log(name, value, myURL.searchParams === searchParams);
});
// Prints:
//   a b true
//   c d true
```

###### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `TThis` | [`URLSearchParams`](#urlsearchparams-2) |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `fn` | (`this`: `TThis`, `value`: `string`, `name`: `string`, `searchParams`: [`URLSearchParams`](url.md#urlsearchparams-1)) => `void` | Invoked for each name-value pair in the query |
| `thisArg?` | `TThis` | To be used as `this` value for when `fn` is called |

###### Returns

`void`

###### Inherited from

[`URLSearchParams`](url.md#urlsearchparams-1).[`forEach`](url.md#foreach)

##### get()

> **get**(`name`: `string`): `string` | `null`

Returns the value of the first name-value pair whose name is `name`. If there
are no such pairs, `null` is returned.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |

###### Returns

`string` | `null`

or `null` if there is no name-value pair with the given `name`.

###### Inherited from

[`URLSearchParams`](url.md#urlsearchparams-1).[`get`](url.md#get)

##### has()

> **has**(`name`: `string`, `value?`: `string`): `boolean`

Checks if the `URLSearchParams` object contains key-value pair(s) based on `name` and an optional `value` argument.

If `value` is provided, returns `true` when name-value pair with
same `name` and `value` exists.

If `value` is not provided, returns `true` if there is at least one name-value
pair whose name is `name`.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |
| `value?` | `string` |

###### Returns

`boolean`

###### Inherited from

[`URLSearchParams`](url.md#urlsearchparams-1).[`has`](url.md#has)

##### keys()

> **keys**(): `IterableIterator`<`string`>

Returns an ES6 `Iterator` over the names of each name-value pair.

```js
const params = new URLSearchParams('foo=bar&#x26;foo=baz');
for (const name of params.keys()) {
  console.log(name);
}
// Prints:
//   foo
//   foo
```

###### Returns

`IterableIterator`<`string`>

###### Inherited from

[`URLSearchParams`](url.md#urlsearchparams-1).[`keys`](url.md#keys)

##### set()

> **set**(`name`: `string`, `value`: `string`): `void`

Sets the value in the `URLSearchParams` object associated with `name` to `value`. If there are any pre-existing name-value pairs whose names are `name`,
set the first such pair's value to `value` and remove all others. If not,
append the name-value pair to the query string.

```js
const params = new URLSearchParams();
params.append('foo', 'bar');
params.append('foo', 'baz');
params.append('abc', 'def');
console.log(params.toString());
// Prints foo=bar&#x26;foo=baz&#x26;abc=def

params.set('foo', 'def');
params.set('xyz', 'opq');
console.log(params.toString());
// Prints foo=def&#x26;abc=def&#x26;xyz=opq
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |
| `value` | `string` |

###### Returns

`void`

###### Inherited from

[`URLSearchParams`](url.md#urlsearchparams-1).[`set`](url.md#set)

##### sort()

> **sort**(): `void`

Sort all existing name-value pairs in-place by their names. Sorting is done
with a [stable sorting algorithm](https://en.wikipedia.org/wiki/Sorting_algorithm#Stability), so relative order between name-value pairs
with the same name is preserved.

This method can be used, in particular, to increase cache hits.

```js
const params = new URLSearchParams('query[]=abc&#x26;type=search&#x26;query[]=123');
params.sort();
console.log(params.toString());
// Prints query%5B%5D=abc&#x26;query%5B%5D=123&#x26;type=search
```

###### Returns

`void`

###### Inherited from

[`URLSearchParams`](url.md#urlsearchparams-1).[`sort`](url.md#sort)

##### toString()

> **toString**(): `string`

Returns the search parameters serialized as a string, with characters
percent-encoded where necessary.

###### Returns

`string`

###### Inherited from

[`URLSearchParams`](url.md#urlsearchparams-1).[`toString`](url.md#tostring-2)

##### values()

> **values**(): `IterableIterator`<`string`>

Returns an ES6 `Iterator` over the values of each name-value pair.

###### Returns

`IterableIterator`<`string`>

###### Inherited from

[`URLSearchParams`](url.md#urlsearchparams-1).[`values`](url.md#values)

## Variables

### URL

> **URL**: *typeof* [`URL`](url.md#url)

`URL` class is a global reference for `require('url').URL`

***

### URLSearchParams

> **URLSearchParams**: *typeof* [`URLSearchParams`](url.md#urlsearchparams-1)

`URLSearchParams` class is a global reference for `require('url').URLSearchParams`

---

---
url: /plugins/reference/sdks/frontend/log.md
---
# Log

### LogSDK

> **LogSDK** = `object`

Utilities to log messages to the console.

#### Properties

##### debug()

> **debug**: (...`data`: `unknown`\[]) => `void`

Log debug message with variable arguments

###### Parameters

| Parameter | Type |
| ------ | ------ |
| ...`data` | `unknown`\[] |

###### Returns

`void`

##### error()

> **error**: (...`data`: `unknown`\[]) => `void`

Log error message with variable arguments

###### Parameters

| Parameter | Type |
| ------ | ------ |
| ...`data` | `unknown`\[] |

###### Returns

`void`

##### info()

> **info**: (...`data`: `unknown`\[]) => `void`

Log info message with variable arguments

###### Parameters

| Parameter | Type |
| ------ | ------ |
| ...`data` | `unknown`\[] |

###### Returns

`void`

##### warn()

> **warn**: (...`data`: `unknown`\[]) => `void`

Log warning message with variable arguments

###### Parameters

| Parameter | Type |
| ------ | ------ |
| ...`data` | `unknown`\[] |

###### Returns

`void`

---

---
url: /plugins/guides/log.md
---
# Log Messages

The frontend SDK provides logging utilities to help you debug your plugin and track information at different severity levels.

## Logging Methods

The `sdk.log` object provides four logging methods:

```ts
sdk.log.debug("Debug message", { data: "value" });
sdk.log.info("Information message");
sdk.log.warn("Warning message");
sdk.log.error("Error message", error);
```

All logging methods accept variable arguments, allowing you to pass multiple values:

```ts
sdk.log.info("User action:", action, "with data:", data);
```

## Using Different Log Levels

### Debug

Use `debug()` for detailed diagnostic information that is typically only useful during development:

```ts
sdk.log.debug("Processing request", requestId);
```

### Info

Use `info()` for general informational messages:

```ts
sdk.log.info("Plugin initialized successfully");
```

### Warn

Use `warn()` for warning messages that indicate potential issues:

```ts
sdk.log.warn("API rate limit approaching:", remaining);
```

### Error

Use `error()` for error messages that indicate failures:

```ts
try {
  await performOperation();
} catch (err) {
  sdk.log.error("Operation failed:", err);
}
```

## Best Practices

* Use appropriate log levels: reserve `debug()` for development, `info()` for normal operations, `warn()` for warnings, and `error()` for errors
* Include context in your log messages to make debugging easier
* Use structured data when logging objects or complex values
* Avoid logging sensitive information such as passwords or API keys

## Examples

### Logging User Actions

This example demonstrates logging at different levels during user interactions. It logs info messages when operations start and complete, error messages when operations fail, and shows corresponding toast notifications to the user.

```vue
<script setup lang="ts">
import Button from "primevue/button";
import { inject } from "vue";

const sdk = inject<CaidoSDK>("sdk");

const performAction = async () => {
  if (!sdk) return;
  
  sdk.log.info("Button clicked, starting operation");
  
  try {
    const result = await performOperation();
    sdk.log.info("Operation completed successfully:", result);
    sdk.window.showToast("Success!", { variant: "success" });
  } catch (err) {
    sdk.log.error("Operation failed:", err);
    sdk.window.showToast("Error occurred", { variant: "error" });
  }
};
</script>

<template>
  <div class="p-4">
    <Button label="Perform Action" @click="performAction" />
  </div>
</template>
```

::: info
For information on creating pages and setting up Vue components, see [Create a Page](/plugins/guides/page.md).
:::

---

---
url: /plugins/guides/automate.md
---
# Manage Automate Sessions and Entries

The Automate SDK allows you to interact with the Automate page, manage sessions and entries, add indicators, and extend the request/response editors with custom functionality.

## Session Management

### Getting Sessions

To retrieve all automate sessions:

```ts
const sessions = sdk.automate.getSessions();
```

Each session contains:

* `id` - The unique identifier
* `name` - The session name
* `createdAt` - The creation date
* `entryIds` - Array of entry IDs in the session

### Getting Entries

To get all entries for a specific session:

```ts
const entries = sdk.automate.getEntries(sessionId);
```

Each entry contains:

* `id` - The unique identifier
* `name` - The entry name
* `createdAt` - The creation date

## Adding Indicators

Indicators are visual badges displayed next to entry names in the collections tree. They're useful for highlighting important entries or showing status information.

### Adding an Entry Indicator

```ts
const indicator = sdk.automate.addEntryIndicator(entryId, {
  icon: "fas fa-exclamation-triangle",
  description: "Security warning",
});
```

The `addEntryIndicator` method returns a handle object with a `remove` method to remove the indicator later:

```ts
// Later, remove the indicator
indicator.remove();
```

### Indicator Options

* `icon` - Font Awesome icon class (e.g., `"fas fa-check"`, `"fas fa-warning"`)
* `description` - Tooltip text shown on hover

## Extending Editors

You can add CodeMirror extensions to the request editor on the Automate page:

```ts
import { Extension } from "@codemirror/state";

const myExtension: Extension = [
  // Your CodeMirror extension configuration
];

sdk.automate.addRequestEditorExtension(myExtension);
```

For more information on creating editor extensions, see the [Extend Editors](/plugins/guides/editor_extensions.md) guide.

## Adding View Modes

You can add custom request and response view modes to the Automate page:

### Request View Modes

```ts
sdk.automate.addRequestViewMode({
  label: "My Custom View",
  view: {
    component: MyComponent,
  },
});
```

### Response View Modes

```ts
sdk.automate.addResponseViewMode({
  label: "My Custom Response View",
  view: {
    component: MyResponseComponent,
  },
});
```

For more information on creating view modes, see the [Add View Modes](/plugins/guides/view_modes.md) guide.

## Page Context

You can access the Automate page context to get information about the current state:

```ts
const context = sdk.window.getPageContext();
if (context?.kind === "Automate") {
  // Access Automate-specific context
  const { selection, requestSelection } = context;
}
```

The Automate page context includes:

* `kind` - Always `"Automate"`
* `selection` - Current selection of sessions or entries
* `requestSelection` - Current request selection

## Examples

### Session Monitor Plugin

This example creates a plugin that monitors automate sessions and adds indicators to entries based on custom criteria:

```ts
import type { Caido } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  const checkEntries = () => {
    const sessions = sdk.automate.getSessions();
    
    sessions.forEach((session) => {
      const entries = sdk.automate.getEntries(session.id);
      
      entries.forEach((entry) => {
        // Add indicator for entries created in the last hour
        const oneHourAgo = Date.now() - 60 * 60 * 1000;
        if (entry.createdAt.getTime() > oneHourAgo) {
          sdk.automate.addEntryIndicator(entry.id, {
            icon: "fas fa-clock",
            description: "Recently created",
          });
        }
      });
    });
  };

  // Check entries periodically
  setInterval(checkEntries, 60000); // Every minute
  
  // Initial check
  checkEntries();
};
```

### Custom Request Analyzer

This example adds a custom view mode to analyze automate requests:

```vue
<script setup lang="ts">
import { computed } from "vue";
import type { Caido, RequestFull } from "@caido/sdk-frontend";

const props = defineProps<{
  sdk: Caido;
  request: RequestFull;
}>();

const analysis = computed(() => {
  const body = props.request.body || "";
  const headers = props.request.headers || {};
  
  return {
    bodySize: body.length,
    hasAuth: !!headers.authorization,
    method: props.request.method,
  };
});
</script>

<template>
  <div class="p-4">
    <h3 class="font-bold mb-2">Request Analysis</h3>
    <div class="space-y-1">
      <div>Body Size: {{ analysis.bodySize }} bytes</div>
      <div>Has Auth: {{ analysis.hasAuth ? "Yes" : "No" }}</div>
      <div>Method: {{ analysis.method }}</div>
    </div>
  </div>
</template>
```

```ts
import type { Caido } from "@caido/sdk-frontend";
import RequestAnalyzer from "./RequestAnalyzer.vue";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  sdk.automate.addRequestViewMode({
    label: "Request Analyzer",
    view: {
      component: RequestAnalyzer,
    },
  });
};
```

---

---
url: /client-sdk/guides/manage_findings.md
---
# Manage Findings

The Client SDK exposes the findings stored in the current Caido project through `client.finding`. Findings are security observations attached to a specific request. You can list them, look one up by ID, and create or update them from a script.

::: info
Findings are project-scoped. A project must be open on the instance for any of these calls to succeed.
:::

## List Findings

To list findings, start a chain with `client.finding.list()` and await it. The result is a `Connection<Finding>` with `pageInfo` (cursors) and `edges`:

```ts
const page = await client.finding.list().first(10);

for (const edge of page.edges) {
  const f = edge.node;
  console.log(`[${f.reporter}] ${f.title} at ${f.host}${f.path}`);
}
```

The `Finding` shape includes `id`, `requestId`, `title`, `reporter`, `description`, `dedupeKey`, `host`, `path`, `hidden`, and `createdAt`.

## Filter by Reporter

To narrow the list, chain `.filter({ reporter: "<name>" })`. This is the only filter field currently supported on findings:

```ts
const mine = await client.finding
  .list()
  .filter({ reporter: "my-plugin" })
  .first(50);

console.log(`Got ${mine.edges.length} finding(s) from "my-plugin"`);
```

## Order Results

To control sort order, chain `.order({ by, ordering })`. The `by` field is one of `"CREATED_AT"`, `"HOST"`, `"ID"`, `"PATH"`, `"REPORTER"`, `"TITLE"`, and `ordering` is `"ASC"` or `"DESC"`:

```ts
const latest = await client.finding
  .list()
  .order({ by: "CREATED_AT", ordering: "DESC" })
  .first(10);
```

## Paginate

To walk through more findings than fit in a single page, call `.next()` on the returned connection. It returns the next page or `undefined` when there are no more:

```ts
let page = await client.finding.list().first(50);
while (page) {
  for (const edge of page.edges) {
    // process edge.node
  }
  page = await page.next();
}
```

## Get a Single Finding

To fetch one finding when you already know its ID, use `client.finding.get(id)`. It returns the `Finding` directly, or `undefined` when the finding does not exist:

```ts
const finding = await client.finding.get("1");
if (finding === undefined) {
  throw new Error("Finding not found");
}

console.log(finding.title, "->", finding.description);
```

## Create a Finding

To create a new finding tied to an existing request, use `client.finding.create(requestId, options)`. The `host` and `path` are pulled automatically from the request:

```ts
const finding = await client.finding.create("1", {
  title: "Potential SSRF",
  reporter: "my-scanner",
  description: "The `redirect_url` parameter is reflected in an outbound request.",
  dedupeKey: "ssrf:/canonical.html:redirect_url",
});

console.log("Created finding", finding.id);
```

The `dedupeKey` is optional but recommended for automated scanners: Caido uses it to skip creating duplicate findings on subsequent runs.

## Update a Finding

To change a finding's title, description, or hidden state, use `client.finding.update(id, options)`. All three fields are required, so fetch the finding first if you only want to change one:

```ts
const current = await client.finding.get("1");
if (current === undefined) {
  throw new Error("Finding not found");
}

await client.finding.update(current.id, {
  title: current.title,
  description: "Updated description with reproduction steps.",
  hidden: current.hidden,
});
```

## Examples

The script below lists every finding in the project, ordered by creation time, and paginates through the full list:

### index.ts

```ts
import { Client } from "@caido/sdk-client";

async function main() {
  const client = new Client({
    url: process.env["CAIDO_INSTANCE_URL"] ?? "http://localhost:8080",
    auth: {
      pat: process.env["CAIDO_PAT"]!,
      cache: { file: ".caido-token.json" },
    },
  });

  await client.connect();

  let page = await client.finding
    .list()
    .order({ by: "CREATED_AT", ordering: "DESC" })
    .first(50);

  let total = 0;
  while (page) {
    for (const edge of page.edges) {
      const f = edge.node;
      console.log(`[${f.createdAt.toISOString()}] ${f.title} - ${f.host}${f.path}`);
      total++;
    }
    page = await page.next();
  }

  console.log(`\nTotal: ${total} finding(s)`);
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});
```

Run it with:

```bash
export CAIDO_PAT=caido_xxxxx
npx tsx ./index.ts
```

A successful run prints one line per finding followed by a total count:

```txt
[caido] Attempting to load cached token
[caido] Loaded token from cache
[2026-05-11T14:02:04.976Z] SDK test finding (updated) - detectportal.firefox.com/canonical.html
[2026-05-11T13:53:58.784Z] SDK test finding (updated) - detectportal.firefox.com/canonical.html

Total: 2 finding(s)
```

---

---
url: /plugins/guides/match_replace.md
---
# Manage Match and Replace

Match and Replace rules allow you to automatically modify HTTP requests and responses based on matching conditions. You can programmatically create, manage, and control match and replace rules and collections.

## Collection Management

### Creating a Collection

To create a new match and replace collection:

```ts
const collection = await sdk.matchReplace.createCollection({
  name: "My Collection",
});
```

### Getting Collections

To retrieve all collections:

```ts
const collections = sdk.matchReplace.getCollections();
```

### Updating a Collection

To update a collection:

```ts
const updated = await sdk.matchReplace.updateCollection(collectionId, {
  name: "Updated Collection Name",
});
```

### Deleting a Collection

To delete a collection:

```ts
await sdk.matchReplace.deleteCollection(collectionId);
```

## Rule Management

### Creating a Rule

To create a new match and replace rule:

```ts
const rule = await sdk.matchReplace.createRule({
  collectionId: collection.id,
  name: "My Rule",
  query: "resp.code.eq:200",
  section: "RequestHeaders",
});
```

The `section` parameter specifies which part of the request/response to match and replace (e.g., `RequestHeaders`, `ResponseBody`, etc.).

### Getting Rules

To retrieve all rules:

```ts
const rules = sdk.matchReplace.getRules();
```

### Getting Active Rules

To get only the active (enabled) rules:

```ts
const activeRules = sdk.matchReplace.getActiveRules();
```

Rules are returned in priority order from highest to lowest.

::: info
Active rules are processed in priority order. Higher priority rules are applied first. Use `getActiveRules()` to see the processing order.
:::

### Updating a Rule

To update a rule:

```ts
const updated = await sdk.matchReplace.updateRule(ruleId, {
  name: "Updated Rule Name",
  query: "resp.code.eq:404",
  section: "ResponseBody",
});
```

### Deleting a Rule

To delete a rule:

```ts
await sdk.matchReplace.deleteRule(ruleId);
```

### Toggling a Rule

To enable or disable a rule:

```ts
await sdk.matchReplace.toggleRule(ruleId, true); // Enable
await sdk.matchReplace.toggleRule(ruleId, false); // Disable
```

### Selecting a Rule

To select a rule for display in the UI:

```ts
sdk.matchReplace.selectRule(ruleId);
```

To clear the selection:

```ts
sdk.matchReplace.selectRule(undefined);
```

### Getting the Current Rule

To get the currently selected rule:

```ts
const currentRule = sdk.matchReplace.getCurrentRule();
```

Returns the currently selected rule, or `undefined` if no rule is selected.

### Subscribing to Rule Changes

To subscribe to changes in the currently selected rule:

```ts
const handler = sdk.matchReplace.onCurrentRuleChange((event) => {
  console.log(`Rule ${event.ruleId} got selected!`);
});

// Later, stop listening
handler.stop();
```

The callback receives an event object with a `ruleId` property that contains the ID of the newly selected rule, or `undefined` if no rule is selected.

::: info
The subscription handler returns an object with a `stop()` method that can be called to unsubscribe from rule changes.
:::

## Adding Components to Match and Replace Slots

You can add custom components to match and replace slots to extend the Match and Replace page UI. Available slots are:

* `MatchReplaceSlot.CreateHeader` - The header area of the rule form create component
* `MatchReplaceSlot.UpdateHeader` - The header area of the rule form update component

### Adding a Button to a Slot

Add a button with a label, icon, and click handler:

```ts
import { MatchReplaceSlot } from "@caido/sdk-frontend";

sdk.matchReplace.addToSlot(MatchReplaceSlot.UpdateHeader, {
  type: "Button",
  label: "My Button",
  icon: "my-icon",
  onClick: () => {
    console.log("Button clicked");
  },
});
```

### Adding a Command to a Slot

Add a button that triggers a registered command:

```ts
import { MatchReplaceSlot } from "@caido/sdk-frontend";

// First register the command
sdk.commands.register("my-command", {
  name: "My Command",
  run: () => {
    sdk.window.showToast("Command executed", { variant: "info" });
  },
});

// Then add to slot
sdk.matchReplace.addToSlot(MatchReplaceSlot.UpdateHeader, {
  type: "Command",
  commandId: "my-command",
  icon: "my-icon",
});
```

### Adding a Custom Component to a Slot

Add a custom Vue component:

```ts
import { MatchReplaceSlot } from "@caido/sdk-frontend";
import MyComponent from "./MyComponent.vue";

sdk.matchReplace.addToSlot(MatchReplaceSlot.CreateHeader, {
  type: "Custom",
  definition: MyComponent,
});
```

## Examples

### Auto-Enable Rules

This example automatically enables all rules in a specific collection named "Auto Rules" when the plugin initializes. It finds the collection, filters rules belonging to it, and enables any that are currently disabled.

```ts
import type { Caido } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  // Get all active rules
  const activeRules = sdk.matchReplace.getActiveRules();
  sdk.log.info(`Found ${activeRules.length} active rules`);

  // Enable all rules in a specific collection
  const collections = sdk.matchReplace.getCollections();
  const targetCollection = collections.find((c) => c.name === "Auto Rules");

  if (targetCollection) {
    const allRules = sdk.matchReplace.getRules();
    const collectionRules = allRules.filter((r) =>
      targetCollection.ruleIds.includes(r.id)
    );

    collectionRules.forEach(async (rule) => {
      if (!rule.enabled) {
        await sdk.matchReplace.toggleRule(rule.id, true);
        sdk.log.info(`Enabled rule: ${rule.name}`);
      }
    });
  }
};
```

### Rule Priority Management

This example demonstrates how to access and log rule priority information. It retrieves all active rules (which are automatically sorted by priority) and logs each rule's name and priority value.

```ts
import type { Caido } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  // Get active rules (already sorted by priority)
  const activeRules = sdk.matchReplace.getActiveRules();

  activeRules.forEach((rule, index) => {
    sdk.log.info(`Rule ${index + 1}: ${rule.name} (Priority: ${rule.priority})`);
  });
};
```

### Tracking Current Rule Changes

This example subscribes to rule selection changes and logs information about the currently selected rule whenever it changes.

```ts
import type { Caido } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  const handler = sdk.matchReplace.onCurrentRuleChange((event) => {
    if (event.ruleId) {
      const rule = sdk.matchReplace.getCurrentRule();
      if (rule) {
        sdk.log.info(`Rule selected: ${rule.name}`);
        sdk.log.info(`Query: ${rule.query}`);
        sdk.log.info(`Enabled: ${rule.isEnabled}`);
      }
    } else {
      sdk.log.info("No rule selected");
    }
  });

  // Store handler for cleanup if needed
  // handler.stop();
};
```

## Adding Indicators to Rules

Indicators are visual badges displayed next to rule names in the collections tree. They're useful for highlighting important rules or showing status information.

### Adding a Rule Indicator

```ts
const indicator = sdk.matchReplace.addRuleIndicator(ruleId, {
  icon: "fas fa-exclamation-triangle",
  description: "Security warning",
});
```

The `addRuleIndicator` method returns a handle object with a `remove` method to remove the indicator later:

```ts
// Later, remove the indicator
indicator.remove();
```

### Indicator Options

* `icon` - Font Awesome icon class (e.g., `"fas fa-check"`, `"fas fa-warning"`)
* `description` - Tooltip text shown on hover

### Example: Rule Status Indicators

This example adds indicators to rules based on their enabled status:

```ts
import type { Caido } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  const updateRuleIndicators = () => {
    const rules = sdk.matchReplace.getRules();
    
    rules.forEach((rule) => {
      if (rule.isEnabled) {
        sdk.matchReplace.addRuleIndicator(rule.id, {
          icon: "fas fa-check-circle",
          description: "Rule is enabled",
        });
      } else {
        sdk.matchReplace.addRuleIndicator(rule.id, {
          icon: "fas fa-circle",
          description: "Rule is disabled",
        });
      }
    });
  };

  // Update indicators when rules change
  sdk.matchReplace.onCurrentRuleChange(() => {
    updateRuleIndicators();
  });

  // Initial update
  updateRuleIndicators();
};
```

### Adding Custom Actions to Match and Replace Slots

This example adds a custom button to the rule update header that duplicates the current rule when clicked.

```ts
import type { Caido } from "@caido/sdk-frontend";
import { MatchReplaceSlot } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  sdk.matchReplace.addToSlot(MatchReplaceSlot.UpdateHeader, {
    type: "Button",
    label: "Duplicate Rule",
    icon: "fas fa-copy",
    onClick: async () => {
      const currentRule = sdk.matchReplace.getCurrentRule();
      if (currentRule) {
        const duplicated = await sdk.matchReplace.createRule({
          collectionId: currentRule.collectionId,
          name: `${currentRule.name} (Copy)`,
          query: currentRule.query,
          section: currentRule.section,
          sources: [],
        });
        sdk.window.showToast(`Rule "${duplicated.name}" created`, {
          variant: "success",
        });
      } else {
        sdk.window.showToast("No rule selected", { variant: "warning" });
      }
    },
  });
};
```

---

---
url: /plugins/guides/replay.md
---
# Manage Replay Sessions

Replay sessions allow you to replay HTTP requests, and collections help organize related sessions. You can programmatically create, manage, and interact with replay sessions and collections.

## Session Management

### Creating a Session

To create a new replay session:

```ts
await sdk.replay.createSession(source, collectionId);
```

The `source` parameter is a `RequestSource` object that can either be a raw HTTP request (with `type: "Raw"`, `raw` string, and `connectionInfo`) or a reference to an existing request by ID (with `type: "ID"` and `id` string). The optional `collectionId` adds the session to a specific collection.

### Getting Sessions

To retrieve all replay sessions:

```ts
const sessions = sdk.replay.getSessions();
```

### Renaming a Session

To rename a session:

```ts
await sdk.replay.renameSession(sessionId, "New Session Name");
```

### Deleting Sessions

To delete one or more sessions:

```ts
const deletedIds = await sdk.replay.deleteSessions([sessionId1, sessionId2]);
```

Returns an array of IDs that were successfully deleted.

## Collection Management

### Creating a Collection

To create a new collection:

```ts
const collection = await sdk.replay.createCollection("My Collection");
```

::: tip
Use collections to organize related replay sessions, making it easier to manage and find specific sessions for testing scenarios.
:::

### Getting Collections

To retrieve all collections:

```ts
const collections = sdk.replay.getCollections();
```

### Renaming a Collection

To rename a collection:

```ts
await sdk.replay.renameCollection(collectionId, "New Collection Name");
```

### Deleting a Collection

To delete a collection:

```ts
const deleted = await sdk.replay.deleteCollection(collectionId);
```

Returns `true` if the collection was successfully deleted.

::: warning
Deleting a collection does not delete the sessions it contains. Sessions are moved to the default location when their collection is deleted.
:::

## Tab Management

### Getting Tabs

To get all open replay tabs:

```ts
const tabs = sdk.replay.getTabs();
```

### Opening a Tab

To open a session in a new tab:

```ts
sdk.replay.openTab(sessionId, { select: true });
```

The `select` option (default: `true`) determines whether to select the tab after opening it.

### Closing a Tab

To close a tab:

```ts
sdk.replay.closeTab(sessionId);
```

## Sending Requests

To send a request to the Replay backend:

```ts
await sdk.replay.sendRequest(requestId);
```

## Subscribing to Session Changes

To listen for changes to the current replay session:

```ts
const handler = sdk.replay.onCurrentSessionChange((event) => {
  console.log("Session changed to:", event.sessionId);
});

// Later, stop listening
handler.stop();
```

## Adding Indicators to Sessions

Indicators are visual badges displayed next to session names in the collections tree. They're useful for highlighting important sessions or showing status information.

### Adding a Session Indicator

```ts
const indicator = sdk.replay.addSessionIndicator(sessionId, {
  icon: "fas fa-exclamation-triangle",
  description: "Security warning",
});
```

The `addSessionIndicator` method returns a handle object with a `remove` method to remove the indicator later:

```ts
// Later, remove the indicator
indicator.remove();
```

### Indicator Options

* `icon` - Font Awesome icon class (e.g., `"fas fa-check"`, `"fas fa-warning"`)
* `description` - Tooltip text shown on hover

## Adding Response View Modes

You can add custom response view modes to the Replay page:

```ts
sdk.replay.addResponseViewMode({
  label: "My Custom Response View",
  view: {
    component: MyResponseComponent,
  },
});
```

For more information on creating response view modes, see the [Add View Modes](/plugins/guides/view_modes.md) guide.

::: info
Sessions and collections are persisted across Caido restarts, so programmatically created items will remain available.
:::

## Examples

### Session Manager Plugin

This example creates a comprehensive session and collection management interface. It displays all replay sessions and collections, allows opening sessions in tabs, creating new collections, and deleting items. It also subscribes to session change events.

```ts
import { Classic } from "@caido/primevue";
import PrimeVue from "primevue/config";
import { createApp } from "vue";

import type { Caido } from "@caido/sdk-frontend";

import App from "./views/App.vue";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  const app = createApp(App);
  
  app.provide("sdk", sdk);
  
  app.use(PrimeVue, {
    unstyled: true,
    pt: Classic,
  });

  const root = document.createElement("div");
  Object.assign(root.style, {
    height: "100%",
    width: "100%",
  });

  app.mount(root);

  sdk.navigation.addPage("/replay-manager", {
    body: root,
  });

  // Listen for session changes
  sdk.replay.onCurrentSessionChange((event) => {
    sdk.log.info("Current session changed to:", event.sessionId);
  });
};
```

```vue
<script setup lang="ts">
import Button from "primevue/button";
import { inject, onMounted, ref } from "vue";

import type { CaidoSDK } from "../index";

const sdk = inject<CaidoSDK>("sdk");

const sessions = ref<Array<{ id: string; name?: string }>>([]);
const collections = ref<Array<{ id: string; name: string; sessionIds: string[] }>>([]);

const refreshSessions = () => {
  if (!sdk) return;
  sessions.value = sdk.replay.getSessions();
};

const refreshCollections = () => {
  if (!sdk) return;
  collections.value = sdk.replay.getCollections();
};

const openSession = (sessionId: string) => {
  if (!sdk) return;
  sdk.replay.openTab(sessionId);
  sdk.navigation.goTo({ id: "replay" });
};

const deleteSession = async (sessionId: string) => {
  if (!sdk) return;
  await sdk.replay.deleteSessions([sessionId]);
  refreshSessions();
  sdk.window.showToast("Session deleted", { variant: "success" });
};

const createCollection = async () => {
  if (!sdk) return;
  const collection = await sdk.replay.createCollection(`Collection ${Date.now()}`);
  if (collection) {
    refreshCollections();
    sdk.window.showToast("Collection created", { variant: "success" });
  }
};

const deleteCollection = async (collectionId: string) => {
  if (!sdk) return;
  await sdk.replay.deleteCollection(collectionId);
  refreshCollections();
  sdk.window.showToast("Collection deleted", { variant: "success" });
};

onMounted(() => {
  refreshSessions();
  refreshCollections();
});
</script>

<template>
  <div class="h-full flex flex-col p-4 gap-4 overflow-auto">
    <div>
      <h2 class="text-lg font-bold mb-2">Collections</h2>
      <Button label="Create Collection" @click="createCollection" class="mb-2" />
      <div v-if="collections.length === 0" class="text-gray-400">No collections found</div>
      <div v-else class="flex flex-col gap-2">
        <div
          v-for="collection in collections"
          :key="collection.id"
          class="p-2 border border-gray-600 rounded"
        >
          <h3 class="font-bold mb-1">{{ collection.name }}</h3>
          <p class="text-sm text-gray-400">{{ collection.sessionIds.length }} sessions</p>
          <Button
            label="Delete"
            severity="secondary"
            size="small"
            class="mt-2"
            @click="deleteCollection(collection.id)"
          />
        </div>
      </div>
    </div>
    <div>
      <h2 class="text-lg font-bold mb-2">Sessions</h2>
      <div v-if="sessions.length === 0" class="text-gray-400">No sessions found</div>
      <div v-else class="flex flex-col gap-2">
        <div
          v-for="session in sessions"
          :key="session.id"
          class="p-2 border border-gray-600 rounded"
        >
          <h3 class="font-bold mb-1">{{ session.name || `Session ${session.id}` }}</h3>
          <div class="flex gap-2 mt-2">
            <Button
              label="Open"
              size="small"
              @click="openSession(session.id)"
            />
            <Button
              label="Delete"
              severity="secondary"
              size="small"
              @click="deleteSession(session.id)"
            />
          </div>
        </div>
      </div>
    </div>
  </div>
</template>
```

### Auto-Organize Sessions

This example automatically organizes replay sessions by creating or finding a collection called "Automated Sessions" and listening for session changes to potentially move sessions into this collection.

```ts
import type { Caido } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  // Create a collection for automated sessions
  let autoCollectionId: string | undefined;

  const initializeCollection = async () => {
    const collections = sdk.replay.getCollections();
    let collection = collections.find((c) => c.name === "Automated Sessions");

    if (!collection) {
      collection = await sdk.replay.createCollection("Automated Sessions");
    }

    if (collection) {
      autoCollectionId = collection.id;
    }
  };

  // When a session is created, add it to the collection
  sdk.replay.onCurrentSessionChange(async (event) => {
    if (event.sessionId && autoCollectionId) {
      // Move session to collection (if not already there)
      const sessions = sdk.replay.getSessions();
      const session = sessions.find((s) => s.id === event.sessionId);
      if (session) {
        // Session management logic here
        sdk.log.info("Session organized:", event.sessionId);
      }
    }
  });

  initializeCollection();
};
```

---

---
url: /plugins/guides/scopes.md
---
# Manage Scopes

Scopes define which requests and responses are included or excluded from various operations in Caido. You can programmatically create, update, delete, and query scopes, as well as set the active scope on different pages.

::: tip
Use scopes to filter requests programmatically across different pages. This is useful for automation and workflow management.
:::

## Creating and Managing Scopes

### Creating a Scope

Create a new scope using `sdk.scopes.createScope()`. The `allowlist` specifies URLs that should be included, while `denylist` specifies URLs that should be excluded. Both support wildcard patterns.

```ts
const scope = await sdk.scopes.createScope({
  name: "My Scope",
  allowlist: ["*example.com", "*github.com"],
  denylist: ["*caido.io"],
});
```

### Getting All Scopes

Retrieve all available scopes using `sdk.scopes.getScopes()`:

```ts
const scopes = sdk.scopes.getScopes();
```

### Updating a Scope

Update an existing scope by providing the scope ID and the fields you want to change. You can update the name, allowlist, or denylist. All fields are optional.

```ts
const updatedScope = await sdk.scopes.updateScope(scopeId, {
  name: "Updated Scope Name",
  allowlist: ["*example.com"],
  denylist: ["*caido.io", "*test.com"],
});
```

### Deleting a Scope

Delete a scope by its ID. The method returns `true` if the scope was successfully deleted.

```ts
const deleted = await sdk.scopes.deleteScope(scopeId);
```

### Getting the Current Scope

To get the currently selected scope:

```ts
const currentScope = sdk.scopes.getCurrentScope();
```

Returns the currently selected scope, or `undefined` if no scope is selected.

### Subscribing to Scope Changes

To subscribe to changes in the currently selected scope:

```ts
const handler = sdk.scopes.onCurrentScopeChange((event) => {
  console.log(`Scope ${event.scopeId} got selected!`);
});

// Later, stop listening
handler.stop();
```

The callback receives an event object with a `scopeId` property that contains the ID of the newly selected scope, or `undefined` if no scope is selected.

::: info
The subscription handler returns an object with a `stop()` method that can be called to unsubscribe from scope changes.
:::

## Adding Components to Scope Slots

You can add custom components to scope slots to extend the Scopes page UI. Available slots are:

* `ScopeSlot.CreateHeader` - The header area of the preset form create component, to the left of the ScopeTooltip
* `ScopeSlot.UpdateHeader` - The header area of the preset form update component, to the left of the ScopeTooltip

### Adding a Button to a Slot

Add a button with a label, icon, and click handler:

```ts
import { ScopeSlot } from "@caido/sdk-frontend";

sdk.scopes.addToSlot(ScopeSlot.UpdateHeader, {
  type: "Button",
  label: "My Button",
  icon: "my-icon",
  onClick: () => {
    console.log("Button clicked");
  },
});
```

### Adding a Command to a Slot

Add a button that triggers a registered command:

```ts
import { ScopeSlot } from "@caido/sdk-frontend";

// First register the command
sdk.commands.register("my-command", {
  name: "My Command",
  run: () => {
    sdk.window.showToast("Command executed", { variant: "info" });
  },
});

// Then add to slot
sdk.scopes.addToSlot(ScopeSlot.UpdateHeader, {
  type: "Command",
  commandId: "my-command",
  icon: "my-icon",
});
```

### Adding a Custom Component to a Slot

Add a custom Vue component:

```ts
import { ScopeSlot } from "@caido/sdk-frontend";
import MyComponent from "./MyComponent.vue";

sdk.scopes.addToSlot(ScopeSlot.CreateHeader, {
  type: "Custom",
  definition: MyComponent,
});
```

## Setting Scopes on Different Pages

Different pages in Caido provide scope operations specific to their context. You can get the current scope ID and set a new scope for each page.

### Setting Scope on HTTP History

Get the current scope ID or set a new scope for the HTTP History page:

```ts
// Get current scope
const currentScopeId = sdk.httpHistory.getScopeId();

// Set scope
await sdk.httpHistory.setScope(scopeId);
```

### Setting Scope on Search

Get the current scope ID or set a new scope for the Search page:

```ts
// Get current scope
const currentScopeId = sdk.search.getScopeId();

// Set scope
await sdk.search.setScope(scopeId);
```

### Setting Scope on Sitemap

Get the current scope ID or set a new scope for the Sitemap page:

```ts
// Get current scope
const currentScopeId = sdk.sitemap.getScopeId();

// Set scope
await sdk.sitemap.setScope(scopeId);
```

### Setting Scope on Intercept

Get the current scope ID or set a new scope for the Intercept page:

```ts
// Get current scope
const currentScopeId = sdk.intercept.getScopeId();

// Set scope
sdk.intercept.setScope(scopeId);
```

::: info
Scope operations on different pages may have different return types. HTTP History and Search return promises, while Intercept returns void.
:::

## Using Wildcard Patterns

Scope allowlists and denylists support wildcard patterns to match multiple URLs:

* `*example.com` - Matches any subdomain of example.com
* `example.com` - Matches exactly example.com
* `*` - Matches everything (when used in allowlist)

Create a scope with wildcard patterns to filter production URLs while excluding test and development environments:

```ts
const scope = await sdk.scopes.createScope({
  name: "Production Scope",
  allowlist: ["*prod.example.com", "*api.example.com"],
  denylist: ["*test.example.com", "*dev.example.com"],
});
```

## Examples

### Scope Management Plugin

This example creates a scope management interface that lists all scopes with their allowlists and denylists. It provides buttons to create new scopes and delete existing ones, with automatic list refreshing.

```ts
import { Classic } from "@caido/primevue";
import PrimeVue from "primevue/config";
import { createApp } from "vue";

import type { Caido } from "@caido/sdk-frontend";

import App from "./views/App.vue";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  const app = createApp(App);
  
  app.provide("sdk", sdk);
  
  app.use(PrimeVue, {
    unstyled: true,
    pt: Classic,
  });

  const root = document.createElement("div");
  Object.assign(root.style, {
    height: "100%",
    width: "100%",
  });

  app.mount(root);

  sdk.navigation.addPage("/scope-manager", {
    body: root,
  });
};
```

```vue
<script setup lang="ts">
import Button from "primevue/button";
import { inject, onMounted, ref } from "vue";

import type { CaidoSDK } from "../index";

const sdk = inject<CaidoSDK>("sdk");
const scopes = ref<Array<{ id: string; name: string; allowlist: string[]; denylist: string[] }>>([]);

const refreshScopes = () => {
  if (!sdk) return;
  scopes.value = sdk.scopes.getScopes();
};

const createScope = async () => {
  if (!sdk) return;
  const scope = await sdk.scopes.createScope({
    name: `Scope ${Date.now()}`,
    allowlist: ["*example.com"],
    denylist: [],
  });
  if (scope) {
    refreshScopes();
    sdk.window.showToast("Scope created", { variant: "success" });
  }
};

const deleteScope = async (id: string) => {
  if (!sdk) return;
  await sdk.scopes.deleteScope(id);
  refreshScopes();
  sdk.window.showToast("Scope deleted", { variant: "success" });
};

onMounted(() => {
  refreshScopes();
});
</script>

<template>
  <div class="h-full flex flex-col p-4 gap-4">
    <Button label="Create New Scope" @click="createScope" />
    <div v-if="scopes.length === 0" class="text-gray-400">No scopes found</div>
    <div v-else class="flex flex-col gap-2">
      <div
        v-for="scope in scopes"
        :key="scope.id"
        class="p-2 border border-gray-600 rounded"
      >
        <h3 class="font-bold mb-1">{{ scope.name }}</h3>
        <p class="text-sm text-gray-400">Allowlist: {{ scope.allowlist.join(", ") }}</p>
        <p class="text-sm text-gray-400">Denylist: {{ scope.denylist.join(", ") }}</p>
        <Button
          label="Delete"
          severity="secondary"
          size="small"
          class="mt-2"
          @click="deleteScope(scope.id)"
        />
      </div>
    </div>
  </div>
</template>
```

### Setting Scope on Page Navigation

This example automatically sets a specific scope when navigating to the HTTP History page. It creates or finds a scope named "Auto Scope" and applies it whenever the user visits HTTP History.

```ts
import type { Caido } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  // Get or create a scope
  let targetScopeId: string | undefined;

  const initializeScope = async () => {
    const scopes = sdk.scopes.getScopes();
    let scope = scopes.find((s) => s.name === "Auto Scope");

    if (!scope) {
      scope = await sdk.scopes.createScope({
        name: "Auto Scope",
        allowlist: ["*example.com"],
        denylist: [],
      });
    }

    if (scope) {
      targetScopeId = scope.id;
    }
  };

  // Set scope when navigating to HTTP History
  sdk.navigation.onPageChange(async (event) => {
    if (event.routeId === "http-history" && targetScopeId) {
      await sdk.httpHistory.setScope(targetScopeId);
      sdk.log.info("Scope set for HTTP History");
    }
  });

  initializeScope();
};
```

### Tracking Current Scope Changes

This example subscribes to scope selection changes and logs information about the currently selected scope whenever it changes.

```ts
import type { Caido } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  const handler = sdk.scopes.onCurrentScopeChange((event) => {
    if (event.scopeId) {
      const scope = sdk.scopes.getCurrentScope();
      if (scope) {
        sdk.log.info(`Scope selected: ${scope.name}`);
        sdk.log.info(`Allowlist: ${scope.allowlist.join(", ")}`);
        sdk.log.info(`Denylist: ${scope.denylist.join(", ")}`);
      }
    } else {
      sdk.log.info("No scope selected");
    }
  });

  // Store handler for cleanup if needed
  // handler.stop();
};
```

### Adding Custom Actions to Scope Slots

This example adds a custom button to the scope update header that duplicates the current scope when clicked.

```ts
import type { Caido } from "@caido/sdk-frontend";
import { ScopeSlot } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  sdk.scopes.addToSlot(ScopeSlot.UpdateHeader, {
    type: "Button",
    label: "Duplicate Scope",
    icon: "fas fa-copy",
    onClick: async () => {
      const currentScope = sdk.scopes.getCurrentScope();
      if (currentScope) {
        const duplicated = await sdk.scopes.createScope({
          name: `${currentScope.name} (Copy)`,
          allowlist: [...currentScope.allowlist],
          denylist: [...currentScope.denylist],
        });
        if (duplicated) {
          sdk.window.showToast(`Scope "${duplicated.name}" created`, {
            variant: "success",
          });
        }
      } else {
        sdk.window.showToast("No scope selected", { variant: "warning" });
      }
    },
  });
};
```

---

---
url: /plugins/guides/sitemap.md
---
# Manage Sitemap

The Sitemap SDK allows you to interact with the Sitemap page, manage entries, work with the tree structure, control scope, add indicators, and extend editors with custom functionality.

## Entry Management

### Getting Tree Entries

To retrieve all sitemap entries in tree format:

```ts
const entries = sdk.sitemap.getTreeEntries();
```

This returns root entries (`SitemapRootEntry`) that contain the full tree structure. Each entry has:

* `id` - The unique identifier
* `label` - The display label
* `kind` - The entry type (Domain, Directory, Request, etc.)
* `parentId` - Optional parent entry ID
* `childState` - Whether children are loaded, loading, or not loaded

### Loading Children

To load children for a specific entry (if they haven't been loaded yet):

```ts
const children = await sdk.sitemap.getChildren(entryId);
```

This will fetch and load children asynchronously if they haven't been loaded yet.

## Entry Kinds

Sitemap entries can be of different kinds:

```ts
import { SitemapEntryKind } from "@caido/sdk-frontend";

// Available kinds:
SitemapEntryKind.Domain      // "DOMAIN"
SitemapEntryKind.Directory   // "DIRECTORY"
SitemapEntryKind.Request     // "REQUEST"
SitemapEntryKind.RequestBody // "REQUEST_BODY"
SitemapEntryKind.RequestQuery // "REQUEST_QUERY"
```

## Scope Management

### Getting Current Scope

To get the current scope ID:

```ts
const scopeId = sdk.sitemap.getScopeId();
```

Returns `undefined` if no scope is currently set.

### Setting Scope

To set the current scope:

```ts
await sdk.sitemap.setScope(scopeId);
```

Pass `undefined` to clear the current scope.

::: tip
For more information on scopes, see the [Scopes](/plugins/guides/scopes.md) guide.
:::

## Adding Indicators

Indicators are visual badges displayed next to entry names in the sitemap tree. They're useful for highlighting important entries or showing status information.

### Adding an Entry Indicator

```ts
const indicator = sdk.sitemap.addEntryIndicator(entryId, {
  icon: "fas fa-exclamation-triangle",
  description: "Security warning",
});
```

The `addEntryIndicator` method returns a handle object with a `remove` method to remove the indicator later:

```ts
// Later, remove the indicator
indicator.remove();
```

## Listening to Child State Updates

You can listen for changes to entry child states (when children are loaded, loading, etc.):

```ts
const handle = sdk.sitemap.onEntryChildStateUpdate((event) => {
  console.log(`Entry ${event.entryId} child state changed:`, event.newChildState);
});

// Later, stop listening
handle.stop();
```

The event contains:

* `entryId` - The ID of the entry that changed
* `newChildState` - The new child state (`"LOADED"`, `"LOADING"`, or `"NOT_LOADED"`)

## Extending Editors

You can add CodeMirror extensions to the request editor on the Sitemap page:

```ts
import { Extension } from "@codemirror/state";

const myExtension: Extension = [
  // Your CodeMirror extension configuration
];

sdk.sitemap.addRequestEditorExtension(myExtension);
```

For more information on creating editor extensions, see the [Extend Editors](/plugins/guides/editor_extensions.md) guide.

## Adding View Modes

You can add custom request and response view modes to the Sitemap page:

### Request View Modes

```ts
sdk.sitemap.addRequestViewMode({
  label: "My Custom View",
  view: {
    component: MyComponent,
  },
});
```

### Response View Modes

```ts
sdk.sitemap.addResponseViewMode({
  label: "My Custom Response View",
  view: {
    component: MyResponseComponent,
  },
});
```

For more information on creating view modes, see the [Add View Modes](/plugins/guides/view_modes.md) guide.

## Page Context

You can access the Sitemap page context to get information about the current state:

```ts
const context = sdk.window.getPageContext();
if (context?.kind === "Sitemap") {
  // Access Sitemap-specific context
  const { entrySelection, requestSelection } = context;
}
```

The Sitemap page context includes:

* `kind` - Always `"Sitemap"`
* `entrySelection` - Current entry selection
* `requestSelection` - Current request selection

## Examples

### Entry Highlighter Plugin

This example adds indicators to entries based on their type:

```ts
import type { Caido } from "@caido/sdk-frontend";
import { SitemapEntryKind } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  const highlightEntries = () => {
    const entries = sdk.sitemap.getTreeEntries();
    
    const processEntry = (entry: any) => {
      // Add indicator for request entries
      if (entry.kind === SitemapEntryKind.Request) {
        sdk.sitemap.addEntryIndicator(entry.id, {
          icon: "fas fa-file-code",
          description: "Request entry",
        });
      }
      
      // Recursively process children if they exist
      if (entry.children) {
        entry.children.forEach(processEntry);
      }
    };
    
    entries.forEach(processEntry);
  };

  // Highlight entries when sitemap is accessed
  sdk.navigation.onPageChange((page) => {
    if (page.id === "sitemap") {
      highlightEntries();
    }
  });
};
```

### Scope-Based Entry Filter

This example monitors scope changes and highlights entries that match the current scope:

```ts
import type { Caido } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  let currentScopeId: string | undefined;
  const indicators = new Map<string, any>();

  const updateHighlights = () => {
    // Remove old indicators
    indicators.forEach((indicator) => indicator.remove());
    indicators.clear();

    if (!currentScopeId) return;

    const entries = sdk.sitemap.getTreeEntries();
    
    const processEntry = (entry: any) => {
      // Add indicator for entries in scope
      // (This is a simplified example - you'd check actual scope matching)
      if (entry.kind === "REQUEST") {
        const indicator = sdk.sitemap.addEntryIndicator(entry.id, {
          icon: "fas fa-check-circle",
          description: "In scope",
        });
        indicators.set(entry.id, indicator);
      }
      
      if (entry.children) {
        entry.children.forEach(processEntry);
      }
    };
    
    entries.forEach(processEntry);
  };

  // Listen for scope changes
  sdk.navigation.onPageChange((page) => {
    if (page.id === "sitemap") {
      const newScopeId = sdk.sitemap.getScopeId();
      if (newScopeId !== currentScopeId) {
        currentScopeId = newScopeId;
        updateHighlights();
      }
    }
  });
};
```

### Child State Monitor

This example monitors child state changes and logs when entries are being loaded:

```ts
import type { Caido } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  const handle = sdk.sitemap.onEntryChildStateUpdate((event) => {
    if (event.newChildState === "LOADING") {
      sdk.log.info(`Loading children for entry: ${event.entryId}`);
    } else if (event.newChildState === "LOADED") {
      sdk.log.info(`Children loaded for entry: ${event.entryId}`);
    }
  });

  // Cleanup on plugin unload (if your plugin supports it)
  // handle.stop();
};
```

---

---
url: /plugins/reference/manifest.md
---
# manifest.json

The `manifest.json` file is the first file that is read by the Caido application when a plugin is installed. It defines the plugin's structure and contains metadata used by the Caido installer.

```json
{
  "id": "authmatrix",
  "name": "AuthMatrix",
  "version": "0.2.0",
  "description": "Grid-based authorization testing across multiple users and roles.",
  "author": {
    "name": "Caido Labs Inc.",
    "email": "dev@caido.io",
    "url": "https://github.com/caido-community/authmatrix"
  },
  "links": {
    "sponsor": "https://patreon.com/..."
  },
  "plugins": [
    {
      "kind": "frontend",
      "id": "authmatrix-frontend",
      "name": "Authmatrix Frontend",
      "entrypoint": "frontend/script.js",
      "style": "frontend/style.css",
      "backend": {
        "id": "authmatrix-backend"
      },
      "assets": "frontend/assets"
    },
    {
      "kind": "backend",
      "id": "authmatrix-backend",
      "name": "Authmatrix Backend",
      "runtime": "javascript",
      "entrypoint": "backend/script.js",
      "assets": "frontend/assets"
    },
    {
      "kind": "workflow",
      "id": "authmatrix-workflow",
      "name": "Authmatrix Workflow",
      "definition": "workflow/definition.json"
    }
  ]
}
```

Here's a summary of each field (**required** fields are marked with an asterisk `*`)

## Main Fields

| Field       | Required | Description                                                                                                                                                                                            |
| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| id          | Yes      | Must be **unique** and must only consist of **lowercase** letters, **numbers**, **hyphens** and **underscores** (\_the order of which must satisfy the regex: `^[a-z][a-z0-9]+(?:[_-][a-z0-9]+)\*$`\_). |
| version     | Yes      | The version of your plugin package. Follows the `MAJOR.MINOR.PATCH` syntax.                                                                                                                            |
| name        | No       | The name of your plugin package. If not supplied, the `id` will be used as the `name`.                                                                                                                 |
| description | No       | A description of the plugin package .                                                                                                                                                                  |
| Author      | No       | See the [author fields](#author-fields).                                                                                                                                                               |
| Links       | No       | See the [links fields](#links-fields)                                                                                                                                                                                 |
| Plugins     | Yes      | Array of plugins. See the [plugin fields](#plugins-fields).                                                                                                                                            |

## Author Fields

The `author` field is optional and may be used for crediting purposes.

| Field | Required | Description                      |
| ----- | -------- | -------------------------------- |
| name  | No       | The name of the author.          |
| email | No       | The email address of the author. |
| url   | No       | A URL to the author's website.   |

## Links Fields

The `links` field is optional and is currently used to provide users with a funding link.

| Field   | Required | Description                             |
| ------- | -------- | --------------------------------------- |
| sponsor | No       | A URL to the project's funding website. |

## Plugins Fields

The `plugins` field is required and must contain an array of plugins.

Plugins can be of type `frontend`, `backend` or `workflow`.

::: tip
You can define multiple plugins of the same type. For example, you can define 3 different frontend plugins that will interact with the same backend plugin.
:::

### Frontend Plugins

| Field      | Required | Description                                                                                                                                                                                                       |
| ---------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| kind       | Yes      | Must be of type `frontend`                                                                                                                                                                                        |
| id         | Yes      | Must be **unique** and must only consist of **lowercase** letters, **numbers**, **hyphens** and **underscores** (\_the order of which must satisfy the regex: `^[a-z][a-z0-9]+(?:[_-][a-z0-9]+)\*$`).              |
| entrypoint | Yes      | Specifies the location of the primary script to be executed when the plugin is launched.                                                                                                                          |
| name       | No       | The cosmetic plugin package name displayed in the [Plugins](https://docs.caido.io/app/quickstart/plugins) table. If not supplied, the `id` will be used as the `name`.                         |
| style      | No       | Specifies the location of the CSS file to be used to stylize elements of your plugin.                                                                                                                             |
| backend    | No       | This object contains the `id` of the associated backend plugin. Specifying this field will allow the frontend plugin to communicate with the backend plugin via [sdk.backend](/plugins/reference/sdks/frontend/#backend). |
| assets     | No       | Extra assets to be bundled with the plugin and loadable at runtime.                                                                                                                                               |

### Backend Plugins

| Field      | Required | Description                                                                                                                                                                                          |
| ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| kind       | Yes      | Must be of type `backend`                                                                                                                                                                            |
| id         | Yes      | Must be **unique** and must only consist of **lowercase** letters, **numbers**, **hyphens** and **underscores** (\_the order of which must satisfy the regex: `^[a-z][a-z0-9]+(?:[_-][a-z0-9]+)\*$`). |
| entrypoint | Yes      | Specifies the location of the primary script to be executed when the plugin is launched.                                                                                                             |
| runtime    | Yes      | Specifies that JavaScript code will be executed.                                                                                                                                                     |
| name       | No       | The name of your plugin. If not supplied, the `id` will be used as the `name`.                                                                                                                       |
| assets     | No       | Extra assets to be bundled with the plugin and loadable at runtime.                                                                                                                                  |

### Workflow Plugins

| Field      | Required | Description                                                                                                                                                                                          |
| ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| kind       | Yes      | Must be of type `workflow`                                                                                                                                                                           |
| id         | Yes      | Must be **unique** and must only consist of **lowercase** letters, **numbers**, **hyphens** and **underscores** (\_the order of which must satisfy the regex: `^[a-z][a-z0-9]+(?:[_-][a-z0-9]+)\*$`). |
| definition | Yes      | Specifies the location of workflow json definition.                                                                                                                                                  |
| name       | No       | The name of your plugin. If not supplied, the `id` will be used as the `name`.                                                                                                                       |

---

---
url: /plugins/reference/sdks/frontend/match-and-replace.md
---
# Match and Replace

### CurrentMatchReplaceRuleChangeEvent

> **CurrentMatchReplaceRuleChangeEvent** = `object`

Event fired when the current match and replace rule changes.

#### Properties

##### ruleId

> **ruleId**: [`ID`](utils.md#id) | `undefined`

The ID of the newly selected rule, or undefined if no rule is selected.

***

### MatchReplaceCollection

> **MatchReplaceCollection** = `object`

A collection in Match and Replace.

#### Properties

##### id

> **id**: [`ID`](utils.md#id)

##### name

> **name**: `string`

##### ruleIds

> **ruleIds**: [`ID`](utils.md#id)\[]

***

### MatchReplaceMatcherName

> **MatchReplaceMatcherName** = `object`

A matcher that matches by name (for headers, query parameters, etc.).

#### Properties

##### kind

> **kind**: `"MatcherName"`

##### name

> **name**: `string`

***

### MatchReplaceMatcherRaw

> **MatchReplaceMatcherRaw** = [`MatchReplaceMatcherRawRegex`](#matchreplacematcherrawregex) | [`MatchReplaceMatcherRawValue`](#matchreplacematcherrawvalue) | [`MatchReplaceMatcherRawFull`](#matchreplacematcherrawfull)

A matcher for raw operations in Match and Replace.

***

### MatchReplaceMatcherRawFull

> **MatchReplaceMatcherRawFull** = `object`

This matcher will match the entire section.

#### Properties

##### kind

> **kind**: `"MatcherRawFull"`

***

### MatchReplaceMatcherRawRegex

> **MatchReplaceMatcherRawRegex** = `object`

This matcher will match using a regex over the section.

#### Properties

##### kind

> **kind**: `"MatcherRawRegex"`

##### regex

> **regex**: `string`

***

### MatchReplaceMatcherRawValue

> **MatchReplaceMatcherRawValue** = `object`

This matcher will match the value if present in the section.

#### Properties

##### kind

> **kind**: `"MatcherRawValue"`

##### value

> **value**: `string`

***

### MatchReplaceOperationAll

> **MatchReplaceOperationAll** = [`KeepOperation`](other.md#keepoperation)<[`MatchReplaceOperationAllRaw`](#matchreplaceoperationallraw)>

An operation for the entire request/response section.

***

### MatchReplaceOperationAllRaw

> **MatchReplaceOperationAllRaw** = `object`

A raw operation for the entire request/response section.

#### Properties

##### kind

> **kind**: `"OperationAllRaw"`

##### matcher

> **matcher**: [`MatchReplaceMatcherRaw`](#matchreplacematcherraw)

##### replacer

> **replacer**: [`MatchReplaceReplacer`](#matchreplacereplacer)

***

### MatchReplaceOperationBody

> **MatchReplaceOperationBody** = [`KeepOperation`](other.md#keepoperation)<[`MatchReplaceOperationBodyRaw`](#matchreplaceoperationbodyraw)>

An operation for the body section.

***

### MatchReplaceOperationBodyRaw

> **MatchReplaceOperationBodyRaw** = `object`

A raw operation for the body section.

#### Properties

##### kind

> **kind**: `"OperationBodyRaw"`

##### matcher

> **matcher**: [`MatchReplaceMatcherRaw`](#matchreplacematcherraw)

##### replacer

> **replacer**: [`MatchReplaceReplacer`](#matchreplacereplacer)

***

### MatchReplaceOperationFirstLine

> **MatchReplaceOperationFirstLine** = [`KeepOperation`](other.md#keepoperation)<[`MatchReplaceOperationFirstLineRaw`](#matchreplaceoperationfirstlineraw)>

An operation for the first line section.

***

### MatchReplaceOperationFirstLineRaw

> **MatchReplaceOperationFirstLineRaw** = `object`

A raw operation for the request first line.

#### Properties

##### kind

> **kind**: `"OperationFirstLineRaw"`

##### matcher

> **matcher**: [`MatchReplaceMatcherRaw`](#matchreplacematcherraw)

##### replacer

> **replacer**: [`MatchReplaceReplacer`](#matchreplacereplacer)

***

### MatchReplaceOperationHeader

> **MatchReplaceOperationHeader** = [`MatchReplaceOperationHeaderRaw`](#matchreplaceoperationheaderraw) | [`MatchReplaceOperationHeaderAdd`](#matchreplaceoperationheaderadd) | [`MatchReplaceOperationHeaderRemove`](#matchreplaceoperationheaderremove) | [`MatchReplaceOperationHeaderUpdate`](#matchreplaceoperationheaderupdate)

An operation for the header section.

***

### MatchReplaceOperationHeaderAdd

> **MatchReplaceOperationHeaderAdd** = `object`

An operation to add a header.

#### Properties

##### kind

> **kind**: `"OperationHeaderAdd"`

##### matcher

> **matcher**: [`MatchReplaceMatcherName`](#matchreplacematchername)

##### replacer

> **replacer**: [`MatchReplaceReplacer`](#matchreplacereplacer)

***

### MatchReplaceOperationHeaderRaw

> **MatchReplaceOperationHeaderRaw** = `object`

A raw operation for the header section.

#### Properties

##### kind

> **kind**: `"OperationHeaderRaw"`

##### matcher

> **matcher**: [`MatchReplaceMatcherRaw`](#matchreplacematcherraw)

##### replacer

> **replacer**: [`MatchReplaceReplacer`](#matchreplacereplacer)

***

### MatchReplaceOperationHeaderRemove

> **MatchReplaceOperationHeaderRemove** = `object`

An operation to remove a header.

#### Properties

##### kind

> **kind**: `"OperationHeaderRemove"`

##### matcher

> **matcher**: [`MatchReplaceMatcherName`](#matchreplacematchername)

***

### MatchReplaceOperationHeaderUpdate

> **MatchReplaceOperationHeaderUpdate** = `object`

An operation to update a header.

#### Properties

##### kind

> **kind**: `"OperationHeaderUpdate"`

##### matcher

> **matcher**: [`MatchReplaceMatcherName`](#matchreplacematchername)

##### replacer

> **replacer**: [`MatchReplaceReplacer`](#matchreplacereplacer)

***

### MatchReplaceOperationMethod

> **MatchReplaceOperationMethod** = [`KeepOperation`](other.md#keepoperation)<[`MatchReplaceOperationMethodUpdate`](#matchreplaceoperationmethodupdate)>

An operation for the request method section.

***

### MatchReplaceOperationMethodUpdate

> **MatchReplaceOperationMethodUpdate** = `object`

An operation to update the request method.

#### Properties

##### kind

> **kind**: `"OperationMethodUpdate"`

##### replacer

> **replacer**: [`MatchReplaceReplacer`](#matchreplacereplacer)

***

### MatchReplaceOperationPath

> **MatchReplaceOperationPath** = [`KeepOperation`](other.md#keepoperation)<[`MatchReplaceOperationPathRaw`](#matchreplaceoperationpathraw)>

An operation for the request path section.

***

### MatchReplaceOperationPathRaw

> **MatchReplaceOperationPathRaw** = `object`

A raw operation for the request path section.

#### Properties

##### kind

> **kind**: `"OperationPathRaw"`

##### matcher

> **matcher**: [`MatchReplaceMatcherRaw`](#matchreplacematcherraw)

##### replacer

> **replacer**: [`MatchReplaceReplacer`](#matchreplacereplacer)

***

### MatchReplaceOperationQuery

> **MatchReplaceOperationQuery** = [`MatchReplaceOperationQueryRaw`](#matchreplaceoperationqueryraw) | [`MatchReplaceOperationQueryAdd`](#matchreplaceoperationqueryadd) | [`MatchReplaceOperationQueryRemove`](#matchreplaceoperationqueryremove) | [`MatchReplaceOperationQueryUpdate`](#matchreplaceoperationqueryupdate)

An operation for the request query section.

***

### MatchReplaceOperationQueryAdd

> **MatchReplaceOperationQueryAdd** = `object`

An operation to add a query parameter.

#### Properties

##### kind

> **kind**: `"OperationQueryAdd"`

##### matcher

> **matcher**: [`MatchReplaceMatcherName`](#matchreplacematchername)

##### replacer

> **replacer**: [`MatchReplaceReplacer`](#matchreplacereplacer)

***

### MatchReplaceOperationQueryRaw

> **MatchReplaceOperationQueryRaw** = `object`

A raw operation for the request query section.

#### Properties

##### kind

> **kind**: `"OperationQueryRaw"`

##### matcher

> **matcher**: [`MatchReplaceMatcherRaw`](#matchreplacematcherraw)

##### replacer

> **replacer**: [`MatchReplaceReplacer`](#matchreplacereplacer)

***

### MatchReplaceOperationQueryRemove

> **MatchReplaceOperationQueryRemove** = `object`

An operation to remove a query parameter.

#### Properties

##### kind

> **kind**: `"OperationQueryRemove"`

##### matcher

> **matcher**: [`MatchReplaceMatcherName`](#matchreplacematchername)

***

### MatchReplaceOperationQueryUpdate

> **MatchReplaceOperationQueryUpdate** = `object`

An operation to update a query parameter.

#### Properties

##### kind

> **kind**: `"OperationQueryUpdate"`

##### matcher

> **matcher**: [`MatchReplaceMatcherName`](#matchreplacematchername)

##### replacer

> **replacer**: [`MatchReplaceReplacer`](#matchreplacereplacer)

***

### MatchReplaceOperationSNI

> **MatchReplaceOperationSNI** = [`KeepOperation`](other.md#keepoperation)<[`MatchReplaceOperationSNIRaw`](#matchreplaceoperationsniraw)>

An operation for the request SNI section.

***

### MatchReplaceOperationSNIRaw

> **MatchReplaceOperationSNIRaw** = `object`

A raw operation for the request SNI.

#### Properties

##### kind

> **kind**: `"OperationSNIRaw"`

##### replacer

> **replacer**: [`MatchReplaceReplacer`](#matchreplacereplacer)

***

### MatchReplaceOperationStatusCode

> **MatchReplaceOperationStatusCode** = [`KeepOperation`](other.md#keepoperation)<[`MatchReplaceOperationStatusCodeUpdate`](#matchreplaceoperationstatuscodeupdate)>

An operation for the response status code section.

***

### MatchReplaceOperationStatusCodeUpdate

> **MatchReplaceOperationStatusCodeUpdate** = `object`

An operation to update the response status code.

#### Properties

##### kind

> **kind**: `"OperationStatusCodeUpdate"`

##### replacer

> **replacer**: [`MatchReplaceReplacer`](#matchreplacereplacer)

***

### MatchReplacePageContext

> **MatchReplacePageContext** = `object`

Match and Replace page context.

#### Properties

##### kind

> **kind**: `"MatchReplace"`

##### selection

> **selection**: [`Selection`](utils.md#selection)<[`ID`](utils.md#id)>

***

### MatchReplaceReplacer

> **MatchReplaceReplacer** = [`MatchReplaceReplacerTerm`](#matchreplacereplacerterm) | [`MatchReplaceReplacerWorkflow`](#matchreplacereplacerworkflow)

A replacer in Match and Replace.

***

### MatchReplaceReplacerTerm

> **MatchReplaceReplacerTerm** = `object`

A replacer that replaces with a term.
If the matcher is a regex, groups will be interpolated.

#### Properties

##### kind

> **kind**: `"ReplacerTerm"`

##### term

> **term**: `string`

***

### MatchReplaceReplacerWorkflow

> **MatchReplaceReplacerWorkflow** = `object`

A replacer that replaces with the result of a workflow.
The input of the workflow depends on the operation and matcher.

#### Properties

##### kind

> **kind**: `"ReplacerWorkflow"`

##### workflowId

> **workflowId**: [`ID`](utils.md#id)

***

### MatchReplaceRule

> **MatchReplaceRule** = `object`

A rule in Match and Replace.

#### Properties

##### collectionId

> **collectionId**: [`ID`](utils.md#id)

The ID of the collection the rule belongs to.

##### id

> **id**: [`ID`](utils.md#id)

The ID of the rule.

##### isEnabled

> **isEnabled**: `boolean`

Whether the rule is enabled.

##### name

> **name**: `string`

The name of the rule.

##### query

> **query**: [`HTTPQL`](utils.md#httpql)

The HTTPQL query to match the rule against.
Only requests that match the query will be affected by the rule.

##### section

> **section**: [`MatchReplaceSection`](#matchreplacesection)

The section of the rule.

***

### MatchReplaceSDK

> **MatchReplaceSDK** = `object`

Utilities to interact with the Match and Replace page.

#### Properties

##### addRuleIndicator()

> **addRuleIndicator**: (`ruleId`: [`ID`](utils.md#id), `indicator`: [`AddIndicatorOptions`](utils.md#addindicatoroptions)) => [`Indicator`](utils.md#indicator)

Add an indicator to a rule.
Indicators are displayed next to the session name in the collections tree.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `ruleId` | [`ID`](utils.md#id) | The ID of the rule to add the indicator to. |
| `indicator` | [`AddIndicatorOptions`](utils.md#addindicatoroptions) | The indicator configuration. |

###### Returns

[`Indicator`](utils.md#indicator)

A handle object with a `remove` method to remove the indicator.

###### Example

```ts
const indicator = sdk.matchReplace.addRuleIndicator(ruleId, {
  icon: "fas fa-exclamation-triangle",
  description: "Security warning",
});

// Later, remove the indicator
indicator.remove();
```

##### addToSlot

> **addToSlot**: [`DefineAddToSlotFn`](slots.md#defineaddtoslotfn)<[`MatchReplaceSlotContent`](#matchreplaceslotcontent)>

Add a component to a slot.

###### Param

The slot to add the component to.

###### Param

The content to add to the slot.

###### Example

```ts
sdk.matchReplace.addToSlot(MatchReplaceSlot.UpdateHeader, {
  type: "Button",
  label: "My Button",
  icon: "my-icon",
  onClick: () => {
    console.log("Button clicked");
  },
});

sdk.matchReplace.addToSlot(MatchReplaceSlot.CreateHeader, {
  type: "Custom",
  definition: MyComponent,
});

sdk.matchReplace.addToSlot(MatchReplaceSlot.UpdateHeader, {
  type: "Command",
  commandId: "my-command",
  icon: "my-icon",
});
```

##### createCollection()

> **createCollection**: (`options`: `object`) => `Promise`<[`MatchReplaceCollection`](#matchreplacecollection)>

Create a collection.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | { `name`: `string`; } | The options for the collection. |
| `options.name` | `string` | The name of the collection. |

###### Returns

`Promise`<[`MatchReplaceCollection`](#matchreplacecollection)>

##### createRule()

> **createRule**: (`options`: `object`) => `Promise`<[`MatchReplaceRule`](#matchreplacerule)>

Create a rule.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | { `collectionId`: [`ID`](utils.md#id); `name`: `string`; `query`: [`HTTPQL`](utils.md#httpql); `section`: [`MatchReplaceSection`](#matchreplacesection); `sources`: [`Source`](#source)\[]; } | The options for the rule. |
| `options.collectionId` | [`ID`](utils.md#id) | The ID of the collection the rule belongs to. |
| `options.name` | `string` | The name of the rule. |
| `options.query` | [`HTTPQL`](utils.md#httpql) | The HTTPQL query to match the rule against. |
| `options.section` | [`MatchReplaceSection`](#matchreplacesection) | - |
| `options.sources` | [`Source`](#source)\[] | The sources the rule belongs to. |

###### Returns

`Promise`<[`MatchReplaceRule`](#matchreplacerule)>

##### deleteCollection()

> **deleteCollection**: (`id`: [`ID`](utils.md#id)) => `Promise`<`void`>

Delete a collection.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](utils.md#id) | The ID of the collection. |

###### Returns

`Promise`<`void`>

##### deleteRule()

> **deleteRule**: (`id`: [`ID`](utils.md#id)) => `Promise`<`void`>

Delete a rule.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](utils.md#id) | The ID of the rule. |

###### Returns

`Promise`<`void`>

##### getActiveRules()

> **getActiveRules**: () => [`MatchReplaceRule`](#matchreplacerule)\[]

Get all active rules.
Rules are ordered in priority from highest to lowest.

###### Returns

[`MatchReplaceRule`](#matchreplacerule)\[]

All active rules.

##### getCollections()

> **getCollections**: () => [`MatchReplaceCollection`](#matchreplacecollection)\[]

Get all collections.

###### Returns

[`MatchReplaceCollection`](#matchreplacecollection)\[]

##### getCurrentRule()

> **getCurrentRule**: () => [`MatchReplaceRule`](#matchreplacerule) | `undefined`

Get the currently selected rule.

###### Returns

[`MatchReplaceRule`](#matchreplacerule) | `undefined`

The currently selected rule, or undefined if no rule is selected.

##### getRules()

> **getRules**: () => [`MatchReplaceRule`](#matchreplacerule)\[]

Get all rules.

###### Returns

[`MatchReplaceRule`](#matchreplacerule)\[]

All rules.

##### onCurrentRuleChange()

> **onCurrentRuleChange**: (`callback`: (`event`: [`CurrentMatchReplaceRuleChangeEvent`](#currentmatchreplacerulechangeevent)) => `void`) => [`ListenerHandle`](utils.md#listenerhandle)

Subscribe to current rule changes.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `callback` | (`event`: [`CurrentMatchReplaceRuleChangeEvent`](#currentmatchreplacerulechangeevent)) => `void` | The callback to call when the selected rule changes. |

###### Returns

[`ListenerHandle`](utils.md#listenerhandle)

An object with a `stop` method that can be called to stop listening to rule changes.

###### Example

```ts
const handler = sdk.matchReplace.onCurrentRuleChange((event) => {
  console.log(`Rule ${event.ruleId} got selected!`);
});

// Later, stop listening
handler.stop();
```

##### selectRule()

> **selectRule**: (`id`: [`ID`](utils.md#id) | `undefined`) => `void`

Select a rule to be displayed in the UI.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](utils.md#id) | `undefined` | The ID of the rule, or undefined to clear the selection. |

###### Returns

`void`

##### toggleRule()

> **toggleRule**: (`id`: [`ID`](utils.md#id), `enabled`: `boolean`) => `Promise`<`void`>

Toggle a rule.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](utils.md#id) | The ID of the rule. |
| `enabled` | `boolean` | Whether the rule should be enabled. |

###### Returns

`Promise`<`void`>

##### updateCollection()

> **updateCollection**: (`id`: [`ID`](utils.md#id), `options`: `object`) => `Promise`<[`MatchReplaceCollection`](#matchreplacecollection)>

Update a collection.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](utils.md#id) | The ID of the collection. |
| `options` | { `name`: `string`; } | The new values for the collection. |
| `options.name` | `string` | The new name of the collection. |

###### Returns

`Promise`<[`MatchReplaceCollection`](#matchreplacecollection)>

##### updateRule()

> **updateRule**: (`id`: [`ID`](utils.md#id), `options`: `object`) => `Promise`<[`MatchReplaceRule`](#matchreplacerule)>

Update a rule.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](utils.md#id) | The ID of the rule. |
| `options` | { `name`: `string`; `query?`: [`HTTPQL`](utils.md#httpql); `section`: [`MatchReplaceSection`](#matchreplacesection); `sources`: [`Source`](#source)\[]; } | The new values for the rule. |
| `options.name` | `string` | The new name of the rule. |
| `options.query?` | [`HTTPQL`](utils.md#httpql) | The new HTTPQL query of the rule. |
| `options.section` | [`MatchReplaceSection`](#matchreplacesection) | The new section of the rule. |
| `options.sources` | [`Source`](#source)\[] | The new sources of the rule. |

###### Returns

`Promise`<[`MatchReplaceRule`](#matchreplacerule)>

***

### MatchReplaceSection

> **MatchReplaceSection** = [`MatchReplaceSectionRequestAll`](#matchreplacesectionrequestall) | [`MatchReplaceSectionRequestBody`](#matchreplacesectionrequestbody) | [`MatchReplaceSectionRequestFirstLine`](#matchreplacesectionrequestfirstline) | [`MatchReplaceSectionRequestHeader`](#matchreplacesectionrequestheader) | [`MatchReplaceSectionRequestMethod`](#matchreplacesectionrequestmethod) | [`MatchReplaceSectionRequestPath`](#matchreplacesectionrequestpath) | [`MatchReplaceSectionRequestQuery`](#matchreplacesectionrequestquery) | [`MatchReplaceSectionRequestSNI`](#matchreplacesectionrequestsni) | [`MatchReplaceSectionResponseAll`](#matchreplacesectionresponseall) | [`MatchReplaceSectionResponseBody`](#matchreplacesectionresponsebody) | [`MatchReplaceSectionResponseFirstLine`](#matchreplacesectionresponsefirstline) | [`MatchReplaceSectionResponseHeader`](#matchreplacesectionresponseheader) | [`MatchReplaceSectionResponseStatusCode`](#matchreplacesectionresponsestatuscode)

A discriminated union of all possible match and replace sections.

***

### MatchReplaceSectionRequestAll

> **MatchReplaceSectionRequestAll** = `object`

A section for the entire request.

#### Properties

##### kind

> **kind**: `"SectionRequestAll"`

##### operation

> **operation**: [`MatchReplaceOperationAll`](#matchreplaceoperationall)

***

### MatchReplaceSectionRequestBody

> **MatchReplaceSectionRequestBody** = `object`

A section for the request body.

#### Properties

##### kind

> **kind**: `"SectionRequestBody"`

##### operation

> **operation**: [`MatchReplaceOperationBody`](#matchreplaceoperationbody)

***

### MatchReplaceSectionRequestFirstLine

> **MatchReplaceSectionRequestFirstLine** = `object`

A section for the request first line.

#### Properties

##### kind

> **kind**: `"SectionRequestFirstLine"`

##### operation

> **operation**: [`MatchReplaceOperationFirstLine`](#matchreplaceoperationfirstline)

***

### MatchReplaceSectionRequestHeader

> **MatchReplaceSectionRequestHeader** = `object`

A section for the request headers.

#### Properties

##### kind

> **kind**: `"SectionRequestHeader"`

##### operation

> **operation**: [`MatchReplaceOperationHeader`](#matchreplaceoperationheader)

***

### MatchReplaceSectionRequestMethod

> **MatchReplaceSectionRequestMethod** = `object`

A section for the request method.

#### Properties

##### kind

> **kind**: `"SectionRequestMethod"`

##### operation

> **operation**: [`MatchReplaceOperationMethod`](#matchreplaceoperationmethod)

***

### MatchReplaceSectionRequestPath

> **MatchReplaceSectionRequestPath** = `object`

A section for the request path.

#### Properties

##### kind

> **kind**: `"SectionRequestPath"`

##### operation

> **operation**: [`MatchReplaceOperationPath`](#matchreplaceoperationpath)

***

### MatchReplaceSectionRequestQuery

> **MatchReplaceSectionRequestQuery** = `object`

A section for the request query string.

#### Properties

##### kind

> **kind**: `"SectionRequestQuery"`

##### operation

> **operation**: [`MatchReplaceOperationQuery`](#matchreplaceoperationquery)

***

### MatchReplaceSectionRequestSNI

> **MatchReplaceSectionRequestSNI** = `object`

A section for the request SNI.

#### Properties

##### kind

> **kind**: `"SectionRequestSNI"`

##### operation

> **operation**: [`MatchReplaceOperationSNI`](#matchreplaceoperationsni)

***

### MatchReplaceSectionResponseAll

> **MatchReplaceSectionResponseAll** = `object`

A section for the entire response.

#### Properties

##### kind

> **kind**: `"SectionResponseAll"`

##### operation

> **operation**: [`MatchReplaceOperationAll`](#matchreplaceoperationall)

***

### MatchReplaceSectionResponseBody

> **MatchReplaceSectionResponseBody** = `object`

A section for the response body.

#### Properties

##### kind

> **kind**: `"SectionResponseBody"`

##### operation

> **operation**: [`MatchReplaceOperationBody`](#matchreplaceoperationbody)

***

### MatchReplaceSectionResponseFirstLine

> **MatchReplaceSectionResponseFirstLine** = `object`

A section for the response first line.

#### Properties

##### kind

> **kind**: `"SectionResponseFirstLine"`

##### operation

> **operation**: [`MatchReplaceOperationFirstLine`](#matchreplaceoperationfirstline)

***

### MatchReplaceSectionResponseHeader

> **MatchReplaceSectionResponseHeader** = `object`

A section for the response headers.

#### Properties

##### kind

> **kind**: `"SectionResponseHeader"`

##### operation

> **operation**: [`MatchReplaceOperationHeader`](#matchreplaceoperationheader)

***

### MatchReplaceSectionResponseStatusCode

> **MatchReplaceSectionResponseStatusCode** = `object`

A section for the response status code.

#### Properties

##### kind

> **kind**: `"SectionResponseStatusCode"`

##### operation

> **operation**: [`MatchReplaceOperationStatusCode`](#matchreplaceoperationstatuscode)

***

### MatchReplaceSlotContent

> **MatchReplaceSlotContent** = `object`

Content that can be added to match and replace slots.

#### Properties

##### create-header

> **create-header**: [`ButtonSlotContent`](slots.md#buttonslotcontent) | [`CustomSlotContent`](slots.md#customslotcontent) | [`CommandSlotContent`](slots.md#commandslotcontent)

##### update-header

> **update-header**: [`ButtonSlotContent`](slots.md#buttonslotcontent) | [`CustomSlotContent`](slots.md#customslotcontent) | [`CommandSlotContent`](slots.md#commandslotcontent)

***

### MatchReplaceSlot

> `const` **MatchReplaceSlot**: `object`

The slots in the Match and Replace UI.

#### Type Declaration

##### CreateHeader

> `readonly` **CreateHeader**: `"create-header"`

The header area of the rule form create component.

##### UpdateHeader

> `readonly` **UpdateHeader**: `"update-header"`

The header area of the rule form update component.

***

### Source

> `const` **Source**: `object`

The source of a match and replace rule.

#### Type Declaration

##### Automate

> `readonly` **Automate**: `"AUTOMATE"`

##### Intercept

> `readonly` **Intercept**: `"INTERCEPT"`

##### Plugin

> `readonly` **Plugin**: `"PLUGIN"`

##### Replay

> `readonly` **Replay**: `"REPLAY"`

##### Sample

> `readonly` **Sample**: `"SAMPLE"`

##### Workflow

> `readonly` **Workflow**: `"WORKFLOW"`

---

---
url: /plugins/reference/sdks/frontend/menu.md
---
# Menu

### MenuItem

> **MenuItem** = [`RequestRowMenuItem`](#requestrowmenuitem) | [`SettingsMenuItem`](#settingsmenuitem) | [`RequestMenuItem`](#requestmenuitem) | [`ResponseMenuItem`](#responsemenuitem)

A content-menu item.

***

### MenuSDK

> **MenuSDK** = `object`

Utilities to insert menu items and context-menus throughout the UI.

#### Properties

##### registerItem()

> **registerItem**: (`item`: [`MenuItem`](#menuitem)) => `void`

Register a menu item.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `item` | [`MenuItem`](#menuitem) | The menu item to register. |

###### Returns

`void`

###### Example

```ts
sdk.menu.registerItem({
  type: "Request",
  commandId: "hello",
  leadingIcon: "fas fa-hand",
});
```

***

### RequestMenuItem

> **RequestMenuItem** = `object`

A context-menu item that appears when right-clicking a request pane.

#### Properties

##### commandId

> **commandId**: [`CommandID`](other.md#commandid)

The command ID to execute when the menu item is clicked.

##### leadingIcon?

> `optional` **leadingIcon**: `string`

The icon to display to the left of the menu item.

##### type

> **type**: `"Request"`

***

### RequestRowMenuItem

> **RequestRowMenuItem** = `object`

A context-menu item that appears when right-clicking a request row.

#### Properties

##### commandId

> **commandId**: [`CommandID`](other.md#commandid)

The command ID to execute when the menu item is clicked.

##### leadingIcon?

> `optional` **leadingIcon**: `string`

The icon to display to the left of the menu item.

##### type

> **type**: `"RequestRow"`

***

### ResponseMenuItem

> **ResponseMenuItem** = `object`

A context-menu item that appears when right-clicking a response pane.

#### Properties

##### commandId

> **commandId**: [`CommandID`](other.md#commandid)

The command ID to execute when the menu item is

##### leadingIcon?

> `optional` **leadingIcon**: `string`

The icon to display to the left of the menu item.

##### type

> **type**: `"Response"`

***

### SettingsMenuItem

> **SettingsMenuItem** = `object`

A menu item that appears in the settings menu.

#### Properties

##### label

> **label**: `string`

The label of the menu item.

##### leadingIcon?

> `optional` **leadingIcon**: [`Icon`](utils.md#icon)

The [Icon](utils.md#icon) to display to the left of the menu item.

##### path

> **path**: `string`

The path that the user will be navigated to when the menu item is clicked
The path must start with "/settings/".

##### type

> **type**: `"Settings"`

---

---
url: /plugins/reference/sdks/backend/meta.md
---
# Meta

### MetaSDK

> **MetaSDK** = `object`

The SDK for metadata information about the plugin.

#### Methods

##### assetsPath()

> **assetsPath**(): `string`

The directory of the plugin's assets in Caido Data.
You can read static data from your plugin in this directory.
You shouldn't write anything there, as the contents can be reset at any time.

###### Returns

`string`

##### db()

> **db**(): `Promise`<[`Database`](other.md#database)>

Get a sqlite database for the plugin stored in Caido Data.
You can use this to store data related to your plugin.

###### Returns

`Promise`<[`Database`](other.md#database)>

##### id()

> **id**(): `string`

The id of the plugin.

###### Returns

`string`

##### path()

> **path**(): `string`

The directory of the plugin in Caido Data.
You can store data related to your plugin in this directory.

###### Returns

`string`

##### updateAvailable()

> **updateAvailable**(): `Promise`<`boolean`>

Check if an update is available for the plugin.

###### Returns

`Promise`<`boolean`>

###### Throws

If Caido Cloud is offline.

##### version()

> **version**(): `string`

Get the version of the plugin.
This uses the semver format.

###### Returns

`string`

---

---
url: /plugins/reference/sdks/frontend/navigation.md
---
# Navigation

### NavigationSDK

> **NavigationSDK** = `object`

Utilities to interact with navigation.

#### Properties

##### addPage()

> **addPage**: (`path`: `string`, `options`: `object`) => `void`

Add a page to the navigation.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `path` | `string` | The path of the page. |
| `options` | { `body`: `HTMLElement`; `onEnter?`: () => `void`; `topbar?`: `HTMLElement`; } | Options for the page. |
| `options.body` | `HTMLElement` | The body of the page. |
| `options.onEnter?` | () => `void` | The callback to execute when the page is entered. |
| `options.topbar?` | `HTMLElement` | The topbar of the page. |

###### Returns

`void`

##### goTo()

> **goTo**: (`route`: `string` | { `id`: [`Routes`](#routes); }) => `void`

Navigate to a route or path.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `route` | `string` | { `id`: [`Routes`](#routes); } | The route to navigate to. Can be a route ID object or a custom path string. |

###### Returns

`void`

###### Example

```ts
sdk.navigation.goTo({ id: Routes.Replay });
sdk.navigation.goTo({ id: Routes.Projects });
sdk.navigation.goTo("/my-plugin-page");
```

##### onPageChange()

> **onPageChange**: (`callback`: (`route`: [`PageChangeEvent`](#pagechangeevent)) => `void`) => [`ListenerHandle`](utils.md#listenerhandle)

Subscribe to page changes.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `callback` | (`route`: [`PageChangeEvent`](#pagechangeevent)) => `void` | The callback to call when the page changes. |

###### Returns

[`ListenerHandle`](utils.md#listenerhandle)

An object with a `stop` method that can be called to stop listening to page changes.

###### Example

```ts
const handler = sdk.navigation.onPageChange((event) => {
  console.log('Page changed to:', event.routeId);
  console.log('- path:', event.path);
});

// Later, stop listening
handler.stop();
```

***

### PageChangeEvent

> **PageChangeEvent** = { `path`: `string`; `routeId`: [`Routes`](#routes); `type`: `"Core"`; } | { `path`: `string`; `type`: `"Plugin"`; }

Event fired when the page changes.

***

### Routes

> `const` **Routes**: `object`

Available route identifiers in Caido.

#### Type Declaration

##### About

> `readonly` **About**: `"About"`

##### Assistant

> `readonly` **Assistant**: `"Assistant"`

##### Automate

> `readonly` **Automate**: `"Automate"`

##### Backups

> `readonly` **Backups**: `"Backups"`

##### Certificate

> `readonly` **Certificate**: `"Certificate"`

##### Environment

> `readonly` **Environment**: `"Environment"`

##### Exports

> `readonly` **Exports**: `"Exports"`

##### Files

> `readonly` **Files**: `"Files"`

##### Filter

> `readonly` **Filter**: `"Filter"`

##### Findings

> `readonly` **Findings**: `"Findings"`

##### HTTPHistory

> `readonly` **HTTPHistory**: `"HTTPHistory"`

##### Intercept

> `readonly` **Intercept**: `"Intercept"`

##### MatchReplace

> `readonly` **MatchReplace**: `"MatchReplace"`

##### Plugins

> `readonly` **Plugins**: `"Plugins"`

##### Projects

> `readonly` **Projects**: `"Projects"`

##### Replay

> `readonly` **Replay**: `"Replay"`

##### Scope

> `readonly` **Scope**: `"Scope"`

##### Search

> `readonly` **Search**: `"Search"`

##### Settings

> `readonly` **Settings**: `"Settings"`

##### Sitemap

> `readonly` **Sitemap**: `"Sitemap"`

##### Websockets

> `readonly` **Websockets**: `"Websockets"`

##### Workflows

> `readonly` **Workflows**: `"Workflows"`

---

---
url: /plugins/reference/sdks/backend/net.md
---
# Net

### ConnectionInfo

Information about a target.

#### Constructors

##### Constructor

> **new ConnectionInfo**(`url`: `string`): [`ConnectionInfo`](#connectioninfo)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `url` | `string` |

###### Returns

[`ConnectionInfo`](#connectioninfo)

#### Accessors

##### host

###### Get Signature

> **get** **host**(): `string`

###### Returns

`string`

###### Set Signature

> **set** **host**(`value`: `string`): `void`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `value` | `string` |

###### Returns

`void`

##### port

###### Get Signature

> **get** **port**(): `number`

###### Returns

`number`

###### Set Signature

> **set** **port**(`value`: `number`): `void`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `value` | `number` |

###### Returns

`void`

##### sni

###### Get Signature

> **get** **sni**(): `string` | `undefined`

###### Returns

`string` | `undefined`

###### Set Signature

> **set** **sni**(`value`: `string` | `null`): `void`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `value` | `string` | `null` |

###### Returns

`void`

##### tls

###### Get Signature

> **get** **tls**(): `boolean`

###### Returns

`boolean`

###### Set Signature

> **set** **tls**(`value`: `boolean`): `void`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `value` | `boolean` |

###### Returns

`void`

***

### Connection

> **Connection** = `object`

A TCP connection.

#### Methods

##### receive()

> **receive**(`size?`: `number`): `Promise`<`Uint8Array`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `size?` | `number` |

###### Returns

`Promise`<`Uint8Array`>

##### send()

> **send**(`bytes`: [`Bytes`](shared.md#bytes)): `Promise`<`void`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `bytes` | [`Bytes`](shared.md#bytes) |

###### Returns

`Promise`<`void`>

***

### NetSDK

> **NetSDK** = `object`

The SDK for the Net service.

#### Methods

##### connect()

###### Call Signature

> **connect**(`info`: [`ConnectionInfo`](#connectioninfo)): `Promise`<[`Connection`](#connection)>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `info` | [`ConnectionInfo`](#connectioninfo) |

###### Returns

`Promise`<[`Connection`](#connection)>

###### Call Signature

> **connect**(`url`: `string`): `Promise`<[`Connection`](#connection)>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `url` | `string` |

###### Returns

`Promise`<[`Connection`](#connection)>

---

---
url: /plugins/reference/sdks/workflow/net.md
---
# Net

### ConnectionInfo

Information about a target.

#### Constructors

##### Constructor

> **new ConnectionInfo**(`url`: `string`): [`ConnectionInfo`](#connectioninfo)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `url` | `string` |

###### Returns

[`ConnectionInfo`](#connectioninfo)

#### Accessors

##### host

###### Get Signature

> **get** **host**(): `string`

###### Returns

`string`

###### Set Signature

> **set** **host**(`value`: `string`): `void`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `value` | `string` |

###### Returns

`void`

##### port

###### Get Signature

> **get** **port**(): `number`

###### Returns

`number`

###### Set Signature

> **set** **port**(`value`: `number`): `void`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `value` | `number` |

###### Returns

`void`

##### sni

###### Get Signature

> **get** **sni**(): `string` | `undefined`

###### Returns

`string` | `undefined`

###### Set Signature

> **set** **sni**(`value`: `string` | `null`): `void`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `value` | `string` | `null` |

###### Returns

`void`

##### tls

###### Get Signature

> **get** **tls**(): `boolean`

###### Returns

`boolean`

###### Set Signature

> **set** **tls**(`value`: `boolean`): `void`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `value` | `boolean` |

###### Returns

`void`

***

### Connection

> **Connection** = `object`

A TCP connection.

#### Methods

##### receive()

> **receive**(`size?`: `number`): `Promise`<`Uint8Array`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `size?` | `number` |

###### Returns

`Promise`<`Uint8Array`>

##### send()

> **send**(`bytes`: [`Bytes`](shared.md#bytes)): `Promise`<`void`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `bytes` | [`Bytes`](shared.md#bytes) |

###### Returns

`Promise`<`void`>

***

### NetSDK

> **NetSDK** = `object`

The SDK for the Net service.

#### Methods

##### connect()

###### Call Signature

> **connect**(`info`: [`ConnectionInfo`](#connectioninfo)): `Promise`<[`Connection`](#connection)>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `info` | [`ConnectionInfo`](#connectioninfo) |

###### Returns

`Promise`<[`Connection`](#connection)>

###### Call Signature

> **connect**(`url`: `string`): `Promise`<[`Connection`](#connection)>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `url` | `string` |

###### Returns

`Promise`<[`Connection`](#connection)>

---

---
url: /plugins/tutorials/notebook.md
---
# Notebook

This guide provides a walkthrough for **Notebook**, a note taking plugin. You can find the repository for Notebook [here](https://github.com/caido-community/notebook).

## manifest.json

For a full breakdown on the properties of the manifest file - view the [manifest.json reference](/plugins/reference/manifest.md) page.

```json
{
  "id": "notebook",
  "name": "Notebook",
  "version": "0.1.0",
  "description": "Note taking plugin.",
  "author": {
    "name": "Ninjeeter",
    "email": "ninjeeter@proton.me",
    "url": "https://github.com/ninjeeter/notebook"
  },
  "plugins": [
    {
      "kind": "frontend",
      "id": "notebook",
      "name": "Notebook",
      "entrypoint": "frontend/script.js",
      "style": "frontend/style.css"
    }
  ]
}

```

## types.ts

The Notebook `types.ts` file exports a type alias of `PluginStorage`. This is a custom type created to define the structure of the `notes` array.

::: tip types.ts

```ts
export type PluginStorage = {
  notes: { datetime: string; note: string; projectName?: string }[];
}
```

Each note element within the array will be an object that has the following properties:

* `datetime` - The date and time the note was stored of type `string`.
* `note` - The note itself of type `string`.
* `projectName` - The Project that the note was taken in of type `string`. This property is **optional**.
  :::

## index.ts

The file first imports the `Caido` type which is the interface to the SDK and the `PluginStorage` type defined in the `types.ts` file.

::: tip index.ts

```ts
// Imports.
import type { Caido } from "@caido/sdk-frontend";

import type { PluginStorage } from "./types";
```

:::

Next, the `Page` variable stores the path for the plugin page.

::: tip index.ts

```ts
// Creates path.
const Page = "/notebook";
```

Each Caido tab represents a separate page. You can conceptualize tabs and pages in the same sense as a web browser. The browser application can have multiple tabs each displaying different pages.
:::

The `Commands` object has two command properties.

::: tip index.ts

```ts
// Syntax of - identifier: "namespace.namespaceIdentifier".
const Commands = {
  clear: "notebook.clear",
  addNoteMenu: "notebook.addNoteMenu",
};
```

:::

The `getNotes` function is responsible for retrieving the notes array from storage.

::: tip index.ts

```ts
// Get notes from storage.
const getNotes = (caido: Caido): PluginStorage["notes"] => {
  const storage = caido.storage.get() as PluginStorage | undefined;
  return storage?.notes ?? [];
};
```

* The function takes the `caido` parameter of type `Caido` which represents the Caido SDK object and is used as the interface.
* The return value of the function will be of type `PluginStorage["notes"]`.
* It starts by calling the `caido.storage.get()` method to retrieve the current stored `notes` array.
* The `?.` operator checks if `storage` is not null/undefined before attempting to access the `notes` property. If the `notes` property exists, its value is returned. Otherwise, if the `notes` property does not exist or is null/undefined - an empty array is returned.
  :::

The `addNoteStorage` function is responsible for adding to the storage.

::: tip index.ts

```ts
// Add note to storage.
const addNoteStorage = async (
  caido: Caido,
  datetime: string,
  note: string,
  projectName?: string,
) => {
  const currentNotes = getNotes(caido);
  const updatedNotes = [...currentNotes, { datetime, note, projectName }];
  await caido.storage.set({ notes: updatedNotes });

  // Print added note to console.
  console.log("Added Note:", { datetime, note, projectName });
};
```

* It first calls the `currentNotes` function to retrieve existing notes/return an empty array.
* The `updatedStorage` variable keeps the notes in the existing stored notes array and appends a new note object using the [spread operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Spread_syntax) `[...storage.notes]`.
* The `caido.storage.set()` method is called which updates the array with the new note. Before calling this method - the plugin is solely working in the frontend environment. So, if you close the Caido application, the data will be lost. This method calls the backend and persists the new note. Storage uses a last-write-wins strategy, meaning that if you add a note in another browser tab it will be overwritten unless you have a `storage.onChange()` method call that syncs your local storage. This `storage.onChange()` method call appears later in the script.
  :::

Next an HTML table element is created.

::: tip index.ts

```ts
// Global scope table.
const table = document.createElement("table");
table.id = "notesTable";
```

* The table is given an `id` of `notesTable` (*to be used for CSS styling*).
* This table has a global scope - allowing other code blocks to easily access it.
  :::

The `clear` function is responsible for clearing the table of all note entries.

::: tip index.ts

```ts
// Resetting the page table.
const clear = (caido: Caido) => {
  if (table) {
    const tbody = table.querySelector("tbody");
    if (tbody) {
      table.textContent = "";
    }
  }
  caido.storage.set({ notes: [] });
};
```

* This will eventually be tied to the `clear command` as its handler function.
  :::

The async `addNoteMenu` function is responsible for awaiting notes to add to the table as table body rows by highlight click-drag selecting text within editor panes in Caido.

::: tip index.ts

```ts
// Add note via prompt or highlight selecting text and selecting context menu option.
const addNoteMenu = async (caido: Caido) => {
  let currentSelect = caido.window.getActiveEditor()?.getSelectedText();

  if (!currentSelect) {
    currentSelect = prompt("No selection - enter note here:") as string;
  }

  if (currentSelect) {
    const project = await caido.graphql.currentProject();
    const projectData = project?.currentProject;
    if (projectData) {
      const projectName = projectData.name || "No Project Selected";
      const datetime = new Date().toLocaleString();

      // Add the note to storage.
      await addNoteStorage(caido, datetime, currentSelect, projectName);
    }
  }
};
```

* The editor panes are accessed using the `caido.window.getActiveEditor()?.getSelectedText();` method.
* If no selection is made, a prompt window will appear asking the user to supply input.
* Once the value is received, if the note was taken while within a specific Caido [Project](https://docs.caido.io/app/quickstart/workspace) then the API call to get the current Project name is made via the `caido.graphql.currentProject()` method.
* If you are currently within a Project, then the Project's name will be included in the `datetimeCell` of the table.
* If you are not currently within a project, "No Project Selected" will be included instead.
* The note will also be added to storage by calling the `addNoteStorage` function.
  :::

The `addPage` function creates the tab's page.

::: tip index.ts

```ts
// Plugin page construction.
const addPage = (caido: Caido) => {
```

* It takes the `caido` parameter.
* This function will later be called in the `init` function to initialize the plugin.
  :::

Within the `addPage` function is the creation of HTML elements.

::: tip index.ts

```ts
  // Header.
  const headerText = document.createElement("h1");
  headerText.textContent = "Notebook";
  headerText.className = "center";

  // Instructions.
  const details = document.createElement("details");
  const summary = document.createElement("summary");
  summary.textContent = "Instructions";
  summary.classList.add("center", "bold-brown");
  details.appendChild(summary);

  const instructions = document.createElement("p");
  instructions.innerHTML = `<span class="bold-brown">To add a note:</span><br>
  1. Supply input in the textarea located at the bottom and click the <span class="light-brown">Add Note</span> button.<br>
  2. Click the <span class="light-brown">>_ Commands</span> button located at the topbar in the upper-right corner. Search/Select <span class="light-brown">Add Note to Notebook</span>. Supply input in the prompt and click <span class="light-brown">OK</span>.<br>
  3. Highlight select text within a request/response pane and open the context menu by right-clicking. Hover over the <span class="light-brown">Plugins</span> item and select <span class="light-brown">Add Note to Notebook</span>.<br>
  4. <span class="light-brown">CTRL+C</span> and <span class="light-brown">CTRL+V</span> within request and response panes is available as well but <span class="red">ensure to deselect the text and unfocus the pane to avoid needing to restart the Caido application.</span><br>***Copying within panes using <span class="light-brown">Copy</span> from the right-click context menu is functional as normal.***<br>
  <br>
  <span class="bold-brown">To clear all notes:</span><br>
  <span class="bold-red">***This will reset the notes in storage. This action cannot be undone.***</span><br>
  1. Click the <span class="light-brown">>_ Commands</span> button located at the topbar in the upper-right corner. Search/Select <span class="light-brown">Clear Notes in Notebook</span>.`;
  instructions.className = "center";

  details.appendChild(instructions);

  // Input textarea.
  const textarea = document.createElement("textarea");
  textarea.placeholder = "Enter note here...";
  textarea.classList.add("text-area");

  // `Add note.` button.
  const addNoteButton = caido.ui.button({
    variant: "primary",
    label: "Add Note",
  });
```

As well as a textarea input field and corresponding submit button.
:::

The `addNoteButton` has an async handler function and is responsible for awaiting notes to add to the table as table body rows by taking the submitted textarea value.

::: tip index.ts

```ts
  addNoteButton.addEventListener("click", async () => {
    const datetime = new Date().toLocaleString();
    let inputValue = textarea.value;

    if (inputValue) {
      const project = await caido.graphql.currentProject();
      const projectData = project?.currentProject;
      const projectName = projectData?.name || "No Project Selected";

      // Add the note to storage.
      await addNoteStorage(caido, datetime, inputValue, projectName);

      // Clear textarea and reset value.
      inputValue = "";
      textarea.value = "";
    }
  });
```

* The function will execute upon the `addNoteButton` being clicked.
* Once the value is received, if the note was taken while within a specific Caido [Project](https://docs.caido.io/app/quickstart/workspace) then the API call to get the current Project name is made via the `caido.graphql.currentProject()` method.
* If you are currently within a Project, then the Project's name will be included in the `datetimeCell` of the table.
* If you are not currently within a project, "No Project Selected" will be included instead.
* The note will also be added to storage by calling the `addNoteStorage` function.
* Once the note is added, the textarea input field is reset.
  :::

A card is an element that consists of a header, body and footer. Since the UI interface is used in Notebook to create a card, the HTML elements are grouped together as the card cannot take an array for each property.

::: tip index.ts

```ts
 // Combining elements into divs since card properties cannot accept arrays.

  const headerContainer = document.createElement("div");
  headerContainer.appendChild(headerText);
  headerContainer.appendChild(details);

  const tableContainer = document.createElement("div");
  tableContainer.appendChild(table);
  tableContainer.classList.add("table-container");

  const buttonContainer = document.createElement("div");
  buttonContainer.appendChild(addNoteButton);
  buttonContainer.classList.add("button-container");

  const footerContainer = document.createElement("div");
  footerContainer.appendChild(textarea);
  footerContainer.appendChild(buttonContainer);
```

:::

The card propeties are then populated with the HTML elements that were previously grouped together using `div` elements.

::: tip index.ts

```ts
  // Card elements.
  const card = caido.ui.card({
    header: headerContainer,
    body: tableContainer,
    footer: footerContainer,
  });
```

:::

The `notebook` page is created, allowing Caido users to be able to navigate to it.

::: tip index.ts

```ts
  // Create plugin page in left tab menu.
  caido.navigation.addPage(Page, {
    body: card,
  });
};
```

* The `body` property stores the previously created card.
* Now the page just awaits registration.
  :::

The `displayNotes` function populates the table with notes.

::: tip index.ts

```ts
const displayNotes = (notes: PluginStorage["notes"] | undefined) => {
  const tbody = table.querySelector("tbody");
  if (tbody) {
    table.textContent = "";
  }

  if (!notes) {
    return;
  }

  notes.forEach((note) => {
    const row = table.insertRow();
    const datetimeCell = row.insertCell();
    const noteCell = row.insertCell();

    datetimeCell.textContent = `${note.datetime} Project: ${note.projectName}`;
    datetimeCell.classList.add("datetime-cell");
    noteCell.textContent = note.note;
  });
};
```

* The function takes the array of notes and iterates through each note element.
* For each note element, a table row is added and populated with the `datetimeCell` and `noteCell`.
  :::

The `init` function is responsible for initializing the plugin.

::: tip index.ts

```ts
export const init = (caido: Caido) => {
```

* The function also receives the `caido` parameter.
  :::

Within the `init` function is the following:

::: tip index.ts

```ts
  // Retrieve notes from storage.
  const notes = getNotes(caido);
  console.log("Current notes:", notes);
```

The notes are retrieved from storage by calling the `getNotes(caido)` function and logged to the console.

```ts
  // Populate table with stored notes.
  displayNotes(notes);

  caido.storage.onChange((value) => {
    displayNotes((value as PluginStorage | undefined)?.notes);
  });
```

* The `displayNotes` function is called to populate the table with notes.
* The `onChange` method is used to register a callback function that will be executed whenever the value of the storage changes. This method ensures that data persists across different sessions (*such as when you add a note in another browser tab*) by syncing local storage. Without the `onChange` method, notes would be overwritten by different sessions.
* *Conceptual explanation*: Caido is open in two browser tabs on 127.0.0.1:8080. Tab 1 has Note A. Tab 2 has Note A and Note B. The server knows about Note A and Note B. Without the `onChange` method - if Tab 1 adds its own Note B, the original Note B will be overwritten.

```ts
  // Register commands.
  // Commands are registered with a unique identifier and a handler function.
  // The run function is called when the command is executed.
  // These commands can be registered in various places like command palette, context menu, etc.
  caido.commands.register(Commands.clear, {
    name: "Clear Notes in Notebook",
    run: () => clear(caido),
  });

  caido.commands.register(Commands.addNoteMenu, {
    name: "Add Note to Notebook",
    run: () => addNoteMenu(caido),
  });
```

The commands that were assigned identifiers in the beginning of the script are registered via the `caido.commands.register()` method and assigned a display name as well as their handler functions.

```ts
  // Register command palette items.
  caido.commandPalette.register(Commands.clear);

  caido.commandPalette.register(Commands.addNoteMenu);
```

* The commands are then registered to the command palette via the `caido.commandPalette.register()` method.
* The commands are now accessible via the `>_Command` button in the Caido application.

```ts
  // Register context menu options.
  caido.menu.registerItem({
    type: "Request",
    commandId: Commands.addNoteMenu,
    leadingIcon: "fas fa-book",
  });

  caido.menu.registerItem({
    type: "Response",
    commandId: Commands.addNoteMenu,
    leadingIcon: "fas fa-book",
  });
```

* The commands are then made available within the right-click context menu via the `caido.menu.registerItem()` method.
* The `commandId` property takes the value of the `Command` object with the command identifier as a property.
* The `"Request"` and `"Response"` values for the `type` property specify that the request and response editor panes of Caido will now include the command. The commands will be available under the `Plugins` category of the context menu.
* The `leadingIcon` is an optional property and sets the graphical icon of the context menu command selection. The first portion of the value specifies the icon style and the second specifies the icon by its identifier. Icons can be found at <https://fontawesome.com/icons>.

```ts
addPage(caido);
```

The page is registered by calling the `addPage(caido)` function.

```ts
caido.sidebar.registerItem("Notebook", Page, {
  icon: "fas fa-book",
});
```

* The tab in the left-hand menu of the Caido application is registered via the `caido.sidebar.registerItem()` method.
* The `sidebar` takes a `name`, `path` and optional additional `options` properties (*the `icon` property is used by Notebook to display a book icon in the tab*). Again, icons can be found at <https://fontawesome.com/icons>.
  :::

## style.css

::: tip style.css

```css
/* Preserves line breaks and wraps lines that exceed content width. */
#instructions {
  white-space: pre-line;
}

#notesTable {
  width: 100%;
}

/* Allow user to select text. */
#notesTable td {
  user-select: auto;
  -webkit-user-select: auto;
}

/* Settings for the datetime column rows. */
#notesTable td:nth-child(1) {
  width: 200px;
  white-space: pre-wrap;
  text-align: left;
  padding: 8px;
}

/* Settings for the note column rows. */
#notesTable td:nth-child(2) {
  width: auto;
  white-space: pre-line;
  word-wrap: break-word;
  text-align: left;
}

/* Expands width of textarea input to fill width. */
.text-area {
  width: 100%;
  resize: none;
}

.center {
  text-align: center;
}

/* Settings for the table. */
.table-container {
  overflow: auto;
  max-height: 100%;
  max-width: 100%;
}

/* Border to separate table elements. */
.table-container table td {
  border: 1px solid black;
  padding: 5px;
}

.button-container {
  display: flex;
  justify-content: space-between;
}

.bold-brown {
  font-weight: bold;
  color: #b49566;
}

.red {
  color: #f58e97;
}

.bold-red {
  font-weight: bold;
  color: #f58e97;
}

.light-brown {
  color: #e9c38b;
}

/* Moves the datetime and Project name to the top of the table entry. */
.datetime-cell {
  vertical-align: top;
  color: #d1bfa5;
}
```

:::

---

---
url: /plugins/reference/sdks/backend/other.md
---
# Other

### Database

A SQLite database.

The implementation uses a connection pool and is fully asynchronous.
Each connection will be spawned in a worker thread.

#### Example

```ts
const db = await open({ filename: "path/to/database.sqlite" });
await db.exec("CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT);");
await db.exec("INSERT INTO test (name) VALUES ('foo');");
```

#### Constructors

##### Constructor

> **new Database**(): [`Database`](#database)

###### Returns

[`Database`](#database)

#### Methods

##### exec()

> **exec**(`sql`: `string`): `Promise`<`void`>

This method allows one or more SQL statements to be executed without returning any results.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `sql` | `string` |

###### Returns

`Promise`<`void`>

##### prepare()

> **prepare**(`sql`: `string`): `Promise`<[`Statement`](#statement)>

Compiles a SQL statement into a [prepared statement](https://www.sqlite.org/c3ref/stmt.html).

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `sql` | `string` |

###### Returns

`Promise`<[`Statement`](#statement)>

***

### Statement

This class represents a single prepared statement. This class cannot be instantiated via its constructor.
Instead, instances are created via the database.prepare() method.

#### Constructors

##### Constructor

> **new Statement**(): [`Statement`](#statement)

###### Returns

[`Statement`](#statement)

#### Methods

##### all()

> **all**<`T`>(...`params`: [`Parameter`](#parameter)\[]): `Promise`<`T`\[]>

This method executes a prepared statement and returns all results as an array of objects.
If the prepared statement does not return any results, this method returns an empty array.
The prepared statement [parameters are bound](https://www.sqlite.org/c3ref/bind_blob.html) using the values in `params`.

###### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `T` *extends* `object` | `object` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| ...`params` | [`Parameter`](#parameter)\[] | The values to bind to the prepared statement. Named parameters are not supported. |

###### Returns

`Promise`<`T`\[]>

##### get()

> **get**<`T`>(...`params`: [`Parameter`](#parameter)\[]): `Promise`<`T` | `undefined`>

This method executes a prepared statement and returns the first result as an object.
If the prepared statement does not return any results, this method returns undefined.
The prepared statement [parameters are bound](https://www.sqlite.org/c3ref/bind_blob.html) using the values in params.

###### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `T` *extends* `object` | `object` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| ...`params` | [`Parameter`](#parameter)\[] | The values to bind to the prepared statement. Named parameters are not supported. |

###### Returns

`Promise`<`T` | `undefined`>

##### run()

> **run**(...`params`: [`Parameter`](#parameter)\[]): `Promise`<[`Result`](#result)>

This method executes a prepared statement and returns an object summarizing the resulting changes.
The prepared statement [parameters are bound](https://www.sqlite.org/c3ref/bind_blob.html) using the values in params.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| ...`params` | [`Parameter`](#parameter)\[] | The values to bind to the prepared statement. Named parameters are not supported. |

###### Returns

`Promise`<[`Result`](#result)>

***

### Console

> **Console** = `object`

Console interface for logging.

Currently logs are only available in the backend logs.
See the [documentation](https://docs.caido.io/app/troubleshooting/report_bug.html#1-backend-logs) on how to retrieve them.

#### Methods

##### debug()

> **debug**(`message`: `any`): `void`

Log a message with the debug level.

Usually used for troubleshooting purposes.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `message` | `any` |

###### Returns

`void`

##### error()

> **error**(`message`: `any`): `void`

Log a message with the error level.

Usually used for critical errors.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `message` | `any` |

###### Returns

`void`

##### log()

> **log**(`message`: `any`): `void`

Log a message with the info level.

Usually used for general information.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `message` | `any` |

###### Returns

`void`

##### warn()

> **warn**(`message`: `any`): `void`

Log a message with the warn level.

Usually used for unexpected behaviors.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `message` | `any` |

###### Returns

`void`

***

### CreateEnvironmentInput

> **CreateEnvironmentInput** = `object`

#### Properties

##### name

> **name**: `string`

The name of the environment.

##### variables

> **variables**: [`EnvironmentVariable`](environment.md#environmentvariable)\[]

The variables of the environment.

***

### EnvironmentVariableInput

> **EnvironmentVariableInput** = `object`

#### Properties

##### name

> **name**: `string`

The name of the environment variable.

##### secret

> **secret**: `boolean`

If the environment variable should be treated as secret.

##### value

> **value**: `string`

The value of the environment variable.

***

### PageInfo

> **PageInfo** = `object`

Information on the current page of paginated data.

#### Properties

##### endCursor

> **endCursor**: [`Cursor`](shared.md#cursor)

##### hasNextPage

> **hasNextPage**: `boolean`

##### hasPreviousPage

> **hasPreviousPage**: `boolean`

##### startCursor

> **startCursor**: [`Cursor`](shared.md#cursor)

***

### Parameter

> **Parameter** = `null` | `number` | `bigint` | `string` | `Uint8Array`

***

### Result

> **Result** = `object`

#### Properties

##### changes

> **changes**: `number`

##### lastInsertRowid

> **lastInsertRowid**: `number`

***

### UpdateEnvironmentInput

> **UpdateEnvironmentInput** = `object`

#### Properties

##### name?

> `optional` **name**: `string`

The name of the environment.

##### variables?

> `optional` **variables**: [`EnvironmentVariableInput`](#environmentvariableinput)\[]

The variables of the environment.

##### version

> **version**: `number`

The version of the environment to update.
If not equal to the current version, the update will fail.

---

---
url: /plugins/reference/sdks/frontend/other.md
---
# Other

### ChildState

> **ChildState** = { `kind`: `"Empty"`; } | { `kind`: `"NotLoaded"`; } | { `items`: [`ID`](utils.md#id)\[]; `kind`: `"Loaded"`; }

***

### CommandID

> **CommandID** = `string` & `object`

A unique command identifier.

#### Type Declaration

##### \_\_commandId?

> `optional` **\_\_commandId**: `never`

#### Example

```ts
"my-super-command"
```

***

### DefineSlotContent

> **DefineSlotContent**<`TType`, `P`> = [`Prettify`](utils.md#prettify)<`object` & `P`>

#### Type Parameters

| Type Parameter |
| ------ |
| `TType` *extends* `string` |
| `P` *extends* `Record`<`string`, `unknown`> |

***

### FilterSlot

> **FilterSlot** = *typeof* [`FilterSlot`](filters.md#filterslot)\[keyof *typeof* [`FilterSlot`](#filterslot-1)]

***

### FooterSlot

> **FooterSlot** = *typeof* [`FooterSlot`](footer.md#footerslot)\[keyof *typeof* [`FooterSlot`](#footerslot-1)]

***

### HTTPHistorySlot

> **HTTPHistorySlot** = *typeof* [`HTTPHistorySlot`](http-history.md#httphistoryslot)\[keyof *typeof* [`HTTPHistorySlot`](#httphistoryslot-1)]

***

### HTTPHistorySlotContent

> **HTTPHistorySlotContent** = `object`

#### Properties

##### toolbar-primary

> **toolbar-primary**: [`ButtonSlotContent`](slots.md#buttonslotcontent) | [`CustomSlotContent`](slots.md#customslotcontent) | [`CommandSlotContent`](slots.md#commandslotcontent)

***

### JSONPrimitive

> **JSONPrimitive** = `string` | `number` | `boolean` | `null` | `undefined`

***

### KeepOperation

> **KeepOperation**<`T`> = `T` & `object`

#### Type Declaration

##### \_\_operation?

> `optional` **\_\_operation**: `never`

#### Type Parameters

| Type Parameter |
| ------ |
| `T` |

***

### MatchReplaceSlot

> **MatchReplaceSlot** = *typeof* [`MatchReplaceSlot`](match-and-replace.md#matchreplaceslot)\[keyof *typeof* [`MatchReplaceSlot`](#matchreplaceslot-1)]

***

### NotAssignableToJson

> **NotAssignableToJson** = `bigint` | `symbol` | `Function`

***

### ReplaySlot

> **ReplaySlot** = *typeof* [`ReplaySlot`](replay.md#replayslot)\[keyof *typeof* [`ReplaySlot`](#replayslot-1)]

***

### ReplaySlotContent

> **ReplaySlotContent** = `object`

#### Properties

##### session-toolbar-primary

> **session-toolbar-primary**: [`ButtonSlotContent`](slots.md#buttonslotcontent) | [`CustomSlotContent`](slots.md#customslotcontent) | [`CommandSlotContent`](slots.md#commandslotcontent)

##### session-toolbar-secondary

> **session-toolbar-secondary**: [`ButtonSlotContent`](slots.md#buttonslotcontent) | [`CustomSlotContent`](slots.md#customslotcontent) | [`CommandSlotContent`](slots.md#commandslotcontent)

##### topbar

> **topbar**: [`ButtonSlotContent`](slots.md#buttonslotcontent) | [`CustomSlotContent`](slots.md#customslotcontent) | [`CommandSlotContent`](slots.md#commandslotcontent)

***

### Routes

> **Routes** = *typeof* [`Routes`](navigation.md#routes)\[keyof *typeof* [`Routes`](#routes-1)]

***

### ScopeSlot

> **ScopeSlot** = *typeof* [`ScopeSlot`](scopes.md#scopeslot)\[keyof *typeof* [`ScopeSlot`](#scopeslot-1)]

***

### ScopeSlotContent

> **ScopeSlotContent** = `object`

#### Properties

##### create-header

> **create-header**: [`ButtonSlotContent`](slots.md#buttonslotcontent) | [`CustomSlotContent`](slots.md#customslotcontent) | [`CommandSlotContent`](slots.md#commandslotcontent)

##### update-header

> **update-header**: [`ButtonSlotContent`](slots.md#buttonslotcontent) | [`CustomSlotContent`](slots.md#customslotcontent) | [`CommandSlotContent`](slots.md#commandslotcontent)

***

### SearchSlot

> **SearchSlot** = *typeof* [`SearchSlot`](search.md#searchslot)\[keyof *typeof* [`SearchSlot`](#searchslot-1)]

***

### SearchSlotContent

> **SearchSlotContent** = `object`

#### Properties

##### search-toolbar-primary

> **search-toolbar-primary**: [`ButtonSlotContent`](slots.md#buttonslotcontent) | [`CustomSlotContent`](slots.md#customslotcontent) | [`CommandSlotContent`](slots.md#commandslotcontent)

***

### SettingsSlot

> **SettingsSlot** = *typeof* [`SettingsSlot`](#settingsslot)\[keyof *typeof* [`SettingsSlot`](#settingsslot-1)]

***

### SettingsSlotContent

> **SettingsSlotContent** = `object`

#### Properties

##### plugins-section

> **plugins-section**: [`SettingsPluginSlotContent`](settings.md#settingspluginslotcontent)

***

### SitemapRootEntry

> **SitemapRootEntry** = `object`

#### Properties

##### childState

> **childState**: [`ChildState`](#childstate)

The child state of the entry.

##### id

> **id**: [`ID`](utils.md#id)

The ID of the entry.

##### label

> **label**: `string`

The label of the entry.

***

### Source

> **Source** = *typeof* [`Source`](match-and-replace.md#source)\[keyof *typeof* [`Source`](#source-1)]

***

### API

Renames and re-exports [Caido](index.md#caido)

---

---
url: /plugins/reference/sdks/workflow/other.md
---
# Other

### Console

> **Console** = `object`

Console interface for logging.

Currently logs are only available in the backend logs.
See the [documentation](https://docs.caido.io/app/troubleshooting/report_bug.html#1-backend-logs) on how to retrieve them.

#### Methods

##### debug()

> **debug**(`message`: `any`): `void`

Log a message with the debug level.

Usually used for troubleshooting purposes.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `message` | `any` |

###### Returns

`void`

##### error()

> **error**(`message`: `any`): `void`

Log a message with the error level.

Usually used for critical errors.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `message` | `any` |

###### Returns

`void`

##### log()

> **log**(`message`: `any`): `void`

Log a message with the info level.

Usually used for general information.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `message` | `any` |

###### Returns

`void`

##### warn()

> **warn**(`message`: `any`): `void`

Log a message with the warn level.

Usually used for unexpected behaviors.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `message` | `any` |

###### Returns

`void`

***

### CreateEnvironmentInput

> **CreateEnvironmentInput** = `object`

#### Properties

##### name

> **name**: `string`

The name of the environment.

##### variables

> **variables**: [`EnvironmentVariable`](environment.md#environmentvariable)\[]

The variables of the environment.

***

### EnvironmentVariableInput

> **EnvironmentVariableInput** = `object`

#### Properties

##### name

> **name**: `string`

The name of the environment variable.

##### secret

> **secret**: `boolean`

If the environment variable should be treated as secret.

##### value

> **value**: `string`

The value of the environment variable.

***

### PageInfo

> **PageInfo** = `object`

Information on the current page of paginated data.

#### Properties

##### endCursor

> **endCursor**: [`Cursor`](shared.md#cursor)

##### hasNextPage

> **hasNextPage**: `boolean`

##### hasPreviousPage

> **hasPreviousPage**: `boolean`

##### startCursor

> **startCursor**: [`Cursor`](shared.md#cursor)

***

### UpdateEnvironmentInput

> **UpdateEnvironmentInput** = `object`

#### Properties

##### name?

> `optional` **name**: `string`

The name of the environment.

##### variables?

> `optional` **variables**: [`EnvironmentVariableInput`](#environmentvariableinput)\[]

The variables of the environment.

##### version

> **version**: `number`

The version of the environment to update.
If not equal to the current version, the update will fail.

---

---
url: /plugins/concepts/package.md
---
# Plugin Architecture

As Caido utilizes a **client/server architecture** - inherently, this means plugin development consists of many parts:

* A manifest.json file
* A frontend plugin
* A backend plugin

You can conceptualize the difference between these parts in the context of operating a car.

The frontend includes all the buttons, dials, pedals, and other controls available to you as the driver. Some components, such as sun visors and the rear-view mirror, are purely frontend. However, most frontend components communicate with the "under-the-hood" backend. This relationship is what allows actions like pressing the gas pedal to accelerate the engine - or, in the context of Caido; clicking a button to send a request.

The manifest.json file acts as the blueprint of the car, defining how all the components fit together.

These parts are packaged together in a single entity known as a **plugin package**.

## manifest.json

The `manifest.json` configuration file defines the plugin package structure and also contains metadata used by the Caido installer.

Here's an example of what the `manifest.json` file should look like:

```json
{
  "id": "authmatrix",
  "name": "AuthMatrix",
  "version": "0.2.0",
  "description": "Grid-based authorization testing across multiple users and roles.",
  "author": {
    "name": "Caido Labs Inc.",
    "email": "dev@caido.io",
    "url": "https://github.com/caido-community/authmatrix"
  },
  "plugins": [
    {
      "kind": "frontend",
      "id": "authmatrix-frontend",
      "name": "Authmatrix Frontend",
      "entrypoint": "frontend/script.js",
      "style": "frontend/style.css",
      "backend": {
        "id": "authmatrix-backend"
      }
    },
    {
      "kind": "backend",
      "id": "authmatrix-backend",
      "name": "Authmatrix Backend",
      "runtime": "javascript",
      "entrypoint": "backend/script.js"
    }
  ]
}
```

::: info
For more information on the `manifest.json` file, refer to the [manifest.json reference](/plugins/reference/manifest.md).
:::

### Frontend Plugin

A "*page*" in Caido simply refers to a user interface. For example, the [Replay](https://docs.caido.io/app/quickstart/replay) and [Automate](https://docs.caido.io/app/quickstart/automate) side menu tabs each produce their own page.

Within these pages are components and elements specific to the feature, such as option menus and buttons. It is through these components and elements that the appearance is customized or communication with the backend occurs.

Think of the Caido application as a browser window with multiple open tabs, each corresponding to a specific page.

Frontend plugins allow you to:

* Add new pages, components and elements.
* Modify the appearance, behavior and functionality of the user-interface.
* Handle user interactions, render data and communicate with the backend server via Caido's API.

::: info
You can find the full list of available frontend SDK functions in the [frontend SDK reference](/plugins/reference/sdks/frontend/index.md).
:::

### Backend Plugin

The backend refers to what is available server-side, what is "*under-the-hood*" or "*out-of-sight*". By incorporating a backend aspect to your plugin, you can extend upon the server-side functionality.

Backend plugins allow you to:

* Interact with the application's data and databases.
* Perform HTTP requests to external APIs.
* Handle computationally intensive tasks.
* Respond to events that occur within Caido.

::: info
You can find the full list of available backend SDK functions in the [backend SDK reference](/plugins/reference/sdks/backend/index.md).
:::

---

---
url: /plugins/concepts/signing.md
---
# Plugin Signing

If you have gone through the [process of publishing a plugin](/plugins/guides/repository.md) to our store, you had to create keys to sign your plugin.
This ensures that your build process outputs a valid signature on each release.
You can see that signature by looking at the attached files of a given release, it contains a `.sig` file.

## Why signing

The digital signatures are built using [public-key cryptography](https://en.wikipedia.org/wiki/Public-key_cryptography).
This means that a private key is used to generate the signature and a public is used to verify it.
That allows users to authenticate the provenance of a given plugin.

In fact, Caido does that automatically when a user downloads a plugin from the store. We use the public key set in the store [`plugin_packages.json`](https://github.com/caido/store/blob/main/plugin_packages.json) to verify the signature of that particular plugin release. If the signature is valid, then we have a higher level of confience that the plugin is genuine and we proceed with the installation.

Obviously this is not a perfect heuristic since a plugin author could go rogue or could disclose its private key by accident, but it is layer of defense to prevent malicious plugins from getting into the store.

## Supported keys

Caido uses [Edwards-curve Digital Signature Algorithm](https://en.wikipedia.org/wiki/EdDSA) (EdDSA) with the `Ed25519` scheme.
We use this scheme throughout the Caido ecosystem.

::: info
We do NOT support any other digital signature scheme. If you try to use another, the signatures will be rejected by Caido.
:::

## Best practices

Here are the best practices to consider as a plugin developer:

* Use one key pair per plugin, that reduces the impact if your key is leaked.
* Store the private key in a secure location, we recommend [Github Actions Secrets](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions).
* Always encrypt your private key and don't leave it as plain-text on your computer, think of it as a password

::: warning
If you accept contributions on your Github repository, make sure you are careful around changes to the `Github Actions` as those could leak your key.
[See the tips of Github](https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/approving-workflow-runs-from-public-forks) on the subject.
:::

---

---
url: /plugins/reference/plugin_packages.md
---
# plugin\_packages.json

The `plugin_packages.json` file in the [caido/store](https://github.com/caido/store) repository contains the metadata for all plugins available in the Caido store.

In order to add your plugin to the store, you'll need to add an entry to this file.

Here's an example of what the `plugin_packages.json` file looks like:

```json
[
  {
    "id": "authmatrix",
    "name": "AuthMatrix",
    "license": "CC0-1.0",
    "description": "Grid-based authorization testing across multiple users and roles.",
    "author": {
      "name": "Caido Labs Inc.",
      "email": "dev@caido.io",
      "url": "https://caido.io"
    },
    "public_key": "MCowBQYDK2VwAyEA+du2fw/I+CV6MKEpu0aJ1ki2+MO2V0SnaRB91+GbHwQ=",
    "repository": "caido-community/authmatrix"
  },
]
```

Here's a summary of each field:

Field|Description
\-----|-----
`id`|A unique identifier for your plugin. Search `plugin_packages.json` to confirm that there's no existing plugin with the same id.
`name`|Your plugin's name. This will be used as the display name in the store.
`license`|The license of your plugin.
`description`|A short description of your plugin.
`author`|Author details of your plugin.
`public_key`|The Base64 part of the public key generated in the [Setting up your repository](/plugins/guides/repository#_3-generate-a-key-pair) guide. **Don't** include the header/footer (`BEGIN/END PUBLIC KEY`).
`repository`|The path to your GitHub repository. For example, if your GitHub repo is <https://github.com/username/repo-name>, the path is `username/repo-name`.

---

---
url: /plugins/reference/modules/llrt/process/process.md
---
[@caido/quickjs-types](../../index.md) / [llrt/process](index.md) / process

# process

---

---
url: /plugins/reference/sdks/backend/projects.md
---
# Projects

### Project

> **Project** = `object`

A saved immutable Project.

#### Methods

##### getId()

> **getId**(): [`ID`](shared.md#id)

The unique Caido [ID](shared.md#id) of the project.

###### Returns

[`ID`](shared.md#id)

##### getName()

> **getName**(): `string`

The name of the project.

###### Returns

`string`

##### getPath()

> **getPath**(): `string`

The directory where the project is located.

###### Returns

`string`

##### getStatus()

> **getStatus**(): [`ProjectStatus`](#projectstatus)

The status of the project.

###### Returns

[`ProjectStatus`](#projectstatus)

##### getVersion()

> **getVersion**(): `string`

The version of the project.
The format is `MAJOR.MINOR.PATCH`.

###### Returns

`string`

***

### ProjectsSDK

> **ProjectsSDK** = `object`

The SDK for the Projects service.

#### Methods

##### getCurrent()

> **getCurrent**(): `Promise`<[`Project`](#project) | `undefined`>

Get the currently selected [Project](#project) if any.

###### Returns

`Promise`<[`Project`](#project) | `undefined`>

###### Example

```js
await sdk.projects.getCurrent();
```

***

### ProjectStatus

> **ProjectStatus** = `"ready"` | `"restoring"` | `"error"`

A [Project](#project) status.

---

---
url: /plugins/reference/sdks/frontend/projects.md
---
# Projects

### ProjectsPageContext

> **ProjectsPageContext** = `object`

Projects page context.

#### Properties

##### kind

> **kind**: `"Projects"`

***

### ProjectsSDK

> **ProjectsSDK** = `object`

Utilities to interact with projects.

#### Properties

##### onCurrentProjectChange()

> **onCurrentProjectChange**: (`callback`: (`event`: [`SelectedProjectChangeEvent`](#selectedprojectchangeevent)) => `void`) => [`ListenerHandle`](utils.md#listenerhandle)

Subscribe to selected project changes.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `callback` | (`event`: [`SelectedProjectChangeEvent`](#selectedprojectchangeevent)) => `void` | The callback to call when the selected project changes. |

###### Returns

[`ListenerHandle`](utils.md#listenerhandle)

An object with a `stop` method that can be called to stop listening to project changes.

###### Example

```ts
const handler = sdk.projects.onCurrentProjectChange((event) => {
  console.log('Selected project changed to:', event.projectId);
});

// Later, stop listening
handler.stop();
```

***

### SelectedProjectChangeEvent

> **SelectedProjectChangeEvent** = `object`

Event fired when the selected project changes.

#### Properties

##### projectId

> **projectId**: [`ID`](utils.md#id) | `undefined`

---

---
url: /plugins/reference/sdks/workflow/projects.md
---
# Projects

### Project

> **Project** = `object`

A saved immutable Project.

#### Methods

##### getId()

> **getId**(): [`ID`](shared.md#id)

The unique Caido [ID](shared.md#id) of the project.

###### Returns

[`ID`](shared.md#id)

##### getName()

> **getName**(): `string`

The name of the project.

###### Returns

`string`

##### getPath()

> **getPath**(): `string`

The directory where the project is located.

###### Returns

`string`

##### getStatus()

> **getStatus**(): [`ProjectStatus`](#projectstatus)

The status of the project.

###### Returns

[`ProjectStatus`](#projectstatus)

##### getVersion()

> **getVersion**(): `string`

The version of the project.
The format is `MAJOR.MINOR.PATCH`.

###### Returns

`string`

***

### ProjectsSDK

> **ProjectsSDK** = `object`

The SDK for the Projects service.

#### Methods

##### getCurrent()

> **getCurrent**(): `Promise`<[`Project`](#project) | `undefined`>

Get the currently selected [Project](#project) if any.

###### Returns

`Promise`<[`Project`](#project) | `undefined`>

###### Example

```js
await sdk.projects.getCurrent();
```

***

### ProjectStatus

> **ProjectStatus** = `"ready"` | `"restoring"` | `"error"`

A [Project](#project) status.

---

---
url: /client-sdk/concepts/community_python.md
---
# Python SDK

A community-maintained Python port of the official [JavaScript Client SDK](https://github.com/caido/sdk-js), hosted at [`caido-community/sdk-py`](https://github.com/caido-community/sdk-py) under the MIT license. The client is published to PyPI as [`caido-sdk-client`](https://pypi.org/project/caido-sdk-client/).

The repository is a monorepo with two packages that mirror the JavaScript split:

* `caido-sdk-client` is the high-level client that scripts use to interact with a Caido instance.
* `caido-server-auth` is the lower-level authentication library that the client builds on.

The Python SDK is `asyncio`-based, and its type names match the JavaScript SDK closely (`Client`, `PATAuthOptions`, `AuthCacheFile`, and so on).

A minimal usage looks like:

```python
client = Client(
    "http://localhost:8080",
    auth=PATAuthOptions(
        pat="caido_xxxxxx",
        cache=AuthCacheFile(file=".secrets.json"),
    ),
)
await client.connect()
```

## Differences from the JavaScript SDK

The Python SDK supports all three [authentication methods](./auth_methods.md) and the file and custom variants of [token caching](./auth_caching.md). The `localStorage` cache variant has no equivalent in Python, since the language does not have a browser storage model.

---

---
url: /plugins/reference/modules/llrt/globals/namespaces/QuickJS.md
---
[@caido/quickjs-types](../../../index.md) / [llrt/globals](../index.md) / QuickJS

# QuickJS

## Interfaces

### ReadableStream

#### Extends

* [`EventEmitter`](../../events.md#eventemitter)

#### Methods

##### addListener()

> **addListener**<`K`>(`eventName`: [`EventKey`](../../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Alias for `emitter.on(eventName, listener)`.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`EventKey`](../../dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`EventEmitter`](../../events.md#eventemitter).[`addListener`](../../events.md#addlistener)

##### emit()

> **emit**<`K`>(`eventName`: [`EventKey`](../../dom-events.md#eventkey), ...`args`: [`AnyRest`](../../events.md#anyrest)): `void`

Synchronously calls each of the listeners registered for the event named `eventName`, in the order they were registered, passing the supplied arguments
to each.

```js
import { EventEmitter } from 'events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener
```

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`EventKey`](../../dom-events.md#eventkey) |
| ...`args` | [`AnyRest`](../../events.md#anyrest) |

###### Returns

`void`

###### Inherited from

[`EventEmitter`](../../events.md#eventemitter).[`emit`](../../events.md#emit)

##### eventNames()

> **eventNames**(): [`EventKey`](../../dom-events.md#eventkey)\[]

Returns an array listing the events for which the emitter has registered
listeners. The values in the array are strings or `Symbol`s.

```js
import { EventEmitter } from 'events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]
```

###### Returns

[`EventKey`](../../dom-events.md#eventkey)\[]

###### Inherited from

[`EventEmitter`](../../events.md#eventemitter).[`eventNames`](../../events.md#eventnames)

##### off()

> **off**<`K`>(`eventName`: [`EventKey`](../../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Alias for `emitter.removeListener()`.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`EventKey`](../../dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`EventEmitter`](../../events.md#eventemitter).[`off`](../../events.md#off)

##### on()

> **on**<`K`>(`eventName`: [`EventKey`](../../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the end of the listeners array for the event
named `eventName`. No checks are made to see if the `listener` has already
been added. Multiple calls passing the same combination of `eventName` and
`listener` will result in the `listener` being added, and called, multiple times.

```js
server.on('connection', (stream) => {
  console.log('someone connected!');
});
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `eventName` | [`EventKey`](../../dom-events.md#eventkey) | The name of the event. |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Inherited from

[`EventEmitter`](../../events.md#eventemitter).[`on`](../../events.md#on)

##### once()

> **once**<`K`>(`eventName`: [`EventKey`](../../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time** `listener` function for the event named `eventName`. The
next time `eventName` is triggered, this listener is removed and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependOnceListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `eventName` | [`EventKey`](../../dom-events.md#eventkey) | The name of the event. |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Since

v0.3.0

###### Inherited from

[`EventEmitter`](../../events.md#eventemitter).[`once`](../../events.md#once)

##### prependListener()

> **prependListener**<`K`>(`eventName`: [`EventKey`](../../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the *beginning* of the listeners array for the
event named `eventName`. No checks are made to see if the `listener` has
already been added. Multiple calls passing the same combination of `eventName`
and `listener` will result in the `listener` being added, and called, multiple times.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `eventName` | [`EventKey`](../../dom-events.md#eventkey) | The name of the event. |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Inherited from

[`EventEmitter`](../../events.md#eventemitter).[`prependListener`](../../events.md#prependlistener)

##### prependOnceListener()

> **prependOnceListener**<`K`>(`eventName`: [`EventKey`](../../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time**`listener` function for the event named `eventName` to the *beginning* of the listeners array.
The next time `eventName` is triggered, this listener is removed, and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `eventName` | [`EventKey`](../../dom-events.md#eventkey) | The name of the event. |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Inherited from

[`EventEmitter`](../../events.md#eventemitter).[`prependOnceListener`](../../events.md#prependoncelistener)

##### read()

> **read**(`size?`: `number`): [`Buffer`](../../buffer.md#buffer) | `null`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `size?` | `number` |

###### Returns

[`Buffer`](../../buffer.md#buffer) | `null`

##### removeListener()

> **removeListener**<`K`>(`eventName`: [`EventKey`](../../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Removes the specified `listener` from the listener array for the event named `eventName`.

`removeListener()` will remove, at most, one instance of a listener from the
listener array. If any single listener has been added multiple times to the
listener array for the specified `eventName`, then `removeListener()` must be
called multiple times to remove each instance.

Once an event is emitted, all listeners attached to it at the time of emitting are called in order.
This implies that any `removeListener()` calls *after* emitting and *before* the last listener finishes execution
will not remove them from `emit()` in progress. Subsequent events behave as expected.

```js
import { EventEmitter } from 'events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A
```

Because listeners are managed using an internal array, calling this will
change the position indices of any listener registered *after* the listener
being removed. This will not impact the order in which listeners are called,
but it means that any copies of the listener array as returned by
the `emitter.listeners()` method will need to be recreated.

When a single function has been added as a handler multiple times for a single
event (as in the example below), `removeListener()` will remove the most
recently added instance. In the example the `once('ping')` listener is removed:

```js
import { EventEmitter } from 'events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`EventKey`](../../dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`EventEmitter`](../../events.md#eventemitter).[`removeListener`](../../events.md#removelistener)

***

### WritableStream

#### Extends

* [`EventEmitter`](../../events.md#eventemitter)

#### Methods

##### addListener()

> **addListener**<`K`>(`eventName`: [`EventKey`](../../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Alias for `emitter.on(eventName, listener)`.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`EventKey`](../../dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`EventEmitter`](../../events.md#eventemitter).[`addListener`](../../events.md#addlistener)

##### emit()

> **emit**<`K`>(`eventName`: [`EventKey`](../../dom-events.md#eventkey), ...`args`: [`AnyRest`](../../events.md#anyrest)): `void`

Synchronously calls each of the listeners registered for the event named `eventName`, in the order they were registered, passing the supplied arguments
to each.

```js
import { EventEmitter } from 'events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener
```

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`EventKey`](../../dom-events.md#eventkey) |
| ...`args` | [`AnyRest`](../../events.md#anyrest) |

###### Returns

`void`

###### Inherited from

[`EventEmitter`](../../events.md#eventemitter).[`emit`](../../events.md#emit)

##### end()

> **end**(): `this`

###### Returns

`this`

##### eventNames()

> **eventNames**(): [`EventKey`](../../dom-events.md#eventkey)\[]

Returns an array listing the events for which the emitter has registered
listeners. The values in the array are strings or `Symbol`s.

```js
import { EventEmitter } from 'events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]
```

###### Returns

[`EventKey`](../../dom-events.md#eventkey)\[]

###### Inherited from

[`EventEmitter`](../../events.md#eventemitter).[`eventNames`](../../events.md#eventnames)

##### off()

> **off**<`K`>(`eventName`: [`EventKey`](../../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Alias for `emitter.removeListener()`.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`EventKey`](../../dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`EventEmitter`](../../events.md#eventemitter).[`off`](../../events.md#off)

##### on()

> **on**<`K`>(`eventName`: [`EventKey`](../../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the end of the listeners array for the event
named `eventName`. No checks are made to see if the `listener` has already
been added. Multiple calls passing the same combination of `eventName` and
`listener` will result in the `listener` being added, and called, multiple times.

```js
server.on('connection', (stream) => {
  console.log('someone connected!');
});
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `eventName` | [`EventKey`](../../dom-events.md#eventkey) | The name of the event. |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Inherited from

[`EventEmitter`](../../events.md#eventemitter).[`on`](../../events.md#on)

##### once()

> **once**<`K`>(`eventName`: [`EventKey`](../../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time** `listener` function for the event named `eventName`. The
next time `eventName` is triggered, this listener is removed and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependOnceListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `eventName` | [`EventKey`](../../dom-events.md#eventkey) | The name of the event. |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Since

v0.3.0

###### Inherited from

[`EventEmitter`](../../events.md#eventemitter).[`once`](../../events.md#once)

##### prependListener()

> **prependListener**<`K`>(`eventName`: [`EventKey`](../../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the *beginning* of the listeners array for the
event named `eventName`. No checks are made to see if the `listener` has
already been added. Multiple calls passing the same combination of `eventName`
and `listener` will result in the `listener` being added, and called, multiple times.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `eventName` | [`EventKey`](../../dom-events.md#eventkey) | The name of the event. |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Inherited from

[`EventEmitter`](../../events.md#eventemitter).[`prependListener`](../../events.md#prependlistener)

##### prependOnceListener()

> **prependOnceListener**<`K`>(`eventName`: [`EventKey`](../../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time**`listener` function for the event named `eventName` to the *beginning* of the listeners array.
The next time `eventName` is triggered, this listener is removed, and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `eventName` | [`EventKey`](../../dom-events.md#eventkey) | The name of the event. |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Inherited from

[`EventEmitter`](../../events.md#eventemitter).[`prependOnceListener`](../../events.md#prependoncelistener)

##### removeListener()

> **removeListener**<`K`>(`eventName`: [`EventKey`](../../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Removes the specified `listener` from the listener array for the event named `eventName`.

`removeListener()` will remove, at most, one instance of a listener from the
listener array. If any single listener has been added multiple times to the
listener array for the specified `eventName`, then `removeListener()` must be
called multiple times to remove each instance.

Once an event is emitted, all listeners attached to it at the time of emitting are called in order.
This implies that any `removeListener()` calls *after* emitting and *before* the last listener finishes execution
will not remove them from `emit()` in progress. Subsequent events behave as expected.

```js
import { EventEmitter } from 'events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A
```

Because listeners are managed using an internal array, calling this will
change the position indices of any listener registered *after* the listener
being removed. This will not impact the order in which listeners are called,
but it means that any copies of the listener array as returned by
the `emitter.listeners()` method will need to be recreated.

When a single function has been added as a handler multiple times for a single
event (as in the example below), `removeListener()` will remove the most
recently added instance. In the example the `once('ping')` listener is removed:

```js
import { EventEmitter } from 'events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`EventKey`](../../dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`EventEmitter`](../../events.md#eventemitter).[`removeListener`](../../events.md#removelistener)

##### write()

> **write**(`chunk`: `string` | [`ArrayBufferView`](#arraybufferview) | [`Buffer`](../../buffer.md#buffer) | `ArrayBuffer` | `SharedArrayBuffer`, `callback?`: (`err?`: `Error` | `null`) => `void`): `void`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `chunk` | `string` | [`ArrayBufferView`](#arraybufferview) | [`Buffer`](../../buffer.md#buffer) | `ArrayBuffer` | `SharedArrayBuffer` |
| `callback?` | (`err?`: `Error` | `null`) => `void` |

###### Returns

`void`

## Type Aliases

### ArrayBufferView

> **ArrayBufferView** = [`TypedArray`](#typedarray) | `DataView`

***

### Platform

> **Platform** = `"darwin"` | `"linux"` | `"win32"`

***

### Signals

> **Signals** = `"SIGABRT"` | `"SIGALRM"` | `"SIGFPE"` | `"SIGHUP"` | `"SIGILL"` | `"SIGINT"` | `"SIGKILL"` | `"SIGPIPE"` | `"SIGQUIT"` | `"SIGSEGV"` | `"SIGTERM"`

***

### TypedArray

> **TypedArray** = `Uint8Array` | `Uint8ClampedArray` | `Uint16Array` | `Uint32Array` | `Int8Array` | `Int16Array` | `Int32Array` | `BigUint64Array` | `BigInt64Array` | `Float32Array` | `Float64Array`

---

---
url: /plugins/reference/modules.md
---
# QuickJS Modules

Here is the reference of the modules available in our engine.

This documentation is auto-generated from the Typescript typing ([`@caido/quickjs-types`](https://www.npmjs.com/package/@caido/quickjs-types)) which is the source of truth.

Some elements are similar to `Node.JS`, but some imports will be different and start with `caido:`.

## Modules

| Module                                   | Description              | Import             | Global |
| ---------------------------------------- | ------------------------ | ------------------ | ------ |
| [abort](llrt/abort.md)                   | Abort signaling          | N/A                | ✔︎      |
| [buffer](llrt/buffer.md)                 | Buffers                  | `buffer`           | ✔︎      |
| [child\_process](llrt/child_process.md)   | Process spawning         | `child_process`    | ✘      |
| [console](extra/console.md)              | Console logging          | N/A                | ✔︎      |
| [crypto](caido/crypto.md)                | Cryptographic primitives | `crypto`           | ✘      |
| [dom-events](llrt/dom-events.md)         | Event Listeners          | N/A                | ✔︎      |
| [dns](llrt/dns.md)                       | DNS                      | `dns`              | ✘      |
| [events](llrt/events.md)                 | Event Emitter            | `events`           | ✘      |
| [fs](llrt/fs/index.md)                   | File system              | `fs`, `fs/promise` | ✘      |
| [http](caido/http.md)                    | Fetch implementation     | `caido:http`       | ✘      |
| [https](llrt/https.md)                   | HTTPS                    | `https`            | ✘      |
| [globals](llrt/globals/index.md)         | Global classes           | N/A                | ✔︎      |
| [net](llrt/net.md)                       | Sockets                  | `net`              | ✘      |
| [os](extra/os.md)                        | OS information           | `os`               | ✘      |
| [path](llrt/path/index.md)               | Path transformation      | `path`             | ✘      |
| [sqlite](extra/sqlite.md)                | SQlite access            | `sqlite`           | ✘      |
| [stream](llrt/stream/stream.md)          | Streams (basic)          | `stream`           | ✔︎      |
| [stream/web](llrt/stream/web/index.md)   | Streams Web              | `stream/web`       | ✘      |
| [string\_decoder](llrt/string_decoder.md) | String Decoder           | `string_decoder`   | ✘      |
| [timers](extra/timers.md)                | Timers                   | N/A                | ✔︎      |
| [url](llrt/url/index.md)                 | URL utilities            | `url`              | ✔︎      |

---

---
url: /client-sdk/guides/receive_events.md
---
# Receive Plugin Events

Plugin backends can emit events that the Client SDK lets you listen to over a streaming connection. This is useful for surfacing work as it happens (interactions arriving, scans completing, sessions changing) or for reacting to backend state from a long-running script.

This guide covers the explicit `subscribeEvent("name")` form, which works for any installed plugin without extra setup. For fully typed events (inferred payload types for known events), see the next guide on the npm spec packages.

::: info
A runnable version of this guide lives in the SDK repository at [`examples/pluginEvent`](https://github.com/caido/sdk-js/tree/main/packages/sdk-client/examples/pluginEvent). Event names emitted by a plugin (like `interaction:received` for `quickssrf`) come from the plugin's own source. Look for `sdk.api.send("name", ...)` calls in the plugin's backend code or check its repository under [caido-community](https://github.com/caido-community).
:::

## Get the Plugin Handle

To subscribe to events from an installed plugin, you first need its **package handle**. Use `client.plugin.pluginPackage()` to look up the installed plugin by its [manifest ID](./install_plugin.md#1-from-the-caido-store):

```ts
const pkg = await client.plugin.pluginPackage("quickssrf");
if (pkg === undefined) {
  throw new Error("quickssrf is not installed");
}
```

`pluginPackage()` returns `undefined` when no installed plugin matches the manifest ID, so always check the result before subscribing.

## Listen for an Event

To start listening, call `pkg.subscribeEvent(name)`. It returns an `AsyncIterable` that yields the arguments emitted by the backend each time the event fires. Iterate over it with a `for await` loop:

```ts
type Interaction = {
  protocol: string;
  remoteAddress: string;
  timestamp: string;
};

type InteractionReceivedEvent = {
  sessionId: string;
  interactions: Interaction[];
};

for await (const [event] of pkg.subscribeEvent("interaction:received")) {
  const typed = event as InteractionReceivedEvent;
  console.log(
    `Got ${typed.interactions.length} interaction(s) for session ${typed.sessionId}`,
  );
}
```

The destructuring `[event]` takes the first argument the backend passed to `sdk.api.send("interaction:received", payload)`. Since the explicit form is untyped (the SDK does not know what shape each event carries), cast or annotate the value yourself.

::: info
For events with multiple arguments, destructure them all: `for await (const [a, b, c] of pkg.subscribeEvent("name"))`. For events with no arguments, the destructured value is `undefined`.
:::

## Multi-Backend Plugins

To listen to events from a specific backend in a package that ships more than one, pass the object form of `subscribeEvent` with the target backend's `manifestId`:

```ts
for await (const [event] of pkg.subscribeEvent({
  name: "myEvent",
  manifestId: "specific-backend",
})) {
  console.log(event);
}
```

If the package has only one backend, the `manifestId` is optional and the SDK picks it automatically.

## Stop a Subscription

To stop receiving events, `break` out of the `for await` loop:

```ts
for await (const [event] of pkg.subscribeEvent("interaction:received")) {
  if (someCondition) break;
}
```

Internally, the SDK keeps a single upstream connection open while at least one listener is active and tears it down when the last one leaves.

## Examples

The script below creates a `quickssrf` session, then listens for `interaction:received` events tied to that session. Once running, trigger the printed SSRF URL externally (for example, `curl <url>`) to see events arrive.

### index.ts

```ts
import { Client } from "@caido/sdk-client";

type Result<T> =
  | { kind: "Ok"; value: T }
  | { kind: "Error"; error: string };

type Provider = {
  id: string;
  name: string;
  url: string;
};

type Session = {
  id: string;
  providerId: string;
  url: string;
};

type Interaction = {
  protocol: string;
  remoteAddress: string;
  timestamp: string;
};

type InteractionReceivedEvent = {
  sessionId: string;
  interactions: Interaction[];
};

async function main() {
  const client = new Client({
    url: process.env["CAIDO_INSTANCE_URL"] ?? "http://localhost:8080",
    auth: {
      pat: process.env["CAIDO_PAT"]!,
      cache: { file: ".caido-token.json" },
    },
  });

  await client.connect();

  const pkg = await client.plugin.pluginPackage("quickssrf");
  if (pkg === undefined) {
    throw new Error("quickssrf is not installed");
  }

  const providers = await pkg.callFunction<Result<Provider[]>>({
    name: "getProviders",
  });
  if (providers.kind === "Error") {
    throw new Error(`getProviders failed: ${providers.error}`);
  }

  const session = await pkg.callFunction<Result<Session>>({
    name: "createSession",
    arguments: [providers.value[0]!.id],
  });
  if (session.kind === "Error") {
    throw new Error(`createSession failed: ${session.error}`);
  }

  console.log("Listening for interactions on", session.value.url);

  for await (const [event] of pkg.subscribeEvent("interaction:received")) {
    const typed = event as InteractionReceivedEvent;
    if (typed.sessionId !== session.value.id) continue;
    for (const interaction of typed.interactions) {
      console.log("Interaction received:", interaction);
    }
  }
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});
```

Run it with:

```bash
export CAIDO_PAT=caido_xxxxx
npx tsx ./index.ts
```

Then trigger the SSRF URL printed at the start, for example with `curl <url>`. The script prints each interaction as it arrives and keeps running until you stop it with Ctrl+C:

```txt
[caido] Loaded token from cache
Listening for interactions on https://oast.site/abcdef1234567890
Interaction received: {
  protocol: 'http',
  remoteAddress: '203.0.113.42',
  timestamp: '2026-05-08T19:00:00Z'
}
```

---

---
url: /plugins/reference.md
---
# Reference

The reference section contains the auto-generated documentation for the frontend, backend, and workflow SDKs, as well as field definitions for various files.

If you need a refresher on how a function works, or whether a certain feature is possible within plugins, this is the place to look.

## SDKs

* **[Backend SDK](./sdks/backend/index.md)** - Backend Software Development Kit.
* **[Frontend SDK](./sdks/frontend/index.md)** - Frontend Software Development Kit.
* **[Workflow SDK](./sdks/workflow/index.md)** - Workflow Software Development Kit.

## Runtime

* **[Backend Modules](./modules/index.md)** - Backend modules

## Files

* **[caido.config.ts](./config.md)** - caido.config.ts field definitions
* **[plugin\_packages.json](./plugin_packages.md)** - plugin\_packages.json field definitions
* **[manifest.json](./manifest.md)** - Manifest.json field definitions

---

---
url: /plugins/guides/shortcuts.md
---
# Register Shortcuts

Keyboard shortcuts provide quick access to commands, improving the user experience for power users and enabling accessibility features.

## Registering a Shortcut

To register a keyboard shortcut for a command, use `sdk.shortcuts.register()`:

```ts
sdk.shortcuts.register("my-command", ["Control", "Shift", "K"]);
```

The first parameter is the command ID (the same ID used when registering the command), and the second parameter is an array of individual keys that form the key combination.

::: warning
Avoid registering shortcuts that conflict with Caido's built-in shortcuts. Common shortcuts like `["Control", "C"]`, `["Control", "V"]`, `["Control", "Z"]` are reserved for standard operations.
:::

## Key Combination Format

Key combinations are specified as an array of individual key strings. Each key should be a valid [`KeyboardEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values) value:

* Modifier keys: `"Control"`, `"Alt"`, `"Shift"`, `"Meta"` (Command on Mac)
* Regular keys: Any letter, number, or special key (e.g., `"K"`, `"F1"`, `"Enter"`)
* Combinations: Array of keys like `["Control", "K"]`, `["Control", "Shift", "F"]`, `["Alt", "F1"]`

```ts
// Single modifier
sdk.shortcuts.register("save", ["Control", "S"]);

// Multiple modifiers
sdk.shortcuts.register("find", ["Control", "Shift", "F"]);

// Alt key
sdk.shortcuts.register("open-settings", ["Alt", "S"]);
```

## Complete Example

```ts
// First, register the command
sdk.commands.register("quick-action", {
  name: "Quick Action",
  run: () => {
    sdk.window.showToast("Quick action executed!", { variant: "info" });
  },
});

// Then register the keyboard shortcut
sdk.shortcuts.register("quick-action", ["Control", "K"]);
```

You can register multiple key combinations for the same command by calling `register` multiple times:

```ts
sdk.shortcuts.register("quick-action", ["Control", "K"]);
sdk.shortcuts.register("quick-action", ["Control", "Q"]);
sdk.shortcuts.register("quick-action", ["F5"]);
```

## Platform Considerations

* On macOS, `"Meta"` refers to the Command key (⌘)
* On Windows/Linux, `"Meta"` refers to the Windows/Super key
* `"Control"` works consistently across platforms
* Consider providing platform-specific shortcuts if needed

## Examples

### Command with Shortcut

This example registers a command that toggles a feature, assigns it a keyboard shortcut (Control+T), and also makes it available in the command palette. This demonstrates the complete setup for a command with keyboard access.

```ts
import type { Caido } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  // Register command
  sdk.commands.register("toggle-feature", {
    name: "Toggle Feature",
    run: () => {
      // Toggle logic here
      sdk.log.info("Feature toggled");
    },
  });

  // Register keyboard shortcut
  sdk.shortcuts.register("toggle-feature", ["Control", "T"]);

  // Also register to command palette
  sdk.commandPalette.register("toggle-feature");
};
```

::: tip
Keyboard shortcuts work globally when the command is available. Use the `when` property on commands to control when shortcuts are active.
:::

---

---
url: /plugins/reference/sdks/backend/replay.md
---
# Replay

### ReplayCollection

> **ReplayCollection** = `object`

A collection of replay sessions.

#### Methods

##### getId()

> **getId**(): [`ID`](shared.md#id)

The unique Caido [ID](shared.md#id) of the replay collection.

###### Returns

[`ID`](shared.md#id)

##### getName()

> **getName**(): `string`

The name of the replay collection.

###### Returns

`string`

***

### ReplaySDK

> **ReplaySDK** = `object`

The SDK for the Replay service.

#### Methods

##### createSession()

> **createSession**(`source?`: [`RequestSource`](shared.md#requestsource), `collection?`: [`ID`](shared.md#id) | [`ReplayCollection`](#replaycollection)): `Promise`<[`ReplaySession`](#replaysession)>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `source?` | [`RequestSource`](shared.md#requestsource) |
| `collection?` | [`ID`](shared.md#id) | [`ReplayCollection`](#replaycollection) |

###### Returns

`Promise`<[`ReplaySession`](#replaysession)>

##### getCollections()

> **getCollections**(): `Promise`<[`ReplayCollection`](#replaycollection)\[]>

###### Returns

`Promise`<[`ReplayCollection`](#replaycollection)\[]>

***

### ReplaySession

> **ReplaySession** = `object`

A replay session.

#### Methods

##### getId()

> **getId**(): [`ID`](shared.md#id)

The unique Caido [ID](shared.md#id) of the replay session.

###### Returns

[`ID`](shared.md#id)

##### getName()

> **getName**(): `string`

The name of the replay session.

###### Returns

`string`

---

---
url: /plugins/reference/sdks/frontend/replay.md
---
# Replay

### CurrentReplaySessionChangeEvent

> **CurrentReplaySessionChangeEvent** = `object`

Event fired when the current replay session changes.

#### Properties

##### sessionId

> **sessionId**: [`ID`](utils.md#id) | `undefined`

The ID of the newly selected session, or undefined if no session is selected.

***

### OpenTabOptions

> **OpenTabOptions** = `object`

Options for opening a tab.

#### Properties

##### select?

> `optional` **select**: `boolean`

Whether to select the tab after opening it.
Defaults to true.

***

### ReplayCollection

> **ReplayCollection** = `object`

A collection in Replay.

#### Properties

##### id

> **id**: [`ID`](utils.md#id)

The ID of the collection.

##### name

> **name**: `string`

The name of the collection.

##### sessionIds

> **sessionIds**: [`ID`](utils.md#id)\[]

The sessions in the collection.

***

### ReplayCollectionCreatedEvent

> **ReplayCollectionCreatedEvent** = `object`

Event fired when a replay collection is created.

#### Properties

##### collection

> **collection**: [`ReplayCollection`](#replaycollection)

The newly created replay collection.

***

### ReplayEntry

> **ReplayEntry** = `object`

A replay entry.

#### Properties

##### id

> **id**: [`ID`](utils.md#id)

The ID of the entry.

##### requestId?

> `optional` **requestId**: [`ID`](utils.md#id)

The ID of the request associated with this entry, if any.

##### sessionId

> **sessionId**: [`ID`](utils.md#id)

The ID of the session this entry belongs to.

***

### ReplayPageContext

> **ReplayPageContext** = `object`

Replay page context.

#### Properties

##### kind

> **kind**: `"Replay"`

##### selection

> **selection**: [`Selection`](utils.md#selection)<[`ReplaySessionId`](#replaysessionid)>

***

### ReplaySDK

> **ReplaySDK** = `object`

Utilities to interact with Replay.

#### Properties

##### addRequestEditorExtension()

> **addRequestEditorExtension**: (`extension`: `Extension`) => `void`

Add an extension to the request editor.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `extension` | `Extension` | The extension to add. |

###### Returns

`void`

##### addRequestViewMode()

> **addRequestViewMode**: (`options`: [`RequestViewModeOptions`](request.md#requestviewmodeoptions)) => `void`

Add a custom view mode for requests.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`RequestViewModeOptions`](request.md#requestviewmodeoptions) | The view mode options. |

###### Returns

`void`

##### addResponseViewMode()

> **addResponseViewMode**: (`options`: [`ResponseViewModeOptions`](response.md#responseviewmodeoptions)) => `void`

Add a custom response view mode.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`ResponseViewModeOptions`](response.md#responseviewmodeoptions) | The view mode options. |

###### Returns

`void`

##### addSessionIndicator()

> **addSessionIndicator**: (`sessionId`: [`ID`](utils.md#id), `indicator`: [`AddIndicatorOptions`](utils.md#addindicatoroptions)) => [`Indicator`](utils.md#indicator)

Add an indicator to a replay session.
Indicators are displayed next to the session name in the collections tree.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `sessionId` | [`ID`](utils.md#id) | The ID of the session to add the indicator to. |
| `indicator` | [`AddIndicatorOptions`](utils.md#addindicatoroptions) | The indicator configuration. |

###### Returns

[`Indicator`](utils.md#indicator)

A handle object with a `remove` method to remove the indicator.

###### Example

```ts
const indicator = sdk.replay.addSessionIndicator(sessionId, {
  icon: "fas fa-exclamation-triangle",
  description: "Security warning",
});

// Later, remove the indicator
indicator.remove();
```

##### addToSlot

> **addToSlot**: [`DefineAddToSlotFn`](slots.md#defineaddtoslotfn)<[`ReplaySlotContent`](other.md#replayslotcontent)>

Add a component to a slot.

###### Param

The slot to add the component to.

###### Param

The content to add to the slot.

###### Example

```ts
addToSlot(ReplaySlot.SessionToolbarPrimary, {
  kind: "Command",
  commandId: "my-command",
  icon: "my-icon",
});

addToSlot(ReplaySlot.SessionToolbarSecondary, {
  kind: "Custom",
  component: MyComponent,
});

addToSlot(ReplaySlot.Topbar, {
  kind: "Button",
  label: "My Button",
  icon: "my-icon",
  onClick: () => {
    console.log("Button clicked");
  },
});
```

##### closeTab()

> **closeTab**: (`sessionId`: [`ID`](utils.md#id)) => `void`

Close a replay tab for the given session.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `sessionId` | [`ID`](utils.md#id) | The ID of the session to close. |

###### Returns

`void`

##### createCollection()

> **createCollection**: (`name`: `string`) => `Promise`<[`ReplayCollection`](#replaycollection)>

Create a new collection.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `name` | `string` | The name of the collection to create. |

###### Returns

`Promise`<[`ReplayCollection`](#replaycollection)>

##### createSession()

> **createSession**: (`source`: [`RequestSource`](#requestsource), `collectionId?`: [`ID`](utils.md#id)) => `Promise`<`void`>

Create a session.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `source` | [`RequestSource`](#requestsource) | - |
| `collectionId?` | [`ID`](utils.md#id) | The ID of the collection to add the request. |

###### Returns

`Promise`<`void`>

##### deleteCollection()

> **deleteCollection**: (`id`: [`ID`](utils.md#id)) => `Promise`<`boolean`>

Delete a collection.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](utils.md#id) | The ID of the collection to delete. |

###### Returns

`Promise`<`boolean`>

Whether the collection was deleted.

##### deleteSessions()

> **deleteSessions**: (`sessionIds`: [`ID`](utils.md#id)\[]) => `Promise`<[`ID`](utils.md#id)\[]>

Delete a session.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `sessionIds` | [`ID`](utils.md#id)\[] | The IDs of the sessions to delete. |

###### Returns

`Promise`<[`ID`](utils.md#id)\[]>

##### getCollections()

> **getCollections**: () => [`ReplayCollection`](#replaycollection)\[]

Get the list of all replay collections.

###### Returns

[`ReplayCollection`](#replaycollection)\[]

The list of all replay collections.

##### getCurrentSession()

> **getCurrentSession**: () => [`ReplaySession`](#replaysession) | `undefined`

Get the currently selected replay session.

###### Returns

[`ReplaySession`](#replaysession) | `undefined`

The currently selected replay session, or undefined if no session is selected.

###### Example

```ts
const currentSession = sdk.replay.getCurrentSession();
if (currentSession) {
  console.log(`Current session: ${currentSession.name}`);
} else {
  console.log("No session is currently selected");
}
```

##### getEntry()

> **getEntry**: (`entryId`: [`ID`](utils.md#id)) => [`ReplayEntry`](#replayentry)

Get a replay entry by its ID.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `entryId` | [`ID`](utils.md#id) | The ID of the entry to get. |

###### Returns

[`ReplayEntry`](#replayentry)

The replay entry.

###### Example

```ts
const entry = await sdk.replay.getEntry(entryId);
console.log(entry.id, entry.sessionId, entry.requestId);
```

##### getSessions()

> **getSessions**: () => [`ReplaySession`](#replaysession)\[]

Get the list of all replay sessions.

###### Returns

[`ReplaySession`](#replaysession)\[]

The list of all replay sessions.

##### getTabs()

> **getTabs**: () => [`ReplayTab`](#replaytab)\[]

Get the list of all open replay tabs.

###### Returns

[`ReplayTab`](#replaytab)\[]

The list of all open replay tabs.

##### moveSession()

> **moveSession**: (`sessionId`: [`ID`](utils.md#id), `collectionId`: [`ID`](utils.md#id)) => `Promise`<[`ReplaySession`](#replaysession)>

Move a session to a different collection.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `sessionId` | [`ID`](utils.md#id) | The ID of the session to move. |
| `collectionId` | [`ID`](utils.md#id) | The ID of the collection to move the session to. |

###### Returns

`Promise`<[`ReplaySession`](#replaysession)>

The updated session.

##### onCollectionCreate()

> **onCollectionCreate**: (`callback`: (`event`: [`ReplayCollectionCreatedEvent`](#replaycollectioncreatedevent)) => `void`) => [`ListenerHandle`](utils.md#listenerhandle)

Subscribe to replay collection creation events.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `callback` | (`event`: [`ReplayCollectionCreatedEvent`](#replaycollectioncreatedevent)) => `void` | The callback to call when a collection is created. |

###### Returns

[`ListenerHandle`](utils.md#listenerhandle)

An object with a `stop` method that can be called to stop listening to collection creation events.

###### Example

```ts
const handler = sdk.replay.onCollectionCreate((event) => {
  console.log(`Collection ${event.collection.id} was created!`);
});

// Later, stop listening
handler.stop();
```

##### onCurrentSessionChange()

> **onCurrentSessionChange**: (`callback`: (`event`: [`CurrentReplaySessionChangeEvent`](#currentreplaysessionchangeevent)) => `void`) => [`ListenerHandle`](utils.md#listenerhandle)

Subscribe to current replay session changes.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `callback` | (`event`: [`CurrentReplaySessionChangeEvent`](#currentreplaysessionchangeevent)) => `void` | The callback to call when the selected session changes. |

###### Returns

[`ListenerHandle`](utils.md#listenerhandle)

An object with a `stop` method that can be called to stop listening to session changes.

###### Example

```ts
const handler = sdk.replay.onCurrentSessionChange((event) => {
  console.log(`Session ${event.sessionId} got selected!`);
});

// Later, stop listening
handler.stop();
```

##### onSessionCreate()

> **onSessionCreate**: (`callback`: (`event`: [`ReplaySessionCreatedEvent`](#replaysessioncreatedevent)) => `void`) => [`ListenerHandle`](utils.md#listenerhandle)

Subscribe to replay session creation events.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `callback` | (`event`: [`ReplaySessionCreatedEvent`](#replaysessioncreatedevent)) => `void` | The callback to call when a session is created. |

###### Returns

[`ListenerHandle`](utils.md#listenerhandle)

An object with a `stop` method that can be called to stop listening to session creation events.

###### Example

```ts
const handler = sdk.replay.onSessionCreate((event) => {
  console.log(`Session ${event.session.id} was created!`);
});

// Later, stop listening
handler.stop();
```

##### openTab()

> **openTab**: (`sessionId`: [`ID`](utils.md#id), `options?`: [`OpenTabOptions`](#opentaboptions)) => `void`

Open a replay tab for the given session.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `sessionId` | [`ID`](utils.md#id) | The ID of the session to open. |
| `options?` | [`OpenTabOptions`](#opentaboptions) | The options for opening the tab. |

###### Returns

`void`

##### renameCollection()

> **renameCollection**: (`id`: [`ID`](utils.md#id), `name`: `string`) => `Promise`<[`ReplayCollection`](#replaycollection)>

Rename a collection.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](utils.md#id) | The ID of the collection to rename. |
| `name` | `string` | The new name of the collection. |

###### Returns

`Promise`<[`ReplayCollection`](#replaycollection)>

The updated collection.

##### renameSession()

> **renameSession**: (`id`: [`ID`](utils.md#id), `name`: `string`) => `Promise`<[`ReplaySession`](#replaysession)>

Rename a session.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](utils.md#id) | The ID of the session to rename. |
| `name` | `string` | The new name of the session. |

###### Returns

`Promise`<[`ReplaySession`](#replaysession)>

The updated session.

##### sendRequest()

> **sendRequest**: (`sessionId`: [`ID`](utils.md#id), `options`: [`SendRequestOptions`](#sendrequestoptions)) => `Promise`<`void`>

Send a request to the Replay backend.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `sessionId` | [`ID`](utils.md#id) | - |
| `options` | [`SendRequestOptions`](#sendrequestoptions) | The options for sending the request. |

###### Returns

`Promise`<`void`>

###### Example

```ts
sendRequest(sessionId, {
  connectionInfo: {
    SNI: "example.com",
    host: "example.com",
    isTLS: true,
    port: 443,
  },
  raw: "GET / HTTP/1.1\r\nHost: example.com\r\n\r\n",
  updateContentLength: false,
});
```

##### showEntry()

> **showEntry**: (`sessionId`: [`ID`](utils.md#id), `entryId`: [`ID`](utils.md#id), `options?`: `object`) => `Promise`<`void`>

Show a specific entry in a replay session.
This will open the session tab if not already open, set it as the selected session, and display the specified entry.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `sessionId` | [`ID`](utils.md#id) | The ID of the session containing the entry. |
| `entryId` | [`ID`](utils.md#id) | The ID of the entry to show. |
| `options?` | { `overwriteDraft?`: `boolean`; } | The options for showing the entry. |
| `options.overwriteDraft?` | `boolean` | Whether to overwrite the request draft. If true, the draft will be removed and the entry's raw request will be shown. If false, the draft will be kept. |

###### Returns

`Promise`<`void`>

###### Example

```ts
await sdk.replay.showEntry(sessionId, entryId, {
  overwriteDraft: true,
});
```

***

### ReplaySession

> **ReplaySession** = `object`

A session in Replay.

#### Properties

##### collectionId

> **collectionId**: [`ID`](utils.md#id)

The ID of the collection the session belongs to.

##### entryIds

> **entryIds**: [`ID`](utils.md#id)\[]

The IDs of all entries in this session.

##### id

> **id**: [`ID`](utils.md#id)

The ID of the session.

##### name

> **name**: `string`

The name of the session.

***

### ReplaySessionCreatedEvent

> **ReplaySessionCreatedEvent** = `object`

Event fired when a replay session is created.

#### Properties

##### session

> **session**: [`ReplaySession`](#replaysession)

The newly created replay session.

***

### ReplaySessionId

> **ReplaySessionId** = `string` & `object`

A unique replay session identifier.

#### Type Declaration

##### \_\_replaySessionId?

> `optional` **\_\_replaySessionId**: `never`

***

### ReplayTab

> **ReplayTab** = `object`

A replay tab.

#### Properties

##### sessionId

> **sessionId**: [`ID`](utils.md#id)

The ID of the session associated with this tab.

***

### RequestSource

> **RequestSource** = { `connectionInfo`: [`SendRequestOptions`](#sendrequestoptions)\[`"connectionInfo"`]; `raw`: `string`; `type`: `"Raw"`; } | { `id`: `string`; `type`: `"ID"`; }

#### Remarks

This type is a discriminated union with two possible shapes:

* A raw request, containing the raw HTTP request string and connection information.
* A reference to an existing request ID.

#### Example

```ts
// Using a raw request
const source: RequestSource = {
  type: "Raw",
  raw: "GET /api/data HTTP/1.1",
  connectionInfo: { ... }
};
// Using an ID
const source: RequestSource = {
  type: "ID",
  id: "request-123"
};
```

***

### SendRequestOptions

> **SendRequestOptions** = `object`

Options for sending a request.

#### Properties

##### background?

> `optional` **background**: `boolean`

Whether to send the request in the background without updating the UI.
If true, the request will not update the UI.
If false, the UI will be updated to display the session and the new request.
Defaults to false.

##### connectionClose?

> `optional` **connectionClose**: `boolean`

Whether to force close the connection by setting Connection: close header.
Defaults to true.

##### connectionInfo

> **connectionInfo**: `object`

The connection information to use for the request.

###### host

> **host**: `string`

The host to use for the request.

###### isTLS

> **isTLS**: `boolean`

Whether the request is TLS.

###### port

> **port**: `number`

The port to use for the request.

###### SNI?

> `optional` **SNI**: `string`

The SNI to use for the request.
If not provided, the SNI will be inferred from the host.

##### overwriteDraft?

> `optional` **overwriteDraft**: `boolean`

Whether to overwrite the editor's draft content.
If true, draft content will be overwritten with the new request.
If false, the draft will be kept.
Defaults to true.

##### raw

> **raw**: `string`

The raw request to send.

##### updateContentLength?

> `optional` **updateContentLength**: `boolean`

Whether to update the content length automatically to match the body.
Defaults to true.

***

### ReplaySlot

> `const` **ReplaySlot**: `object`

The slots in the Replay UI.

#### Type Declaration

##### SessionToolbarPrimary

> `readonly` **SessionToolbarPrimary**: `"session-toolbar-primary"`

The left side of the session toolbar.

##### SessionToolbarSecondary

> `readonly` **SessionToolbarSecondary**: `"session-toolbar-secondary"`

The right side of the session toolbar.

##### Topbar

> `readonly` **Topbar**: `"topbar"`

The left side of the topbar.

---

---
url: /plugins/reference/sdks/workflow/replay.md
---
# Replay

### ReplayCollection

> **ReplayCollection** = `object`

A collection of replay sessions.

#### Methods

##### getId()

> **getId**(): [`ID`](shared.md#id)

The unique Caido [ID](shared.md#id) of the replay collection.

###### Returns

[`ID`](shared.md#id)

##### getName()

> **getName**(): `string`

The name of the replay collection.

###### Returns

`string`

***

### ReplaySDK

> **ReplaySDK** = `object`

The SDK for the Replay service.

#### Methods

##### createSession()

> **createSession**(`source?`: [`RequestSource`](shared.md#requestsource), `collection?`: [`ID`](shared.md#id) | [`ReplayCollection`](#replaycollection)): `Promise`<[`ReplaySession`](#replaysession)>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `source?` | [`RequestSource`](shared.md#requestsource) |
| `collection?` | [`ID`](shared.md#id) | [`ReplayCollection`](#replaycollection) |

###### Returns

`Promise`<[`ReplaySession`](#replaysession)>

##### getCollections()

> **getCollections**(): `Promise`<[`ReplayCollection`](#replaycollection)\[]>

###### Returns

`Promise`<[`ReplayCollection`](#replaycollection)\[]>

***

### ReplaySession

> **ReplaySession** = `object`

A replay session.

#### Methods

##### getId()

> **getId**(): [`ID`](shared.md#id)

The unique Caido [ID](shared.md#id) of the replay session.

###### Returns

[`ID`](shared.md#id)

##### getName()

> **getName**(): `string`

The name of the replay session.

###### Returns

`string`

---

---
url: /plugins/reference/sdks/frontend/request.md
---
# Request

### RequestDraft

> **RequestDraft** = [`Prettify`](utils.md#prettify)<[`As`](utils.md#as)<`"RequestDraft"`> & `object`>

A draft request that has not yet been saved to the database.

***

### RequestFull

> **RequestFull** = [`Prettify`](utils.md#prettify)<[`As`](utils.md#as)<`"RequestFull"`> & `object`>

A complete request with all metadata and raw content.

***

### RequestMeta

> **RequestMeta** = [`Prettify`](utils.md#prettify)<[`As`](utils.md#as)<`"RequestMeta"`> & `object`>

Metadata about a request without the raw content.

***

### RequestViewModeOptions

> **RequestViewModeOptions** = `object`

Options for defining a custom request view mode.

#### Properties

##### label

> **label**: `string`

The label of the view mode.

##### view

> **view**: [`ComponentDefinition`](utils.md#componentdefinition)

The component to render when the view mode is selected.

##### when()?

> `optional` **when**: (`request`: [`RequestFull`](#requestfull) | [`RequestDraft`](#requestdraft)) => `boolean`

A function that determines if the view mode should be shown for a given request.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `request` | [`RequestFull`](#requestfull) | [`RequestDraft`](#requestdraft) |

###### Returns

`boolean`

---

---
url: /plugins/reference/sdks/backend/requests.md
---
# Requests

### Body

The body of a [Request](#request) or [Response](#response).

Calling `to<FORMAT>` will try to convert the body to the desired format.

#### Constructors

##### Constructor

> **new Body**(`data`: `string` | `number`\[] | `Uint8Array`): [`Body`](#body)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `data` | `string` | `number`\[] | `Uint8Array` |

###### Returns

[`Body`](#body)

#### Properties

##### length

> `readonly` **length**: `number`

The length of the body in bytes.

#### Methods

##### toJson()

> **toJson**(): `unknown`

Try to parse the body as JSON.

###### Returns

`unknown`

###### Throws

If the body is not valid JSON.

##### toRaw()

> **toRaw**(): `Uint8Array`

Get the raw body as an array of bytes.

###### Returns

`Uint8Array`

##### toText()

> **toText**(): `string`

Parse the body as a string.

Unprintable characters will be replaced with `�`.

###### Returns

`string`

***

### RequestSpec

A mutable Request that has not yet been sent.

#### Constructors

##### Constructor

> **new RequestSpec**(`url`: `string`): [`RequestSpec`](#requestspec)

Build a new [RequestSpec](#requestspec) from a URL string.
We try to infer as much information as possible from the URL, including the scheme, host, path and query.

You can convert a saved immutable [Request](#request) object into a [RequestSpec](#requestspec) object by using the `toSpec()` method.

By default:

* Method is `GET`.
* Path is `/`.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `url` | `string` |

###### Returns

[`RequestSpec`](#requestspec)

###### Throws

If the URL is invalid.

###### Example

```js
const spec = new RequestSpec("https://example.com");
```

#### Methods

##### getBody()

> **getBody**(): [`Body`](#body) | `undefined`

The body of the request.

###### Returns

[`Body`](#body) | `undefined`

##### getHeader()

> **getHeader**(`name`: `string` | [`GetHeaderOptions`](#getheaderoptions)): `string`\[] | `undefined`

Get a header value.

Header name is case-insensitive.
The header might have multiple values.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` | [`GetHeaderOptions`](#getheaderoptions) |

###### Returns

`string`\[] | `undefined`

##### getHeaders()

> **getHeaders**(): `Record`<`string`, `string`\[]>

The headers of the request.

Header names are case-insensitive.
Each header might have multiple values.

###### Returns

`Record`<`string`, `string`\[]>

###### Example

```json
{
  "Host": ["caido.io"],
  "Connection": ["keep-alive"],
  "Content-Length": ["95"]
}
```

##### getHost()

> **getHost**(): `string`

Get the host of the request.

###### Returns

`string`

##### getInfo()

> **getInfo**(): [`ConnectionInfo`](net.md#connectioninfo)

Get the connection information of the request.

###### Returns

[`ConnectionInfo`](net.md#connectioninfo)

The connection information.

##### getMethod()

###### Call Signature

> **getMethod**(): `string`

Get the HTTP method of the request.

Get the raw version by passing `{ raw: true }` in the options.

###### Returns

`string`

###### Call Signature

> **getMethod**(`options`: [`RawOption`](shared.md#rawoption)): `Uint8Array`

Get the HTTP method of the request.

Get the raw version by passing `{ raw: true }` in the options.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | [`RawOption`](shared.md#rawoption) |

###### Returns

`Uint8Array`

##### getPath()

###### Call Signature

> **getPath**(): `string`

Get the path of the request.

Get the raw version by passing `{ raw: true }` in the options.

###### Returns

`string`

###### Call Signature

> **getPath**(`options`: [`RawOption`](shared.md#rawoption)): `Uint8Array`

Get the path of the request.

Get the raw version by passing `{ raw: true }` in the options.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | [`RawOption`](shared.md#rawoption) |

###### Returns

`Uint8Array`

##### getPort()

> **getPort**(): `number`

Get the port of the request.

###### Returns

`number`

##### getQuery()

###### Call Signature

> **getQuery**(): `string`

Get the unparsed query of the request.

Get the raw version by passing `{ raw: true }` in the options.

Excludes the leading `?`.

###### Returns

`string`

###### Call Signature

> **getQuery**(`options`: [`RawOption`](shared.md#rawoption)): `Uint8Array`

Get the unparsed query of the request.

Get the raw version by passing `{ raw: true }` in the options.

Excludes the leading `?`.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | [`RawOption`](shared.md#rawoption) |

###### Returns

`Uint8Array`

##### getRaw()

> **getRaw**(): [`RequestSpecRaw`](#requestspecraw)

This methods converts the [RequestSpec](#requestspec) to a [RequestSpecRaw](#requestspecraw).

This is useful to retrieve the raw bytes of the request.

###### Returns

[`RequestSpecRaw`](#requestspecraw)

###### Example

```js
const spec = new RequestSpec("https://example.com");
const specRaw = spec.getRaw();
const bytes = specRaw.getRaw(); // GET / HTTP/1.1\r\nHost: example.com\r\n\r\n
```

##### getTls()

> **getTls**(): `boolean`

Get if the request uses TLS (HTTPS).

###### Returns

`boolean`

##### getUrl()

> **getUrl**(): `string`

The full URL of the request.

###### Returns

`string`

##### removeHeader()

> **removeHeader**(`name`: `string`): `void`

Removes a header.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |

###### Returns

`void`

##### setBody()

> **setBody**(`body`: [`Bytes`](shared.md#bytes) | [`Body`](#body), `options?`: [`SetBodyOptions`](#setbodyoptions)): `void`

Set the body of the request.

The body can either be a [Body](#body) or any type that can be converted to [Bytes](shared.md#bytes).

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `body` | [`Bytes`](shared.md#bytes) | [`Body`](#body) |
| `options?` | [`SetBodyOptions`](#setbodyoptions) |

###### Returns

`void`

###### Example

```js
const body = new Body("Hello world.");
const options = { updateContentLength: true };
request.setBody(body, options);
```

##### setHeader()

> **setHeader**(`name`: `string`, `value`: `string`): `void`

Set a header value.

This will overwrite any existing values.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |
| `value` | `string` |

###### Returns

`void`

##### setHost()

> **setHost**(`host`: `string`): `void`

Set the host of the request.

It will also update the `Host` header.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `host` | `string` |

###### Returns

`void`

##### setMethod()

> **setMethod**(`method`: [`Bytes`](shared.md#bytes)): `void`

Set the HTTP method of the request.

All strings are accepted.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `method` | [`Bytes`](shared.md#bytes) |

###### Returns

`void`

##### setPath()

> **setPath**(`path`: [`Bytes`](shared.md#bytes)): `void`

Set the path of the request.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `path` | [`Bytes`](shared.md#bytes) |

###### Returns

`void`

##### setPort()

> **setPort**(`port`: `number`): `void`

Set the port of the request.

The port number must be between 1 and 65535.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `port` | `number` |

###### Returns

`void`

##### setQuery()

> **setQuery**(`query`: [`Bytes`](shared.md#bytes)): `void`

Set the unparsed query of the request.

The query string should not include the leading `?`.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `query` | [`Bytes`](shared.md#bytes) |

###### Returns

`void`

###### Example

```js
spec.setQuery("q=hello");
```

##### setRaw()

> **setRaw**(`raw`: [`Bytes`](shared.md#bytes)): [`RequestSpecRaw`](#requestspecraw)

This method sets the raw [Bytes](shared.md#bytes) of the request and converts it to a [RequestSpecRaw](#requestspecraw).

This is useful when you have a prepared [RequestSpec](#requestspec) and you just want to modify the raw data.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `raw` | [`Bytes`](shared.md#bytes) |

###### Returns

[`RequestSpecRaw`](#requestspecraw)

###### Example

```js
const rawBytes = []; // RAW BYTES HERE
const request = new RequestSpec("https://example.com");
const rawRequest = request.setRaw(rawBytes);
```

##### setTls()

> **setTls**(`tls`: `boolean`): `void`

Set if the request uses TLS (HTTPS).

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `tls` | `boolean` |

###### Returns

`void`

##### parse()

###### Call Signature

> `static` **parse**(`bytes`: [`Bytes`](shared.md#bytes)): [`RequestSpec`](#requestspec)

Parses raw bytes into a [RequestSpec](#requestspec).

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `bytes` | [`Bytes`](shared.md#bytes) |

###### Returns

[`RequestSpec`](#requestspec)

###### Throws

If the bytes are not a valid HTTP request.

###### Example

```js
const rawInput = 'GET / HTTP/1.1\r\nHost: example.com\r\n\r\n';
const spec = RequestSpec.parse(rawInput);
spec.setHeader('x-caido', 'test');
const specRaw = spec.getRaw();
const rawOutput = specRaw.getRaw(); // Will contain the new header
```

###### Call Signature

> `static` **parse**(`raw`: [`RequestSpecRaw`](#requestspecraw)): [`RequestSpec`](#requestspec)

Parses the raw bytes of a [RequestSpecRaw](#requestspecraw) into a [RequestSpec](#requestspec).

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `raw` | [`RequestSpecRaw`](#requestspecraw) |

###### Returns

[`RequestSpec`](#requestspec)

###### Throws

If the bytes are not a valid HTTP request.

***

### RequestSpecRaw

A mutable raw Request that has not yet been sent.

#### Constructors

##### Constructor

> **new RequestSpecRaw**(`url`: `string`): [`RequestSpecRaw`](#requestspecraw)

Build a new [RequestSpecRaw](#requestspecraw) from a URL string. Only the host, port and scheme will be parsed.

You can convert a saved immutable [Request](#request) object into a [RequestSpecRaw](#requestspecraw) object by using the `toSpecRaw()` method.

You MUST use `setRaw` to set the raw bytes of the request.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `url` | `string` |

###### Returns

[`RequestSpecRaw`](#requestspecraw)

###### Example

```js
const spec = new RequestSpecRaw("https://example.com");
```

#### Methods

##### getHost()

> **getHost**(): `string`

Get the host of the request.

###### Returns

`string`

##### getInfo()

> **getInfo**(): [`ConnectionInfo`](net.md#connectioninfo)

Get the connection information of the request.

###### Returns

[`ConnectionInfo`](net.md#connectioninfo)

The connection information.

##### getPort()

> **getPort**(): `number`

Get the port of the request.

###### Returns

`number`

##### getRaw()

> **getRaw**(): `Uint8Array`

Get the raw bytes of the request.

###### Returns

`Uint8Array`

##### ~~getSpec()~~

> **getSpec**(): [`RequestSpec`](#requestspec)

This methods converts the [RequestSpecRaw](#requestspecraw) to a [RequestSpec](#requestspec).

###### Returns

[`RequestSpec`](#requestspec)

###### Deprecated

Use `toSpec` instead.

###### Throws

If the bytes are not a valid HTTP request.

###### See

[RequestSpec.parse](#parse)

##### getTls()

> **getTls**(): `boolean`

Get if the request uses TLS (HTTPS).

###### Returns

`boolean`

##### setHost()

> **setHost**(`host`: `string`): `void`

Set the host of the request.

It will NOT update the `Host` header.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `host` | `string` |

###### Returns

`void`

##### setPort()

> **setPort**(`port`: `number`): `void`

Set the port of the request.

The port number must be between 1 and 65535.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `port` | `number` |

###### Returns

`void`

##### setRaw()

> **setRaw**(`raw`: [`Bytes`](shared.md#bytes)): `void`

Set the raw [Bytes](shared.md#bytes) of the request.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `raw` | [`Bytes`](shared.md#bytes) |

###### Returns

`void`

##### setTls()

> **setTls**(`tls`: `boolean`): `void`

Set if the request uses TLS (HTTPS).

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `tls` | `boolean` |

###### Returns

`void`

##### toSpec()

> **toSpec**(): [`RequestSpec`](#requestspec)

This methods converts the [RequestSpecRaw](#requestspecraw) to a [RequestSpec](#requestspec).

###### Returns

[`RequestSpec`](#requestspec)

###### Throws

If the bytes are not a valid HTTP request.

###### See

[RequestSpec.parse](#parse)

***

### GetHeaderOptions

> **GetHeaderOptions** = `object`

Options for getting a header value.

#### Properties

##### name

> **name**: `string`

The name of the header to get.
Header name is case-insensitive.

##### split?

> `optional` **split**: `boolean`

Whether to split the header value on commas.

###### Default

```ts
false
```

***

### Request

> **Request** = `object`

An immutable saved Request.

To modify, use `toSpec` to get a `RequestSpec` object.

#### Methods

##### getBody()

> **getBody**(): [`Body`](#body) | `undefined`

The body of the request.

###### Returns

[`Body`](#body) | `undefined`

##### getCreatedAt()

> **getCreatedAt**(): `Date`

The datetime the request was recorded by the proxy.

###### Returns

`Date`

##### getHeader()

> **getHeader**(`name`: `string` | [`GetHeaderOptions`](#getheaderoptions)): `string`\[] | `undefined`

Get a header value.

Header name is case-insensitive.
The header might have multiple values.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` | [`GetHeaderOptions`](#getheaderoptions) |

###### Returns

`string`\[] | `undefined`

##### getHeaders()

> **getHeaders**(): `Record`<`string`, `string`\[]>

The headers of the request.

Header names are case-insensitive.
Each header might have multiple values.

###### Returns

`Record`<`string`, `string`\[]>

###### Example

```json
{
  "Host": ["caido.io"],
  "Connection": ["keep-alive"],
  "Content-Length": ["95"]
}
```

##### getHost()

> **getHost**(): `string`

The target host of the request.

###### Returns

`string`

##### getId()

> **getId**(): [`ID`](shared.md#id)

The unique Caido [ID](shared.md#id) of the request.

###### Returns

[`ID`](shared.md#id)

##### getMethod()

> **getMethod**(): `string`

The HTTP method of the request.

###### Returns

`string`

##### getPath()

> **getPath**(): `string`

The path of the request.

###### Returns

`string`

##### getPort()

> **getPort**(): `number`

The target port of the request.

###### Returns

`number`

##### getQuery()

> **getQuery**(): `string`

The unparsed query of the request.

Excludes the leading `?`.

###### Returns

`string`

##### getRaw()

> **getRaw**(): [`RequestRaw`](#requestraw)

The raw version of the request.

Used to access the bytes directly.

###### Returns

[`RequestRaw`](#requestraw)

##### getTls()

> **getTls**(): `boolean`

If the request uses TLS (HTTPS).

###### Returns

`boolean`

##### getUrl()

> **getUrl**(): `string`

The full URL of the request.

###### Returns

`string`

##### toSpec()

> **toSpec**(): [`RequestSpec`](#requestspec)

Copied the request to a mutable un-saved [RequestSpec](#requestspec).
This enables you to make modify a request before re-sending it.

###### Returns

[`RequestSpec`](#requestspec)

##### toSpecRaw()

> **toSpecRaw**(): [`RequestSpecRaw`](#requestspecraw)

Copied the request to a mutable un-saved [RequestSpecRaw](#requestspecraw).
The raw requests are not parsed and can be used to send invalid HTTP Requests.

###### Returns

[`RequestSpecRaw`](#requestspecraw)

***

### RequestOrderField

> **RequestOrderField** = `"ext"` | `"host"` | `"id"` | `"method"` | `"path"` | `"query"` | `"created_at"` | `"source"`

Field to order requests by.

***

### RequestRaw

> **RequestRaw** = `object`

An immutable saved raw Request.

#### Methods

##### toBytes()

> **toBytes**(): `Uint8Array`

Get the raw request as an array of bytes.

###### Returns

`Uint8Array`

##### toText()

> **toText**(): `string`

Parse the raw request as a string.

Unprintable characters will be replaced with `�`.

###### Returns

`string`

***

### RequestResponse

> **RequestResponse** = `object`

An immutable saved Request and Response pair.

#### Properties

##### request

> **request**: [`Request`](#request)

##### response

> **response**: [`Response`](#response)

***

### RequestResponseOpt

> **RequestResponseOpt** = `object`

An immutable saved Request and optional Response pair.

#### Properties

##### request

> **request**: [`Request`](#request)

##### response?

> `optional` **response**: [`Response`](#response)

***

### RequestsConnection

> **RequestsConnection** = `object`

A connection of requests.

#### Properties

##### items

> **items**: [`RequestsConnectionItem`](#requestsconnectionitem)\[]

##### pageInfo

> **pageInfo**: [`PageInfo`](other.md#pageinfo)

***

### RequestsConnectionItem

> **RequestsConnectionItem** = `object`

An item in a connection of requests.

#### Properties

##### cursor

> **cursor**: [`Cursor`](shared.md#cursor)

##### request

> **request**: [`Request`](#request)

##### response?

> `optional` **response**: [`Response`](#response)

***

### RequestSendOptions

> **RequestSendOptions** = `object`

Options for sending a request.

#### Properties

##### connection?

> `optional` **connection**: [`Connection`](net.md#connection)

The [Connection](net.md#connection) to use for the request.

If provided, the request will be sent through the connection.

If not provided, the engine will open a new connection to the target.

###### Default

```ts
undefined
```

##### plugins?

> `optional` **plugins**: `boolean`

If true, the request will be sent through the upstream plugins.

It defaults to to true most of the time except when called from
a `onUpstream` callback.

###### Default

```ts
true
```

##### save?

> `optional` **save**: `boolean`

If true, the request and response will be saved to the database
and the user will see them in the Search tab.

If you do not save, the request and response IDs will be set to 0.

###### Default

```ts
true
```

##### timeouts?

> `optional` **timeouts**: [`RequestSendTimeouts`](#requestsendtimeouts) | `number`

The timeouts to use for sending a request and receiving a response.

If a number is provided, it will be used as the global timeout and
the other timeouts will be set to infinity.

See the [RequestSendTimeouts](#requestsendtimeouts) for the default values.

***

### RequestSendPayload

> **RequestSendPayload** = [`RequestResponse`](#requestresponse) & `object`

A saved Request and Response pair with the connection used to send the request.

#### Type Declaration

##### connection

> **connection**: [`Connection`](net.md#connection)

***

### RequestSendTimeouts

> **RequestSendTimeouts** = `object`

Timeouts for sending a request and receiving a response.

#### Properties

##### connect?

> `optional` **connect**: `number`

The timeout to open the TCP connection to the target host
and perform the TLS handshake.

Defaults to 30s.

##### extra?

> `optional` **extra**: `number`

The timeout to read data after we have a read the full response.

This is useful if you believe the server will send more data
than implied by the Content-Length header.

Defaults to 0s (no timeout).

##### global?

> `optional` **global**: `number`

The global timeout for sending a request and receiving a response.

No default value.

##### partial?

> `optional` **partial**: `number`

The timeout between each read attempt for the response.
On a slow connection, this is important to increase.

Defaults to 5s.

##### response?

> `optional` **response**: `number`

The timeout to receive the first byte of the response.

After the first byte is received, the partial timeout will be used.

Defaults to 30s.

***

### RequestsQuery

> **RequestsQuery** = `object`

Query builder to fetch requests.

#### Methods

##### after()

> **after**(`cursor`: [`Cursor`](shared.md#cursor)): [`RequestsQuery`](#requestsquery)

Requests after a given cursor.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `cursor` | [`Cursor`](shared.md#cursor) | [Cursor](shared.md#cursor) of the request |

###### Returns

[`RequestsQuery`](#requestsquery)

##### ascending()

###### Call Signature

> **ascending**(`target`: `"req"`, `field`: [`RequestOrderField`](#requestorderfield)): [`RequestsQuery`](#requestsquery)

Ascending ordering.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `target` | `"req"` | Target of the ordering: req or resp. |
| `field` | [`RequestOrderField`](#requestorderfield) | Field to order by. |

###### Returns

[`RequestsQuery`](#requestsquery)

###### Call Signature

> **ascending**(`target`: `"resp"`, `field`: [`ResponseOrderField`](#responseorderfield)): [`RequestsQuery`](#requestsquery)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `target` | `"resp"` |
| `field` | [`ResponseOrderField`](#responseorderfield) |

###### Returns

[`RequestsQuery`](#requestsquery)

##### before()

> **before**(`cursor`: [`Cursor`](shared.md#cursor)): [`RequestsQuery`](#requestsquery)

Requests before a given cursor.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `cursor` | [`Cursor`](shared.md#cursor) | [Cursor](shared.md#cursor) of the request |

###### Returns

[`RequestsQuery`](#requestsquery)

##### descending()

###### Call Signature

> **descending**(`target`: `"req"`, `field`: [`RequestOrderField`](#requestorderfield)): [`RequestsQuery`](#requestsquery)

Descending ordering.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `target` | `"req"` | Target of the ordering: req or resp. |
| `field` | [`RequestOrderField`](#requestorderfield) | Field to order by. |

###### Returns

[`RequestsQuery`](#requestsquery)

###### Call Signature

> **descending**(`target`: `"resp"`, `field`: [`ResponseOrderField`](#responseorderfield)): [`RequestsQuery`](#requestsquery)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `target` | `"resp"` |
| `field` | [`ResponseOrderField`](#responseorderfield) |

###### Returns

[`RequestsQuery`](#requestsquery)

##### execute()

> **execute**(): `Promise`<[`RequestsConnection`](#requestsconnection)>

Execute the query.

###### Returns

`Promise`<[`RequestsConnection`](#requestsconnection)>

###### Throws

If a query parameter is invalid or the query cannot be executed.

##### filter()

> **filter**(`filter`: `string`): [`RequestsQuery`](#requestsquery)

Filter requests.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `filter` | `string` | HTTPQL filter |

###### Returns

[`RequestsQuery`](#requestsquery)

##### first()

> **first**(`n`: `number`): [`RequestsQuery`](#requestsquery)

First n requests.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `n` | `number` | Number of requests to return |

###### Returns

[`RequestsQuery`](#requestsquery)

##### last()

> **last**(`n`: `number`): [`RequestsQuery`](#requestsquery)

Last n requests.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `n` | `number` | Number of requests to return |

###### Returns

[`RequestsQuery`](#requestsquery)

***

### RequestsSDK

> **RequestsSDK** = `object`

The SDK for the Requests service.

#### Methods

##### get()

> **get**(`id`: [`ID`](shared.md#id)): `Promise`<[`RequestResponseOpt`](#requestresponseopt) | `undefined`>

Get a request by its unique [ID](shared.md#id).

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `id` | [`ID`](shared.md#id) |

###### Returns

`Promise`<[`RequestResponseOpt`](#requestresponseopt) | `undefined`>

###### Example

```js
await sdk.requests.get("1");
```

##### inScope()

> **inScope**(`request`: [`RequestSpec`](#requestspec) | [`Request`](#request), `scopes?`: [`Scope`](scope.md#scope)\[] | [`ID`](shared.md#id)\[]): `boolean`

Checks if a request is in scope.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `request` | [`RequestSpec`](#requestspec) | [`Request`](#request) | The request to check |
| `scopes?` | [`Scope`](scope.md#scope)\[] | [`ID`](shared.md#id)\[] | Optional scopes or scope IDs to check against. If not provided, checks against the default scope. |

###### Returns

`boolean`

True if the request is in scope

###### Example

```js
// Check against default scope
if (sdk.requests.inScope(request)) {
 sdk.console.log("In scope");
}

// Check against specific scopes
const isInScope = sdk.requests.inScope(request, [scope1, scope2]);
sdk.console.log(isInScope); // true or false
```

##### matches()

> **matches**(`filter`: `string`, `request`: [`Request`](#request), `response?`: [`Response`](#response)): `boolean`

Checks if a request/response matches an HTTPQL filter.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `filter` | `string` | HTTPQL filter |
| `request` | [`Request`](#request) | The [Request](#request) to match against |
| `response?` | [`Response`](#response) | The [Response](#response) to match against |

###### Returns

`boolean`

##### query()

> **query**(): [`RequestsQuery`](#requestsquery)

Query requests of the current project.

###### Returns

[`RequestsQuery`](#requestsquery)

###### Example

```js
const page = await sqk.requests.query().first(2).execute();
sdk.console.log(`ID: ${page.items[1].request.getId()}`);
```

##### send()

> **send**(`request`: [`RequestSpec`](#requestspec) | [`RequestSpecRaw`](#requestspecraw), `options?`: [`RequestSendOptions`](#requestsendoptions)): `Promise`<[`RequestSendPayload`](#requestsendpayload)>

Sends an HTTP request, either a [RequestSpec](#requestspec) or [RequestSpecRaw](#requestspecraw).

This respects the upstream proxy settings.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `request` | [`RequestSpec`](#requestspec) | [`RequestSpecRaw`](#requestspecraw) |
| `options?` | [`RequestSendOptions`](#requestsendoptions) |

###### Returns

`Promise`<[`RequestSendPayload`](#requestsendpayload)>

###### Throws

If the request cannot be sent.
If the request times out, the error message will contain the word "Timeout".

###### Example

```js
const spec = new RequestSpec("https://example.com");
try {
  const res = await sdk.requests.send(request)
  sdk.console.log(res.request.getId());
  sdk.console.log(res.response.getCode());
} catch (err) {
  sdk.console.error(err);
}
```

***

### Response

> **Response** = `object`

An immutable saved Response.

#### Methods

##### getBody()

> **getBody**(): [`Body`](#body) | `undefined`

The body of the response

###### Returns

[`Body`](#body) | `undefined`

##### getCode()

> **getCode**(): `number`

The status code of the response.

###### Returns

`number`

##### getCreatedAt()

> **getCreatedAt**(): `Date`

The datetime the response was recorded by the proxy.

###### Returns

`Date`

##### getHeader()

> **getHeader**(`name`: `string` | [`GetHeaderOptions`](#getheaderoptions)): `string`\[] | `undefined`

Get a header value.

Header name is case-insensitive.
The header might have multiple values.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` | [`GetHeaderOptions`](#getheaderoptions) |

###### Returns

`string`\[] | `undefined`

##### getHeaders()

> **getHeaders**(): `Record`<`string`, `string`\[]>

The headers of the response.

Header names are case-insensitive.
Each header might have multiple values.

###### Returns

`Record`<`string`, `string`\[]>

###### Example

```json
{
  "Date": ["Sun, 26 May 2024 10:59:21 GMT"],
  "Content-Type": ["text/html"]
}
```

##### getId()

> **getId**(): [`ID`](shared.md#id)

The unique Caido [ID](shared.md#id) of the response.

###### Returns

[`ID`](shared.md#id)

##### getRaw()

> **getRaw**(): [`ResponseRaw`](#responseraw)

The raw version of the response.

Used to access the bytes directly.

###### Returns

[`ResponseRaw`](#responseraw)

##### getRoundtripTime()

> **getRoundtripTime**(): `number`

The time it took to send the request and receive the response in milliseconds.

###### Returns

`number`

***

### ResponseOrderField

> **ResponseOrderField** = `"length"` | `"roundtrip"` | `"code"`

Field to order responses by.

***

### ResponseRaw

> **ResponseRaw** = `object`

An immutable saved raw Response.

#### Methods

##### toBytes()

> **toBytes**(): `Uint8Array`

Get the raw response as an array of bytes.

###### Returns

`Uint8Array`

##### toText()

> **toText**(): `string`

Parse the raw response as a string.

Unprintable characters will be replaced with `�`.

###### Returns

`string`

***

### SetBodyOptions

> **SetBodyOptions** = `object`

Options when setting the body of a Request.

#### Properties

##### updateContentLength

> **updateContentLength**: `boolean`

Should update the Content-export type header.

###### Default

```ts
true
```

---

---
url: /plugins/reference/sdks/workflow/requests.md
---
# Requests

### Body

The body of a [Request](#request) or [Response](#response).

Calling `to<FORMAT>` will try to convert the body to the desired format.

#### Constructors

##### Constructor

> **new Body**(`data`: `string` | `number`\[] | `Uint8Array`): [`Body`](#body)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `data` | `string` | `number`\[] | `Uint8Array` |

###### Returns

[`Body`](#body)

#### Properties

##### length

> `readonly` **length**: `number`

The length of the body in bytes.

#### Methods

##### toJson()

> **toJson**(): `unknown`

Try to parse the body as JSON.

###### Returns

`unknown`

###### Throws

If the body is not valid JSON.

##### toRaw()

> **toRaw**(): `Uint8Array`

Get the raw body as an array of bytes.

###### Returns

`Uint8Array`

##### toText()

> **toText**(): `string`

Parse the body as a string.

Unprintable characters will be replaced with `�`.

###### Returns

`string`

***

### RequestSpec

A mutable Request that has not yet been sent.

#### Constructors

##### Constructor

> **new RequestSpec**(`url`: `string`): [`RequestSpec`](#requestspec)

Build a new [RequestSpec](#requestspec) from a URL string.
We try to infer as much information as possible from the URL, including the scheme, host, path and query.

You can convert a saved immutable [Request](#request) object into a [RequestSpec](#requestspec) object by using the `toSpec()` method.

By default:

* Method is `GET`.
* Path is `/`.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `url` | `string` |

###### Returns

[`RequestSpec`](#requestspec)

###### Throws

If the URL is invalid.

###### Example

```js
const spec = new RequestSpec("https://example.com");
```

#### Methods

##### getBody()

> **getBody**(): [`Body`](#body) | `undefined`

The body of the request.

###### Returns

[`Body`](#body) | `undefined`

##### getHeader()

> **getHeader**(`name`: `string` | [`GetHeaderOptions`](#getheaderoptions)): `string`\[] | `undefined`

Get a header value.

Header name is case-insensitive.
The header might have multiple values.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` | [`GetHeaderOptions`](#getheaderoptions) |

###### Returns

`string`\[] | `undefined`

##### getHeaders()

> **getHeaders**(): `Record`<`string`, `string`\[]>

The headers of the request.

Header names are case-insensitive.
Each header might have multiple values.

###### Returns

`Record`<`string`, `string`\[]>

###### Example

```json
{
  "Host": ["caido.io"],
  "Connection": ["keep-alive"],
  "Content-Length": ["95"]
}
```

##### getHost()

> **getHost**(): `string`

Get the host of the request.

###### Returns

`string`

##### getInfo()

> **getInfo**(): [`ConnectionInfo`](net.md#connectioninfo)

Get the connection information of the request.

###### Returns

[`ConnectionInfo`](net.md#connectioninfo)

The connection information.

##### getMethod()

###### Call Signature

> **getMethod**(): `string`

Get the HTTP method of the request.

Get the raw version by passing `{ raw: true }` in the options.

###### Returns

`string`

###### Call Signature

> **getMethod**(`options`: [`RawOption`](shared.md#rawoption)): `Uint8Array`

Get the HTTP method of the request.

Get the raw version by passing `{ raw: true }` in the options.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | [`RawOption`](shared.md#rawoption) |

###### Returns

`Uint8Array`

##### getPath()

###### Call Signature

> **getPath**(): `string`

Get the path of the request.

Get the raw version by passing `{ raw: true }` in the options.

###### Returns

`string`

###### Call Signature

> **getPath**(`options`: [`RawOption`](shared.md#rawoption)): `Uint8Array`

Get the path of the request.

Get the raw version by passing `{ raw: true }` in the options.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | [`RawOption`](shared.md#rawoption) |

###### Returns

`Uint8Array`

##### getPort()

> **getPort**(): `number`

Get the port of the request.

###### Returns

`number`

##### getQuery()

###### Call Signature

> **getQuery**(): `string`

Get the unparsed query of the request.

Get the raw version by passing `{ raw: true }` in the options.

Excludes the leading `?`.

###### Returns

`string`

###### Call Signature

> **getQuery**(`options`: [`RawOption`](shared.md#rawoption)): `Uint8Array`

Get the unparsed query of the request.

Get the raw version by passing `{ raw: true }` in the options.

Excludes the leading `?`.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | [`RawOption`](shared.md#rawoption) |

###### Returns

`Uint8Array`

##### getRaw()

> **getRaw**(): [`RequestSpecRaw`](#requestspecraw)

This methods converts the [RequestSpec](#requestspec) to a [RequestSpecRaw](#requestspecraw).

This is useful to retrieve the raw bytes of the request.

###### Returns

[`RequestSpecRaw`](#requestspecraw)

###### Example

```js
const spec = new RequestSpec("https://example.com");
const specRaw = spec.getRaw();
const bytes = specRaw.getRaw(); // GET / HTTP/1.1\r\nHost: example.com\r\n\r\n
```

##### getTls()

> **getTls**(): `boolean`

Get if the request uses TLS (HTTPS).

###### Returns

`boolean`

##### getUrl()

> **getUrl**(): `string`

The full URL of the request.

###### Returns

`string`

##### removeHeader()

> **removeHeader**(`name`: `string`): `void`

Removes a header.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |

###### Returns

`void`

##### setBody()

> **setBody**(`body`: [`Bytes`](shared.md#bytes) | [`Body`](#body), `options?`: [`SetBodyOptions`](#setbodyoptions)): `void`

Set the body of the request.

The body can either be a [Body](#body) or any type that can be converted to [Bytes](shared.md#bytes).

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `body` | [`Bytes`](shared.md#bytes) | [`Body`](#body) |
| `options?` | [`SetBodyOptions`](#setbodyoptions) |

###### Returns

`void`

###### Example

```js
const body = new Body("Hello world.");
const options = { updateContentLength: true };
request.setBody(body, options);
```

##### setHeader()

> **setHeader**(`name`: `string`, `value`: `string`): `void`

Set a header value.

This will overwrite any existing values.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |
| `value` | `string` |

###### Returns

`void`

##### setHost()

> **setHost**(`host`: `string`): `void`

Set the host of the request.

It will also update the `Host` header.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `host` | `string` |

###### Returns

`void`

##### setMethod()

> **setMethod**(`method`: [`Bytes`](shared.md#bytes)): `void`

Set the HTTP method of the request.

All strings are accepted.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `method` | [`Bytes`](shared.md#bytes) |

###### Returns

`void`

##### setPath()

> **setPath**(`path`: [`Bytes`](shared.md#bytes)): `void`

Set the path of the request.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `path` | [`Bytes`](shared.md#bytes) |

###### Returns

`void`

##### setPort()

> **setPort**(`port`: `number`): `void`

Set the port of the request.

The port number must be between 1 and 65535.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `port` | `number` |

###### Returns

`void`

##### setQuery()

> **setQuery**(`query`: [`Bytes`](shared.md#bytes)): `void`

Set the unparsed query of the request.

The query string should not include the leading `?`.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `query` | [`Bytes`](shared.md#bytes) |

###### Returns

`void`

###### Example

```js
spec.setQuery("q=hello");
```

##### setRaw()

> **setRaw**(`raw`: [`Bytes`](shared.md#bytes)): [`RequestSpecRaw`](#requestspecraw)

This method sets the raw [Bytes](shared.md#bytes) of the request and converts it to a [RequestSpecRaw](#requestspecraw).

This is useful when you have a prepared [RequestSpec](#requestspec) and you just want to modify the raw data.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `raw` | [`Bytes`](shared.md#bytes) |

###### Returns

[`RequestSpecRaw`](#requestspecraw)

###### Example

```js
const rawBytes = []; // RAW BYTES HERE
const request = new RequestSpec("https://example.com");
const rawRequest = request.setRaw(rawBytes);
```

##### setTls()

> **setTls**(`tls`: `boolean`): `void`

Set if the request uses TLS (HTTPS).

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `tls` | `boolean` |

###### Returns

`void`

##### parse()

###### Call Signature

> `static` **parse**(`bytes`: [`Bytes`](shared.md#bytes)): [`RequestSpec`](#requestspec)

Parses raw bytes into a [RequestSpec](#requestspec).

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `bytes` | [`Bytes`](shared.md#bytes) |

###### Returns

[`RequestSpec`](#requestspec)

###### Throws

If the bytes are not a valid HTTP request.

###### Example

```js
const rawInput = 'GET / HTTP/1.1\r\nHost: example.com\r\n\r\n';
const spec = RequestSpec.parse(rawInput);
spec.setHeader('x-caido', 'test');
const specRaw = spec.getRaw();
const rawOutput = specRaw.getRaw(); // Will contain the new header
```

###### Call Signature

> `static` **parse**(`raw`: [`RequestSpecRaw`](#requestspecraw)): [`RequestSpec`](#requestspec)

Parses the raw bytes of a [RequestSpecRaw](#requestspecraw) into a [RequestSpec](#requestspec).

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `raw` | [`RequestSpecRaw`](#requestspecraw) |

###### Returns

[`RequestSpec`](#requestspec)

###### Throws

If the bytes are not a valid HTTP request.

***

### RequestSpecRaw

A mutable raw Request that has not yet been sent.

#### Constructors

##### Constructor

> **new RequestSpecRaw**(`url`: `string`): [`RequestSpecRaw`](#requestspecraw)

Build a new [RequestSpecRaw](#requestspecraw) from a URL string. Only the host, port and scheme will be parsed.

You can convert a saved immutable [Request](#request) object into a [RequestSpecRaw](#requestspecraw) object by using the `toSpecRaw()` method.

You MUST use `setRaw` to set the raw bytes of the request.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `url` | `string` |

###### Returns

[`RequestSpecRaw`](#requestspecraw)

###### Example

```js
const spec = new RequestSpecRaw("https://example.com");
```

#### Methods

##### getHost()

> **getHost**(): `string`

Get the host of the request.

###### Returns

`string`

##### getInfo()

> **getInfo**(): [`ConnectionInfo`](net.md#connectioninfo)

Get the connection information of the request.

###### Returns

[`ConnectionInfo`](net.md#connectioninfo)

The connection information.

##### getPort()

> **getPort**(): `number`

Get the port of the request.

###### Returns

`number`

##### getRaw()

> **getRaw**(): `Uint8Array`

Get the raw bytes of the request.

###### Returns

`Uint8Array`

##### ~~getSpec()~~

> **getSpec**(): [`RequestSpec`](#requestspec)

This methods converts the [RequestSpecRaw](#requestspecraw) to a [RequestSpec](#requestspec).

###### Returns

[`RequestSpec`](#requestspec)

###### Deprecated

Use `toSpec` instead.

###### Throws

If the bytes are not a valid HTTP request.

###### See

[RequestSpec.parse](#parse)

##### getTls()

> **getTls**(): `boolean`

Get if the request uses TLS (HTTPS).

###### Returns

`boolean`

##### setHost()

> **setHost**(`host`: `string`): `void`

Set the host of the request.

It will NOT update the `Host` header.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `host` | `string` |

###### Returns

`void`

##### setPort()

> **setPort**(`port`: `number`): `void`

Set the port of the request.

The port number must be between 1 and 65535.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `port` | `number` |

###### Returns

`void`

##### setRaw()

> **setRaw**(`raw`: [`Bytes`](shared.md#bytes)): `void`

Set the raw [Bytes](shared.md#bytes) of the request.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `raw` | [`Bytes`](shared.md#bytes) |

###### Returns

`void`

##### setTls()

> **setTls**(`tls`: `boolean`): `void`

Set if the request uses TLS (HTTPS).

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `tls` | `boolean` |

###### Returns

`void`

##### toSpec()

> **toSpec**(): [`RequestSpec`](#requestspec)

This methods converts the [RequestSpecRaw](#requestspecraw) to a [RequestSpec](#requestspec).

###### Returns

[`RequestSpec`](#requestspec)

###### Throws

If the bytes are not a valid HTTP request.

###### See

[RequestSpec.parse](#parse)

***

### GetHeaderOptions

> **GetHeaderOptions** = `object`

Options for getting a header value.

#### Properties

##### name

> **name**: `string`

The name of the header to get.
Header name is case-insensitive.

##### split?

> `optional` **split**: `boolean`

Whether to split the header value on commas.

###### Default

```ts
false
```

***

### Request

> **Request** = `object`

An immutable saved Request.

To modify, use `toSpec` to get a `RequestSpec` object.

#### Methods

##### getBody()

> **getBody**(): [`Body`](#body) | `undefined`

The body of the request.

###### Returns

[`Body`](#body) | `undefined`

##### getCreatedAt()

> **getCreatedAt**(): `Date`

The datetime the request was recorded by the proxy.

###### Returns

`Date`

##### getHeader()

> **getHeader**(`name`: `string` | [`GetHeaderOptions`](#getheaderoptions)): `string`\[] | `undefined`

Get a header value.

Header name is case-insensitive.
The header might have multiple values.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` | [`GetHeaderOptions`](#getheaderoptions) |

###### Returns

`string`\[] | `undefined`

##### getHeaders()

> **getHeaders**(): `Record`<`string`, `string`\[]>

The headers of the request.

Header names are case-insensitive.
Each header might have multiple values.

###### Returns

`Record`<`string`, `string`\[]>

###### Example

```json
{
  "Host": ["caido.io"],
  "Connection": ["keep-alive"],
  "Content-Length": ["95"]
}
```

##### getHost()

> **getHost**(): `string`

The target host of the request.

###### Returns

`string`

##### getId()

> **getId**(): [`ID`](shared.md#id)

The unique Caido [ID](shared.md#id) of the request.

###### Returns

[`ID`](shared.md#id)

##### getMethod()

> **getMethod**(): `string`

The HTTP method of the request.

###### Returns

`string`

##### getPath()

> **getPath**(): `string`

The path of the request.

###### Returns

`string`

##### getPort()

> **getPort**(): `number`

The target port of the request.

###### Returns

`number`

##### getQuery()

> **getQuery**(): `string`

The unparsed query of the request.

Excludes the leading `?`.

###### Returns

`string`

##### getRaw()

> **getRaw**(): [`RequestRaw`](#requestraw)

The raw version of the request.

Used to access the bytes directly.

###### Returns

[`RequestRaw`](#requestraw)

##### getTls()

> **getTls**(): `boolean`

If the request uses TLS (HTTPS).

###### Returns

`boolean`

##### getUrl()

> **getUrl**(): `string`

The full URL of the request.

###### Returns

`string`

##### toSpec()

> **toSpec**(): [`RequestSpec`](#requestspec)

Copied the request to a mutable un-saved [RequestSpec](#requestspec).
This enables you to make modify a request before re-sending it.

###### Returns

[`RequestSpec`](#requestspec)

##### toSpecRaw()

> **toSpecRaw**(): [`RequestSpecRaw`](#requestspecraw)

Copied the request to a mutable un-saved [RequestSpecRaw](#requestspecraw).
The raw requests are not parsed and can be used to send invalid HTTP Requests.

###### Returns

[`RequestSpecRaw`](#requestspecraw)

***

### RequestOrderField

> **RequestOrderField** = `"ext"` | `"host"` | `"id"` | `"method"` | `"path"` | `"query"` | `"created_at"` | `"source"`

Field to order requests by.

***

### RequestRaw

> **RequestRaw** = `object`

An immutable saved raw Request.

#### Methods

##### toBytes()

> **toBytes**(): `Uint8Array`

Get the raw request as an array of bytes.

###### Returns

`Uint8Array`

##### toText()

> **toText**(): `string`

Parse the raw request as a string.

Unprintable characters will be replaced with `�`.

###### Returns

`string`

***

### RequestResponse

> **RequestResponse** = `object`

An immutable saved Request and Response pair.

#### Properties

##### request

> **request**: [`Request`](#request)

##### response

> **response**: [`Response`](#response)

***

### RequestResponseOpt

> **RequestResponseOpt** = `object`

An immutable saved Request and optional Response pair.

#### Properties

##### request

> **request**: [`Request`](#request)

##### response?

> `optional` **response**: [`Response`](#response)

***

### RequestsConnection

> **RequestsConnection** = `object`

A connection of requests.

#### Properties

##### items

> **items**: [`RequestsConnectionItem`](#requestsconnectionitem)\[]

##### pageInfo

> **pageInfo**: [`PageInfo`](other.md#pageinfo)

***

### RequestsConnectionItem

> **RequestsConnectionItem** = `object`

An item in a connection of requests.

#### Properties

##### cursor

> **cursor**: [`Cursor`](shared.md#cursor)

##### request

> **request**: [`Request`](#request)

##### response?

> `optional` **response**: [`Response`](#response)

***

### RequestSendOptions

> **RequestSendOptions** = `object`

Options for sending a request.

#### Properties

##### connection?

> `optional` **connection**: [`Connection`](net.md#connection)

The [Connection](net.md#connection) to use for the request.

If provided, the request will be sent through the connection.

If not provided, the engine will open a new connection to the target.

###### Default

```ts
undefined
```

##### plugins?

> `optional` **plugins**: `boolean`

If true, the request will be sent through the upstream plugins.

It defaults to to true most of the time except when called from
a `onUpstream` callback.

###### Default

```ts
true
```

##### save?

> `optional` **save**: `boolean`

If true, the request and response will be saved to the database
and the user will see them in the Search tab.

If you do not save, the request and response IDs will be set to 0.

###### Default

```ts
true
```

##### timeouts?

> `optional` **timeouts**: [`RequestSendTimeouts`](#requestsendtimeouts) | `number`

The timeouts to use for sending a request and receiving a response.

If a number is provided, it will be used as the global timeout and
the other timeouts will be set to infinity.

See the [RequestSendTimeouts](#requestsendtimeouts) for the default values.

***

### RequestSendPayload

> **RequestSendPayload** = [`RequestResponse`](#requestresponse) & `object`

A saved Request and Response pair with the connection used to send the request.

#### Type Declaration

##### connection

> **connection**: [`Connection`](net.md#connection)

***

### RequestSendTimeouts

> **RequestSendTimeouts** = `object`

Timeouts for sending a request and receiving a response.

#### Properties

##### connect?

> `optional` **connect**: `number`

The timeout to open the TCP connection to the target host
and perform the TLS handshake.

Defaults to 30s.

##### extra?

> `optional` **extra**: `number`

The timeout to read data after we have a read the full response.

This is useful if you believe the server will send more data
than implied by the Content-Length header.

Defaults to 0s (no timeout).

##### global?

> `optional` **global**: `number`

The global timeout for sending a request and receiving a response.

No default value.

##### partial?

> `optional` **partial**: `number`

The timeout between each read attempt for the response.
On a slow connection, this is important to increase.

Defaults to 5s.

##### response?

> `optional` **response**: `number`

The timeout to receive the first byte of the response.

After the first byte is received, the partial timeout will be used.

Defaults to 30s.

***

### RequestsQuery

> **RequestsQuery** = `object`

Query builder to fetch requests.

#### Methods

##### after()

> **after**(`cursor`: [`Cursor`](shared.md#cursor)): [`RequestsQuery`](#requestsquery)

Requests after a given cursor.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `cursor` | [`Cursor`](shared.md#cursor) | [Cursor](shared.md#cursor) of the request |

###### Returns

[`RequestsQuery`](#requestsquery)

##### ascending()

###### Call Signature

> **ascending**(`target`: `"req"`, `field`: [`RequestOrderField`](#requestorderfield)): [`RequestsQuery`](#requestsquery)

Ascending ordering.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `target` | `"req"` | Target of the ordering: req or resp. |
| `field` | [`RequestOrderField`](#requestorderfield) | Field to order by. |

###### Returns

[`RequestsQuery`](#requestsquery)

###### Call Signature

> **ascending**(`target`: `"resp"`, `field`: [`ResponseOrderField`](#responseorderfield)): [`RequestsQuery`](#requestsquery)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `target` | `"resp"` |
| `field` | [`ResponseOrderField`](#responseorderfield) |

###### Returns

[`RequestsQuery`](#requestsquery)

##### before()

> **before**(`cursor`: [`Cursor`](shared.md#cursor)): [`RequestsQuery`](#requestsquery)

Requests before a given cursor.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `cursor` | [`Cursor`](shared.md#cursor) | [Cursor](shared.md#cursor) of the request |

###### Returns

[`RequestsQuery`](#requestsquery)

##### descending()

###### Call Signature

> **descending**(`target`: `"req"`, `field`: [`RequestOrderField`](#requestorderfield)): [`RequestsQuery`](#requestsquery)

Descending ordering.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `target` | `"req"` | Target of the ordering: req or resp. |
| `field` | [`RequestOrderField`](#requestorderfield) | Field to order by. |

###### Returns

[`RequestsQuery`](#requestsquery)

###### Call Signature

> **descending**(`target`: `"resp"`, `field`: [`ResponseOrderField`](#responseorderfield)): [`RequestsQuery`](#requestsquery)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `target` | `"resp"` |
| `field` | [`ResponseOrderField`](#responseorderfield) |

###### Returns

[`RequestsQuery`](#requestsquery)

##### execute()

> **execute**(): `Promise`<[`RequestsConnection`](#requestsconnection)>

Execute the query.

###### Returns

`Promise`<[`RequestsConnection`](#requestsconnection)>

###### Throws

If a query parameter is invalid or the query cannot be executed.

##### filter()

> **filter**(`filter`: `string`): [`RequestsQuery`](#requestsquery)

Filter requests.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `filter` | `string` | HTTPQL filter |

###### Returns

[`RequestsQuery`](#requestsquery)

##### first()

> **first**(`n`: `number`): [`RequestsQuery`](#requestsquery)

First n requests.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `n` | `number` | Number of requests to return |

###### Returns

[`RequestsQuery`](#requestsquery)

##### last()

> **last**(`n`: `number`): [`RequestsQuery`](#requestsquery)

Last n requests.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `n` | `number` | Number of requests to return |

###### Returns

[`RequestsQuery`](#requestsquery)

***

### RequestsSDK

> **RequestsSDK** = `object`

The SDK for the Requests service.

#### Methods

##### get()

> **get**(`id`: [`ID`](shared.md#id)): `Promise`<[`RequestResponseOpt`](#requestresponseopt) | `undefined`>

Get a request by its unique [ID](shared.md#id).

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `id` | [`ID`](shared.md#id) |

###### Returns

`Promise`<[`RequestResponseOpt`](#requestresponseopt) | `undefined`>

###### Example

```js
await sdk.requests.get("1");
```

##### inScope()

> **inScope**(`request`: [`Request`](#request) | [`RequestSpec`](#requestspec), `scopes?`: [`Scope`](scope.md#scope)\[] | [`ID`](shared.md#id)\[]): `boolean`

Checks if a request is in scope.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `request` | [`Request`](#request) | [`RequestSpec`](#requestspec) | The request to check |
| `scopes?` | [`Scope`](scope.md#scope)\[] | [`ID`](shared.md#id)\[] | Optional scopes or scope IDs to check against. If not provided, checks against the default scope. |

###### Returns

`boolean`

True if the request is in scope

###### Example

```js
// Check against default scope
if (sdk.requests.inScope(request)) {
 sdk.console.log("In scope");
}

// Check against specific scopes
const isInScope = sdk.requests.inScope(request, [scope1, scope2]);
sdk.console.log(isInScope); // true or false
```

##### matches()

> **matches**(`filter`: `string`, `request`: [`Request`](#request), `response?`: [`Response`](#response)): `boolean`

Checks if a request/response matches an HTTPQL filter.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `filter` | `string` | HTTPQL filter |
| `request` | [`Request`](#request) | The [Request](#request) to match against |
| `response?` | [`Response`](#response) | The [Response](#response) to match against |

###### Returns

`boolean`

##### query()

> **query**(): [`RequestsQuery`](#requestsquery)

Query requests of the current project.

###### Returns

[`RequestsQuery`](#requestsquery)

###### Example

```js
const page = await sqk.requests.query().first(2).execute();
sdk.console.log(`ID: ${page.items[1].request.getId()}`);
```

##### send()

> **send**(`request`: [`RequestSpec`](#requestspec) | [`RequestSpecRaw`](#requestspecraw), `options?`: [`RequestSendOptions`](#requestsendoptions)): `Promise`<[`RequestSendPayload`](#requestsendpayload)>

Sends an HTTP request, either a [RequestSpec](#requestspec) or [RequestSpecRaw](#requestspecraw).

This respects the upstream proxy settings.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `request` | [`RequestSpec`](#requestspec) | [`RequestSpecRaw`](#requestspecraw) |
| `options?` | [`RequestSendOptions`](#requestsendoptions) |

###### Returns

`Promise`<[`RequestSendPayload`](#requestsendpayload)>

###### Throws

If the request cannot be sent.
If the request times out, the error message will contain the word "Timeout".

###### Example

```js
const spec = new RequestSpec("https://example.com");
try {
  const res = await sdk.requests.send(request)
  sdk.console.log(res.request.getId());
  sdk.console.log(res.response.getCode());
} catch (err) {
  sdk.console.error(err);
}
```

***

### Response

> **Response** = `object`

An immutable saved Response.

#### Methods

##### getBody()

> **getBody**(): [`Body`](#body) | `undefined`

The body of the response

###### Returns

[`Body`](#body) | `undefined`

##### getCode()

> **getCode**(): `number`

The status code of the response.

###### Returns

`number`

##### getCreatedAt()

> **getCreatedAt**(): `Date`

The datetime the response was recorded by the proxy.

###### Returns

`Date`

##### getHeader()

> **getHeader**(`name`: `string` | [`GetHeaderOptions`](#getheaderoptions)): `string`\[] | `undefined`

Get a header value.

Header name is case-insensitive.
The header might have multiple values.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` | [`GetHeaderOptions`](#getheaderoptions) |

###### Returns

`string`\[] | `undefined`

##### getHeaders()

> **getHeaders**(): `Record`<`string`, `string`\[]>

The headers of the response.

Header names are case-insensitive.
Each header might have multiple values.

###### Returns

`Record`<`string`, `string`\[]>

###### Example

```json
{
  "Date": ["Sun, 26 May 2024 10:59:21 GMT"],
  "Content-Type": ["text/html"]
}
```

##### getId()

> **getId**(): [`ID`](shared.md#id)

The unique Caido [ID](shared.md#id) of the response.

###### Returns

[`ID`](shared.md#id)

##### getRaw()

> **getRaw**(): [`ResponseRaw`](#responseraw)

The raw version of the response.

Used to access the bytes directly.

###### Returns

[`ResponseRaw`](#responseraw)

##### getRoundtripTime()

> **getRoundtripTime**(): `number`

The time it took to send the request and receive the response in milliseconds.

###### Returns

`number`

***

### ResponseOrderField

> **ResponseOrderField** = `"length"` | `"roundtrip"` | `"code"`

Field to order responses by.

***

### ResponseRaw

> **ResponseRaw** = `object`

An immutable saved raw Response.

#### Methods

##### toBytes()

> **toBytes**(): `Uint8Array`

Get the raw response as an array of bytes.

###### Returns

`Uint8Array`

##### toText()

> **toText**(): `string`

Parse the raw response as a string.

Unprintable characters will be replaced with `�`.

###### Returns

`string`

***

### SetBodyOptions

> **SetBodyOptions** = `object`

Options when setting the body of a Request.

#### Properties

##### updateContentLength

> **updateContentLength**: `boolean`

Should update the Content-export type header.

###### Default

```ts
true
```

---

---
url: /plugins/reference/sdks/frontend/response.md
---
# Response

### ResponseFull

> **ResponseFull** = [`Prettify`](utils.md#prettify)<[`As`](utils.md#as)<`"ResponseFull"`> & `object`>

A complete response with all metadata and raw content.

***

### ResponseViewModeOptions

> **ResponseViewModeOptions** = `object`

Options for defining a custom response view mode.

#### Properties

##### label

> **label**: `string`

The label of the view mode.

##### view

> **view**: [`ComponentDefinition`](utils.md#componentdefinition)

The component to render when the view mode is selected.

##### when()?

> `optional` **when**: (`response`: [`ResponseFull`](#responsefull), `request`: [`RequestMeta`](request.md#requestmeta) | [`RequestFull`](request.md#requestfull)) => `boolean`

A function that determines if the view mode should be shown for a given response.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `response` | [`ResponseFull`](#responsefull) |
| `request` | [`RequestMeta`](request.md#requestmeta) | [`RequestFull`](request.md#requestfull) |

###### Returns

`boolean`

---

---
url: /plugins/concepts/runtime.md
---
# Runtime

All extensions to Caido are written in Javascript. This allows us to have an unified developement experience across the frontend and backend.

But each Javascript runtime is a bit different, we will go over the specificities in this document.

## Frontend

Javascript in the frontend (from `Frontend Plugins`) runs inside the browser or electron.

WIP

## Backend

Javascript in the backend (from `Workflows` and `Backend Plugins`) runs in a small embedded engine called [QuickJS](https://github.com/bellard/quickjs). This engines supports most of the [ES2023 specification](https://tc39.es/ecma262/2023/), but don't be surprised if some more recent language improvements are not available.

By default this engine doesn't come with any of the modules you might expect from [NodeJS](https://nodejs.org/api/).
To bridge the gap we are re-implementing some of the most popular modules ourselves.
While we try to document those modules here, the most up-to-date documentation will always be the `Typescript` definition from `@caido/sdk-backend` or `@caido/sdk-workflow`.

Here are the modules we have implemented so far:

* [`child_process`](/plugins/concepts/child_process.md)
* `sqlite` (Async version)
* `buffer`
* `fs` / `fs/promise`
* `net`
* `os`
* `path`
* `crypto` (Partially)

---

---
url: /plugins/reference/sdks/backend/runtime.md
---
# Runtime

### RuntimeSDK

> **RuntimeSDK** = `object`

The SDK for the runtime information.

#### Accessors

##### version

###### Get Signature

> **get** **version**(): `string`

Get the current version of Caido.

###### Returns

`string`

---

---
url: /plugins/reference/sdks/frontend/runtime.md
---
# Runtime

### RuntimeSDK

> **RuntimeSDK** = `object`

Utilities to interact with the runtime.

#### Accessors

##### version

###### Get Signature

> **get** **version**(): `string`

Get the current version of Caido.

###### Returns

`string`

---

---
url: /plugins/reference/sdks/workflow/runtime.md
---
# Runtime

### RuntimeSDK

> **RuntimeSDK** = `object`

The SDK for the runtime information.

#### Accessors

##### version

###### Get Signature

> **get** **version**(): `string`

Get the current version of Caido.

###### Returns

`string`

---

---
url: /plugins/reference/sdks/backend/scope.md
---
# Scope

### Scope

> **Scope** = `object`

A saved immutable Scope.

#### Properties

##### allowlist

> `readonly` **allowlist**: `string`\[]

The allowlist of the scope.

##### denylist

> `readonly` **denylist**: `string`\[]

The denylist of the scope.

##### id

> `readonly` **id**: [`ID`](shared.md#id)

The unique Caido [ID](shared.md#id) of the scope.

##### name

> `readonly` **name**: `string`

The name of the scope.

***

### ScopeSDK

> **ScopeSDK** = `object`

The SDK for the Scope service.

#### Methods

##### getAll()

> **getAll**(): `Promise`<[`Scope`](#scope)\[]>

Get all the scopes.

###### Returns

`Promise`<[`Scope`](#scope)\[]>

An array of [Scope](#scope)

---

---
url: /plugins/reference/sdks/workflow/scope.md
---
# Scope

### Scope

> **Scope** = `object`

A saved immutable Scope.

#### Properties

##### allowlist

> `readonly` **allowlist**: `string`\[]

The allowlist of the scope.

##### denylist

> `readonly` **denylist**: `string`\[]

The denylist of the scope.

##### id

> `readonly` **id**: [`ID`](shared.md#id)

The unique Caido [ID](shared.md#id) of the scope.

##### name

> `readonly` **name**: `string`

The name of the scope.

***

### ScopeSDK

> **ScopeSDK** = `object`

The SDK for the Scope service.

#### Methods

##### getAll()

> **getAll**(): `Promise`<[`Scope`](#scope)\[]>

Get all the scopes.

###### Returns

`Promise`<[`Scope`](#scope)\[]>

An array of [Scope](#scope)

---

---
url: /plugins/reference/sdks/frontend/scopes.md
---
# Scopes

### CurrentScopeChangeEvent

> **CurrentScopeChangeEvent** = `object`

Event fired when the current scope changes.

#### Properties

##### scopeId

> **scopeId**: [`ID`](utils.md#id) | `undefined`

The ID of the newly selected scope, or undefined if no scope is selected.

***

### Scope

> **Scope** = `object`

Represents a scope.

#### Properties

##### allowlist

> **allowlist**: `string`\[]

The list of included items.

##### denylist

> **denylist**: `string`\[]

The list of excluded items.

##### id

> **id**: [`ID`](utils.md#id)

The unique ID of the scope.

##### name

> **name**: `string`

The name of the scope.

***

### ScopePageContext

> **ScopePageContext** = `object`

Scope page context.

#### Properties

##### kind

> **kind**: `"Scope"`

##### selection

> **selection**: [`Selection`](utils.md#selection)<[`ID`](utils.md#id)>

***

### ScopesSDK

> **ScopesSDK** = `object`

Utilities to interact with scopes

#### Properties

##### addToSlot

> **addToSlot**: [`DefineAddToSlotFn`](slots.md#defineaddtoslotfn)<[`ScopeSlotContent`](other.md#scopeslotcontent)>

Add a component to a slot.

###### Param

The slot to add the component to.

###### Param

The content to add to the slot.

###### Example

```ts
sdk.scopes.addToSlot(ScopeSlot.UpdateHeader, {
  type: "Button",
  label: "My Button",
  icon: "my-icon",
  onClick: () => {
    console.log("Button clicked");
  },
});

sdk.scopes.addToSlot(ScopeSlot.CreateHeader, {
  type: "Custom",
  definition: MyComponent,
});

sdk.scopes.addToSlot(ScopeSlot.UpdateHeader, {
  type: "Command",
  commandId: "my-command",
  icon: "my-icon",
});
```

##### createScope()

> **createScope**: (`options`: `object`) => `Promise`<[`Scope`](#scope) | `undefined`>

Create a scope.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | { `allowlist`: `string`\[]; `denylist`: `string`\[]; `name`: `string`; } | Options for the scope. |
| `options.allowlist` | `string`\[] | The list of included items in the scope. |
| `options.denylist` | `string`\[] | The list of excluded items in the scope. |
| `options.name` | `string` | The name of the scope. |

###### Returns

`Promise`<[`Scope`](#scope) | `undefined`>

The created scope.

###### Example

```ts
const newScope = await sdk.scopes.createScope({
  name: "Example",
  allowlist: ["*example.com", "*github.com"],
  denylist: ["*caido.io"],
});
```

##### deleteScope()

> **deleteScope**: (`id`: [`ID`](utils.md#id)) => `Promise`<`boolean`>

Delete a scope.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](utils.md#id) | The id of the scope to delete. |

###### Returns

`Promise`<`boolean`>

Whether the scope was deleted.

##### getCurrentScope()

> **getCurrentScope**: () => [`Scope`](#scope) | `undefined`

Get the currently selected scope.

###### Returns

[`Scope`](#scope) | `undefined`

The currently selected scope, or undefined if no scope is selected.

##### getScopes()

> **getScopes**: () => [`Scope`](#scope)\[]

Get all scopes.

###### Returns

[`Scope`](#scope)\[]

A list of scopes.

##### onCurrentScopeChange()

> **onCurrentScopeChange**: (`callback`: (`event`: [`CurrentScopeChangeEvent`](#currentscopechangeevent)) => `void`) => [`ListenerHandle`](utils.md#listenerhandle)

Subscribe to current scope changes.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `callback` | (`event`: [`CurrentScopeChangeEvent`](#currentscopechangeevent)) => `void` | The callback to call when the selected scope changes. |

###### Returns

[`ListenerHandle`](utils.md#listenerhandle)

An object with a `stop` method that can be called to stop listening to scope changes.

###### Example

```ts
const handler = sdk.scopes.onCurrentScopeChange((event) => {
  console.log(`Scope ${event.scopeId} got selected!`);
});

// Later, stop listening
handler.stop();
```

##### updateScope()

> **updateScope**: (`id`: [`ID`](utils.md#id), `options`: `object`) => `Promise`<[`Scope`](#scope) | `undefined`>

Update a scope.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](utils.md#id) | The id of the scope to update. |
| `options` | { `allowlist?`: `string`\[]; `denylist?`: `string`\[]; `name?`: `string`; } | Options for the scope. |
| `options.allowlist?` | `string`\[] | The list of included items in the scope. |
| `options.denylist?` | `string`\[] | The list of excluded items in the scope. |
| `options.name?` | `string` | The name of the scope. |

###### Returns

`Promise`<[`Scope`](#scope) | `undefined`>

The updated scope.

***

### ScopeSlot

> `const` **ScopeSlot**: `object`

The slots in the Scopes UI.

#### Type Declaration

##### CreateHeader

> `readonly` **CreateHeader**: `"create-header"`

The header area of the preset form create component, to the left of the ScopeTooltip.

##### UpdateHeader

> `readonly` **UpdateHeader**: `"update-header"`

The header area of the preset form update component, to the left of the ScopeTooltip.

---

---
url: /plugins/reference/sdks/frontend/search.md
---
# Search

### SearchPageContext

> **SearchPageContext** = `object`

Search page context.

#### Properties

##### kind

> **kind**: `"Search"`

***

### SearchSDK

> **SearchSDK** = `object`

Utilities to interact with the Search page.

#### Properties

##### addRequestEditorExtension()

> **addRequestEditorExtension**: (`extension`: `Extension`) => `void`

Add an extension to the request editor.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `extension` | `Extension` | The extension to add. |

###### Returns

`void`

##### addRequestViewMode()

> **addRequestViewMode**: (`options`: [`RequestViewModeOptions`](request.md#requestviewmodeoptions)) => `void`

Add a custom request view mode.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`RequestViewModeOptions`](request.md#requestviewmodeoptions) | The view mode options. |

###### Returns

`void`

##### addResponseViewMode()

> **addResponseViewMode**: (`options`: [`ResponseViewModeOptions`](response.md#responseviewmodeoptions)) => `void`

Add a custom response view mode.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`ResponseViewModeOptions`](response.md#responseviewmodeoptions) | The view mode options. |

###### Returns

`void`

##### addToSlot()

> **addToSlot**: <`T`>(`slot`: `T`, `content`: [`SearchSlotContent`](other.md#searchslotcontent)\[`T`]) => `void`

Add content to a slot in the Search UI.

###### Type Parameters

| Type Parameter |
| ------ |
| `T` *extends* [`SearchSlot`](#searchslot) |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `slot` | `T` | The slot to add content to. |
| `content` | [`SearchSlotContent`](other.md#searchslotcontent)\[`T`] | The content to add. |

###### Returns

`void`

##### getQuery()

> **getQuery**: () => [`HTTPQL`](utils.md#httpql)

Get the current HTTPQL query.

###### Returns

[`HTTPQL`](utils.md#httpql)

The current HTTPQL query.

##### getScopeId()

> **getScopeId**: () => [`ID`](utils.md#id) | `undefined`

Get the current scope ID.

###### Returns

[`ID`](utils.md#id) | `undefined`

The current scope ID.

##### scrollTo()

> **scrollTo**: (`id`: [`ID`](utils.md#id)) => `void`

Scrolls the Search table to a specific request.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](utils.md#id) | The ID of the request to scroll to. |

###### Returns

`void`

##### setQuery()

> **setQuery**: (`query`: [`HTTPQL`](utils.md#httpql)) => `void`

Set the HTTPQL query that will be applied on the search table results.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `query` | [`HTTPQL`](utils.md#httpql) | The HTTPQL query. |

###### Returns

`void`

##### setScope()

> **setScope**: (`id`: [`ID`](utils.md#id) | `undefined`) => `Promise`<`void`>

Set the current scope.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](utils.md#id) | `undefined` | The ID of the scope to set. |

###### Returns

`Promise`<`void`>

***

### SearchSlot

> `const` **SearchSlot**: `object`

The slots in the Search UI.

#### Type Declaration

##### ToolbarPrimary

> `readonly` **ToolbarPrimary**: `"search-toolbar-primary"`

The primary slot in the search toolbar.

---

---
url: /plugins/guides/fetch.md
---
# Send a Fetch Request

Caido's [HTTP Module](/plugins/reference/modules/caido/http.md) provides an implementation of the [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). With this module, you can create and send asynchronous HTTP requests and handle their responses.

In this guide, we'll cover how to create a custom endpoint that sends a `fetch` request in a backend plugin, and call it from a frontend plugin.

::: warning NOTE
The request and response objects of this module differ from those used in the [Backend SDK](/plugins/reference/sdks/backend/index.md) and [Workflow SDK](/plugins/reference/sdks/workflow/index.md). Due to this, their properties and methods differ as well. Additionally, they are not routed through the proxy and must adhere to the HTTP specification in order to be interpreted correctly.
:::

## fetch()

The `fetch()` function takes either a URL or a [Request](/plugins/reference/modules/caido/http.html#request) object and as it's `input` parameter and an optional [RequestOpts](/plugins/reference/modules/caido/http.html#requestopts) parameter that can be included to configure specific elements of the request. The function will return a Promise that resolves to a [Response](/plugins/reference/modules/caido/http.html#response) object:

```ts
fetch(input: string | Request, init?: RequestOpts): Promise<Response>
```

## Creating and Sending a Request

First, the necessary type aliases are imported. `SDK` is the interface used to interact with Caido. `DefineAPI` is used to structure the API: definining what methods or endpoints are available, the parameters those methods accept and what types of values they return.

```ts
import { SDK, DefineAPI } from "caido:plugin";
```

To send a request, you will also need to import the `Request` class and the `fetch()` function from the `caido:http` module.

```ts
// Request object under the alias of FetchRequest.
import { Request as FetchRequest, fetch } from "caido:http";
```

Next, let's define an asynchronous function, specify request elements, and output the details to the [backend logs](https://docs.caido.io/app/reference/data_storage). In this example we define two URL query parameters, the `Accept` header, and the `User-Agent` header.

```ts
export async function callApi(sdk: SDK) {
  // Create a URL with search parameters.
  const url = "https://example.com?" + new URLSearchParams({
    paramA: "a",
    paramB: "b"
  }).toString();

  // Create a new fetch request with various RequestOpts.
  const fetchRequest = new FetchRequest(url, {
    // If no method is explicitly set, defaults to GET.
    headers: {
      "Accept": "application/json",
      "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0.0.0 Safari/537.36"
    }
  });

  // Log the fetch request details.
  sdk.console.log("\nFetch Request:");
  sdk.console.log(`URL: ${fetchRequest.url}`);
  sdk.console.log(`Method: ${fetchRequest.method}`);
  sdk.console.log("Headers: " + JSON.stringify(Object.fromEntries(fetchRequest.headers.entries())));
```

We must await for the request to be sent and processed before we are able to obtain data from the response. By accessing the response properties, we can print the data to the backend logs.

```ts
  try {
    const response = await fetch(fetchRequest);
    
    // Log the response data.
    sdk.console.log("\nFetch Response:");
    sdk.console.log(`Status: ${response.status}`);
    sdk.console.log(`Status Text: ${response.statusText}`);
    sdk.console.log("Headers: " + JSON.stringify(Object.fromEntries(response.headers.entries())));
    
    return {
      status: response.status,
      statusText: response.statusText,
      headers: Object.fromEntries(response.headers.entries())
    };
  } catch (error: any) {
    sdk.console.error("Error making fetch request: " + error.message);
    return `Error: ${error.message}`;
  }
}
```

Using the `DefineAPI` utility, we state that the `callApi` function is available to be called and link the definition using `typeof`. The definition is stored in the type alias `API` and exported so it can be used in other files.

```ts
export type API = DefineAPI<{
  callApi: typeof callApi;
}>;
```

Next, we define an initialization function that will add the `API` type alias to the base `SDK` and register the `callApi` function under the name `"callApi"`.

```ts
export function init(sdk: SDK<API>) {
  sdk.api.register("callApi", callApi);
}
```

::: tip
To view the entire script, expand the following:

```ts
import type { SDK, DefineAPI } from "caido:plugin";
import { Request as FetchRequest, fetch } from "caido:http";

export async function callApi(sdk: SDK) {
  // Create a URL with search parameters.
  const url = "https://example.com?" + new URLSearchParams({
    paramA: "a",
    paramB: "b"
  }).toString();

  // Create a new fetch request with various RequestOpts.
  const fetchRequest = new FetchRequest(url, {
    // If no method is explicitly set, defaults to GET.
    headers: {
      "Accept": "application/json",
      "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0.0.0 Safari/537.36"
    }
  });

  // Log the fetch request details.
  sdk.console.log("\nFetch Request:");
  sdk.console.log(`URL: ${fetchRequest.url}`);
  sdk.console.log(`Method: ${fetchRequest.method}`);
  sdk.console.log("Headers: " + JSON.stringify(Object.fromEntries(fetchRequest.headers.entries())));

  try {
    const response = await fetch(fetchRequest);
    
    // Log the response data.
    sdk.console.log("\nFetch Response:");
    sdk.console.log(`Status: ${response.status}`);
    sdk.console.log(`Status Text: ${response.statusText}`);
    sdk.console.log("Headers: " + JSON.stringify(Object.fromEntries(response.headers.entries())));
    
    return {
      status: response.status,
      statusText: response.statusText,
      headers: Object.fromEntries(response.headers.entries())
    };
  } catch (error: any) {
    sdk.console.error("Error making fetch request: " + error.message);
    return `Error: ${error.message}`;
  }
}

export type API = DefineAPI<{
  callApi: typeof callApi;
}>;

export function init(sdk: SDK<API>) {
  sdk.api.register("callApi", callApi);
}
```

::: info
Within the logs, the message will resemble:

```text
2025-04-29T16:06:01.503261Z DEBUG actix-rt|system:0|arbiter:23 api|controller: Calling plugin (6aff5b11-5baf-452a-8971-f4c6f1eb7859) function: callApi    
2025-04-29T16:06:01.503303Z  INFO plugin:6aff5b11-5baf-452a-8971-f4c6f1eb7859 plugin|executor: Calling method callApi (6aff5b11-5baf-452a-8971-f4c6f1eb7859)    
2025-04-29T16:06:01.503316Z DEBUG plugin:6aff5b11-5baf-452a-8971-f4c6f1eb7859 js|runtime: Triggering API callApi (6aff5b11-5baf-452a-8971-f4c6f1eb7859)    
2025-04-29T16:06:01.503391Z  INFO plugin:6aff5b11-5baf-452a-8971-f4c6f1eb7859 js|sdk: 
Fetch Request:    
2025-04-29T16:06:01.503406Z  INFO plugin:6aff5b11-5baf-452a-8971-f4c6f1eb7859 js|sdk: URL: https://example.com?paramA=a&paramB=b    
2025-04-29T16:06:01.503412Z  INFO plugin:6aff5b11-5baf-452a-8971-f4c6f1eb7859 js|sdk: Method: GET    
2025-04-29T16:06:01.503446Z  INFO plugin:6aff5b11-5baf-452a-8971-f4c6f1eb7859 js|sdk: Headers: {"accept":"application/json","user-agent":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/135.0.0.0 Safari/537.36"}    
2025-04-29T16:06:02.856522Z  INFO plugin:6aff5b11-5baf-452a-8971-f4c6f1eb7859 js|sdk: 
Fetch Response:    
2025-04-29T16:06:02.856554Z  INFO plugin:6aff5b11-5baf-452a-8971-f4c6f1eb7859 js|sdk: Status: 200    
2025-04-29T16:06:02.856562Z  INFO plugin:6aff5b11-5baf-452a-8971-f4c6f1eb7859 js|sdk: Status Text: OK    
2025-04-29T16:06:02.856650Z  INFO plugin:6aff5b11-5baf-452a-8971-f4c6f1eb7859 js|sdk: Headers: {"accept-ranges":"bytes","content-type":"text/html","etag":"\"84238dfc8092e5d9c0dac8ef93371a07:1736799080.121134\"","last-modified":"Mon, 13 Jan 2025 20:11:20 GMT","vary":"Accept-Encoding","content-encoding":"gzip","cache-control":"max-age=2775","date":"Tue, 29 Apr 2025 16:06:01 GMT","alt-svc":"h3=\":443\"; ma=93600,h3-29=\":443\"; ma=93600,quic=\":443\"; ma=93600; v=\"43\"","content-length":"648","connection":"keep-alive"}
```

:::

### Calling the Endpoint from Frontend

To call the endpoint from a Vue component, use the backend SDK:

```vue
<script setup lang="ts">
import Button from "primevue/button";
import { inject, ref } from "vue";

const sdk = inject<CaidoSDK>("sdk");
const result = ref<string>("Result will appear here.");

const handleFetch = async () => {
  if (!sdk) return;
  const data = await sdk.backend.callApi();
  result.value = `Result: ${JSON.stringify(data, null, 2)}`;
};
</script>

<template>
  <div class="p-4 flex flex-col gap-4">
    <Button label="Fetch" @click="handleFetch" />
    <p class="text-gray-400">{{ result }}</p>
  </div>
</template>
```

::: info
For information on creating pages and setting up Vue components, see [Create a Page](/plugins/guides/page.md).
:::

---

---
url: /plugins/guides/events.md
---
# Send Events to the Frontend

In this guide, you will learn how to facilitate event-driven communication between the backend and the frontend components of a plugin.

This can be accomplished using the `onInterceptResponse()` method provided by the Caido SDK.

The event can then be subscribed to on the frontend using `sdk.backend.onEvent()`.

## Registering an API Endpoint and Event

To demonstrate, we will create a plugin that emits an event containing response data to the frontend.

### /packages/backend/src/index.ts

```ts
import { SDK, DefineAPI, DefineEvents } from "caido:plugin";

type RequestEvent = {
  id: string;
  status: number;
  url: string;
};

export type BackendEvents = DefineEvents<{
  "request-completed": (data: RequestEvent) => void;
}>;

export type BackendAPI = DefineAPI<{}>;

export function init(sdk: SDK<BackendAPI, BackendEvents>) {
  sdk.events.onInterceptResponse((sdk, request, response) => {
    sdk.api.send("request-completed", {
      id: response.getId(),
      status: response.getCode(),
      url: `${request.getHost()}:${request.getPort()}${request.getPath()}${request.getQuery()}`
    });
  });
}
```

### Script Breakdown

First, import the required dependencies. `SDK` is the interface used to interact with Caido. `DefineAPI` is used to structure the API: definining what methods or endpoints are available, the parameters those methods accept and what types of values they return. `DefineEvents` is used to structure events that can be sent between the backend and frontend.

```ts
import { SDK, DefineAPI, DefineEvents } from "caido:plugin";
```

Next, create a type alias that defines the data and data type of the event message that will be sent to the frontend.

```ts
type RequestEvent = {
  id: string;
  status: number;
  url: string;
};
```

Using the `DefineEvents` utility, we state the event named `request-completed` will carry a `data` object using the `RequestEvent` type declarations. This is made available by exporting `BackendEvents`.

```ts
export type BackendEvents = DefineEvents<{
  "request-completed": (data: RequestEvent) => void;
}>;
```

Next, we define an empty API type using `DefineAPI` to satisy the `SDK` parameter requirements.

::: tip
[Learn how to create and call custom backend functions.](/plugins/guides/rpc.md)
:::

```ts
export type BackendAPI = DefineAPI<{}>;
```

The `init` function includes the `BackendAPI` and `BackendEvents` as `SDK` types, which tells the SDK what API calls and events are available to use. When a response to a request is received with `onInterceptResponse()`, the callback function will use various `get` methods available to request and response objects to extract the data. Once the data is collected, the event is sent to the frontend using the `sdk.api.send()` method.

```ts
export function init(sdk: SDK<BackendAPI, BackendEvents>) {
  sdk.events.onInterceptResponse((sdk, request, response) => {
    sdk.api.send("request-completed", {
      id: response.getId(),
      status: response.getCode(),
      url: `${request.getHost()}:${request.getPort()}${request.getPath()}${request.getQuery()}`
    });
  });
}
```

## Receiving the Event

Now that we've created our endpoint in the backend plugin, we can call `sendRequest` which will execute the function and emit the `request-completed` event with the response data.

The API and events are made available to the frontend script by extending the `Caido` inferface with the imports.

```ts
export type CaidoSDK = Caido<BackendAPI, BackendEvents>;
```

The event is subscribed to using the `sdk.backend.onEvent()` method that listens for the `request-completed` event and uses its `data` to print to a list.

```ts
sdk.backend.onEvent("request-completed", (data) => {
  const listItem = document.createElement("li");
  listItem.textContent = `Request to ${data.url} completed with status ${data.status} (ID: ${data.id})`;
  resultsList.insertBefore(listItem, resultsList.firstChild);
});
```

### Subscribing to Events in Vue

To subscribe to backend events in a Vue component:

```vue
<script setup lang="ts">
import { inject, onMounted, ref } from "vue";

const sdk = inject<CaidoSDK>("sdk");
const results = ref<string[]>([]);

onMounted(() => {
  if (!sdk) return;
  
  sdk.backend.onEvent("request-completed", (data) => {
    const message = `Request to ${data.url} completed with status ${data.status} (ID: ${data.id})`;
    results.value.unshift(message);
  });
});
</script>

<template>
  <div class="p-4">
    <ul class="list-none p-4">
      <li v-for="(result, index) in results" :key="index" class="mb-2">
        {{ result }}
      </li>
    </ul>
  </div>
</template>
```

::: info
For information on creating pages and setting up Vue components, see [Create a Page](/plugins/guides/page.md).
:::

## The Result

---

---
url: /plugins/guides/request.md
---
# Send HTTP Requests

Requests can be interacted with and sent in both Workflows and plugins.

## Creating and Modifying Requests

Used to create mutable request objects that have not yet been sent.

In Caido, requests that have been proxied can be interacted with via the an object of the `Request` type. These objects **cannot** be modified.

To create a request object that **can** be modified, the `RequestSpec` object class is used.

Compared to a `Request` object which only has methods to get a request's data, the `RequestSpec` object has different `set` methods available in order to specify certain HTTP request elements.

Although, Caido will automatically create a valid request based on the URL supplied as the constructor argument when creating a new `RequestSpec` object, these can be used to overwrite the properties of the automatically generated request.

* `removeHeader()` - Removes a header.
* `setBody()` - Specifies/overwrites the body of a request.
* `setHeader()` - Specifies a header or overwrites the same header with a different value.
* `setHost()` - Changes the target domain.
* `setMethod()` - Specifies/overwrites the HTTP method to be used.
* `setPath()` - Specifies/overwrites the URL path.
* `setPort()` - Specifies/overwrites the port.
* `setQuery()` - Specifies/overwrites the URL query.
* `setRaw()` - Sets the request to raw bytes.
* `setTls()` - Specifies/overwrites if HTTPS is to be used or not.

### Creating and Sending a Request

In the `/packages/backend/src/index.ts` file, you will first need to import the `RequestSpec`, `SDK` and `DefineAPI` type aliases.

```ts
import { RequestSpec, Response } from "caido:utils";
import { SDK, DefineAPI } from "caido:plugin";
```

Next, define an asynchronous function that creates a new `RequestSpec` object using the target URL as the constructor. At this point, you can explicitly set request properties by calling the appropriate methods.

```ts
async function sendRequest(sdk: SDK): Promise<void> {
  const spec = new RequestSpec("https://example.com/");
  spec.setMethod("GET");
  spec.setHost("example.com");
  spec.setPort(443);
  spec.setPath("/");
  spec.setQuery("query=test")
  spec.setTls(true);
```

We must await for the request to be sent and processed before we are able to obtain data from the response. Using template literals, we can print the data to the backend logs.

```ts
  let sentRequest = await sdk.requests.send(spec);

  if (sentRequest.response) {
    let domain = spec.getHost();
    let port = spec.getPort();
    let path = spec.getPath();
    let query = spec.getQuery();
    let id = sentRequest.response.getId();
    let code = sentRequest.response.getCode();
    sdk.console.log(`REQ ${id}: ${domain}:${port}${path}${query} received a status code of ${code}`);
  }
}
```

The entry in the backend log file will resemble:

```txt
2024-10-09T19:10:34.825319Z  INFO plugin:d69424f6-a091-4660-8193-2ec624b54c5e js|sdk: REQ 4110: example.com:443/?query=test received a status code of 200
```

In order to use this new API call, the API itself must be defined and exported for use in the `/packages/frontend/src/index.ts` file. By using `typeof sendRequest`, you tie the function to a method named `sendRequest`.

```ts
export type API = DefineAPI<{
  sendRequest: typeof sendRequest;
}>;
```

Finally, upon plugin initialization, the `sendRequest` function is registered to the backend.

```ts
export function init(sdk: SDK<API>) {
  sdk.api.register("sendRequest", sendRequest);
}
```

::: tip
To view the entire backend script, expand the following:

```ts
import { RequestSpec } from "caido:utils";
import { SDK, DefineAPI } from "caido:plugin";

async function sendRequest(sdk: SDK): Promise<void> {
  const spec = new RequestSpec("https://example.com/");
  spec.setMethod("GET");
  spec.setHost("example.com");
  spec.setPort(443);
  spec.setPath("/");
  spec.setQuery("query=test")
  spec.setTls(true);

  let sentRequest = await sdk.requests.send(spec);

  if (sentRequest.response) {
    let domain = spec.getHost();
    let port = spec.getPort();
    let path = spec.getPath();
    let query = spec.getQuery();
    let id = sentRequest.response.getId();
    let code = sentRequest.response.getCode();
    sdk.console.log(`REQ ${id}: ${domain}:${port}${path}${query} received a status code of ${code}`);
  }
}

export type API = DefineAPI<{
  sendRequest: typeof sendRequest;
}>;

export function init(sdk: SDK<API>) {
  sdk.api.register("sendRequest", sendRequest);
}
```

By registering a command in the frontend, defining the command to make a backend call to execute the `sendRequest` function and then registering the function on the frontend - it can be called at the click of a button:

### Calling from Frontend

To call the backend function from a Vue component:

```vue
<script setup lang="ts">
import Button from "primevue/button";
import { inject } from "vue";

const sdk = inject<CaidoSDK>("sdk");

const sendRequest = async () => {
  if (!sdk) return;
  await sdk.backend.sendRequest();
};
</script>

<template>
  <div class="p-4">
    <Button label="Send Request" @click="sendRequest" />
  </div>
</template>
```

::: info
For information on creating pages and setting up Vue components, see [Create a Page](/plugins/guides/page.md).
:::

---

---
url: /plugins/guides/repository.md
---
# Set Up Repository

Caido uses [GitHub](https://github.com) to download and distribute plugin packages. To share your plugin with the community, you’ll first need to set up a Github repository that meets Caido’s requirements.

## 1. Create Your Project

Let's create a new project. Run the following command in your terminal and follow the instructions:

```bash
pnpm create @caido-community/plugin
```

This command will help you generate the basic structure and files needed for your plugin project.

If you’re new to Caido or want more detailed instructions, visit the [Getting Started](/plugins/guides/) section for additional guidance on using this setup process .

## 2. Create a Repository

Now we'll create a repository on Github. This repository will host your plugin code, and will be used to distribute your plugin package in the Caido Store.

1. Visit <https://github.com/new>
2. Give it a name and a description
3. Click the `Create repository` button
4. In your terminal, navigate to your project folder (created in the step 1)

```bash
cd my-plugin
```

5. Connect your local project to your Github repository

```bash
git init
git add .
git commit -m "init"
git branch -M main
git remote add origin git@github.com:YOUR_USERNAME/YOUR_REPO_NAME.git
git push -u origin main
```

::: info
The steps above will create a repository under your own account.

If you would like to host your repository under the [caido-community](https://github.com/caido-community) organization instead, you can request a repository on our [Discord server](https://links.caido.io/www-discord).
:::

## 3. Enable Immutable Releases

Before creating your release, you must enable immutable releases in your repository settings. Immutable releases prevent published releases from being modified or deleted, ensuring users always install the exact version that was reviewed and approved.

1. Go to your repository on GitHub
2. Navigate to **Settings** → **General**
3. Scroll down to the **Releases** section
4. Enable **Immutable releases**

## 4. Generate a Key-Pair

Plugin packages **must** be digitally signed to be installable in Caido.

To sign your plugin package, you need to generate a public/private key-pair.

::: info
Plugin package signing is done using [Ed25519 public-key signatures](https://cendyne.dev/posts/2022-03-06-ed25519-signatures.html).
:::

### Generate the Private Key

Run the following command to generate a private key:

```bash
openssl genpkey -algorithm ed25519 -out private.pem
```

This will create a file `private.pem` with the private key. We will use this key to sign our plugin package when we create a release.

::: warning
**Keep this key private!** Ideally, you should encrypt it or store it in [Github Action Secrets](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions).
:::

The file `private.pem` will contain the following format:

```text
-----BEGIN PRIVATE KEY-----
<SOME BASE64 DATA ON ONE LINE>
-----END PRIVATE KEY-----
```

### Generate the Public Key

Run the following command to generate a public key:

```bash
openssl pkey -in private.pem -pubout --out public.pem
```

This will create a file `public.pem` with the public key. We will use this key when submitting the plugin package to the store.

The file `public.pem` will contain the following format:

```text
-----BEGIN PUBLIC KEY-----
<SOME BASE64 DATA ON ONE LINE>
-----END PUBLIC KEY-----
```

## 5. Create a Release

Now that your repository and key-pair are ready, it’s time to create a release!

1. [Create a Github Action Secret](https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository) called `PRIVATE_KEY` with the content of the private key generated in [step 4](#4-generate-a-key-pair).
2. Go to the `Actions` tab of your repository and trigger the `Release` workflow.

This will create an immutable release with the version specified in your project's [caido.config.ts](/plugins/guides/config#version) file.

## What's next?

Now that you have a repository and a release, you can submit your plugin to the Caido Store for review.

---

---
url: /plugins/reference/sdks/frontend/settings.md
---
# Settings

### SettingsPluginSlotContent

> **SettingsPluginSlotContent** = [`CustomSlotContent`](slots.md#customslotcontent) & `object`

Content for a settings plugin slot.

#### Type Declaration

##### name

> **name**: `string`

The name of the plugin settings page displayed in the sidebar.

***

### SettingsSDK

> **SettingsSDK** = `object`

Utilities to interact with the settings page.

#### Properties

##### addToSlot

> **addToSlot**: [`DefineAddToSlotFn`](slots.md#defineaddtoslotfn)<[`SettingsSlotContent`](other.md#settingsslotcontent)>

Add a component to a slot.

###### Param

The slot to add the component to.

###### Param

The content to add to the slot.

###### Example

```ts
sdk.settings.addToSlot(SettingsSlot.PluginsSection, {
  type: "Custom",
  name: "My Plugin Settings",
  definition: MySettingsComponent,
});
```

***

### SettingsSlot

> `const` **SettingsSlot**: `object`

The slots in the Settings UI.

#### Type Declaration

##### PluginsSection

> `readonly` **PluginsSection**: `"plugins-section"`

The plugins section in the settings sidebar.

---

---
url: /plugins/reference/sdks/backend/shared.md
---
# Shared

### Bytes

> **Bytes** = `string` | `number`\[] | `Uint8Array`

Types that can be converted to bytes in inputs.

***

### Cursor

> **Cursor** = `string` & `object`

A cursor for pagination.

#### Type Declaration

##### \_\_cursor?

> `optional` **\_\_cursor**: `never`

***

### DefineAPI

> **DefineAPI**<`API`> = `{ [K in keyof API]: DefineAPICallback<API[K]> }`

Define a Plugin backend functions that are callable from the frontend.

#### Type Parameters

| Type Parameter |
| ------ |
| `API` *extends* `Record`<`string`, (...`args`: `any`\[]) => [`MaybePromise`](#maybepromise)<`any`>> |

#### Example

```typescript
function generateNumber(sdk: SDK, min: number, max: number): number {
  return Math.floor(Math.random() * (max - min + 1) + min);
}

export type API = DefineAPI<{
  generateNumber: typeof generateNumber;
}>;

export function init(sdk: SDK<API>) {
  sdk.api.register("generateNumber", generateNumber);
}
```

***

### DefineAPICallback

> **DefineAPICallback**<`F`> = `F` *extends* (`sdk`: [`SDK`](index.md#sdk), ...`args`: infer A) => infer R ? (...`args`: `A`) => `R` : `"Your callback must respect the format (sdk: SDK, ...args: unknown[]) => MaybePromise<unknown>"`

Parser for Plugin backend callable functions

#### Type Parameters

| Type Parameter |
| ------ |
| `F` |

***

### DefineEventCallback

> **DefineEventCallback**<`F`> = `F` *extends* (...`args`: infer A) => [`MaybePromise`](#maybepromise)<`void`> ? (...`args`: `A`) => [`MaybePromise`](#maybepromise)<`void`> : `"Your callback must respect the format (...args: unknown[]) => MaybePromise<void>"`

Parser for Plugin backend events callbacks.

#### Type Parameters

| Type Parameter |
| ------ |
| `F` |

***

### DefineEvents

> **DefineEvents**<`Events`> = `{ [K in keyof Events]: DefineEventCallback<Events[K]> }`

Define a Plugin backend events that the frontend can receive.

#### Type Parameters

| Type Parameter |
| ------ |
| `Events` *extends* `Record`<`string`, (...`args`: `any`\[]) => [`MaybePromise`](#maybepromise)<`void`>> |

#### Example

```typescript
type MyEventData = { id: string; name: string };

export type BackendEvents = DefineEvents<{
  "myevent": (data: MyEventData) => void;
}>;

export function init(sdk: SDK<{}, BackendEvents>) {
  sdk.api.send("myevent", { id: "1", name: "hello" });
}
```

***

### ID

> **ID** = `string` & `object`

A unique identifier.

#### Type Declaration

##### \_\_id?

> `optional` **\_\_id**: `never`

***

### MaybePromise

> **MaybePromise**<`T`> = `T` | `Promise`<`T`>

Promise or value.

#### Type Parameters

| Type Parameter |
| ------ |
| `T` |

***

### MaybePromise

> **MaybePromise**<`T`> = `T` | `Promise`<`T`>

Promise or value.

#### Type Parameters

| Type Parameter |
| ------ |
| `T` |

***

### RawOption

> **RawOption** = `object`

Option to return raw value

#### Properties

##### raw

> **raw**: `true`

***

### RequestSource

> **RequestSource** = [`ID`](#id) | [`Request`](requests.md#request) | [`RequestSpec`](requests.md#requestspec) | [`RequestSpecRaw`](requests.md#requestspecraw)

The source of a request.

---

---
url: /plugins/reference/sdks/workflow/shared.md
---
# Shared

### Bytes

> **Bytes** = `string` | `number`\[] | `Uint8Array`

Types that can be converted to bytes in inputs.

***

### Cursor

> **Cursor** = `string` & `object`

A cursor for pagination.

#### Type Declaration

##### \_\_cursor?

> `optional` **\_\_cursor**: `never`

***

### ID

> **ID** = `string` & `object`

A unique identifier.

#### Type Declaration

##### \_\_id?

> `optional` **\_\_id**: `never`

***

### RawOption

> **RawOption** = `object`

Option to return raw value

#### Properties

##### raw

> **raw**: `true`

***

### RequestSource

> **RequestSource** = [`ID`](#id) | [`Request`](requests.md#request) | [`RequestSpec`](requests.md#requestspec) | [`RequestSpecRaw`](requests.md#requestspecraw)

The source of a request.

---

---
url: /plugins/reference/sdks/frontend/shortcuts.md
---
# Shortcuts

### ShortcutsSDK

> **ShortcutsSDK** = `object`

Utilities to interact with shortcuts.

#### Properties

##### register()

> **register**: (`commandId`: [`CommandID`](other.md#commandid), `keys`: `string`\[]) => `void`

Register a shortcut.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `commandId` | [`CommandID`](other.md#commandid) | The id of the command to run when the shortcut is triggered. |
| `keys` | `string`\[] | The keys of the shortcut. Check out [KeyboardEvent.key](https://developer.mozilla.org/en-US/docs/Web/API/UI_Events/Keyboard_event_key_values) for the list of supported keys. |

###### Returns

`void`

---

---
url: /plugins/guides/dialogs.md
---
# Show Dialogs

When you need to display a modal window to collect user input, show important information, or confirm an action, use dialogs to create focused interactions with users.

## Show a Simple Dialog

To display a basic dialog, create a DOM element and pass it to `sdk.window.showDialog()`. The method returns a `Dialog` object that you can use to programmatically close the dialog later.

```ts
const content = document.createElement("div");
content.textContent = "This is a dialog";

const dialog = sdk.window.showDialog(content);
```

## Customize Dialog Behavior

You can customize how the dialog appears and behaves by passing an options object as the second parameter. Common options include setting a title, controlling whether the dialog is modal, and configuring how users can close it.

```ts
const dialog = sdk.window.showDialog(component, {
  title: "My Dialog",
  modal: true,
  closable: true,
  closeOnEscape: true,
  draggable: false,
  position: "center",
});
```

The `modal` option controls whether the dialog blocks interaction with the rest of the application (default: `true`). Set `closable` to control whether users can close the dialog (default: `true`), and `closeOnEscape` to allow closing with the Escape key (default: `true`). Use `draggable` to make the dialog draggable (default: `false`), and `position` to set where it appears: `"left"`, `"right"`, `"top"`, `"bottom"`, `"center"`, `"topleft"`, `"topright"`, `"bottomleft"`, or `"bottomright"` (default: `"center"`).

::: tip
Use modal dialogs for critical actions that require user attention. Non-modal dialogs are useful for displaying information that doesn't block the user's workflow.
:::

::: warning
Always provide a way to close dialogs, either through a close button or by enabling `closable` and `closeOnEscape` options.
:::

## Close a Dialog Programmatically

Close a dialog programmatically by calling the `close()` method on the `Dialog` object returned from `showDialog()`. This is useful when you need to close the dialog based on user actions or application logic.

```ts
const dialog = sdk.window.showDialog(content);

// Later, close the dialog
dialog.close();
```

## Examples

### Confirmation Dialog

This example creates a reusable confirmation dialog function that displays a message and returns a promise resolving to `true` if confirmed or `false` if cancelled.

```ts
import Button from "primevue/button";

const showConfirmationDialog = (sdk: CaidoSDK, message: string): Promise<boolean> => {
  return new Promise((resolve) => {
    const container = document.createElement("div");
    container.className = "p-5 flex flex-col gap-4";

    const messageEl = document.createElement("p");
    messageEl.textContent = message;
    container.appendChild(messageEl);

    const buttonContainer = document.createElement("div");
    buttonContainer.className = "flex gap-2 justify-end";

    const confirmButton = document.createElement("button");
    confirmButton.textContent = "Confirm";
    confirmButton.className = "px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700";
    confirmButton.addEventListener("click", () => {
      dialog.close();
      resolve(true);
    });

    const cancelButton = document.createElement("button");
    cancelButton.textContent = "Cancel";
    cancelButton.className = "px-4 py-2 bg-gray-600 text-white rounded hover:bg-gray-700";
    cancelButton.addEventListener("click", () => {
      dialog.close();
      resolve(false);
    });

    buttonContainer.appendChild(cancelButton);
    buttonContainer.appendChild(confirmButton);
    container.appendChild(buttonContainer);

    const dialog = sdk.window.showDialog(container, {
      title: "Confirmation",
      modal: true,
      closable: true,
    });
  });
};
```

To use this dialog in a Vue component, call it from a button click handler:

```vue
<script setup lang="ts">
import Button from "primevue/button";
import { inject } from "vue";

const sdk = inject<CaidoSDK>("sdk");

const handleDelete = async () => {
  const confirmed = await showConfirmationDialog(
    sdk!,
    "Are you sure you want to delete this item?"
  );

  if (confirmed) {
    sdk?.window.showToast("Item deleted", { variant: "success" });
  } else {
    sdk?.window.showToast("Cancelled", { variant: "info" });
  }
};
</script>

<template>
  <Button label="Delete Item" @click="handleDelete" />
</template>
```

::: info
For information on creating pages and setting up Vue components, see [Create a Page](/plugins/guides/page.md).
:::

### Form Dialog

This example creates a dialog with a text input field that collects user input. The dialog returns the entered value when submitted, or `null` if cancelled. The input is automatically focused when the dialog opens.

```ts
const showFormDialog = (sdk: CaidoSDK): Promise<string | null> => {
  return new Promise((resolve) => {
    const container = document.createElement("div");
    container.className = "p-5 flex flex-col gap-4";

    const input = document.createElement("input");
    input.type = "text";
    input.placeholder = "Enter value";
    input.className = "px-3 py-2 border border-gray-600 rounded bg-gray-800 text-white";
    container.appendChild(input);

    const buttonContainer = document.createElement("div");
    buttonContainer.className = "flex gap-2 justify-end";

    const submitButton = document.createElement("button");
    submitButton.textContent = "Submit";
    submitButton.className = "px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700";
    submitButton.addEventListener("click", () => {
      dialog.close();
      resolve(input.value || null);
    });

    const cancelButton = document.createElement("button");
    cancelButton.textContent = "Cancel";
    cancelButton.className = "px-4 py-2 bg-gray-600 text-white rounded hover:bg-gray-700";
    cancelButton.addEventListener("click", () => {
      dialog.close();
      resolve(null);
    });

    buttonContainer.appendChild(cancelButton);
    buttonContainer.appendChild(submitButton);
    container.appendChild(buttonContainer);

    const dialog = sdk.window.showDialog(container, {
      title: "Enter Value",
      modal: true,
    });

    // Focus the input when dialog opens
    input.focus();
  });
};
```

---

---
url: /plugins/reference/sdks/frontend/sidebar.md
---
# Sidebar

### SidebarItem

> **SidebarItem** = `object`

Represents a sidebar item.

#### Properties

##### setCount()

> **setCount**: (`count`: `number`) => `void`

Set the value of a notification badge next to the sidebar item.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `count` | `number` | The number to display in the badge. A value of 0 will hide the badge. |

###### Returns

`void`

***

### SidebarSDK

> **SidebarSDK** = `object`

Utilities to interact with the sidebar.

#### Properties

##### registerItem()

> **registerItem**: (`name`: `string`, `path`: `string`, `options?`: `object`) => [`SidebarItem`](#sidebaritem)

Register a sidebar item.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `name` | `string` | The name of the sidebar item. |
| `path` | `string` | The path that the user will be navigated to when the sidebar item is clicked. |
| `options?` | { `group?`: `string`; `icon?`: [`Icon`](utils.md#icon); `isExternal?`: `boolean`; } | Options for the sidebar item. |
| `options.group?` | `string` | The group the sidebar item belongs to. |
| `options.icon?` | [`Icon`](utils.md#icon) | The [Icon](utils.md#icon) of the sidebar item. |
| `options.isExternal?` | `boolean` | Whether the path points to an external URL. |

###### Returns

[`SidebarItem`](#sidebaritem)

The created sidebar item.

###### Example

```ts
sdk.sidebar.registerItem("My Plugin", "/my-plugin-page", {
  icon: "fas fa-rocket",
});
```

---

---
url: /plugins/reference/sdks/frontend/sitemap.md
---
# Sitemap

### SitemapEntry

> **SitemapEntry** = `object`

An entry in sitemap.

#### Properties

##### childState

> **childState**: [`ChildState`](other.md#childstate)

The child state of the entry.

##### id

> **id**: [`ID`](utils.md#id)

The ID of the entry.

##### kind

> **kind**: [`SitemapEntryKind`](#sitemapentrykind)

The kind of the entry.

##### label

> **label**: `string`

The label of the entry.

##### parentId?

> `optional` **parentId**: [`ID`](utils.md#id)

The ID of the parent entry.

***

### SitemapEntryChildStateUpdateEvent

> **SitemapEntryChildStateUpdateEvent** = `object`

Event fired when the child state of a sitemap entry changes.

#### Properties

##### entryId

> **entryId**: [`ID`](utils.md#id)

The ID of the entry that changed.

##### newChildState

> **newChildState**: [`ChildState`](other.md#childstate)

The new child state of the entry.

***

### SitemapEntryKind

> **SitemapEntryKind** = *typeof* [`SitemapEntryKind`](#sitemapentrykind)\[keyof *typeof* [`SitemapEntryKind`](#sitemapentrykind-2)]

The kind of a sitemap entry.

#### Example

```ts
const entry = {
  id: "123",
  label: "Example",
  kind: SitemapEntryKind.Request,
};
```

***

### SitemapPageContext

> **SitemapPageContext** = `object`

Sitemap page context.

#### Properties

##### entrySelection

> **entrySelection**: [`Selection`](utils.md#selection)<[`ID`](utils.md#id)>

##### kind

> **kind**: `"Sitemap"`

##### requestSelection

> **requestSelection**: [`Selection`](utils.md#selection)<[`ID`](utils.md#id)>

***

### SitemapSDK

> **SitemapSDK** = `object`

Utilities to interact with the Sitemap page.

#### Properties

##### addEntryIndicator()

> **addEntryIndicator**: (`entryId`: [`ID`](utils.md#id), `indicator`: [`AddIndicatorOptions`](utils.md#addindicatoroptions)) => [`Indicator`](utils.md#indicator)

Add an indicator to a sitemap session.
Indicators are displayed next to the entry name in the collections tree.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `entryId` | [`ID`](utils.md#id) | The ID of the entry to add the indicator to. |
| `indicator` | [`AddIndicatorOptions`](utils.md#addindicatoroptions) | The indicator configuration. |

###### Returns

[`Indicator`](utils.md#indicator)

A handle object with a `remove` method to remove the indicator.

###### Example

```ts
const indicator = sdk.sitemap.addEntryIndicator(entryId, {
  icon: "fas fa-exclamation-triangle",
  description: "Security warning",
});

// Later, remove the indicator
indicator.remove();
```

##### addRequestEditorExtension()

> **addRequestEditorExtension**: (`extension`: `Extension`) => `void`

Add an extension to the request editor.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `extension` | `Extension` | The extension to add. |

###### Returns

`void`

##### addRequestViewMode()

> **addRequestViewMode**: (`options`: [`RequestViewModeOptions`](request.md#requestviewmodeoptions)) => `void`

Add a custom request view mode.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`RequestViewModeOptions`](request.md#requestviewmodeoptions) | The view mode options. |

###### Returns

`void`

##### addResponseViewMode()

> **addResponseViewMode**: (`options`: [`ResponseViewModeOptions`](response.md#responseviewmodeoptions)) => `void`

Add a custom response view mode.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options` | [`ResponseViewModeOptions`](response.md#responseviewmodeoptions) | The view mode options. |

###### Returns

`void`

##### getChildren()

> **getChildren**: (`entryId`: [`ID`](utils.md#id)) => `Promise`<[`SitemapEntry`](#sitemapentry)\[]>

Load children for a sitemap entry.
This will fetch and load children if they haven't been loaded yet.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `entryId` | [`ID`](utils.md#id) | The ID of the entry to load children for. |

###### Returns

`Promise`<[`SitemapEntry`](#sitemapentry)\[]>

Promise that resolves when children are loaded.

##### getScopeId()

> **getScopeId**: () => [`ID`](utils.md#id) | `undefined`

Get the current scope ID.

###### Returns

[`ID`](utils.md#id) | `undefined`

The current scope ID.

##### getTreeEntries()

> **getTreeEntries**: () => [`SitemapRootEntry`](other.md#sitemaprootentry)\[]

Get the list of all sitemap entries in tree format.

###### Returns

[`SitemapRootEntry`](other.md#sitemaprootentry)\[]

The list of all sitemap entries.

##### onEntryChildStateUpdate()

> **onEntryChildStateUpdate**: (`callback`: (`event`: [`SitemapEntryChildStateUpdateEvent`](#sitemapentrychildstateupdateevent)) => `void`) => [`ListenerHandle`](utils.md#listenerhandle)

Listen for child state updates on a sitemap entry.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `callback` | (`event`: [`SitemapEntryChildStateUpdateEvent`](#sitemapentrychildstateupdateevent)) => `void` | The callback function that receives the entry ID and new child state. |

###### Returns

[`ListenerHandle`](utils.md#listenerhandle)

A handle object with a `stop` method to stop listening.

###### Example

```ts
const handle = sdk.sitemap.onEntryChildStateUpdate((entryId, newChildState) => {
  console.log(`Entry ${entryId} child state changed:`, newChildState);
});

// Later, stop listening
handle.stop();
```

##### setScope()

> **setScope**: (`id`: [`ID`](utils.md#id) | `undefined`) => `void`

Set the current scope.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `id` | [`ID`](utils.md#id) | `undefined` | The ID of the scope to set. |

###### Returns

`void`

***

### SitemapEntryKind

> `const` **SitemapEntryKind**: `object`

The kind of a sitemap entry.

#### Type Declaration

##### Directory

> `readonly` **Directory**: `"DIRECTORY"`

##### Domain

> `readonly` **Domain**: `"DOMAIN"`

##### Request

> `readonly` **Request**: `"REQUEST"`

##### RequestBody

> `readonly` **RequestBody**: `"REQUEST_BODY"`

##### RequestQuery

> `readonly` **RequestQuery**: `"REQUEST_QUERY"`

---

---
url: /plugins/reference/sdks/frontend/slots.md
---
# Slots

### ButtonSlotContent

> **ButtonSlotContent** = [`DefineSlotContent`](other.md#defineslotcontent)<`"Button"`, { `icon?`: `string`; `label`: `string`; `onClick`: () => `void`; }>

Content for a button slot.

***

### CommandSlotContent

> **CommandSlotContent** = [`DefineSlotContent`](other.md#defineslotcontent)<`"Command"`, { `commandId`: [`CommandID`](other.md#commandid); `icon?`: `string`; }>

Content for a command slot.

***

### CustomSlotContent

> **CustomSlotContent** = [`DefineSlotContent`](other.md#defineslotcontent)<`"Custom"`, { `definition`: [`ComponentDefinition`](utils.md#componentdefinition); }>

Content for a custom component slot.

***

### DefineAddToSlotFn()

> **DefineAddToSlotFn**<`TMap`> = <`K`>(`slot`: `K`, `spec`: `TMap`\[`K`]) => `void`

A function type for adding content to slots.

#### Type Parameters

| Type Parameter |
| ------ |
| `TMap` *extends* `Record`<`string`, [`DefineSlotContent`](other.md#defineslotcontent)<`string`, `Record`<`string`, `unknown`>>> |

#### Type Parameters

| Type Parameter |
| ------ |
| `K` *extends* `string` | `number` | `symbol` |

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `slot` | `K` |
| `spec` | `TMap`\[`K`] |

#### Returns

`void`

***

### SlotContent

> **SlotContent** = [`ButtonSlotContent`](#buttonslotcontent) | [`CustomSlotContent`](#customslotcontent) | [`CommandSlotContent`](#commandslotcontent)

Union type of all possible slot content types.

---

---
url: /plugins/guides/spawning_process.md
---
# Spawn a Process

You might want to spawn a process to interact with external tools or programs.

To do this, you can use the `spawn` function from the `child_process` module.

::: info
This module is similar to NodeJS's `child_process` module, but with some differences. You can find more information in the [child\_process](/plugins/concepts/child_process.md) documentation.
:::

## Launching a Process

The code below spawns a process that echoes "Hello, world!" to the console.

```js
import { spawn } from "child_process";

const child = spawn("echo", ["Hello, world!"]);
```

## Reading STDOUT and STDERR

To handle the output and error streams of the child process, you can use the `stdout` and `stderr` properties of the child process.

```js
let output = "";
child.stdout.on("data", (data) => {
  output += data.toString();
});

let error = "";
child.stderr.on("data", (data) => {
  error += data.toString();
});
```

## Waiting for Exit

To wait for the child process to close and check the exit code, you can use the `close` event of the child process.

```js
const exitCode = await new Promise((resolve, reject) => {
  child.on("close", resolve);
});

if (exitCode) {
  throw new Error(`subprocess error exit ${exitCode}, ${error}`);
}
```

## Driving a Process to Completion

Combining the two methods, we can drive any child process to completion and get its output.

```js
async function driveChild(child) {
  let output = "";
  child.stdout.on("data", (data) => {
    output += data.toString();
  });

  let error = "";
  child.stderr.on("data", (data) => {
    error += data.toString();
  });

  const exitCode = await new Promise((resolve, reject) => {
    child.on("close", resolve);
  });

  if (exitCode) {
    throw new Error(`subprocess error exit ${exitCode}, ${error}`);
  }

  return output;
}

export async function test() {
  const child = spawn("echo", ["Hello, world!"]);
  const result = await driveChild(child);
  return result;
}
```

## Executing Within a Shell

You can use the `shell: true` or `shell: '/shell/path'` options to execute the command in a shell.

```js
import { spawn } from "child_process";

export async function test() {
  const child = spawn("echo", ["Hello, world!"], { shell: true });
  const result = await driveChild(child);
  return result;
}
```

---

---
url: /plugins/reference/sdks/frontend/storage.md
---
# Storage

### StorageSDK

> **StorageSDK** = `object`

Utilities to interact with frontend-plugin storage.

#### Properties

##### get()

> **get**: () => [`JSONValue`](json.md#jsonvalue)

Get the storage.

###### Returns

[`JSONValue`](json.md#jsonvalue)

The storage.

##### onChange()

> **onChange**: (`callback`: (`value`: [`JSONValue`](json.md#jsonvalue)) => `void`) => `void`

Subscribe to storage changes.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `callback` | (`value`: [`JSONValue`](json.md#jsonvalue)) => `void` | The callback to call when the storage changes. |

###### Returns

`void`

##### set()

> **set**: <`T`>(`value`: [`JSONCompatible`](json.md#jsoncompatible)<`T`>) => `Promise`<`void`>

Set the storage.

###### Type Parameters

| Type Parameter |
| ------ |
| `T` |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `value` | [`JSONCompatible`](json.md#jsoncompatible)<`T`> | The value to set the storage to |

###### Returns

`Promise`<`void`>

A promise that resolves when the storage has been set.

---

---
url: /plugins/guides/sqlite.md
---
# Store Data in SQLite

For storing data generated by your plugin, Caido utilizes SQLite databases.

SQLite is a lightweight database engine made available via a small library. It requires no setup, administration or separate server. Instead, all data is stored in a single file.

## Getting a Database

The `sdk.meta.db()` utility provides a SQLite database specific to your plugin. You can view the location of the generated file using `sdk.meta.path()`:

```ts
const db = await sdk.meta.db();

const dataPath = sdk.meta.path();
sdk.console.log(`Database will be stored in: ${dataPath}`);
```

::: tip
To create a database at different location, use `open`:

```ts
import { open } from 'sqlite'

async function newDatabase() {
  const db = await open({ filename: "path/to/database.sqlite" });
  await db.exec("CREATE TABLE test (id INTEGER PRIMARY KEY, name TEXT);");
  await db.exec("INSERT INTO test (name) VALUES ('foo');");
}
```

:::

## Creating Tables

You can run direct SQL statements by supplying them as an arguement to the `.exec()` method:

```ts
// Create a new table if it doesn't exist.
// This will create a table named "test" with two columns: id and name.
await db.exec(`
  CREATE TABLE IF NOT EXISTS test (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL
  );
`);
```

## Inserting Rows

Instead of using direct statements every time you want to add to a table, you can use `.prepare()` to create predefined statements with placeholders, marked with `(?)` for new entry values.

Then, you can execute these prepared statements with the `.run()` method that takes the placeholder values as arguements:

```ts
const insertStatement = await db.prepare("INSERT INTO test (name) VALUES (?)");

// Execute the insert statement to add "Ninjeeter" as a name entry.
const result = await insertStatement.run("Ninjeeter");
```

Using `.lastInsertRowid` will return the ID of the last inserted row:

```ts
console.log(`Inserted row with ID: ${result.lastInsertRowid}`);
```

## Retrieving Data

To select all the columns in a table and return every row, use the wildcard character `*` and the `.all()` method:

```ts
const selectStatement = await db.prepare("SELECT * FROM test");
const rows = await selectStatement.all();
sdk.console.log("Current records: " + JSON.stringify(rows));
```

You can return specific rows by preparing a statement and using the `.get()` method which takes an arguement that will be used to match the table entry:

```ts
// Prepare a statement to get a single row by ID
const getByIdStatement = await db.prepare("SELECT * FROM test WHERE id = ?");

// Returns the first matching row or undefined if none found.
const row = await getByIdStatement.get(1); // Get row with ID 1.

if (row) {
    sdk.console.log(`Found record: ${JSON.stringify(row)}`);
} else {
    sdk.console.log("No record found with that ID");
}
```

### /packages/backend/src/index.ts

```ts
import type { DefineAPI, SDK } from "caido:plugin";

async function initDatabase(sdk: SDK) {
  try {
    const db = await sdk.meta.db();
    
    const dataPath = sdk.meta.path();
    sdk.console.log(`Database will be stored in: ${dataPath}`);
    
    await db.exec(`
      CREATE TABLE IF NOT EXISTS test (
        id INTEGER PRIMARY KEY,
        name TEXT NOT NULL
      );
    `);

    const insertStatement = await db.prepare("INSERT INTO test (name) VALUES (?)");
    const result = await insertStatement.run("foo");
    sdk.console.log(`Inserted row with ID: ${result.lastInsertRowid}`);

    const selectStatement = await db.prepare("SELECT * FROM test");
    const rows = await selectStatement.all();
    sdk.console.log("Current records: " + JSON.stringify(rows));

    const getByIdStatement = await db.prepare("SELECT * FROM test WHERE id = ?");

    const row = await getByIdStatement.get(1);

    if (row) {
        sdk.console.log(`Found record: ${JSON.stringify(row)}`);
    } else {
        sdk.console.log("No record found with that ID");
    }

    return db;
  } catch (error) {
    sdk.console.error(`Database initialization failed: ${error}`);
    throw error;
  }
}

export type API = DefineAPI<{
}>;

export async function init(sdk: SDK<API>) {
  await initDatabase(sdk);
  sdk.console.log("Database initialized.");
}
```

## The Result

In your backend logs, you will see the following entries:

```txt
Database will be stored in: [~]\Caido\data\plugins\[PLUGIN UUID]
Inserted row with ID: 1
Current records: [{"id":1,"name":"Ninjeeter"}]
Found record: {"id":1,"name":"Ninjeeter"}
```

---

---
url: /plugins/guides/frontend_storage.md
---
# Store Frontend Data

By default, the frontend component of a plugin is stateless, meaning data will be lost between Caido sessions. However, if your plugin needs to persist data in the frontend you can utilize the storage system through `sdk.storage`.

The storage system is defined by the [StorageSDK](/plugins/reference/sdks/frontend/#sdk) interface and provides these methods:

* `set()`: Puts new data into the storage.
* `get()`: Fetches the current data from storage.
* `onChange()`: Sets up a listener that runs when the storage changes.

::: info
Stored data needs to be JSON serializable.
:::

::: info
Although frontend storage actually exists in the backend, it is inaccessible by the backend component. To share data with the backend component of a plugin, you will need to [create and call a custom function](/plugins/guides/rpc.md).
:::

## User Preferences

To demonstrate its usage, let's create a frontend interface that offers light and dark theme options.

### App.vue

```ts
<script setup lang="ts">
import Button from "primevue/button";
import { useSDK } from "@/plugins/sdk";
import { ref, onMounted, watch } from "vue";

const sdk = useSDK();

const currentTheme = ref<"light" | "dark" | null>(null);

const updateTheme = async (theme: "light" | "dark") => {
  await sdk.storage.set({ theme });
  currentTheme.value = theme;
};

const applyTheme = (theme: "light" | "dark") => {
  const root = document.getElementById('plugin--frontend-vue');
  if (root) {
    if (theme === "dark") {
      root.style.backgroundColor = "#202227";
    } else {
      root.style.backgroundColor = "#FFFFFF";
    }
  }
};

const loadSettings = () => {
  const settings = sdk.storage.get() as { theme: "light" | "dark" } | null;
  if (settings?.theme) {
    currentTheme.value = settings.theme;
    applyTheme(settings.theme);
  } else {
    currentTheme.value = "light";
    applyTheme("light");
  }
};

watch(currentTheme, (newTheme) => {
  if (newTheme) {
    applyTheme(newTheme);
  }
});

sdk.storage.onChange((newSettings) => {
  const settings = newSettings as { theme: "light" | "dark" } | null;
  if (settings?.theme) {
    currentTheme.value = settings.theme;
  }
});

onMounted(() => {
  loadSettings();
});
</script>

<template>
  <div class="h-full flex justify-center items-center" :style="{ backgroundColor: currentTheme === 'dark' ? '#202227' : '#FFFFFF' }">
    <div class="flex flex-col gap-4">
      <div class="flex gap-2">
        <!-- Light theme button -->
        <Button 
          label="Light" 
          @click="updateTheme('light')"
          :disabled="currentTheme === 'light'"
        />
        <!-- Dark theme button -->
        <Button 
          label="Dark" 
          @click="updateTheme('dark')"
          :disabled="currentTheme === 'dark'"
        />
      </div>
    </div>
  </div>
</template>
```

### Script Breakdown

First, the `<script>` block with TypeScript support is opened and the Caido SDK is imported along with three Vue reactivity utilities:

* `ref`: Tracks value changes to automatically update the user interface.
* `onMounted`: Registers a callback function that will be executed after a component has been added to the user interface.
* `watch`: Monitors for changes to reactive components and executes a callback function when a change occurs.

```ts
<script setup lang="ts">
import Button from "primevue/button";
import { useSDK } from "@/plugins/sdk";
import { ref, onMounted, watch } from "vue";
```

The Caido SDK is initialized so the plugin can access its functionality.

```ts
const sdk = useSDK();
```

A variable named `currentTheme` is defined that will dynamically store the theme selection, starting with `null` to account for the first initialization.

```ts
const currentTheme = ref<"light" | "dark" | null>(null);
```

Next, an asynchronous function named `updateTheme` is defined to save the current theme selection in storage using `sdk.storage.set()`.

```ts
const updateTheme = async (theme: "light" | "dark") => {
  await sdk.storage.set({ theme });
  currentTheme.value = theme;
};
```

To apply the theme to the user interface, the `applyTheme` function switches the background color of the user interface.

```ts
const applyTheme = (theme: "light" | "dark") => {
  const root = document.getElementById('plugin--frontend-vue');
  if (root) {
    if (theme === "dark") {
      root.style.backgroundColor = "#202227";
    } else {
      root.style.backgroundColor = "#FFFFFF";
    }
  }
};
```

To retrieve the saved theme setting from storage, `sdk.storage.get()` is called by the `loadSettings` function. If a theme exists in storage, it will be applied. If there is no saved theme selection, the theme will default to light.

```ts
const loadSettings = () => {
  const settings = sdk.storage.get() as { theme: "light" | "dark" } | null;
  if (settings?.theme) {
    currentTheme.value = settings.theme;
    applyTheme(settings.theme);
  } else {
    currentTheme.value = "light";
    applyTheme("light");
  }
};
```

The `watch` utility is used to monitor for changes to the value of the `currentTheme` variable and calls the `applyTheme` function if the value changes:

```ts
watch(currentTheme, (newTheme) => {
  if (newTheme) {
    applyTheme(newTheme);
  }
});
```

With `sdk.storage.onChange()`, if a theme change is made from other user interfaces, they will be applied to this plugin's user interface as well.

```ts
sdk.storage.onChange((newSettings) => {
  const settings = newSettings as { theme: "light" | "dark" } | null;
  if (settings?.theme) {
    currentTheme.value = settings.theme;
  }
});
```

When the page is loaded, the `loadSettings()` function will be called.

```ts
onMounted(() => {
  loadSettings();
});
</script>
```

A button for both themes are added to the user interface that will call the `updateTheme` function to update the saved theme in storage when clicked. If the corresponding theme is already saved, its button will be disabled.

```vue
<template>
  <div class="h-full flex justify-center items-center" :style="{ backgroundColor: currentTheme === 'dark' ? '#202227' : '#FFFFFF' }">
    <div class="flex flex-col gap-4">
      <div class="flex gap-2">
        <!-- Light theme button -->
        <Button 
          label="Light" 
          @click="updateTheme('light')"
          :disabled="currentTheme === 'light'"
        />
        <!-- Dark theme button -->
        <Button 
          label="Dark" 
          @click="updateTheme('dark')"
          :disabled="currentTheme === 'dark'"
        />
      </div>
    </div>
  </div>
</template>
```

---

---
url: /plugins/reference/modules/llrt/stream/stream.md
---
[@caido/quickjs-types](../../index.md) / [llrt/stream](index.md) / stream

# stream

## Classes

### DefaultDuplexStream

#### Extends

* [`DefaultReadableStream`](#defaultreadablestream)

#### Extended by

* [`Socket`](../net.md#socket)

#### Implements

* [`DefaultWritableStream`](#defaultwritablestream)

#### Constructors

##### Constructor

> **new DefaultDuplexStream**(): [`DefaultDuplexStream`](#defaultduplexstream)

###### Returns

[`DefaultDuplexStream`](#defaultduplexstream)

###### Inherited from

[`DefaultReadableStream`](#defaultreadablestream).[`constructor`](#constructor-1)

#### Methods

##### \[dispose]\()

> **\[dispose]**(): `void`

Calls `readable.destroy()`.

###### Returns

`void`

###### Inherited from

[`DefaultReadableStream`](#defaultreadablestream).[`[dispose]`](#dispose-2)

##### addListener()

###### Call Signature

> **addListener**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. error
3. finish

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`addListener`](#addlistener-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`addListener`](#addlistener-5)

###### Call Signature

> **addListener**(`event`: `"close"`, `listener`: () => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. error
3. finish

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`addListener`](#addlistener-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`addListener`](#addlistener-5)

###### Call Signature

> **addListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. error
3. finish

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`addListener`](#addlistener-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`addListener`](#addlistener-5)

###### Call Signature

> **addListener**(`event`: `"finish"`, `listener`: () => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. error
3. finish

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"finish"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`addListener`](#addlistener-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`addListener`](#addlistener-5)

##### destroy()

> **destroy**(`error?`: `Error`): `this`

Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'` event. After this call, the readable
stream will release any internal resources and subsequent calls to `push()` will be ignored.

Once `destroy()` has been called any further calls will be a no-op and no
further errors except from `_destroy()` may be emitted as `'error'`.

Implementors should not override this method, but instead implement `readable._destroy()`.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `error?` | `Error` | Error which will be passed as payload in `'error'` event |

###### Returns

`this`

###### Inherited from

[`DefaultReadableStream`](#defaultreadablestream).[`destroy`](#destroy-2)

##### emit()

###### Call Signature

> **emit**(`event`: [`EventKey`](../dom-events.md#eventkey), ...`args`: `any`\[]): `boolean`

Synchronously calls each of the listeners registered for the event named `eventName`, in the order they were registered, passing the supplied arguments
to each.

```js
import { EventEmitter } from 'events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) |
| ...`args` | `any`\[] |

###### Returns

`boolean`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`emit`](#emit-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`emit`](#emit-5)

###### Call Signature

> **emit**(`event`: `"close"`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |

###### Returns

`boolean`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`emit`](#emit-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`emit`](#emit-5)

###### Call Signature

> **emit**(`event`: `"error"`, `err`: `Error`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `err` | `Error` |

###### Returns

`boolean`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`emit`](#emit-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`emit`](#emit-5)

###### Call Signature

> **emit**(`event`: `"finish"`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"finish"` |

###### Returns

`boolean`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`emit`](#emit-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`emit`](#emit-5)

##### end()

> **end**(): `this`

Calling the `writable.end()` method signals that no more data will be written
to the `Writable`.

Calling the [write](#write) method after calling [end](#end) will raise an error.

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`end`](#end-2)

##### eventNames()

> **eventNames**(): [`EventKey`](../dom-events.md#eventkey)\[]

Returns an array listing the events for which the emitter has registered
listeners. The values in the array are strings or `Symbol`s.

```js
import { EventEmitter } from 'events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]
```

###### Returns

[`EventKey`](../dom-events.md#eventkey)\[]

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`eventNames`](#eventnames-4)

###### Inherited from

[`DefaultReadableStream`](#defaultreadablestream).[`eventNames`](#eventnames-2)

##### off()

> **off**<`K`>(`eventName`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Alias for `emitter.removeListener()`.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`EventKey`](../dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`off`](#off-4)

###### Inherited from

[`DefaultReadableStream`](#defaultreadablestream).[`off`](#off-2)

##### on()

###### Call Signature

> **on**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the end of the listeners array for the event
named `eventName`. No checks are made to see if the `listener` has already
been added. Multiple calls passing the same combination of `eventName` and
`listener` will result in the `listener` being added, and called, multiple times.

```js
server.on('connection', (stream) => {
  console.log('someone connected!');
});
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`on`](#on-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`on`](#on-5)

###### Call Signature

> **on**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`on`](#on-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`on`](#on-5)

###### Call Signature

> **on**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`on`](#on-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`on`](#on-5)

###### Call Signature

> **on**(`event`: `"finish"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"finish"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`on`](#on-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`on`](#on-5)

##### once()

###### Call Signature

> **once**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time** `listener` function for the event named `eventName`. The
next time `eventName` is triggered, this listener is removed and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependOnceListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Since

v0.3.0

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`once`](#once-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`once`](#once-5)

###### Call Signature

> **once**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`once`](#once-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`once`](#once-5)

###### Call Signature

> **once**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`once`](#once-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`once`](#once-5)

###### Call Signature

> **once**(`event`: `"finish"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"finish"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`once`](#once-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`once`](#once-5)

##### prependListener()

###### Call Signature

> **prependListener**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the *beginning* of the listeners array for the
event named `eventName`. No checks are made to see if the `listener` has
already been added. Multiple calls passing the same combination of `eventName`
and `listener` will result in the `listener` being added, and called, multiple times.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`prependListener`](#prependlistener-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`prependListener`](#prependlistener-5)

###### Call Signature

> **prependListener**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`prependListener`](#prependlistener-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`prependListener`](#prependlistener-5)

###### Call Signature

> **prependListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`prependListener`](#prependlistener-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`prependListener`](#prependlistener-5)

###### Call Signature

> **prependListener**(`event`: `"finish"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"finish"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`prependListener`](#prependlistener-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`prependListener`](#prependlistener-5)

##### prependOnceListener()

###### Call Signature

> **prependOnceListener**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time**`listener` function for the event named `eventName` to the *beginning* of the listeners array.
The next time `eventName` is triggered, this listener is removed, and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`prependOnceListener`](#prependoncelistener-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`prependOnceListener`](#prependoncelistener-5)

###### Call Signature

> **prependOnceListener**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`prependOnceListener`](#prependoncelistener-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`prependOnceListener`](#prependoncelistener-5)

###### Call Signature

> **prependOnceListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`prependOnceListener`](#prependoncelistener-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`prependOnceListener`](#prependoncelistener-5)

###### Call Signature

> **prependOnceListener**(`event`: `"finish"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"finish"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`prependOnceListener`](#prependoncelistener-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`prependOnceListener`](#prependoncelistener-5)

##### read()

> **read**(`size?`: `number`): [`Buffer`](../buffer.md#buffer) | `null`

The `readable.read()` method reads data out of the internal buffer and
returns it. If no data is available to be read, `null` is returned. By default,
the data is returned as a `Buffer` object unless an encoding has been
specified using the `readable.setEncoding()` method or the stream is operating
in object mode.

The optional `size` argument specifies a specific number of bytes to read. If
`size` bytes are not available to be read, `null` will be returned *unless* the
stream has ended, in which case all of the data remaining in the internal buffer
will be returned.

If the `size` argument is not specified, all of the data contained in the
internal buffer will be returned.

The `size` argument must be less than or equal to 1 GiB.

The `readable.read()` method should only be called on `Readable` streams
operating in paused mode. In flowing mode, `readable.read()` is called
automatically until the internal buffer is fully drained.

```js
const readable = getReadableStreamSomehow();

// 'readable' may be triggered multiple times as data is buffered in
readable.on('readable', () => {
  let chunk;
  console.log('Stream is readable (new data received in buffer)');
  // Use a loop to make sure we read all currently available data
  while (null !== (chunk = readable.read())) {
    console.log(`Read ${chunk.length} bytes of data...`);
  }
});

// 'end' will be triggered once when there is no more data available
readable.on('end', () => {
  console.log('Reached end of stream.');
});
```

Each call to `readable.read()` returns a chunk of data, or `null`. The chunks
are not concatenated. A `while` loop is necessary to consume all data
currently in the buffer. When reading a large file `.read()` may return `null`,
having consumed all buffered content so far, but there is still more data to
come not yet buffered. In this case a new `'readable'` event will be emitted
when there is more data in the buffer. Finally the `'end'` event will be
emitted when there is no more data to come.

Therefore to read a file's whole contents from a `readable`, it is necessary
to collect chunks across multiple `'readable'` events:

```js
const chunks = [];

readable.on('readable', () => {
  let chunk;
  while (null !== (chunk = readable.read())) {
    chunks.push(chunk);
  }
});

readable.on('end', () => {
  const content = chunks.join('');
});
```

A `Readable` stream in object mode will always return a single item from
a call to `readable.read(size)`, regardless of the value of the `size` argument.

If the `readable.read()` method returns a chunk of data, a `'data'` event will
also be emitted.

Calling [read](#read-4) after the `'end'` event has
been emitted will return `null`. No runtime error will be raised.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `size?` | `number` | Optional argument to specify how much data to read. |

###### Returns

[`Buffer`](../buffer.md#buffer) | `null`

###### Inherited from

[`DefaultReadableStream`](#defaultreadablestream).[`read`](#read-2)

##### removeListener()

###### Call Signature

> **removeListener**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Removes the specified `listener` from the listener array for the event named `eventName`.

`removeListener()` will remove, at most, one instance of a listener from the
listener array. If any single listener has been added multiple times to the
listener array for the specified `eventName`, then `removeListener()` must be
called multiple times to remove each instance.

Once an event is emitted, all listeners attached to it at the time of emitting are called in order.
This implies that any `removeListener()` calls *after* emitting and *before* the last listener finishes execution
will not remove them from `emit()` in progress. Subsequent events behave as expected.

```js
import { EventEmitter } from 'events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A
```

Because listeners are managed using an internal array, calling this will
change the position indices of any listener registered *after* the listener
being removed. This will not impact the order in which listeners are called,
but it means that any copies of the listener array as returned by
the `emitter.listeners()` method will need to be recreated.

When a single function has been added as a handler multiple times for a single
event (as in the example below), `removeListener()` will remove the most
recently added instance. In the example the `once('ping')` listener is removed:

```js
import { EventEmitter } from 'events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`removeListener`](#removelistener-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`removeListener`](#removelistener-5)

###### Call Signature

> **removeListener**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`removeListener`](#removelistener-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`removeListener`](#removelistener-5)

###### Call Signature

> **removeListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`removeListener`](#removelistener-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`removeListener`](#removelistener-5)

###### Call Signature

> **removeListener**(`event`: `"finish"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"finish"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`removeListener`](#removelistener-12)

###### Overrides

[`DefaultReadableStream`](#defaultreadablestream).[`removeListener`](#removelistener-5)

##### write()

> **write**(`chunk`: `string` | [`ArrayBufferView`](../globals/namespaces/QuickJS.md#arraybufferview) | [`Buffer`](../buffer.md#buffer) | `ArrayBuffer` | `SharedArrayBuffer`, `callback?`: (`error?`: `Error` | `null`) => `void`): `void`

The `writable.write()` method writes some data to the stream, and calls the
supplied `callback` once the data has been fully handled. If an error
occurs, the `callback` will be called with the error as its
first argument. The `callback` is usually called asynchronously and before `'error'`
is emitted.

```js
function write(data, cb) {
  if (!stream.write(data)) {
    stream.once('drain', cb);
  } else {
    process.nextTick(cb);
  }
}

// Wait for cb to be called before doing any other write.
write('hello', () => {
  console.log('Write completed, do more writes now.');
});
```

A `Writable` stream in object mode will always ignore the `encoding` argument.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `chunk` | `string` | [`ArrayBufferView`](../globals/namespaces/QuickJS.md#arraybufferview) | [`Buffer`](../buffer.md#buffer) | `ArrayBuffer` | `SharedArrayBuffer` | Optional data to write. `chunk` must be a {string}, {Buffer}, {TypedArray} or {DataView}. |
| `callback?` | (`error?`: `Error` | `null`) => `void` | Callback for when this chunk of data is flushed. |

###### Returns

`void`

`false` if the stream wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`.

###### Since

v0.9.4

###### Implementation of

[`DefaultWritableStream`](#defaultwritablestream).[`write`](#write-2)

***

### DefaultReadableStream

#### Extends

* [`ReadableStreamInner`](#readablestreaminner)

#### Extended by

* [`DefaultDuplexStream`](#defaultduplexstream)

#### Constructors

##### Constructor

> **new DefaultReadableStream**(): [`DefaultReadableStream`](#defaultreadablestream)

###### Returns

[`DefaultReadableStream`](#defaultreadablestream)

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`constructor`](#constructor-3)

#### Methods

##### \[dispose]\()

> **\[dispose]**(): `void`

Calls `readable.destroy()`.

###### Returns

`void`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`[dispose]`](#dispose-4)

##### addListener()

###### Call Signature

> **addListener**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. data
3. end
4. error
5. readable

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`addListener`](#addlistener-17)

###### Call Signature

> **addListener**(`event`: `"close"`, `listener`: () => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. data
3. end
4. error
5. readable

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`addListener`](#addlistener-17)

###### Call Signature

> **addListener**(`event`: `"data"`, `listener`: (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. data
3. end
4. error
5. readable

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"data"` |
| `listener` | (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`addListener`](#addlistener-17)

###### Call Signature

> **addListener**(`event`: `"end"`, `listener`: () => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. data
3. end
4. error
5. readable

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"end"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`addListener`](#addlistener-17)

###### Call Signature

> **addListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. data
3. end
4. error
5. readable

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`addListener`](#addlistener-17)

###### Call Signature

> **addListener**(`event`: `"readable"`, `listener`: () => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. data
3. end
4. error
5. readable

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"readable"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`addListener`](#addlistener-17)

##### destroy()

> **destroy**(`error?`: `Error`): `this`

Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'` event. After this call, the readable
stream will release any internal resources and subsequent calls to `push()` will be ignored.

Once `destroy()` has been called any further calls will be a no-op and no
further errors except from `_destroy()` may be emitted as `'error'`.

Implementors should not override this method, but instead implement `readable._destroy()`.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `error?` | `Error` | Error which will be passed as payload in `'error'` event |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`destroy`](#destroy-4)

##### emit()

###### Call Signature

> **emit**(`event`: [`EventKey`](../dom-events.md#eventkey), ...`args`: `any`\[]): `boolean`

Synchronously calls each of the listeners registered for the event named `eventName`, in the order they were registered, passing the supplied arguments
to each.

```js
import { EventEmitter } from 'events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) |
| ...`args` | `any`\[] |

###### Returns

`boolean`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`emit`](#emit-17)

###### Call Signature

> **emit**(`event`: `"close"`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |

###### Returns

`boolean`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`emit`](#emit-17)

###### Call Signature

> **emit**(`event`: `"data"`, `chunk`: [`Buffer`](../buffer.md#buffer)): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"data"` |
| `chunk` | [`Buffer`](../buffer.md#buffer) |

###### Returns

`boolean`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`emit`](#emit-17)

###### Call Signature

> **emit**(`event`: `"end"`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"end"` |

###### Returns

`boolean`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`emit`](#emit-17)

###### Call Signature

> **emit**(`event`: `"error"`, `err`: `Error`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `err` | `Error` |

###### Returns

`boolean`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`emit`](#emit-17)

###### Call Signature

> **emit**(`event`: `"readable"`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"readable"` |

###### Returns

`boolean`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`emit`](#emit-17)

##### eventNames()

> **eventNames**(): [`EventKey`](../dom-events.md#eventkey)\[]

Returns an array listing the events for which the emitter has registered
listeners. The values in the array are strings or `Symbol`s.

```js
import { EventEmitter } from 'events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]
```

###### Returns

[`EventKey`](../dom-events.md#eventkey)\[]

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`eventNames`](#eventnames-6)

##### off()

> **off**<`K`>(`eventName`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Alias for `emitter.removeListener()`.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`EventKey`](../dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`off`](#off-6)

##### on()

###### Call Signature

> **on**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the end of the listeners array for the event
named `eventName`. No checks are made to see if the `listener` has already
been added. Multiple calls passing the same combination of `eventName` and
`listener` will result in the `listener` being added, and called, multiple times.

```js
server.on('connection', (stream) => {
  console.log('someone connected!');
});
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`on`](#on-17)

###### Call Signature

> **on**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`on`](#on-17)

###### Call Signature

> **on**(`event`: `"data"`, `listener`: (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"data"` |
| `listener` | (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`on`](#on-17)

###### Call Signature

> **on**(`event`: `"end"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"end"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`on`](#on-17)

###### Call Signature

> **on**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`on`](#on-17)

###### Call Signature

> **on**(`event`: `"readable"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"readable"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`on`](#on-17)

##### once()

###### Call Signature

> **once**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time** `listener` function for the event named `eventName`. The
next time `eventName` is triggered, this listener is removed and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependOnceListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Since

v0.3.0

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`once`](#once-17)

###### Call Signature

> **once**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`once`](#once-17)

###### Call Signature

> **once**(`event`: `"data"`, `listener`: (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"data"` |
| `listener` | (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`once`](#once-17)

###### Call Signature

> **once**(`event`: `"end"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"end"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`once`](#once-17)

###### Call Signature

> **once**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`once`](#once-17)

###### Call Signature

> **once**(`event`: `"readable"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"readable"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`once`](#once-17)

##### prependListener()

###### Call Signature

> **prependListener**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the *beginning* of the listeners array for the
event named `eventName`. No checks are made to see if the `listener` has
already been added. Multiple calls passing the same combination of `eventName`
and `listener` will result in the `listener` being added, and called, multiple times.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`prependListener`](#prependlistener-17)

###### Call Signature

> **prependListener**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`prependListener`](#prependlistener-17)

###### Call Signature

> **prependListener**(`event`: `"data"`, `listener`: (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"data"` |
| `listener` | (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`prependListener`](#prependlistener-17)

###### Call Signature

> **prependListener**(`event`: `"end"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"end"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`prependListener`](#prependlistener-17)

###### Call Signature

> **prependListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`prependListener`](#prependlistener-17)

###### Call Signature

> **prependListener**(`event`: `"readable"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"readable"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`prependListener`](#prependlistener-17)

##### prependOnceListener()

###### Call Signature

> **prependOnceListener**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time**`listener` function for the event named `eventName` to the *beginning* of the listeners array.
The next time `eventName` is triggered, this listener is removed, and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`prependOnceListener`](#prependoncelistener-17)

###### Call Signature

> **prependOnceListener**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`prependOnceListener`](#prependoncelistener-17)

###### Call Signature

> **prependOnceListener**(`event`: `"data"`, `listener`: (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"data"` |
| `listener` | (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`prependOnceListener`](#prependoncelistener-17)

###### Call Signature

> **prependOnceListener**(`event`: `"end"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"end"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`prependOnceListener`](#prependoncelistener-17)

###### Call Signature

> **prependOnceListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`prependOnceListener`](#prependoncelistener-17)

###### Call Signature

> **prependOnceListener**(`event`: `"readable"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"readable"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`prependOnceListener`](#prependoncelistener-17)

##### read()

> **read**(`size?`: `number`): [`Buffer`](../buffer.md#buffer) | `null`

The `readable.read()` method reads data out of the internal buffer and
returns it. If no data is available to be read, `null` is returned. By default,
the data is returned as a `Buffer` object unless an encoding has been
specified using the `readable.setEncoding()` method or the stream is operating
in object mode.

The optional `size` argument specifies a specific number of bytes to read. If
`size` bytes are not available to be read, `null` will be returned *unless* the
stream has ended, in which case all of the data remaining in the internal buffer
will be returned.

If the `size` argument is not specified, all of the data contained in the
internal buffer will be returned.

The `size` argument must be less than or equal to 1 GiB.

The `readable.read()` method should only be called on `Readable` streams
operating in paused mode. In flowing mode, `readable.read()` is called
automatically until the internal buffer is fully drained.

```js
const readable = getReadableStreamSomehow();

// 'readable' may be triggered multiple times as data is buffered in
readable.on('readable', () => {
  let chunk;
  console.log('Stream is readable (new data received in buffer)');
  // Use a loop to make sure we read all currently available data
  while (null !== (chunk = readable.read())) {
    console.log(`Read ${chunk.length} bytes of data...`);
  }
});

// 'end' will be triggered once when there is no more data available
readable.on('end', () => {
  console.log('Reached end of stream.');
});
```

Each call to `readable.read()` returns a chunk of data, or `null`. The chunks
are not concatenated. A `while` loop is necessary to consume all data
currently in the buffer. When reading a large file `.read()` may return `null`,
having consumed all buffered content so far, but there is still more data to
come not yet buffered. In this case a new `'readable'` event will be emitted
when there is more data in the buffer. Finally the `'end'` event will be
emitted when there is no more data to come.

Therefore to read a file's whole contents from a `readable`, it is necessary
to collect chunks across multiple `'readable'` events:

```js
const chunks = [];

readable.on('readable', () => {
  let chunk;
  while (null !== (chunk = readable.read())) {
    chunks.push(chunk);
  }
});

readable.on('end', () => {
  const content = chunks.join('');
});
```

A `Readable` stream in object mode will always return a single item from
a call to `readable.read(size)`, regardless of the value of the `size` argument.

If the `readable.read()` method returns a chunk of data, a `'data'` event will
also be emitted.

Calling [read](#read-4) after the `'end'` event has
been emitted will return `null`. No runtime error will be raised.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `size?` | `number` | Optional argument to specify how much data to read. |

###### Returns

[`Buffer`](../buffer.md#buffer) | `null`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`read`](#read-4)

##### removeListener()

###### Call Signature

> **removeListener**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Removes the specified `listener` from the listener array for the event named `eventName`.

`removeListener()` will remove, at most, one instance of a listener from the
listener array. If any single listener has been added multiple times to the
listener array for the specified `eventName`, then `removeListener()` must be
called multiple times to remove each instance.

Once an event is emitted, all listeners attached to it at the time of emitting are called in order.
This implies that any `removeListener()` calls *after* emitting and *before* the last listener finishes execution
will not remove them from `emit()` in progress. Subsequent events behave as expected.

```js
import { EventEmitter } from 'events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A
```

Because listeners are managed using an internal array, calling this will
change the position indices of any listener registered *after* the listener
being removed. This will not impact the order in which listeners are called,
but it means that any copies of the listener array as returned by
the `emitter.listeners()` method will need to be recreated.

When a single function has been added as a handler multiple times for a single
event (as in the example below), `removeListener()` will remove the most
recently added instance. In the example the `once('ping')` listener is removed:

```js
import { EventEmitter } from 'events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`removeListener`](#removelistener-17)

###### Call Signature

> **removeListener**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`removeListener`](#removelistener-17)

###### Call Signature

> **removeListener**(`event`: `"data"`, `listener`: (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"data"` |
| `listener` | (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`removeListener`](#removelistener-17)

###### Call Signature

> **removeListener**(`event`: `"end"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"end"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`removeListener`](#removelistener-17)

###### Call Signature

> **removeListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`removeListener`](#removelistener-17)

###### Call Signature

> **removeListener**(`event`: `"readable"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"readable"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`ReadableStreamInner`](#readablestreaminner).[`removeListener`](#removelistener-17)

***

### DefaultWritableStream

#### Extends

* [`WritableStreamInner`](#writablestreaminner)

#### Constructors

##### Constructor

> **new DefaultWritableStream**(): [`DefaultWritableStream`](#defaultwritablestream)

###### Returns

[`DefaultWritableStream`](#defaultwritablestream)

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`constructor`](#constructor-4)

#### Methods

##### addListener()

###### Call Signature

> **addListener**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. error
3. finish

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`addListener`](#addlistener-24)

###### Call Signature

> **addListener**(`event`: `"close"`, `listener`: () => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. error
3. finish

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`addListener`](#addlistener-24)

###### Call Signature

> **addListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. error
3. finish

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`addListener`](#addlistener-24)

###### Call Signature

> **addListener**(`event`: `"finish"`, `listener`: () => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. error
3. finish

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"finish"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`addListener`](#addlistener-24)

##### emit()

###### Call Signature

> **emit**(`event`: [`EventKey`](../dom-events.md#eventkey), ...`args`: `any`\[]): `boolean`

Synchronously calls each of the listeners registered for the event named `eventName`, in the order they were registered, passing the supplied arguments
to each.

```js
import { EventEmitter } from 'events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) |
| ...`args` | `any`\[] |

###### Returns

`boolean`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`emit`](#emit-24)

###### Call Signature

> **emit**(`event`: `"close"`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |

###### Returns

`boolean`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`emit`](#emit-24)

###### Call Signature

> **emit**(`event`: `"error"`, `err`: `Error`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `err` | `Error` |

###### Returns

`boolean`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`emit`](#emit-24)

###### Call Signature

> **emit**(`event`: `"finish"`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"finish"` |

###### Returns

`boolean`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`emit`](#emit-24)

##### end()

> **end**(): `this`

Calling the `writable.end()` method signals that no more data will be written
to the `Writable`.

Calling the [write](#write-4) method after calling [end](#end-4) will raise an error.

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`end`](#end-4)

##### eventNames()

> **eventNames**(): [`EventKey`](../dom-events.md#eventkey)\[]

Returns an array listing the events for which the emitter has registered
listeners. The values in the array are strings or `Symbol`s.

```js
import { EventEmitter } from 'events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]
```

###### Returns

[`EventKey`](../dom-events.md#eventkey)\[]

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`eventNames`](#eventnames-8)

##### off()

> **off**<`K`>(`eventName`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Alias for `emitter.removeListener()`.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`EventKey`](../dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`off`](#off-8)

##### on()

###### Call Signature

> **on**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the end of the listeners array for the event
named `eventName`. No checks are made to see if the `listener` has already
been added. Multiple calls passing the same combination of `eventName` and
`listener` will result in the `listener` being added, and called, multiple times.

```js
server.on('connection', (stream) => {
  console.log('someone connected!');
});
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`on`](#on-24)

###### Call Signature

> **on**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`on`](#on-24)

###### Call Signature

> **on**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`on`](#on-24)

###### Call Signature

> **on**(`event`: `"finish"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"finish"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`on`](#on-24)

##### once()

###### Call Signature

> **once**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time** `listener` function for the event named `eventName`. The
next time `eventName` is triggered, this listener is removed and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependOnceListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Since

v0.3.0

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`once`](#once-24)

###### Call Signature

> **once**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`once`](#once-24)

###### Call Signature

> **once**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`once`](#once-24)

###### Call Signature

> **once**(`event`: `"finish"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"finish"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`once`](#once-24)

##### prependListener()

###### Call Signature

> **prependListener**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the *beginning* of the listeners array for the
event named `eventName`. No checks are made to see if the `listener` has
already been added. Multiple calls passing the same combination of `eventName`
and `listener` will result in the `listener` being added, and called, multiple times.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`prependListener`](#prependlistener-24)

###### Call Signature

> **prependListener**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`prependListener`](#prependlistener-24)

###### Call Signature

> **prependListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`prependListener`](#prependlistener-24)

###### Call Signature

> **prependListener**(`event`: `"finish"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"finish"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`prependListener`](#prependlistener-24)

##### prependOnceListener()

###### Call Signature

> **prependOnceListener**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time**`listener` function for the event named `eventName` to the *beginning* of the listeners array.
The next time `eventName` is triggered, this listener is removed, and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`prependOnceListener`](#prependoncelistener-24)

###### Call Signature

> **prependOnceListener**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`prependOnceListener`](#prependoncelistener-24)

###### Call Signature

> **prependOnceListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`prependOnceListener`](#prependoncelistener-24)

###### Call Signature

> **prependOnceListener**(`event`: `"finish"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"finish"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`prependOnceListener`](#prependoncelistener-24)

##### removeListener()

###### Call Signature

> **removeListener**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Removes the specified `listener` from the listener array for the event named `eventName`.

`removeListener()` will remove, at most, one instance of a listener from the
listener array. If any single listener has been added multiple times to the
listener array for the specified `eventName`, then `removeListener()` must be
called multiple times to remove each instance.

Once an event is emitted, all listeners attached to it at the time of emitting are called in order.
This implies that any `removeListener()` calls *after* emitting and *before* the last listener finishes execution
will not remove them from `emit()` in progress. Subsequent events behave as expected.

```js
import { EventEmitter } from 'events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A
```

Because listeners are managed using an internal array, calling this will
change the position indices of any listener registered *after* the listener
being removed. This will not impact the order in which listeners are called,
but it means that any copies of the listener array as returned by
the `emitter.listeners()` method will need to be recreated.

When a single function has been added as a handler multiple times for a single
event (as in the example below), `removeListener()` will remove the most
recently added instance. In the example the `once('ping')` listener is removed:

```js
import { EventEmitter } from 'events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`removeListener`](#removelistener-24)

###### Call Signature

> **removeListener**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`removeListener`](#removelistener-24)

###### Call Signature

> **removeListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`removeListener`](#removelistener-24)

###### Call Signature

> **removeListener**(`event`: `"finish"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"finish"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`removeListener`](#removelistener-24)

##### write()

> **write**(`chunk`: `string` | [`ArrayBufferView`](../globals/namespaces/QuickJS.md#arraybufferview) | [`Buffer`](../buffer.md#buffer) | `ArrayBuffer` | `SharedArrayBuffer`, `callback?`: (`error?`: `Error` | `null`) => `void`): `void`

The `writable.write()` method writes some data to the stream, and calls the
supplied `callback` once the data has been fully handled. If an error
occurs, the `callback` will be called with the error as its
first argument. The `callback` is usually called asynchronously and before `'error'`
is emitted.

```js
function write(data, cb) {
  if (!stream.write(data)) {
    stream.once('drain', cb);
  } else {
    process.nextTick(cb);
  }
}

// Wait for cb to be called before doing any other write.
write('hello', () => {
  console.log('Write completed, do more writes now.');
});
```

A `Writable` stream in object mode will always ignore the `encoding` argument.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `chunk` | `string` | [`ArrayBufferView`](../globals/namespaces/QuickJS.md#arraybufferview) | [`Buffer`](../buffer.md#buffer) | `ArrayBuffer` | `SharedArrayBuffer` | Optional data to write. `chunk` must be a {string}, {Buffer}, {TypedArray} or {DataView}. |
| `callback?` | (`error?`: `Error` | `null`) => `void` | Callback for when this chunk of data is flushed. |

###### Returns

`void`

`false` if the stream wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`.

###### Since

v0.9.4

###### Inherited from

[`WritableStreamInner`](#writablestreaminner).[`write`](#write-4)

***

### ReadableStreamInner

#### Extends

* [`EventEmitter`](../events.md#eventemitter)

#### Extended by

* [`DefaultReadableStream`](#defaultreadablestream)

#### Implements

* [`ReadableStream`](../globals/namespaces/QuickJS.md#readablestream)

#### Constructors

##### Constructor

> **new ReadableStreamInner**(): [`ReadableStreamInner`](#readablestreaminner)

###### Returns

[`ReadableStreamInner`](#readablestreaminner)

###### Inherited from

[`EventEmitter`](../events.md#eventemitter).[`constructor`](../events.md#constructor)

#### Methods

##### \[dispose]\()

> **\[dispose]**(): `void`

Calls `readable.destroy()`.

###### Returns

`void`

##### addListener()

###### Call Signature

> **addListener**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. data
3. end
4. error
5. readable

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Implementation of

[`ReadableStream`](../globals/namespaces/QuickJS.md#readablestream).[`addListener`](../globals/namespaces/QuickJS.md#addlistener)

###### Overrides

[`EventEmitter`](../events.md#eventemitter).[`addListener`](../events.md#addlistener)

###### Call Signature

> **addListener**(`event`: `"close"`, `listener`: () => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. data
3. end
4. error
5. readable

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.addListener`

###### Overrides

`EventEmitter.addListener`

###### Call Signature

> **addListener**(`event`: `"data"`, `listener`: (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. data
3. end
4. error
5. readable

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"data"` |
| `listener` | (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.addListener`

###### Overrides

`EventEmitter.addListener`

###### Call Signature

> **addListener**(`event`: `"end"`, `listener`: () => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. data
3. end
4. error
5. readable

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"end"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.addListener`

###### Overrides

`EventEmitter.addListener`

###### Call Signature

> **addListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. data
3. end
4. error
5. readable

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.addListener`

###### Overrides

`EventEmitter.addListener`

###### Call Signature

> **addListener**(`event`: `"readable"`, `listener`: () => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. data
3. end
4. error
5. readable

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"readable"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.addListener`

###### Overrides

`EventEmitter.addListener`

##### destroy()

> **destroy**(`error?`: `Error`): `this`

Destroy the stream. Optionally emit an `'error'` event, and emit a `'close'` event. After this call, the readable
stream will release any internal resources and subsequent calls to `push()` will be ignored.

Once `destroy()` has been called any further calls will be a no-op and no
further errors except from `_destroy()` may be emitted as `'error'`.

Implementors should not override this method, but instead implement `readable._destroy()`.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `error?` | `Error` | Error which will be passed as payload in `'error'` event |

###### Returns

`this`

##### emit()

###### Call Signature

> **emit**(`event`: [`EventKey`](../dom-events.md#eventkey), ...`args`: `any`\[]): `boolean`

Synchronously calls each of the listeners registered for the event named `eventName`, in the order they were registered, passing the supplied arguments
to each.

```js
import { EventEmitter } from 'events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) |
| ...`args` | `any`\[] |

###### Returns

`boolean`

###### Implementation of

[`ReadableStream`](../globals/namespaces/QuickJS.md#readablestream).[`emit`](../globals/namespaces/QuickJS.md#emit)

###### Overrides

[`EventEmitter`](../events.md#eventemitter).[`emit`](../events.md#emit)

###### Call Signature

> **emit**(`event`: `"close"`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |

###### Returns

`boolean`

###### Implementation of

`QuickJS.ReadableStream.emit`

###### Overrides

`EventEmitter.emit`

###### Call Signature

> **emit**(`event`: `"data"`, `chunk`: [`Buffer`](../buffer.md#buffer)): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"data"` |
| `chunk` | [`Buffer`](../buffer.md#buffer) |

###### Returns

`boolean`

###### Implementation of

`QuickJS.ReadableStream.emit`

###### Overrides

`EventEmitter.emit`

###### Call Signature

> **emit**(`event`: `"end"`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"end"` |

###### Returns

`boolean`

###### Implementation of

`QuickJS.ReadableStream.emit`

###### Overrides

`EventEmitter.emit`

###### Call Signature

> **emit**(`event`: `"error"`, `err`: `Error`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `err` | `Error` |

###### Returns

`boolean`

###### Implementation of

`QuickJS.ReadableStream.emit`

###### Overrides

`EventEmitter.emit`

###### Call Signature

> **emit**(`event`: `"readable"`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"readable"` |

###### Returns

`boolean`

###### Implementation of

`QuickJS.ReadableStream.emit`

###### Overrides

`EventEmitter.emit`

##### eventNames()

> **eventNames**(): [`EventKey`](../dom-events.md#eventkey)\[]

Returns an array listing the events for which the emitter has registered
listeners. The values in the array are strings or `Symbol`s.

```js
import { EventEmitter } from 'events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]
```

###### Returns

[`EventKey`](../dom-events.md#eventkey)\[]

###### Implementation of

[`ReadableStream`](../globals/namespaces/QuickJS.md#readablestream).[`eventNames`](../globals/namespaces/QuickJS.md#eventnames)

###### Inherited from

[`EventEmitter`](../events.md#eventemitter).[`eventNames`](../events.md#eventnames)

##### off()

> **off**<`K`>(`eventName`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Alias for `emitter.removeListener()`.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`EventKey`](../dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Implementation of

[`ReadableStream`](../globals/namespaces/QuickJS.md#readablestream).[`off`](../globals/namespaces/QuickJS.md#off)

###### Inherited from

[`EventEmitter`](../events.md#eventemitter).[`off`](../events.md#off)

##### on()

###### Call Signature

> **on**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the end of the listeners array for the event
named `eventName`. No checks are made to see if the `listener` has already
been added. Multiple calls passing the same combination of `eventName` and
`listener` will result in the `listener` being added, and called, multiple times.

```js
server.on('connection', (stream) => {
  console.log('someone connected!');
});
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Implementation of

[`ReadableStream`](../globals/namespaces/QuickJS.md#readablestream).[`on`](../globals/namespaces/QuickJS.md#on)

###### Overrides

[`EventEmitter`](../events.md#eventemitter).[`on`](../events.md#on)

###### Call Signature

> **on**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.on`

###### Overrides

`EventEmitter.on`

###### Call Signature

> **on**(`event`: `"data"`, `listener`: (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"data"` |
| `listener` | (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.on`

###### Overrides

`EventEmitter.on`

###### Call Signature

> **on**(`event`: `"end"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"end"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.on`

###### Overrides

`EventEmitter.on`

###### Call Signature

> **on**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.on`

###### Overrides

`EventEmitter.on`

###### Call Signature

> **on**(`event`: `"readable"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"readable"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.on`

###### Overrides

`EventEmitter.on`

##### once()

###### Call Signature

> **once**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time** `listener` function for the event named `eventName`. The
next time `eventName` is triggered, this listener is removed and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependOnceListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Since

v0.3.0

###### Implementation of

[`ReadableStream`](../globals/namespaces/QuickJS.md#readablestream).[`once`](../globals/namespaces/QuickJS.md#once)

###### Overrides

[`EventEmitter`](../events.md#eventemitter).[`once`](../events.md#once)

###### Call Signature

> **once**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.once`

###### Overrides

`EventEmitter.once`

###### Call Signature

> **once**(`event`: `"data"`, `listener`: (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"data"` |
| `listener` | (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.once`

###### Overrides

`EventEmitter.once`

###### Call Signature

> **once**(`event`: `"end"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"end"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.once`

###### Overrides

`EventEmitter.once`

###### Call Signature

> **once**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.once`

###### Overrides

`EventEmitter.once`

###### Call Signature

> **once**(`event`: `"readable"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"readable"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.once`

###### Overrides

`EventEmitter.once`

##### prependListener()

###### Call Signature

> **prependListener**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the *beginning* of the listeners array for the
event named `eventName`. No checks are made to see if the `listener` has
already been added. Multiple calls passing the same combination of `eventName`
and `listener` will result in the `listener` being added, and called, multiple times.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Implementation of

[`ReadableStream`](../globals/namespaces/QuickJS.md#readablestream).[`prependListener`](../globals/namespaces/QuickJS.md#prependlistener)

###### Overrides

[`EventEmitter`](../events.md#eventemitter).[`prependListener`](../events.md#prependlistener)

###### Call Signature

> **prependListener**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.prependListener`

###### Overrides

`EventEmitter.prependListener`

###### Call Signature

> **prependListener**(`event`: `"data"`, `listener`: (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"data"` |
| `listener` | (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.prependListener`

###### Overrides

`EventEmitter.prependListener`

###### Call Signature

> **prependListener**(`event`: `"end"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"end"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.prependListener`

###### Overrides

`EventEmitter.prependListener`

###### Call Signature

> **prependListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.prependListener`

###### Overrides

`EventEmitter.prependListener`

###### Call Signature

> **prependListener**(`event`: `"readable"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"readable"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.prependListener`

###### Overrides

`EventEmitter.prependListener`

##### prependOnceListener()

###### Call Signature

> **prependOnceListener**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time**`listener` function for the event named `eventName` to the *beginning* of the listeners array.
The next time `eventName` is triggered, this listener is removed, and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Implementation of

[`ReadableStream`](../globals/namespaces/QuickJS.md#readablestream).[`prependOnceListener`](../globals/namespaces/QuickJS.md#prependoncelistener)

###### Overrides

[`EventEmitter`](../events.md#eventemitter).[`prependOnceListener`](../events.md#prependoncelistener)

###### Call Signature

> **prependOnceListener**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.prependOnceListener`

###### Overrides

`EventEmitter.prependOnceListener`

###### Call Signature

> **prependOnceListener**(`event`: `"data"`, `listener`: (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"data"` |
| `listener` | (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.prependOnceListener`

###### Overrides

`EventEmitter.prependOnceListener`

###### Call Signature

> **prependOnceListener**(`event`: `"end"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"end"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.prependOnceListener`

###### Overrides

`EventEmitter.prependOnceListener`

###### Call Signature

> **prependOnceListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.prependOnceListener`

###### Overrides

`EventEmitter.prependOnceListener`

###### Call Signature

> **prependOnceListener**(`event`: `"readable"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"readable"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.prependOnceListener`

###### Overrides

`EventEmitter.prependOnceListener`

##### read()

> **read**(`size?`: `number`): [`Buffer`](../buffer.md#buffer) | `null`

The `readable.read()` method reads data out of the internal buffer and
returns it. If no data is available to be read, `null` is returned. By default,
the data is returned as a `Buffer` object unless an encoding has been
specified using the `readable.setEncoding()` method or the stream is operating
in object mode.

The optional `size` argument specifies a specific number of bytes to read. If
`size` bytes are not available to be read, `null` will be returned *unless* the
stream has ended, in which case all of the data remaining in the internal buffer
will be returned.

If the `size` argument is not specified, all of the data contained in the
internal buffer will be returned.

The `size` argument must be less than or equal to 1 GiB.

The `readable.read()` method should only be called on `Readable` streams
operating in paused mode. In flowing mode, `readable.read()` is called
automatically until the internal buffer is fully drained.

```js
const readable = getReadableStreamSomehow();

// 'readable' may be triggered multiple times as data is buffered in
readable.on('readable', () => {
  let chunk;
  console.log('Stream is readable (new data received in buffer)');
  // Use a loop to make sure we read all currently available data
  while (null !== (chunk = readable.read())) {
    console.log(`Read ${chunk.length} bytes of data...`);
  }
});

// 'end' will be triggered once when there is no more data available
readable.on('end', () => {
  console.log('Reached end of stream.');
});
```

Each call to `readable.read()` returns a chunk of data, or `null`. The chunks
are not concatenated. A `while` loop is necessary to consume all data
currently in the buffer. When reading a large file `.read()` may return `null`,
having consumed all buffered content so far, but there is still more data to
come not yet buffered. In this case a new `'readable'` event will be emitted
when there is more data in the buffer. Finally the `'end'` event will be
emitted when there is no more data to come.

Therefore to read a file's whole contents from a `readable`, it is necessary
to collect chunks across multiple `'readable'` events:

```js
const chunks = [];

readable.on('readable', () => {
  let chunk;
  while (null !== (chunk = readable.read())) {
    chunks.push(chunk);
  }
});

readable.on('end', () => {
  const content = chunks.join('');
});
```

A `Readable` stream in object mode will always return a single item from
a call to `readable.read(size)`, regardless of the value of the `size` argument.

If the `readable.read()` method returns a chunk of data, a `'data'` event will
also be emitted.

Calling [read](#read-4) after the `'end'` event has
been emitted will return `null`. No runtime error will be raised.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `size?` | `number` | Optional argument to specify how much data to read. |

###### Returns

[`Buffer`](../buffer.md#buffer) | `null`

###### Implementation of

[`ReadableStream`](../globals/namespaces/QuickJS.md#readablestream).[`read`](../globals/namespaces/QuickJS.md#read)

##### removeListener()

###### Call Signature

> **removeListener**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Removes the specified `listener` from the listener array for the event named `eventName`.

`removeListener()` will remove, at most, one instance of a listener from the
listener array. If any single listener has been added multiple times to the
listener array for the specified `eventName`, then `removeListener()` must be
called multiple times to remove each instance.

Once an event is emitted, all listeners attached to it at the time of emitting are called in order.
This implies that any `removeListener()` calls *after* emitting and *before* the last listener finishes execution
will not remove them from `emit()` in progress. Subsequent events behave as expected.

```js
import { EventEmitter } from 'events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A
```

Because listeners are managed using an internal array, calling this will
change the position indices of any listener registered *after* the listener
being removed. This will not impact the order in which listeners are called,
but it means that any copies of the listener array as returned by
the `emitter.listeners()` method will need to be recreated.

When a single function has been added as a handler multiple times for a single
event (as in the example below), `removeListener()` will remove the most
recently added instance. In the example the `once('ping')` listener is removed:

```js
import { EventEmitter } from 'events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Implementation of

[`ReadableStream`](../globals/namespaces/QuickJS.md#readablestream).[`removeListener`](../globals/namespaces/QuickJS.md#removelistener)

###### Overrides

[`EventEmitter`](../events.md#eventemitter).[`removeListener`](../events.md#removelistener)

###### Call Signature

> **removeListener**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.removeListener`

###### Overrides

`EventEmitter.removeListener`

###### Call Signature

> **removeListener**(`event`: `"data"`, `listener`: (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"data"` |
| `listener` | (`chunk`: [`Buffer`](../buffer.md#buffer)) => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.removeListener`

###### Overrides

`EventEmitter.removeListener`

###### Call Signature

> **removeListener**(`event`: `"end"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"end"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.removeListener`

###### Overrides

`EventEmitter.removeListener`

###### Call Signature

> **removeListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.removeListener`

###### Overrides

`EventEmitter.removeListener`

###### Call Signature

> **removeListener**(`event`: `"readable"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"readable"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.ReadableStream.removeListener`

###### Overrides

`EventEmitter.removeListener`

***

### WritableStreamInner

#### Extends

* [`EventEmitter`](../events.md#eventemitter)

#### Extended by

* [`DefaultWritableStream`](#defaultwritablestream)

#### Implements

* [`WritableStream`](../globals/namespaces/QuickJS.md#writablestream)

#### Constructors

##### Constructor

> **new WritableStreamInner**(): [`WritableStreamInner`](#writablestreaminner)

###### Returns

[`WritableStreamInner`](#writablestreaminner)

###### Inherited from

[`EventEmitter`](../events.md#eventemitter).[`constructor`](../events.md#constructor)

#### Methods

##### addListener()

###### Call Signature

> **addListener**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. error
3. finish

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Implementation of

[`WritableStream`](../globals/namespaces/QuickJS.md#writablestream).[`addListener`](../globals/namespaces/QuickJS.md#addlistener-2)

###### Overrides

[`EventEmitter`](../events.md#eventemitter).[`addListener`](../events.md#addlistener)

###### Call Signature

> **addListener**(`event`: `"close"`, `listener`: () => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. error
3. finish

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.WritableStream.addListener`

###### Overrides

`EventEmitter.addListener`

###### Call Signature

> **addListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. error
3. finish

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.WritableStream.addListener`

###### Overrides

`EventEmitter.addListener`

###### Call Signature

> **addListener**(`event`: `"finish"`, `listener`: () => `void`): `this`

Event emitter
The defined events on documents including:

1. close
2. error
3. finish

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"finish"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.WritableStream.addListener`

###### Overrides

`EventEmitter.addListener`

##### emit()

###### Call Signature

> **emit**(`event`: [`EventKey`](../dom-events.md#eventkey), ...`args`: `any`\[]): `boolean`

Synchronously calls each of the listeners registered for the event named `eventName`, in the order they were registered, passing the supplied arguments
to each.

```js
import { EventEmitter } from 'events';
const myEmitter = new EventEmitter();

// First listener
myEmitter.on('event', function firstListener() {
  console.log('Helloooo! first listener');
});
// Second listener
myEmitter.on('event', function secondListener(arg1, arg2) {
  console.log(`event with parameters ${arg1}, ${arg2} in second listener`);
});
// Third listener
myEmitter.on('event', function thirdListener(...args) {
  const parameters = args.join(', ');
  console.log(`event with parameters ${parameters} in third listener`);
});

myEmitter.emit('event', 1, 2, 3, 4, 5);

// Prints:
// Helloooo! first listener
// event with parameters 1, 2 in second listener
// event with parameters 1, 2, 3, 4, 5 in third listener
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) |
| ...`args` | `any`\[] |

###### Returns

`boolean`

###### Implementation of

[`WritableStream`](../globals/namespaces/QuickJS.md#writablestream).[`emit`](../globals/namespaces/QuickJS.md#emit-2)

###### Overrides

[`EventEmitter`](../events.md#eventemitter).[`emit`](../events.md#emit)

###### Call Signature

> **emit**(`event`: `"close"`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |

###### Returns

`boolean`

###### Implementation of

`QuickJS.WritableStream.emit`

###### Overrides

`EventEmitter.emit`

###### Call Signature

> **emit**(`event`: `"error"`, `err`: `Error`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `err` | `Error` |

###### Returns

`boolean`

###### Implementation of

`QuickJS.WritableStream.emit`

###### Overrides

`EventEmitter.emit`

###### Call Signature

> **emit**(`event`: `"finish"`): `boolean`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"finish"` |

###### Returns

`boolean`

###### Implementation of

`QuickJS.WritableStream.emit`

###### Overrides

`EventEmitter.emit`

##### end()

> **end**(): `this`

Calling the `writable.end()` method signals that no more data will be written
to the `Writable`.

Calling the [write](#write-4) method after calling [end](#end-4) will raise an error.

###### Returns

`this`

###### Implementation of

[`WritableStream`](../globals/namespaces/QuickJS.md#writablestream).[`end`](../globals/namespaces/QuickJS.md#end)

##### eventNames()

> **eventNames**(): [`EventKey`](../dom-events.md#eventkey)\[]

Returns an array listing the events for which the emitter has registered
listeners. The values in the array are strings or `Symbol`s.

```js
import { EventEmitter } from 'events';

const myEE = new EventEmitter();
myEE.on('foo', () => {});
myEE.on('bar', () => {});

const sym = Symbol('symbol');
myEE.on(sym, () => {});

console.log(myEE.eventNames());
// Prints: [ 'foo', 'bar', Symbol(symbol) ]
```

###### Returns

[`EventKey`](../dom-events.md#eventkey)\[]

###### Implementation of

[`WritableStream`](../globals/namespaces/QuickJS.md#writablestream).[`eventNames`](../globals/namespaces/QuickJS.md#eventnames-2)

###### Inherited from

[`EventEmitter`](../events.md#eventemitter).[`eventNames`](../events.md#eventnames)

##### off()

> **off**<`K`>(`eventName`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Alias for `emitter.removeListener()`.

###### Type Parameters

| Type Parameter |
| ------ |
| `K` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `eventName` | [`EventKey`](../dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Implementation of

[`WritableStream`](../globals/namespaces/QuickJS.md#writablestream).[`off`](../globals/namespaces/QuickJS.md#off-2)

###### Inherited from

[`EventEmitter`](../events.md#eventemitter).[`off`](../events.md#off)

##### on()

###### Call Signature

> **on**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the end of the listeners array for the event
named `eventName`. No checks are made to see if the `listener` has already
been added. Multiple calls passing the same combination of `eventName` and
`listener` will result in the `listener` being added, and called, multiple times.

```js
server.on('connection', (stream) => {
  console.log('someone connected!');
});
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.on('foo', () => console.log('a'));
myEE.prependListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Implementation of

[`WritableStream`](../globals/namespaces/QuickJS.md#writablestream).[`on`](../globals/namespaces/QuickJS.md#on-2)

###### Overrides

[`EventEmitter`](../events.md#eventemitter).[`on`](../events.md#on)

###### Call Signature

> **on**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.WritableStream.on`

###### Overrides

`EventEmitter.on`

###### Call Signature

> **on**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.WritableStream.on`

###### Overrides

`EventEmitter.on`

###### Call Signature

> **on**(`event`: `"finish"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"finish"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.WritableStream.on`

###### Overrides

`EventEmitter.on`

##### once()

###### Call Signature

> **once**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time** `listener` function for the event named `eventName`. The
next time `eventName` is triggered, this listener is removed and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

By default, event listeners are invoked in the order they are added. The `emitter.prependOnceListener()` method can be used as an alternative to add the
event listener to the beginning of the listeners array.

```js
import { EventEmitter } from 'events';
const myEE = new EventEmitter();
myEE.once('foo', () => console.log('a'));
myEE.prependOnceListener('foo', () => console.log('b'));
myEE.emit('foo');
// Prints:
//   b
//   a
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Since

v0.3.0

###### Implementation of

[`WritableStream`](../globals/namespaces/QuickJS.md#writablestream).[`once`](../globals/namespaces/QuickJS.md#once-2)

###### Overrides

[`EventEmitter`](../events.md#eventemitter).[`once`](../events.md#once)

###### Call Signature

> **once**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.WritableStream.once`

###### Overrides

`EventEmitter.once`

###### Call Signature

> **once**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.WritableStream.once`

###### Overrides

`EventEmitter.once`

###### Call Signature

> **once**(`event`: `"finish"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"finish"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.WritableStream.once`

###### Overrides

`EventEmitter.once`

##### prependListener()

###### Call Signature

> **prependListener**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds the `listener` function to the *beginning* of the listeners array for the
event named `eventName`. No checks are made to see if the `listener` has
already been added. Multiple calls passing the same combination of `eventName`
and `listener` will result in the `listener` being added, and called, multiple times.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Implementation of

[`WritableStream`](../globals/namespaces/QuickJS.md#writablestream).[`prependListener`](../globals/namespaces/QuickJS.md#prependlistener-2)

###### Overrides

[`EventEmitter`](../events.md#eventemitter).[`prependListener`](../events.md#prependlistener)

###### Call Signature

> **prependListener**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.WritableStream.prependListener`

###### Overrides

`EventEmitter.prependListener`

###### Call Signature

> **prependListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.WritableStream.prependListener`

###### Overrides

`EventEmitter.prependListener`

###### Call Signature

> **prependListener**(`event`: `"finish"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"finish"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.WritableStream.prependListener`

###### Overrides

`EventEmitter.prependListener`

##### prependOnceListener()

###### Call Signature

> **prependOnceListener**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Adds a **one-time**`listener` function for the event named `eventName` to the *beginning* of the listeners array.
The next time `eventName` is triggered, this listener is removed, and then invoked.

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) | - |
| `listener` | (...`args`: `any`\[]) => `void` | The callback function |

###### Returns

`this`

###### Implementation of

[`WritableStream`](../globals/namespaces/QuickJS.md#writablestream).[`prependOnceListener`](../globals/namespaces/QuickJS.md#prependoncelistener-2)

###### Overrides

[`EventEmitter`](../events.md#eventemitter).[`prependOnceListener`](../events.md#prependoncelistener)

###### Call Signature

> **prependOnceListener**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.WritableStream.prependOnceListener`

###### Overrides

`EventEmitter.prependOnceListener`

###### Call Signature

> **prependOnceListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.WritableStream.prependOnceListener`

###### Overrides

`EventEmitter.prependOnceListener`

###### Call Signature

> **prependOnceListener**(`event`: `"finish"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"finish"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.WritableStream.prependOnceListener`

###### Overrides

`EventEmitter.prependOnceListener`

##### removeListener()

###### Call Signature

> **removeListener**(`event`: [`EventKey`](../dom-events.md#eventkey), `listener`: (...`args`: `any`\[]) => `void`): `this`

Removes the specified `listener` from the listener array for the event named `eventName`.

`removeListener()` will remove, at most, one instance of a listener from the
listener array. If any single listener has been added multiple times to the
listener array for the specified `eventName`, then `removeListener()` must be
called multiple times to remove each instance.

Once an event is emitted, all listeners attached to it at the time of emitting are called in order.
This implies that any `removeListener()` calls *after* emitting and *before* the last listener finishes execution
will not remove them from `emit()` in progress. Subsequent events behave as expected.

```js
import { EventEmitter } from 'events';
class MyEmitter extends EventEmitter {}
const myEmitter = new MyEmitter();

const callbackA = () => {
  console.log('A');
  myEmitter.removeListener('event', callbackB);
};

const callbackB = () => {
  console.log('B');
};

myEmitter.on('event', callbackA);

myEmitter.on('event', callbackB);

// callbackA removes listener callbackB but it will still be called.
// Internal listener array at time of emit [callbackA, callbackB]
myEmitter.emit('event');
// Prints:
//   A
//   B

// callbackB is now removed.
// Internal listener array [callbackA]
myEmitter.emit('event');
// Prints:
//   A
```

Because listeners are managed using an internal array, calling this will
change the position indices of any listener registered *after* the listener
being removed. This will not impact the order in which listeners are called,
but it means that any copies of the listener array as returned by
the `emitter.listeners()` method will need to be recreated.

When a single function has been added as a handler multiple times for a single
event (as in the example below), `removeListener()` will remove the most
recently added instance. In the example the `once('ping')` listener is removed:

```js
import { EventEmitter } from 'events';
const ee = new EventEmitter();

function pong() {
  console.log('pong');
}

ee.on('ping', pong);
ee.once('ping', pong);
ee.removeListener('ping', pong);

ee.emit('ping');
ee.emit('ping');
```

Returns a reference to the `EventEmitter`, so that calls can be chained.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | [`EventKey`](../dom-events.md#eventkey) |
| `listener` | (...`args`: `any`\[]) => `void` |

###### Returns

`this`

###### Implementation of

[`WritableStream`](../globals/namespaces/QuickJS.md#writablestream).[`removeListener`](../globals/namespaces/QuickJS.md#removelistener-2)

###### Overrides

[`EventEmitter`](../events.md#eventemitter).[`removeListener`](../events.md#removelistener)

###### Call Signature

> **removeListener**(`event`: `"close"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"close"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.WritableStream.removeListener`

###### Overrides

`EventEmitter.removeListener`

###### Call Signature

> **removeListener**(`event`: `"error"`, `listener`: (`err`: `Error`) => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"error"` |
| `listener` | (`err`: `Error`) => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.WritableStream.removeListener`

###### Overrides

`EventEmitter.removeListener`

###### Call Signature

> **removeListener**(`event`: `"finish"`, `listener`: () => `void`): `this`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | `"finish"` |
| `listener` | () => `void` |

###### Returns

`this`

###### Implementation of

`QuickJS.WritableStream.removeListener`

###### Overrides

`EventEmitter.removeListener`

##### write()

> **write**(`chunk`: `string` | [`ArrayBufferView`](../globals/namespaces/QuickJS.md#arraybufferview) | [`Buffer`](../buffer.md#buffer) | `ArrayBuffer` | `SharedArrayBuffer`, `callback?`: (`error?`: `Error` | `null`) => `void`): `void`

The `writable.write()` method writes some data to the stream, and calls the
supplied `callback` once the data has been fully handled. If an error
occurs, the `callback` will be called with the error as its
first argument. The `callback` is usually called asynchronously and before `'error'`
is emitted.

```js
function write(data, cb) {
  if (!stream.write(data)) {
    stream.once('drain', cb);
  } else {
    process.nextTick(cb);
  }
}

// Wait for cb to be called before doing any other write.
write('hello', () => {
  console.log('Write completed, do more writes now.');
});
```

A `Writable` stream in object mode will always ignore the `encoding` argument.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `chunk` | `string` | [`ArrayBufferView`](../globals/namespaces/QuickJS.md#arraybufferview) | [`Buffer`](../buffer.md#buffer) | `ArrayBuffer` | `SharedArrayBuffer` | Optional data to write. `chunk` must be a {string}, {Buffer}, {TypedArray} or {DataView}. |
| `callback?` | (`error?`: `Error` | `null`) => `void` | Callback for when this chunk of data is flushed. |

###### Returns

`void`

`false` if the stream wishes for the calling code to wait for the `'drain'` event to be emitted before continuing to write additional data; otherwise `true`.

###### Since

v0.9.4

###### Implementation of

[`WritableStream`](../globals/namespaces/QuickJS.md#writablestream).[`write`](../globals/namespaces/QuickJS.md#write)

---

---
url: /plugins/reference/modules/llrt/stream/web/stream/web.md
---
[@caido/quickjs-types](../../../../index.md) / [llrt/stream/web](../index.md) / stream/web

# stream/web

## Interfaces

### ByteLengthQueuingStrategy

This Streams API interface provides a built-in byte length queuing
strategy that can be used when constructing streams.

#### Extends

* [`QueuingStrategy`](#queuingstrategy)<`ArrayBufferView`>

#### Properties

##### highWaterMark

> `readonly` **highWaterMark**: `number`

###### Overrides

[`QueuingStrategy`](#queuingstrategy).[`highWaterMark`](#highwatermark-2)

##### size

> `readonly` **size**: [`QueuingStrategySize`](#queuingstrategysize-1)<`ArrayBufferView`>

###### Overrides

[`QueuingStrategy`](#queuingstrategy).[`size`](#size-2)

***

### CountQueuingStrategy

This Streams API interface provides a built-in byte length queuing
strategy that can be used when constructing streams.

#### Extends

* [`QueuingStrategy`](#queuingstrategy)

#### Properties

##### highWaterMark

> `readonly` **highWaterMark**: `number`

###### Overrides

[`QueuingStrategy`](#queuingstrategy).[`highWaterMark`](#highwatermark-2)

##### size

> `readonly` **size**: [`QueuingStrategySize`](#queuingstrategysize-1)

###### Overrides

[`QueuingStrategy`](#queuingstrategy).[`size`](#size-2)

***

### QueuingStrategy

#### Extended by

* [`ByteLengthQueuingStrategy`](#bytelengthqueuingstrategy)
* [`CountQueuingStrategy`](#countqueuingstrategy)

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `T` | `any` |

#### Properties

##### highWaterMark?

> `optional` **highWaterMark**: `number`

##### size?

> `optional` **size**: [`QueuingStrategySize`](#queuingstrategysize-1)<`T`>

***

### QueuingStrategyInit

#### Properties

##### highWaterMark

> **highWaterMark**: `number`

Creates a new ByteLengthQueuingStrategy with the provided high water
mark.

Note that the provided high water mark will not be validated ahead of
time. Instead, if it is negative, NaN, or not a number, the resulting
ByteLengthQueuingStrategy will cause the corresponding stream
constructor to throw.

***

### QueuingStrategySize()

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `T` | `any` |

> **QueuingStrategySize**(`chunk?`: `T`): `number`

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `chunk?` | `T` |

#### Returns

`number`

***

### ReadableByteStreamController

#### Properties

##### byobRequest

> `readonly` **byobRequest**: `undefined`

##### desiredSize

> `readonly` **desiredSize**: `number` | `null`

#### Methods

##### close()

> **close**(): `void`

###### Returns

`void`

##### enqueue()

> **enqueue**(`chunk`: `ArrayBufferView`): `void`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `chunk` | `ArrayBufferView` |

###### Returns

`void`

##### error()

> **error**(`error?`: `any`): `void`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `error?` | `any` |

###### Returns

`void`

***

### ReadableByteStreamControllerCallback()

> **ReadableByteStreamControllerCallback**(`controller`: [`ReadableByteStreamController`](#readablebytestreamcontroller)): `void` | `PromiseLike`<`void`>

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `controller` | [`ReadableByteStreamController`](#readablebytestreamcontroller) |

#### Returns

`void` | `PromiseLike`<`void`>

***

### ReadableStream

This Streams API interface represents a readable stream of byte data.

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `R` | `any` |

#### Properties

##### locked

> `readonly` **locked**: `boolean`

#### Methods

##### \[asyncIterator]\()

> **\[asyncIterator]**(): [`ReadableStreamAsyncIterator`](#readablestreamasynciterator-2)<`R`>

###### Returns

[`ReadableStreamAsyncIterator`](#readablestreamasynciterator-2)<`R`>

##### cancel()

> **cancel**(`reason?`: `any`): `Promise`<`void`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `reason?` | `any` |

###### Returns

`Promise`<`void`>

##### getReader()

###### Call Signature

> **getReader**(`options`: `object`): [`ReadableStreamBYOBReader`](#readablestreambyobreader)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `options` | { `mode`: `"byob"`; } |
| `options.mode` | `"byob"` |

###### Returns

[`ReadableStreamBYOBReader`](#readablestreambyobreader)

###### Call Signature

> **getReader**(): [`ReadableStreamDefaultReader`](#readablestreamdefaultreader)<`R`>

###### Returns

[`ReadableStreamDefaultReader`](#readablestreamdefaultreader)<`R`>

###### Call Signature

> **getReader**(`options?`: [`ReadableStreamGetReaderOptions`](#readablestreamgetreaderoptions)): [`ReadableStreamReader`](#readablestreamreader)<`R`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `options?` | [`ReadableStreamGetReaderOptions`](#readablestreamgetreaderoptions) |

###### Returns

[`ReadableStreamReader`](#readablestreamreader)<`R`>

##### pipeThrough()

> **pipeThrough**<`T`>(`transform`: [`ReadableWritablePair`](#readablewritablepair)<`T`, `R`>, `options?`: [`StreamPipeOptions`](#streampipeoptions)): [`ReadableStream`](#readablestream)<`T`>

###### Type Parameters

| Type Parameter |
| ------ |
| `T` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `transform` | [`ReadableWritablePair`](#readablewritablepair)<`T`, `R`> |
| `options?` | [`StreamPipeOptions`](#streampipeoptions) |

###### Returns

[`ReadableStream`](#readablestream)<`T`>

##### pipeTo()

> **pipeTo**(`destination`: [`WritableStream`](#writablestream)<`R`>, `options?`: [`StreamPipeOptions`](#streampipeoptions)): `Promise`<`void`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `destination` | [`WritableStream`](#writablestream)<`R`> |
| `options?` | [`StreamPipeOptions`](#streampipeoptions) |

###### Returns

`Promise`<`void`>

##### tee()

> **tee**(): \[[`ReadableStream`](#readablestream)<`R`>, [`ReadableStream`](#readablestream)<`R`>]

###### Returns

\[[`ReadableStream`](#readablestream)<`R`>, [`ReadableStream`](#readablestream)<`R`>]

##### values()

> **values**(`options?`: `object`): [`ReadableStreamAsyncIterator`](#readablestreamasynciterator-2)<`R`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `options?` | { `preventCancel?`: `boolean`; } |
| `options.preventCancel?` | `boolean` |

###### Returns

[`ReadableStreamAsyncIterator`](#readablestreamasynciterator-2)<`R`>

***

### ReadableStreamAsyncIterator

#### Extends

* `AsyncIterableIterator`<`T`>

#### Type Parameters

| Type Parameter |
| ------ |
| `T` |

#### Methods

##### \[asyncIterator]\()

> **\[asyncIterator]**(): [`ReadableStreamAsyncIterator`](#readablestreamasynciterator-2)<`T`>

###### Returns

[`ReadableStreamAsyncIterator`](#readablestreamasynciterator-2)<`T`>

###### Overrides

`AsyncIterableIterator.[asyncIterator]`

***

### ReadableStreamBYOBReader

[MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBReader)

#### Extends

* [`ReadableStreamGenericReader`](#readablestreamgenericreader)

#### Properties

##### closed

> `readonly` **closed**: `Promise`<`undefined`>

###### Inherited from

[`ReadableStreamGenericReader`](#readablestreamgenericreader).[`closed`](#closed-2)

#### Methods

##### cancel()

> **cancel**(`reason?`: `any`): `Promise`<`void`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `reason?` | `any` |

###### Returns

`Promise`<`void`>

###### Inherited from

[`ReadableStreamGenericReader`](#readablestreamgenericreader).[`cancel`](#cancel-6)

##### read()

> **read**<`T`>(`view`: `T`): `Promise`<[`ReadableStreamReadResult`](#readablestreamreadresult)<`T`>>

[MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBReader/read)

###### Type Parameters

| Type Parameter |
| ------ |
| `T` *extends* `ArrayBufferView` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `view` | `T` |

###### Returns

`Promise`<[`ReadableStreamReadResult`](#readablestreamreadresult)<`T`>>

##### releaseLock()

> **releaseLock**(): `void`

[MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBReader/releaseLock)

###### Returns

`void`

***

### ReadableStreamBYOBRequest

[MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBRequest)

#### Properties

##### view

> `readonly` **view**: `ArrayBufferView` | `null`

[MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBRequest/view)

#### Methods

##### respond()

> **respond**(`bytesWritten`: `number`): `void`

[MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBRequest/respond)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `bytesWritten` | `number` |

###### Returns

`void`

##### respondWithNewView()

> **respondWithNewView**(`view`: `ArrayBufferView`): `void`

[MDN Reference](https://developer.mozilla.org/docs/Web/API/ReadableStreamBYOBRequest/respondWithNewView)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `view` | `ArrayBufferView` |

###### Returns

`void`

***

### ReadableStreamDefaultController

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `R` | `any` |

#### Properties

##### desiredSize

> `readonly` **desiredSize**: `number` | `null`

#### Methods

##### close()

> **close**(): `void`

###### Returns

`void`

##### enqueue()

> **enqueue**(`chunk?`: `R`): `void`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `chunk?` | `R` |

###### Returns

`void`

##### error()

> **error**(`e?`: `any`): `void`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `e?` | `any` |

###### Returns

`void`

***

### ReadableStreamDefaultReader

#### Extends

* [`ReadableStreamGenericReader`](#readablestreamgenericreader)

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `R` | `any` |

#### Properties

##### closed

> `readonly` **closed**: `Promise`<`undefined`>

###### Inherited from

[`ReadableStreamGenericReader`](#readablestreamgenericreader).[`closed`](#closed-2)

#### Methods

##### cancel()

> **cancel**(`reason?`: `any`): `Promise`<`void`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `reason?` | `any` |

###### Returns

`Promise`<`void`>

###### Inherited from

[`ReadableStreamGenericReader`](#readablestreamgenericreader).[`cancel`](#cancel-6)

##### read()

> **read**(): `Promise`<[`ReadableStreamReadResult`](#readablestreamreadresult)<`R`>>

###### Returns

`Promise`<[`ReadableStreamReadResult`](#readablestreamreadresult)<`R`>>

##### releaseLock()

> **releaseLock**(): `void`

###### Returns

`void`

***

### ReadableStreamErrorCallback()

> **ReadableStreamErrorCallback**(`reason`: `any`): `void` | `PromiseLike`<`void`>

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `reason` | `any` |

#### Returns

`void` | `PromiseLike`<`void`>

***

### ReadableStreamGenericReader

#### Extended by

* [`ReadableStreamDefaultReader`](#readablestreamdefaultreader)
* [`ReadableStreamBYOBReader`](#readablestreambyobreader)

#### Properties

##### closed

> `readonly` **closed**: `Promise`<`undefined`>

#### Methods

##### cancel()

> **cancel**(`reason?`: `any`): `Promise`<`void`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `reason?` | `any` |

###### Returns

`Promise`<`void`>

***

### ReadableStreamGetReaderOptions

#### Properties

##### mode?

> `optional` **mode**: `"byob"`

Creates a ReadableStreamBYOBReader and locks the stream to the new reader.

This call behaves the same way as the no-argument variant, except that it only works on readable byte streams, i.e. streams which were constructed specifically with the ability to handle "bring your own buffer" reading. The returned BYOB reader provides the ability to directly read individual chunks from the stream via its read() method, into developer-supplied buffers, allowing more precise control over allocation.

***

### ReadableStreamReadDoneResult

#### Type Parameters

| Type Parameter |
| ------ |
| `T` |

#### Properties

##### done

> **done**: `true`

##### value?

> `optional` **value**: `T`

***

### ReadableStreamReadValueResult

#### Type Parameters

| Type Parameter |
| ------ |
| `T` |

#### Properties

##### done

> **done**: `false`

##### value

> **value**: `T`

***

### ReadableWritablePair

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `R` | `any` |
| `W` | `any` |

#### Properties

##### readable

> **readable**: [`ReadableStream`](#readablestream)<`R`>

##### writable

> **writable**: [`WritableStream`](#writablestream)<`W`>

Provides a convenient, chainable way of piping this readable stream
through a transform stream (or any other { writable, readable }
pair). It simply pipes the stream into the writable side of the
supplied pair, and returns the readable side for further use.

Piping a stream will lock it for the duration of the pipe, preventing
any other consumer from acquiring a reader.

***

### StreamPipeOptions

#### Properties

##### preventAbort?

> `optional` **preventAbort**: `boolean`

##### preventCancel?

> `optional` **preventCancel**: `boolean`

##### preventClose?

> `optional` **preventClose**: `boolean`

Pipes this readable stream to a given writable stream destination.
The way in which the piping process behaves under various error
conditions can be customized with a number of passed options. It
returns a promise that fulfills when the piping process completes
successfully, or rejects if any errors were encountered.

Piping a stream will lock it for the duration of the pipe, preventing
any other consumer from acquiring a reader.

Errors and closures of the source and destination streams propagate
as follows:

An error in this source readable stream will abort destination,
unless preventAbort is truthy. The returned promise will be rejected
with the source's error, or with any error that occurs during
aborting the destination.

An error in destination will cancel this source readable stream,
unless preventCancel is truthy. The returned promise will be rejected
with the destination's error, or with any error that occurs during
canceling the source.

When this source readable stream closes, destination will be closed,
unless preventClose is truthy. The returned promise will be fulfilled
once this process completes, unless an error is encountered while
closing the destination, in which case it will be rejected with that
error.

If destination starts out closed or closing, this source readable
stream will be canceled, unless preventCancel is true. The returned
promise will be rejected with an error indicating piping to a closed
stream failed, or with any error that occurs during canceling the
source.

The signal option can be set to an AbortSignal to allow aborting an
ongoing pipe operation via the corresponding AbortController. In this
case, this source readable stream will be canceled, and destination
aborted, unless the respective options preventCancel or preventAbort
are set.

##### signal?

> `optional` **signal**: [`AbortSignal`](../../../abort.md#abortsignal)

***

### UnderlyingByteSource

#### Properties

##### autoAllocateChunkSize?

> `optional` **autoAllocateChunkSize**: `number`

##### cancel?

> `optional` **cancel**: [`ReadableStreamErrorCallback`](#readablestreamerrorcallback)

##### pull?

> `optional` **pull**: [`ReadableByteStreamControllerCallback`](#readablebytestreamcontrollercallback)

##### start?

> `optional` **start**: [`ReadableByteStreamControllerCallback`](#readablebytestreamcontrollercallback)

##### type

> **type**: `"bytes"`

***

### UnderlyingSink

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `W` | `any` |

#### Properties

##### abort?

> `optional` **abort**: [`UnderlyingSinkAbortCallback`](#underlyingsinkabortcallback)

##### close?

> `optional` **close**: [`UnderlyingSinkCloseCallback`](#underlyingsinkclosecallback)

##### start?

> `optional` **start**: [`UnderlyingSinkStartCallback`](#underlyingsinkstartcallback)

##### type?

> `optional` **type**: `undefined`

##### write?

> `optional` **write**: [`UnderlyingSinkWriteCallback`](#underlyingsinkwritecallback)<`W`>

***

### UnderlyingSinkAbortCallback()

> **UnderlyingSinkAbortCallback**(`reason?`: `any`): `void` | `PromiseLike`<`void`>

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `reason?` | `any` |

#### Returns

`void` | `PromiseLike`<`void`>

***

### UnderlyingSinkCloseCallback()

> **UnderlyingSinkCloseCallback**(): `void` | `PromiseLike`<`void`>

#### Returns

`void` | `PromiseLike`<`void`>

***

### UnderlyingSinkStartCallback()

> **UnderlyingSinkStartCallback**(`controller`: [`WritableStreamDefaultController`](#writablestreamdefaultcontroller)): `any`

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `controller` | [`WritableStreamDefaultController`](#writablestreamdefaultcontroller) |

#### Returns

`any`

***

### UnderlyingSinkWriteCallback()

#### Type Parameters

| Type Parameter |
| ------ |
| `W` |

> **UnderlyingSinkWriteCallback**(`chunk`: `W`, `controller`: [`WritableStreamDefaultController`](#writablestreamdefaultcontroller)): `void` | `PromiseLike`<`void`>

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `chunk` | `W` |
| `controller` | [`WritableStreamDefaultController`](#writablestreamdefaultcontroller) |

#### Returns

`void` | `PromiseLike`<`void`>

***

### UnderlyingSource

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `R` | `any` |

#### Properties

##### cancel?

> `optional` **cancel**: [`UnderlyingSourceCancelCallback`](#underlyingsourcecancelcallback)

##### pull?

> `optional` **pull**: [`UnderlyingSourcePullCallback`](#underlyingsourcepullcallback)<`R`>

##### start?

> `optional` **start**: [`UnderlyingSourceStartCallback`](#underlyingsourcestartcallback)<`R`>

##### type?

> `optional` **type**: `undefined`

***

### UnderlyingSourceCancelCallback()

> **UnderlyingSourceCancelCallback**(`reason?`: `any`): `void` | `PromiseLike`<`void`>

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `reason?` | `any` |

#### Returns

`void` | `PromiseLike`<`void`>

***

### UnderlyingSourcePullCallback()

#### Type Parameters

| Type Parameter |
| ------ |
| `R` |

> **UnderlyingSourcePullCallback**(`controller`: [`ReadableStreamController`](#readablestreamcontroller)<`R`>): `void` | `PromiseLike`<`void`>

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `controller` | [`ReadableStreamController`](#readablestreamcontroller)<`R`> |

#### Returns

`void` | `PromiseLike`<`void`>

***

### UnderlyingSourceStartCallback()

#### Type Parameters

| Type Parameter |
| ------ |
| `R` |

> **UnderlyingSourceStartCallback**(`controller`: [`ReadableStreamController`](#readablestreamcontroller)<`R`>): `any`

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `controller` | [`ReadableStreamController`](#readablestreamcontroller)<`R`> |

#### Returns

`any`

***

### WritableStream

This Streams API interface provides a standard abstraction for writing
streaming data to a destination, known as a sink. This object comes with
built-in back pressure and queuing.

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `W` | `any` |

#### Properties

##### locked

> `readonly` **locked**: `boolean`

#### Methods

##### abort()

> **abort**(`reason?`: `any`): `Promise`<`void`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `reason?` | `any` |

###### Returns

`Promise`<`void`>

##### close()

> **close**(): `Promise`<`void`>

###### Returns

`Promise`<`void`>

##### getWriter()

> **getWriter**(): [`WritableStreamDefaultWriter`](#writablestreamdefaultwriter)<`W`>

###### Returns

[`WritableStreamDefaultWriter`](#writablestreamdefaultwriter)<`W`>

***

### WritableStreamDefaultController

This Streams API interface represents a controller allowing control of a
WritableStream's state. When constructing a WritableStream, the
underlying sink is given a corresponding WritableStreamDefaultController
instance to manipulate.

#### Methods

##### error()

> **error**(`e?`: `any`): `void`

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `e?` | `any` |

###### Returns

`void`

***

### WritableStreamDefaultWriter

This Streams API interface is the object returned by
WritableStream.getWriter() and once created locks the < writer to the
WritableStream ensuring that no other streams can write to the underlying
sink.

#### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `W` | `any` |

#### Properties

##### closed

> `readonly` **closed**: `Promise`<`undefined`>

##### desiredSize

> `readonly` **desiredSize**: `number` | `null`

##### ready

> `readonly` **ready**: `Promise`<`undefined`>

#### Methods

##### abort()

> **abort**(`reason?`: `any`): `Promise`<`void`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `reason?` | `any` |

###### Returns

`Promise`<`void`>

##### close()

> **close**(): `Promise`<`void`>

###### Returns

`Promise`<`void`>

##### releaseLock()

> **releaseLock**(): `void`

###### Returns

`void`

##### write()

> **write**(`chunk?`: `W`): `Promise`<`void`>

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `chunk?` | `W` |

###### Returns

`Promise`<`void`>

## Type Aliases

### ReadableStreamController

> **ReadableStreamController**<`T`> = [`ReadableStreamDefaultController`](#readablestreamdefaultcontroller)<`T`>

#### Type Parameters

| Type Parameter |
| ------ |
| `T` |

***

### ReadableStreamReader

> **ReadableStreamReader**<`T`> = [`ReadableStreamDefaultReader`](#readablestreamdefaultreader)<`T`> | [`ReadableStreamBYOBReader`](#readablestreambyobreader)

#### Type Parameters

| Type Parameter |
| ------ |
| `T` |

***

### ReadableStreamReaderMode

> **ReadableStreamReaderMode** = `"byob"`

***

### ReadableStreamReadResult

> **ReadableStreamReadResult**<`T`> = [`ReadableStreamReadValueResult`](#readablestreamreadvalueresult)<`T`> | [`ReadableStreamReadDoneResult`](#readablestreamreaddoneresult)<`T`>

#### Type Parameters

| Type Parameter |
| ------ |
| `T` |

## Variables

### ByteLengthQueuingStrategy

> **ByteLengthQueuingStrategy**: {(`init`: [`QueuingStrategyInit`](#queuingstrategyinit)): [`ByteLengthQueuingStrategy`](#bytelengthqueuingstrategy); `prototype`: [`ByteLengthQueuingStrategy`](#bytelengthqueuingstrategy); }

#### Type Declaration

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `init` | [`QueuingStrategyInit`](#queuingstrategyinit) |

#### Returns

[`ByteLengthQueuingStrategy`](#bytelengthqueuingstrategy)

##### prototype

> **prototype**: [`ByteLengthQueuingStrategy`](#bytelengthqueuingstrategy)

***

### CountQueuingStrategy

> **CountQueuingStrategy**: {(`init`: [`QueuingStrategyInit`](#queuingstrategyinit)): [`CountQueuingStrategy`](#countqueuingstrategy); `prototype`: [`CountQueuingStrategy`](#countqueuingstrategy); }

#### Type Declaration

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `init` | [`QueuingStrategyInit`](#queuingstrategyinit) |

#### Returns

[`CountQueuingStrategy`](#countqueuingstrategy)

##### prototype

> **prototype**: [`CountQueuingStrategy`](#countqueuingstrategy)

***

### ReadableByteStreamController

> **ReadableByteStreamController**: {(): [`ReadableByteStreamController`](#readablebytestreamcontroller); `prototype`: [`ReadableByteStreamController`](#readablebytestreamcontroller); }

#### Type Declaration

#### Returns

[`ReadableByteStreamController`](#readablebytestreamcontroller)

##### prototype

> **prototype**: [`ReadableByteStreamController`](#readablebytestreamcontroller)

***

### ReadableStream

> **ReadableStream**: {(`underlyingSource`: [`UnderlyingByteSource`](#underlyingbytesource), `strategy?`: [`QueuingStrategy`](#queuingstrategy)<`Uint8Array`>): [`ReadableStream`](#readablestream)<`Uint8Array`>; <`R`>(`underlyingSource?`: [`UnderlyingSource`](#underlyingsource)<`R`>, `strategy?`: [`QueuingStrategy`](#queuingstrategy)<`R`>): [`ReadableStream`](#readablestream)<`R`>; `prototype`: [`ReadableStream`](#readablestream); `from`: [`ReadableStream`](#readablestream)<`T`>; }

#### Type Declaration

#### Call Signature

> **new ReadableStream**(`underlyingSource`: [`UnderlyingByteSource`](#underlyingbytesource), `strategy?`: [`QueuingStrategy`](#queuingstrategy)<`Uint8Array`>): [`ReadableStream`](#readablestream)<`Uint8Array`>

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `underlyingSource` | [`UnderlyingByteSource`](#underlyingbytesource) |
| `strategy?` | [`QueuingStrategy`](#queuingstrategy)<`Uint8Array`> |

##### Returns

[`ReadableStream`](#readablestream)<`Uint8Array`>

#### Call Signature

> **new ReadableStream**<`R`>(`underlyingSource?`: [`UnderlyingSource`](#underlyingsource)<`R`>, `strategy?`: [`QueuingStrategy`](#queuingstrategy)<`R`>): [`ReadableStream`](#readablestream)<`R`>

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `underlyingSource?` | [`UnderlyingSource`](#underlyingsource)<`R`> |
| `strategy?` | [`QueuingStrategy`](#queuingstrategy)<`R`> |

##### Returns

[`ReadableStream`](#readablestream)<`R`>

##### prototype

> **prototype**: [`ReadableStream`](#readablestream)

##### from()

> **from**<`T`>(`iterable`: `Iterable`<`T`, `any`, `any`> | `AsyncIterable`<`T`, `any`, `any`>): [`ReadableStream`](#readablestream)<`T`>

###### Type Parameters

| Type Parameter |
| ------ |
| `T` |

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `iterable` | `Iterable`<`T`, `any`, `any`> | `AsyncIterable`<`T`, `any`, `any`> |

###### Returns

[`ReadableStream`](#readablestream)<`T`>

***

### ReadableStreamBYOBReader

> **ReadableStreamBYOBReader**: {(`stream`: [`ReadableStream`](#readablestream)): [`ReadableStreamBYOBReader`](#readablestreambyobreader); `prototype`: [`ReadableStreamBYOBReader`](#readablestreambyobreader); }

#### Type Declaration

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `stream` | [`ReadableStream`](#readablestream) |

#### Returns

[`ReadableStreamBYOBReader`](#readablestreambyobreader)

##### prototype

> **prototype**: [`ReadableStreamBYOBReader`](#readablestreambyobreader)

***

### ReadableStreamBYOBRequest

> **ReadableStreamBYOBRequest**: {(): [`ReadableStreamBYOBRequest`](#readablestreambyobrequest); `prototype`: [`ReadableStreamBYOBRequest`](#readablestreambyobrequest); }

#### Type Declaration

#### Returns

[`ReadableStreamBYOBRequest`](#readablestreambyobrequest)

##### prototype

> **prototype**: [`ReadableStreamBYOBRequest`](#readablestreambyobrequest)

***

### ReadableStreamDefaultController

> **ReadableStreamDefaultController**: {(): [`ReadableStreamDefaultController`](#readablestreamdefaultcontroller); `prototype`: [`ReadableStreamDefaultController`](#readablestreamdefaultcontroller); }

#### Type Declaration

#### Returns

[`ReadableStreamDefaultController`](#readablestreamdefaultcontroller)

##### prototype

> **prototype**: [`ReadableStreamDefaultController`](#readablestreamdefaultcontroller)

***

### ReadableStreamDefaultReader

> **ReadableStreamDefaultReader**: {<`R`>(`stream`: [`ReadableStream`](#readablestream)<`R`>): [`ReadableStreamDefaultReader`](#readablestreamdefaultreader)<`R`>; `prototype`: [`ReadableStreamDefaultReader`](#readablestreamdefaultreader); }

#### Type Declaration

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `stream` | [`ReadableStream`](#readablestream)<`R`> |

#### Returns

[`ReadableStreamDefaultReader`](#readablestreamdefaultreader)<`R`>

##### prototype

> **prototype**: [`ReadableStreamDefaultReader`](#readablestreamdefaultreader)

***

### WritableStream

> **WritableStream**: {<`W`>(`underlyingSink?`: [`UnderlyingSink`](#underlyingsink)<`W`>, `strategy?`: [`QueuingStrategy`](#queuingstrategy)<`W`>): [`WritableStream`](#writablestream)<`W`>; `prototype`: [`WritableStream`](#writablestream); }

#### Type Declaration

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `underlyingSink?` | [`UnderlyingSink`](#underlyingsink)<`W`> |
| `strategy?` | [`QueuingStrategy`](#queuingstrategy)<`W`> |

#### Returns

[`WritableStream`](#writablestream)<`W`>

##### prototype

> **prototype**: [`WritableStream`](#writablestream)

***

### WritableStreamDefaultController

> **WritableStreamDefaultController**: {(): [`WritableStreamDefaultController`](#writablestreamdefaultcontroller); `prototype`: [`WritableStreamDefaultController`](#writablestreamdefaultcontroller); }

#### Type Declaration

#### Returns

[`WritableStreamDefaultController`](#writablestreamdefaultcontroller)

##### prototype

> **prototype**: [`WritableStreamDefaultController`](#writablestreamdefaultcontroller)

***

### WritableStreamDefaultWriter

> **WritableStreamDefaultWriter**: {<`W`>(`stream`: [`WritableStream`](#writablestream)<`W`>): [`WritableStreamDefaultWriter`](#writablestreamdefaultwriter)<`W`>; `prototype`: [`WritableStreamDefaultWriter`](#writablestreamdefaultwriter); }

#### Type Declaration

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `stream` | [`WritableStream`](#writablestream)<`W`> |

#### Returns

[`WritableStreamDefaultWriter`](#writablestreamdefaultwriter)<`W`>

##### prototype

> **prototype**: [`WritableStreamDefaultWriter`](#writablestreamdefaultwriter)

---

---
url: /plugins/guides/store.md
---
# Submit to Store

If you want to share your plugin package with the Caido community, the best way is to submit it to the official list of plugin packages.

Once we've reviewed and published your plugin package, users will be able to install it directly from within Caido.

The submission process is done once. Once your plugin package has been accepted, you'll be able to release new versions of it by creating new releases in your repository.

## Prerequisites

Before submitting your plugin package to the store, make sure you have followed the [Setting Up Your Repository](/plugins/guides/repository) guide.

By this point, you should have a repository with a [Github release](https://docs.github.com/en/repositories/releasing-projects-on-github/about-releases) of your plugin package.

## 1. Submit Your Plugin for Review

The official list of plugin packages can be found in the `plugin_packages.json` file in the [caido/store](https://github.com/caido/store) repository.

In order to submit your plugin package, you need to update the `plugin_packages.json` file via a [pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests).

1. Visit [plugin\_packages.json](https://github.com/caido/store/edit/main/plugin_packages.json) to edit the file.

2. Add a new entry at the end of the JSON array. **Remember to add a comma after the closing brace `}` of the previous entry otherwise the json will not be valid.** Visit the [reference](/plugins/reference/plugin_packages) page for more information on each field.

   ```json
   {
     "id": "my-unique-plugin",
     "name": "My Unique Plugin",
     "license": "MIT",
     "description": "This my super cool new Caido plugin",
     "author": {
       "name": "John Doe",
       "email": "john@example.com",
       "url": "https://example.com"
     },
     "public_key": "MCowBQYDK2VwAyEA0zDx1tIO7S/d+AYFjLLmTA6pvuEyf+70KfcgVi1DNhc=",
     "repository": "john/my-unique-plugin"
   }
   ```

3. Select `Commit changes...` in the upper-right corner.

4. Select `Propose changes`.

5. Name your pull request `Add <YOUR PLUGIN PACKAGE NAME>`

6. Fill in the details in the description for the pull request. For the checkboxes, insert an x between the brackets, `[x]`, to mark them as done.

7. Click `Create pull request`.

You've now submitted your plugin package to the Caido store. Our bot will verify that the format is correct and you will have to sign the [Contributor License Agreement](https://cla-assistant.io/caido/store).
Once your submission is ready for review, you can sit back and wait for the Caido team to review it.

## 2. Address Review Comments

Once a Caido team member has reviewed your plugin, they will add a comment to your pull request with the result of the review. The reviewer may ask that you update your plugin, or they can offer suggestions on how you can improve it.

Address any required changes and update the GitHub release with the new changes. Leave a comment on the PR to let us know you've addressed the feedback.

We will publish the plugin as soon we have verified that all required changes have been addressed.

## What's next?

Once your plugin is published, it is time to announce it to the community! ✨

* Announce it in the Plugin `#discussion` channel on [Discord](https://links.caido.io/www-discord).

---

---
url: /plugins/guides/application_events.md
---
# Subscribe to Application Events

You can subscribe to various application events to react to state changes in Caido, such as project selection, workflow lifecycle, replay session changes, and backend plugin events.

::: tip
Application events enable reactive programming patterns. Use them to keep your plugin's state synchronized with Caido's state.
:::

## Subscribing to Backend Plugin Events

To listen for events sent from your backend plugin:

```ts
sdk.backend.onEvent("my-event", (data) => {
  console.log("Received event:", data);
});
```

::: info
For more details on backend events, see [Sending Events to the Frontend](/plugins/guides/events.md).
:::

::: warning
Be careful not to create infinite loops when reacting to events. For example, updating workflow state in a workflow update handler could trigger another update event.
:::

## Subscribing to Project Events

### Project Selection Changes

To listen for when the current project changes:

```ts
const handler = sdk.projects.onCurrentProjectChange((event) => {
  console.log("Project changed to:", event.projectId);
});

// Later, stop listening
handler.stop();
```

::: info
All event subscription methods return a `ListenerHandle` with a `stop()` method. Call `stop()` when your plugin is unloaded to prevent memory leaks.
:::

## Subscribing to Workflow Events

### Workflow Created

```ts
const handler = sdk.workflows.onCreatedWorkflow((workflow) => {
  console.log("Workflow created:", workflow.name);
});
```

### Workflow Updated

```ts
const handler = sdk.workflows.onUpdatedWorkflow((workflow) => {
  console.log("Workflow updated:", workflow.name);
});
```

### Workflow Deleted

```ts
const handler = sdk.workflows.onDeletedWorkflow((workflowId) => {
  console.log("Workflow deleted:", workflowId);
});
```

::: info
For more details on workflow events, see [How to Interact with Workflows](/plugins/guides/workflows.md).
:::

## Subscribing to Replay Session Events

### Current Session Changes

To listen for when the current replay session changes:

```ts
const handler = sdk.replay.onCurrentSessionChange((event) => {
  console.log("Session changed to:", event.sessionId);
});
```

::: info
For more details on replay events, see [How to Manage Replay Sessions and Collections](/plugins/guides/replay.md).
:::

## Subscribing to Navigation Events

### Page Changes

To listen for page navigation changes:

```ts
const handler = sdk.navigation.onPageChange((event) => {
  console.log("Page changed to:", event.routeId);
});
```

::: info
For more details on navigation events, see [How to Listen to Page Navigation Changes](/plugins/guides/navigation_events.md).
:::

## Examples

### Project-Specific Configuration

This example manages project-specific configuration by listening to project change events. When switching projects, it cleans up resources from the previous project and loads configuration for the new project.

```ts
import type { Caido } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  let currentProjectId: string | undefined;

  sdk.projects.onCurrentProjectChange((event) => {
    const previousProject = currentProjectId;
    currentProjectId = event.projectId;

    // Clean up previous project
    if (previousProject) {
      sdk.log.info(`Leaving project: ${previousProject}`);
      // Clean up project-specific resources
    }

    // Initialize new project
    if (currentProjectId) {
      sdk.log.info(`Entering project: ${currentProjectId}`);
      // Load project-specific configuration
      loadProjectConfig(currentProjectId);
    }
  });

  const loadProjectConfig = (projectId: string) => {
    // Load configuration specific to this project
    sdk.log.info(`Loading config for project: ${projectId}`);
  };
};
```

### Workflow Automation

This example reacts to workflow lifecycle events to trigger automation or notifications. It logs when workflows are created, updated, or deleted, and can perform actions like updating related UI or cleaning up resources.

```ts
import type { Caido } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  // React to workflow changes
  sdk.workflows.onCreatedWorkflow((workflow) => {
    sdk.log.info(`New workflow created: ${workflow.name}`);
    // Trigger automation or notifications
  });

  sdk.workflows.onUpdatedWorkflow((workflow) => {
    sdk.log.info(`Workflow updated: ${workflow.name}`);
    // Update related UI or data
  });

  sdk.workflows.onDeletedWorkflow((workflowId) => {
    sdk.log.info(`Workflow deleted: ${workflowId}`);
    // Clean up related resources
  });
};
```

---

---
url: /plugins/concepts/tooling.md
---
# Tooling for Plugin Development

While plugins can be developed with raw JavaScript - Caido offers **plugin starterkits**, preassembled packages that also provide tooling to assist in development.

The frontend starterkit can be found [here](https://github.com/caido/starterkit-plugin-frontend).

## Package Management

Caido utilizes the [Performant Node Package Manager(a.k.a. pnpm)](https://pnpm.io/) for plugin package management. You have a couple choices of package management (*npm, yarn, pnpm, etc.*) - we chose pnpm. Plugins do not have dependencies, they are self contained. The Javascript dependencies are bundled into them.

The files related to package management within the starterkit repository are:

* `package.json`: This is the main configuration file for the package as a whole - it contains the project metadata and specifies the required dependencies to be used at runtime/build time. *View the [pnpm package.json](https://pnpm.io/package_json) documentation for more information.*
* `pnpm-lock.yaml`: This file ensures the same versions of dependencies are installed with every installation. *View the [pnpm-lock.yaml](https://pnpm.io/git#lockfiles) documentation for more information.*

## TypeScript

Externally, [TypeScript](https://docs.caido.io/app/concepts/workflows_js#typing) is used by Caido for the starterkit package.

The file related to TypeScript within the starterkit repository is:

* `tsconfig.json`: This file provides instructions to the compiler when TypeScript is converted to JS. *View the <https://www.typescriptlang.org/docs/handbook/tsconfig-json.html> documentation for more information.*

## Build Tool

Once the package is developed, the code is processed by the [Vite](https://vitejs.dev/guide/) build tool. In general, a build tool automates the process of compiling, testing and packaging code into a deployable package - ensuring the plugin is ready for use and sharing.

The file related to the Vite build tool within the starterkit repository is:

* `vite.config.ts`: This file is a configuration file for customizing the build process. *View the [vite.config.js](https://v2.vitejs.dev/config/) documentation for more information.*

---

---
url: /plugins/tutorials.md
---
# Tutorials

This section of the documentation is dedicated to providing step-by-step tutorials for developers to get started with Caido.

If you are new to plugin development, the tutorials here will give you a feel for what it's like to build plugins for Caido.

## Example Plugins

* [Notebook](/plugins/tutorials/notebook.md): A simple notebook plugin for in-app note taking.

---

---
url: /plugins/reference/sdks/frontend/ui.md
---
# UI

### UISDK

> **UISDK** = `object`

Utilities to create UI components.

#### Properties

##### button()

> **button**: (`options?`: `object`) => `HTMLElement`

Create a button.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options?` | { `label?`: `string`; `leadingIcon?`: [`Icon`](utils.md#icon); `size?`: `"small"` | `"medium"` | `"large"`; `trailingIcon?`: [`Icon`](utils.md#icon); `variant?`: `"primary"` | `"secondary"` | `"tertiary"`; } | Options for the button. |
| `options.label?` | `string` | The label of the button. |
| `options.leadingIcon?` | [`Icon`](utils.md#icon) | The leading icon of the button. |
| `options.size?` | `"small"` | `"medium"` | `"large"` | The size of the button. |
| `options.trailingIcon?` | [`Icon`](utils.md#icon) | The trailing icon of the button. |
| `options.variant?` | `"primary"` | `"secondary"` | `"tertiary"` | The variant of the button. |

###### Returns

`HTMLElement`

The button element.

###### Example

```ts
const deleteButton = sdk.ui.button({
  variant: "primary",
  label: "Delete",
  trailingIcon: "fas fa-trash-can",
  size: "small",
});
```

##### card()

> **card**: (`options?`: `object`) => `HTMLElement`

Create a card.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options?` | { `body?`: `HTMLElement`; `footer?`: `HTMLElement`; `header?`: `HTMLElement`; } | Options for the card. |
| `options.body?` | `HTMLElement` | The body of the card. |
| `options.footer?` | `HTMLElement` | The footer of the card. |
| `options.header?` | `HTMLElement` | The header of the card. |

###### Returns

`HTMLElement`

The card element.

##### httpRequestEditor()

> **httpRequestEditor**: () => [`HTTPRequestEditor`](editor.md#httprequesteditor)

Create an HTTP request editor

###### Returns

[`HTTPRequestEditor`](editor.md#httprequesteditor)

The HTTP request editor.

##### httpResponseEditor()

> **httpResponseEditor**: () => [`HTTPResponseEditor`](editor.md#httpresponseeditor)

Create an HTTP response editor

###### Returns

[`HTTPResponseEditor`](editor.md#httpresponseeditor)

The HTTP response editor.

##### well()

> **well**: (`options?`: `object`) => `HTMLElement`

Create a well.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `options?` | { `body?`: `HTMLElement`; `footer?`: `HTMLElement`; `header?`: `HTMLElement`; } | Options for the well. |
| `options.body?` | `HTMLElement` | The body of the well. |
| `options.footer?` | `HTMLElement` | The footer of the well. |
| `options.header?` | `HTMLElement` | The header of the well. |

###### Returns

`HTMLElement`

The well element.

---

---
url: /plugins/concepts/ui.md
---
# UI Styling

When using the Caido [community plugin template](https://github.com/caido-community/create-plugin), you have the option to customize the user-interface.

For this, Caido uses the following dependencies:

* [Vue.js](https://vuejs.org/): A JavaScript framework for building user-interfaces.
* [PrimeVue](https://primevue.org/): A library for Vue.js that provides a wide range of pre-built UI components.
* [TailWind CSS](https://tailwindcss.com/): A CSS framework that allows applications to be styled using predefined utility classes.

The `@caido/primevue` and `@caido/tailwindcss` packages are custom adaptations that are configured to align with the theme of the Caido application.

The `tailwindcss-primeui` package acts as a bridge, allowing PrimeVue components to be styled using Tailwind CSS.

Within the `tailwind.config.ts` file, both the `tailwindPrimeui` and `tailwindCaido` plugins are imported to inject the necessary classes.

By leveraging these technologies and creating relationships between them, we are able to customize and maintain consistency in the appearance of the frontend component of Caido plugins.

## What's next?

[Learn how to use the PrimeVue library to build a plugin frontend.](/plugins/guides/styling.md)

---

---
url: /plugins/reference/modules/llrt/url/url.md
---
[@caido/quickjs-types](../../index.md) / [llrt/url](index.md) / url

# url

## Classes

### URL

Browser-compatible `URL` class, implemented by following the WHATWG URL
Standard. [Examples of parsed URLs](https://url.spec.whatwg.org/#example-url-parsing) may be found in the Standard itself.
The `URL` class is also available on the global object.

In accordance with browser conventions, all properties of `URL` objects
are implemented as getters and setters on the class prototype, rather than as
data properties on the object itself. Thus, unlike `legacy urlObject`s,
using the `delete` keyword on any properties of `URL` objects (e.g. `delete myURL.protocol`, `delete myURL.pathname`, etc) has no effect but will still
return `true`.

#### Extended by

* [`URL`](index.md#url-1)

#### Constructors

##### Constructor

> **new URL**(`input`: `string` | { `toString`: () => `string`; }, `base?`: `string` | [`URL`](#url)): [`URL`](#url)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `input` | `string` | { `toString`: () => `string`; } |
| `base?` | `string` | [`URL`](#url) |

###### Returns

[`URL`](#url)

#### Properties

##### hash

> **hash**: `string`

Gets and sets the fragment portion of the URL.

```js
const myURL = new URL('https://example.org/foo#bar');
console.log(myURL.hash);
// Prints #bar

myURL.hash = 'baz';
console.log(myURL.href);
// Prints https://example.org/foo#baz
```

Invalid URL characters included in the value assigned to the `hash` property
are `percent-encoded`. The selection of which characters to
percent-encode may vary somewhat from what the [parse](#parse-2) and [format](#format) methods would produce.

##### host

> **host**: `string`

Gets and sets the host portion of the URL.

```js
const myURL = new URL('https://example.org:81/foo');
console.log(myURL.host);
// Prints example.org:81

myURL.host = 'example.com:82';
console.log(myURL.href);
// Prints https://example.com:82/foo
```

Invalid host values assigned to the `host` property are ignored.

##### hostname

> **hostname**: `string`

Gets and sets the host name portion of the URL. The key difference between`url.host` and `url.hostname` is that `url.hostname` does *not* include the
port.

```js
const myURL = new URL('https://example.org:81/foo');
console.log(myURL.hostname);
// Prints example.org

// Setting the hostname does not change the port
myURL.hostname = 'example.com';
console.log(myURL.href);
// Prints https://example.com:81/foo

// Use myURL.host to change the hostname and port
myURL.host = 'example.org:82';
console.log(myURL.href);
// Prints https://example.org:82/foo
```

Invalid host name values assigned to the `hostname` property are ignored.

##### href

> **href**: `string`

Gets and sets the serialized URL.

```js
const myURL = new URL('https://example.org/foo');
console.log(myURL.href);
// Prints https://example.org/foo

myURL.href = 'https://example.com/bar';
console.log(myURL.href);
// Prints https://example.com/bar
```

Getting the value of the `href` property is equivalent to calling [toString](#tostring).

Setting the value of this property to a new value is equivalent to creating a
new `URL` object using `new URL(value)`. Each of the `URL` object's properties will be modified.

If the value assigned to the `href` property is not a valid URL, a `TypeError` will be thrown.

##### origin

> `readonly` **origin**: `string`

Gets the read-only serialization of the URL's origin.

```js
const myURL = new URL('https://example.org/foo/bar?baz');
console.log(myURL.origin);
// Prints https://example.org
```

```js
const idnURL = new URL('https://測試');
console.log(idnURL.origin);
// Prints https://xn--g6w251d

console.log(idnURL.hostname);
// Prints xn--g6w251d
```

##### password

> **password**: `string`

Gets and sets the password portion of the URL.

```js
const myURL = new URL('https://abc:xyz@example.com');
console.log(myURL.password);
// Prints xyz

myURL.password = '123';
console.log(myURL.href);
// Prints https://abc:123@example.com/
```

Invalid URL characters included in the value assigned to the `password` property
are `percent-encoded`. The selection of which characters to
percent-encode may vary somewhat from what the [parse](#parse-2) and [format](#format) methods would produce.

##### pathname

> **pathname**: `string`

Gets and sets the path portion of the URL.

```js
const myURL = new URL('https://example.org/abc/xyz?123');
console.log(myURL.pathname);
// Prints /abc/xyz

myURL.pathname = '/abcdef';
console.log(myURL.href);
// Prints https://example.org/abcdef?123
```

Invalid URL characters included in the value assigned to the `pathname` property are `percent-encoded`. The selection of which characters
to percent-encode may vary somewhat from what the [parse](#parse-2) and [format](#format) methods would produce.

##### port

> **port**: `string`

Gets and sets the port portion of the URL.

The port value may be a number or a string containing a number in the range `0` to `65535` (inclusive). Setting the value to the default port of the `URL` objects given `protocol` will
result in the `port` value becoming
the empty string (`''`).

The port value can be an empty string in which case the port depends on
the protocol/scheme.

Upon assigning a value to the port, the value will first be converted to a
string using `.toString()`.

If that string is invalid but it begins with a number, the leading number is
assigned to `port`.
If the number lies outside the range denoted above, it is ignored.

```js
const myURL = new URL('https://example.org:8888');
console.log(myURL.port);
// Prints 8888

// Default ports are automatically transformed to the empty string
// (HTTPS protocol's default port is 443)
myURL.port = '443';
console.log(myURL.port);
// Prints the empty string
console.log(myURL.href);
// Prints https://example.org/

myURL.port = 1234;
console.log(myURL.port);
// Prints 1234
console.log(myURL.href);
// Prints https://example.org:1234/

// Completely invalid port strings are ignored
myURL.port = 'abcd';
console.log(myURL.port);
// Prints 1234

// Leading numbers are treated as a port number
myURL.port = '5678abcd';
console.log(myURL.port);
// Prints 5678

// Non-integers are truncated
myURL.port = 1234.5678;
console.log(myURL.port);
// Prints 1234

// Out-of-range numbers which are not represented in scientific notation
// will be ignored.
myURL.port = 1e10; // 10000000000, will be range-checked as described below
console.log(myURL.port);
// Prints 1234
```

Numbers which contain a decimal point,
such as floating-point numbers or numbers in scientific notation,
are not an exception to this rule.
Leading numbers up to the decimal point will be set as the URL's port,
assuming they are valid:

```js
myURL.port = 4.567e21;
console.log(myURL.port);
// Prints 4 (because it is the leading number in the string '4.567e21')
```

##### protocol

> **protocol**: `string`

Gets and sets the protocol portion of the URL.

```js
const myURL = new URL('https://example.org');
console.log(myURL.protocol);
// Prints https:

myURL.protocol = 'ftp';
console.log(myURL.href);
// Prints ftp://example.org/
```

Invalid URL protocol values assigned to the `protocol` property are ignored.

##### search

> **search**: `string`

Gets and sets the serialized query portion of the URL.

```js
const myURL = new URL('https://example.org/abc?123');
console.log(myURL.search);
// Prints ?123

myURL.search = 'abc=xyz';
console.log(myURL.href);
// Prints https://example.org/abc?abc=xyz
```

Any invalid URL characters appearing in the value assigned the `search` property will be `percent-encoded`. The selection of which
characters to percent-encode may vary somewhat from what the [parse](#parse-2) and [format](#format) methods would produce.

##### searchParams

> `readonly` **searchParams**: [`URLSearchParams`](#urlsearchparams-1)

Gets the `URLSearchParams` object representing the query parameters of the
URL. This property is read-only but the `URLSearchParams` object it provides
can be used to mutate the URL instance; to replace the entirety of query
parameters of the URL, use the [search](#search) setter. See `URLSearchParams` documentation for details.

Use care when using `.searchParams` to modify the `URL` because,
per the WHATWG specification, the `URLSearchParams` object uses
different rules to determine which characters to percent-encode. For
instance, the `URL` object will not percent encode the ASCII tilde (`~`)
character, while `URLSearchParams` will always encode it:

```js
const myURL = new URL('https://example.org/abc?foo=~bar');

console.log(myURL.search);  // prints ?foo=~bar

// Modify the URL via searchParams...
myURL.searchParams.sort();

console.log(myURL.search);  // prints ?foo=%7Ebar
```

##### username

> **username**: `string`

Gets and sets the username portion of the URL.

```js
const myURL = new URL('https://abc:xyz@example.com');
console.log(myURL.username);
// Prints abc

myURL.username = '123';
console.log(myURL.href);
// Prints https://123:xyz@example.com/
```

Any invalid URL characters appearing in the value assigned the `username` property will be `percent-encoded`. The selection of which
characters to percent-encode may vary somewhat from what the [parse](#parse-2) and [format](#format) methods would produce.

#### Methods

##### toJSON()

> **toJSON**(): `string`

The `toJSON()` method on the `URL` object returns the serialized URL. The
value returned is equivalent to that of [href](#href) and [toString](#tostring).

This method is automatically called when an `URL` object is serialized
with [`JSON.stringify()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify).

```js
const myURLs = [
  new URL('https://www.example.com'),
  new URL('https://test.example.org'),
];
console.log(JSON.stringify(myURLs));
// Prints ["https://www.example.com/","https://test.example.org/"]
```

###### Returns

`string`

##### toString()

> **toString**(): `string`

The `toString()` method on the `URL` object returns the serialized URL. The
value returned is equivalent to that of [href](#href) and [toJSON](#tojson).

###### Returns

`string`

##### canParse()

> `static` **canParse**(`input`: `string`, `base?`: `string`): `boolean`

Checks if an `input` relative to the `base` can be parsed to a `URL`.

```js
const isValid = URL.canParse('/foo', 'https://example.org/'); // true

const isNotValid = URL.canParse('/foo'); // false
```

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `input` | `string` | The absolute or relative input URL to parse. If `input` is relative, then `base` is required. If `input` is absolute, the `base` is ignored. If `input` is not a string, it is `converted to a string` first. |
| `base?` | `string` | The base URL to resolve against if the `input` is not absolute. If `base` is not a string, it is `converted to a string` first. |

###### Returns

`boolean`

##### parse()

> `static` **parse**(`input`: `string`, `base?`: `string`): [`URL`](#url) | `null`

Parses a string as a URL. If `base` is provided, it will be used as the base URL for the purpose of resolving non-absolute `input` URLs.
Returns `null` if `input` is not a valid.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `input` | `string` | The absolute or relative input URL to parse. If `input` is relative, then `base` is required. If `input` is absolute, the `base` is ignored. If `input` is not a string, it is `converted to a string` first. |
| `base?` | `string` | The base URL to resolve against if the `input` is not absolute. If `base` is not a string, it is `converted to a string` first. |

###### Returns

[`URL`](#url) | `null`

***

### URLSearchParams

The `URLSearchParams` API provides read and write access to the query of a `URL`. The `URLSearchParams` class can also be used standalone with one of the
four following constructors.
The `URLSearchParams` class is also available on the global object.

The WHATWG `URLSearchParams` interface and the `querystring` module have
similar purpose, but the purpose of the `querystring` module is more
general, as it allows the customization of delimiter characters (`&#x26;` and `=`).
On the other hand, this API is designed purely for URL query strings.

```js
const myURL = new URL('https://example.org/?abc=123');
console.log(myURL.searchParams.get('abc'));
// Prints 123

myURL.searchParams.append('abc', 'xyz');
console.log(myURL.href);
// Prints https://example.org/?abc=123&#x26;abc=xyz

myURL.searchParams.delete('abc');
myURL.searchParams.set('a', 'b');
console.log(myURL.href);
// Prints https://example.org/?a=b

const newSearchParams = new URLSearchParams(myURL.searchParams);
// The above is equivalent to
// const newSearchParams = new URLSearchParams(myURL.search);

newSearchParams.append('a', 'c');
console.log(myURL.href);
// Prints https://example.org/?a=b
console.log(newSearchParams.toString());
// Prints a=b&#x26;a=c

// newSearchParams.toString() is implicitly called
myURL.search = newSearchParams;
console.log(myURL.href);
// Prints https://example.org/?a=b&#x26;a=c
newSearchParams.delete('a');
console.log(myURL.href);
// Prints https://example.org/?a=b&#x26;a=c
```

#### Extended by

* [`URLSearchParams`](index.md#urlsearchparams-2)

#### Implements

* `Iterable`<\[`string`, `string`]>

#### Constructors

##### Constructor

> **new URLSearchParams**(`init?`: `string` | `Iterable`<\[`string`, `string`], `any`, `any`> | [`URLSearchParams`](#urlsearchparams-1) | `Record`<`string`, `string` | readonly `string`\[]> | readonly \[`string`, `string`]\[]): [`URLSearchParams`](#urlsearchparams-1)

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `init?` | `string` | `Iterable`<\[`string`, `string`], `any`, `any`> | [`URLSearchParams`](#urlsearchparams-1) | `Record`<`string`, `string` | readonly `string`\[]> | readonly \[`string`, `string`]\[] |

###### Returns

[`URLSearchParams`](#urlsearchparams-1)

#### Methods

##### \[iterator]\()

> **\[iterator]**(): `IterableIterator`<\[`string`, `string`]>

###### Returns

`IterableIterator`<\[`string`, `string`]>

###### Implementation of

`Iterable.[iterator]`

##### append()

> **append**(`name`: `string`, `value`: `string`): `void`

Append a new name-value pair to the query string.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |
| `value` | `string` |

###### Returns

`void`

##### delete()

> **delete**(`name`: `string`, `value?`: `string`): `void`

If `value` is provided, removes all name-value pairs
where name is `name` and value is `value`.

If `value` is not provided, removes all name-value pairs whose name is `name`.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |
| `value?` | `string` |

###### Returns

`void`

##### entries()

> **entries**(): `IterableIterator`<\[`string`, `string`]>

Returns an ES6 `Iterator` over each of the name-value pairs in the query.
Each item of the iterator is a JavaScript `Array`. The first item of the `Array` is the `name`, the second item of the `Array` is the `value`.

Alias for `urlSearchParams[@@iterator]()`.

###### Returns

`IterableIterator`<\[`string`, `string`]>

##### forEach()

> **forEach**<`TThis`>(`fn`: (`this`: `TThis`, `value`: `string`, `name`: `string`, `searchParams`: [`URLSearchParams`](#urlsearchparams-1)) => `void`, `thisArg?`: `TThis`): `void`

Iterates over each name-value pair in the query and invokes the given function.

```js
const myURL = new URL('https://example.org/?a=b&#x26;c=d');
myURL.searchParams.forEach((value, name, searchParams) => {
  console.log(name, value, myURL.searchParams === searchParams);
});
// Prints:
//   a b true
//   c d true
```

###### Type Parameters

| Type Parameter | Default type |
| ------ | ------ |
| `TThis` | [`URLSearchParams`](#urlsearchparams-1) |

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `fn` | (`this`: `TThis`, `value`: `string`, `name`: `string`, `searchParams`: [`URLSearchParams`](#urlsearchparams-1)) => `void` | Invoked for each name-value pair in the query |
| `thisArg?` | `TThis` | To be used as `this` value for when `fn` is called |

###### Returns

`void`

##### get()

> **get**(`name`: `string`): `string` | `null`

Returns the value of the first name-value pair whose name is `name`. If there
are no such pairs, `null` is returned.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |

###### Returns

`string` | `null`

or `null` if there is no name-value pair with the given `name`.

##### has()

> **has**(`name`: `string`, `value?`: `string`): `boolean`

Checks if the `URLSearchParams` object contains key-value pair(s) based on `name` and an optional `value` argument.

If `value` is provided, returns `true` when name-value pair with
same `name` and `value` exists.

If `value` is not provided, returns `true` if there is at least one name-value
pair whose name is `name`.

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |
| `value?` | `string` |

###### Returns

`boolean`

##### keys()

> **keys**(): `IterableIterator`<`string`>

Returns an ES6 `Iterator` over the names of each name-value pair.

```js
const params = new URLSearchParams('foo=bar&#x26;foo=baz');
for (const name of params.keys()) {
  console.log(name);
}
// Prints:
//   foo
//   foo
```

###### Returns

`IterableIterator`<`string`>

##### set()

> **set**(`name`: `string`, `value`: `string`): `void`

Sets the value in the `URLSearchParams` object associated with `name` to `value`. If there are any pre-existing name-value pairs whose names are `name`,
set the first such pair's value to `value` and remove all others. If not,
append the name-value pair to the query string.

```js
const params = new URLSearchParams();
params.append('foo', 'bar');
params.append('foo', 'baz');
params.append('abc', 'def');
console.log(params.toString());
// Prints foo=bar&#x26;foo=baz&#x26;abc=def

params.set('foo', 'def');
params.set('xyz', 'opq');
console.log(params.toString());
// Prints foo=def&#x26;abc=def&#x26;xyz=opq
```

###### Parameters

| Parameter | Type |
| ------ | ------ |
| `name` | `string` |
| `value` | `string` |

###### Returns

`void`

##### sort()

> **sort**(): `void`

Sort all existing name-value pairs in-place by their names. Sorting is done
with a [stable sorting algorithm](https://en.wikipedia.org/wiki/Sorting_algorithm#Stability), so relative order between name-value pairs
with the same name is preserved.

This method can be used, in particular, to increase cache hits.

```js
const params = new URLSearchParams('query[]=abc&#x26;type=search&#x26;query[]=123');
params.sort();
console.log(params.toString());
// Prints query%5B%5D=abc&#x26;query%5B%5D=123&#x26;type=search
```

###### Returns

`void`

##### toString()

> **toString**(): `string`

Returns the search parameters serialized as a string, with characters
percent-encoded where necessary.

###### Returns

`string`

##### values()

> **values**(): `IterableIterator`<`string`>

Returns an ES6 `Iterator` over the values of each name-value pair.

###### Returns

`IterableIterator`<`string`>

## Interfaces

### Url

#### Properties

##### auth

> **auth**: `string` | `null`

##### hash

> **hash**: `string` | `null`

##### host

> **host**: `string` | `null`

##### hostname

> **hostname**: `string` | `null`

##### href

> **href**: `string`

##### path

> **path**: `string` | `null`

##### pathname

> **pathname**: `string` | `null`

##### port

> **port**: `string` | `null`

##### protocol

> **protocol**: `string` | `null`

##### query

> **query**: `string` | `null`

##### search

> **search**: `string` | `null`

##### slashes

> **slashes**: `boolean` | `null`

***

### URLFormatOptions

#### Properties

##### auth?

> `optional` **auth**: `boolean`

`true` if the serialized URL string should include the username and password, `false` otherwise.

###### Default

```ts
true
```

##### fragment?

> `optional` **fragment**: `boolean`

`true` if the serialized URL string should include the fragment, `false` otherwise.

###### Default

```ts
true
```

##### search?

> `optional` **search**: `boolean`

`true` if the serialized URL string should include the search query, `false` otherwise.

###### Default

```ts
true
```

##### unicode?

> `optional` **unicode**: `boolean`

`true` if Unicode characters appearing in the host component of the URL string should be encoded directly as opposed to
being Punycode encoded.

###### Default

```ts
false
```

## Functions

### domainToASCII()

> **domainToASCII**(`domain`: `string`): `string`

Returns the [Punycode](https://tools.ietf.org/html/rfc5891#section-4.4) ASCII serialization of the `domain`. If `domain` is an
invalid domain, the empty string is returned.

It performs the inverse operation to [domainToUnicode](#domaintounicode).

```js
import url from 'url';

console.log(url.domainToASCII('español.com'));
// Prints xn--espaol-zwa.com
console.log(url.domainToASCII('中文.com'));
// Prints xn--fiq228c.com
console.log(url.domainToASCII('xn--iñvalid.com'));
// Prints an empty string
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `domain` | `string` |

#### Returns

`string`

***

### domainToUnicode()

> **domainToUnicode**(`domain`: `string`): `string`

Returns the Unicode serialization of the `domain`. If `domain` is an invalid
domain, the empty string is returned.

It performs the inverse operation to [domainToASCII](#domaintoascii).

```js
import url from 'url';

console.log(url.domainToUnicode('xn--espaol-zwa.com'));
// Prints español.com
console.log(url.domainToUnicode('xn--fiq228c.com'));
// Prints 中文.com
console.log(url.domainToUnicode('xn--iñvalid.com'));
// Prints an empty string
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `domain` | `string` |

#### Returns

`string`

***

### fileURLToPath()

> **fileURLToPath**(`url`: `string` | [`URL`](#url)): `string`

This function ensures the correct decodings of percent-encoded characters as
well as ensuring a cross-platform valid absolute path string.

```js
import { fileURLToPath } from 'url';

const __filename = fileURLToPath(import.meta.url);

new URL('file:///C:/path/').pathname;      // Incorrect: /C:/path/
fileURLToPath('file:///C:/path/');         // Correct:   C:\path\ (Windows)

new URL('file://nas/foo.txt').pathname;    // Incorrect: /foo.txt
fileURLToPath('file://nas/foo.txt');       // Correct:   \\nas\foo.txt (Windows)

new URL('file:///你好.txt').pathname;      // Incorrect: /%E4%BD%A0%E5%A5%BD.txt
fileURLToPath('file:///你好.txt');         // Correct:   /你好.txt (POSIX)

new URL('file:///hello world').pathname;   // Incorrect: /hello%20world
fileURLToPath('file:///hello world');      // Correct:   /hello world (POSIX)
```

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `url` | `string` | [`URL`](#url) | The file URL string or URL object to convert to a path. |

#### Returns

`string`

The fully-resolved platform-specific Node.js file path.

***

### format()

> **format**(`urlObject`: [`URL`](#url), `options?`: [`URLFormatOptions`](#urlformatoptions)): `string`

The `url.format()` method returns a formatted URL string derived from `urlObject`.

```js
const url = require('url');
url.format({
  protocol: 'https',
  hostname: 'example.com',
  pathname: '/some/path',
  query: {
    page: 1,
    format: 'json',
  },
});

// => 'https://example.com/some/path?page=1&#x26;format=json'
```

If `urlObject` is not an object or a string, `url.format()` will throw a `TypeError`.

The formatting process operates as follows:

* A new empty string `result` is created.
* If `urlObject.protocol` is a string, it is appended as-is to `result`.
* Otherwise, if `urlObject.protocol` is not `undefined` and is not a string, an `Error` is thrown.
* For all string values of `urlObject.protocol` that *do not end* with an ASCII
  colon (`:`) character, the literal string `:` will be appended to `result`.
* If either of the following conditions is true, then the literal string `//` will be appended to `result`:
  * `urlObject.slashes` property is true;
  * `urlObject.protocol` begins with `http`, `https`, `ftp`, `gopher`, or `file`;
* If the value of the `urlObject.auth` property is truthy, and either `urlObject.host` or `urlObject.hostname` are not `undefined`, the value of `urlObject.auth` will be coerced into a string
  and appended to `result` followed by the literal string `@`.
* If the `urlObject.host` property is `undefined` then:
  * If the `urlObject.hostname` is a string, it is appended to `result`.
  * Otherwise, if `urlObject.hostname` is not `undefined` and is not a string,
    an `Error` is thrown.
  * If the `urlObject.port` property value is truthy, and `urlObject.hostname` is not `undefined`:
    \* The literal string `:` is appended to `result`, and
    \* The value of `urlObject.port` is coerced to a string and appended to `result`.
* Otherwise, if the `urlObject.host` property value is truthy, the value of `urlObject.host` is coerced to a string and appended to `result`.
* If the `urlObject.pathname` property is a string that is not an empty string:
  * If the `urlObject.pathname` *does not start* with an ASCII forward slash
    (`/`), then the literal string `'/'` is appended to `result`.
  * The value of `urlObject.pathname` is appended to `result`.
* Otherwise, if `urlObject.pathname` is not `undefined` and is not a string, an `Error` is thrown.
* If the `urlObject.search` property is `undefined` and if the `urlObject.query`property is an `Object`, the literal string `?` is appended to `result` followed by the output of calling the
  `querystring` module's `stringify()` method passing the value of `urlObject.query`.
* Otherwise, if `urlObject.search` is a string:
  * If the value of `urlObject.search` *does not start* with the ASCII question
    mark (`?`) character, the literal string `?` is appended to `result`.
  * The value of `urlObject.search` is appended to `result`.
* Otherwise, if `urlObject.search` is not `undefined` and is not a string, an `Error` is thrown.
* If the `urlObject.hash` property is a string:
  * If the value of `urlObject.hash` *does not start* with the ASCII hash (`#`)
    character, the literal string `#` is appended to `result`.
  * The value of `urlObject.hash` is appended to `result`.
* Otherwise, if the `urlObject.hash` property is not `undefined` and is not a
  string, an `Error` is thrown.
* `result` is returned.

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `urlObject` | [`URL`](#url) | A URL object (as returned by `url.parse()` or constructed otherwise). If a string, it is converted to an object by passing it to `url.parse()`. |
| `options?` | [`URLFormatOptions`](#urlformatoptions) | - |

#### Returns

`string`

#### Legacy

Use the WHATWG URL API instead.

***

### ~~parse()~~

> **parse**(`urlString`: `string`, `parseQueryString?`: `boolean`, `slashesDenoteHost?`: `boolean`): [`Url`](#url-1)

The `url.parse()` method takes a URL string, parses it, and returns a URL
object.

A `TypeError` is thrown if `urlString` is not a string.

A `URIError` is thrown if the `auth` property is present but cannot be decoded.

`url.parse()` uses a lenient, non-standard algorithm for parsing URL
strings. It is prone to security issues such as [host name spoofing](https://hackerone.com/reports/678487) and incorrect handling of usernames and passwords. Do not use with untrusted
input. CVEs are not issued for `url.parse()` vulnerabilities. Use the `WHATWG URL` API instead.

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `urlString` | `string` | The URL string to parse. |
| `parseQueryString?` | `boolean` | If `true`, the `query` property will always be set to an object returned by the querystring module's `parse()` method. If `false`, the `query` property on the returned URL object will be an unparsed, undecoded string. |
| `slashesDenoteHost?` | `boolean` | If `true`, the first token after the literal string `//` and preceding the next `/` will be interpreted as the `host`. For instance, given `//foo/bar`, the result would be `{host: 'foo', pathname: '/bar'}` rather than `{pathname: '//foo/bar'}`. |

#### Returns

[`Url`](#url-1)

#### Deprecated

Use the WHATWG URL API instead.

***

### pathToFileURL()

> **pathToFileURL**(`path`: `string`): [`URL`](#url)

This function ensures that `path` is resolved absolutely, and that the URL
control characters are correctly encoded when converting into a File URL.

```js
import { pathToFileURL } from 'url';

new URL('/foo#1', 'file:');           // Incorrect: file:///foo#1
pathToFileURL('/foo#1');              // Correct:   file:///foo%231 (POSIX)

new URL('/some/path%.c', 'file:');    // Incorrect: file:///some/path%.c
pathToFileURL('/some/path%.c');       // Correct:   file:///some/path%25.c (POSIX)
```

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `path` | `string` | The path to convert to a File URL. |

#### Returns

[`URL`](#url)

The file URL object.

***

### urlToHttpOptions()

> **urlToHttpOptions**(`url`: [`URL`](#url)): `Object`

This utility function converts a URL object into an ordinary options object as
expected by the `http.request()` and `https.request()` APIs.

```js
import { urlToHttpOptions } from 'url';
const myURL = new URL('https://a:b@測試?abc#foo');

console.log(urlToHttpOptions(myURL));
/*
{
  protocol: 'https:',
  hostname: 'xn--g6w251d',
  hash: '#foo',
  search: '?abc',
  pathname: '/',
  path: '/?abc',
  href: 'https://a:b@xn--g6w251d/?abc#foo',
  auth: 'a:b'
}

```

#### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `url` | [`URL`](#url) | The `WHATWG URL` object to convert to an options object. |

#### Returns

`Object`

Options object

---

---
url: /client-sdk/guides/spec_typing.md
---
# Use a Plugin's NPM Spec Package

Some plugins publish a small npm package containing the TypeScript types for their backend functions and events. When you install that spec package and pass it as a generic to the Client SDK, you get fully typed function calls, autocomplete on method names, typed event payloads, and zero hand-written type definitions.

This is the recommended way to call a plugin from a script when a spec package is available. For plugins that do not publish a spec, fall back to the explicit forms shown in [Call a Plugin Function](./call_function.md) and [Receive Plugin Events](./receive_events.md).

::: info
A runnable version of this guide lives in the SDK repository at [`examples/functionCallSpec`](https://github.com/caido/sdk-js/tree/main/packages/sdk-client/examples/functionCallSpec). Spec packages live under the [`@caido-community`](https://www.npmjs.com/org/caido-community) npm scope. Their source code is in the plugin's repository under [caido-community](https://github.com/caido-community), usually inside a `packages/shared` folder.
:::

## Install the Spec Package

To get typed access to a plugin, install its spec package. The convention is `@caido-community/<plugin-manifest-id>`. For example, the spec for the `quickssrf` plugin is published as `@caido-community/quickssrf`:

::: code-group

```bash [pnpm]
pnpm add @caido-community/quickssrf
```

```bash [npm]
npm install @caido-community/quickssrf
```

```bash [yarn]
yarn add @caido-community/quickssrf
```

:::

## Pass the Spec to the Client

To enable typed access, import the `Spec` type from the package and pass it as a generic to `client.plugin.pluginPackage()` (or `client.plugin.install()`):

```ts
import { Client } from "@caido/sdk-client";
import type { Spec as QuickSSRFSpec } from "@caido-community/quickssrf";

const client = new Client({ url: "http://localhost:8080" });
await client.connect();

const pkg = await client.plugin.pluginPackage<QuickSSRFSpec>("quickssrf");
if (pkg === undefined) {
  throw new Error("quickssrf is not installed");
}
```

From this point, every function and event exposed by the plugin is typed on the `pkg` handle.

## Call Typed Functions

To call a function, access it directly on the `pkg` handle as if it were a local method. The SDK proxies the call to the backend and returns a properly typed promise:

```ts
const providers = await pkg.getProviders();
// providers is typed as Result<Provider[]>

if (providers.kind === "Error") {
  throw new Error(providers.error);
}

const session = await pkg.createSession(providers.value[0].id);
// session is typed as Result<Session>
```

A few things that change compared to the explicit `callFunction()` form:

* **Autocomplete** lists every function declared in the spec (`getProviders`, `createSession`, `addProvider`, etc.) as you type `pkg.`
* **Argument types** are checked at compile time. Passing the wrong number or shape of arguments is a TypeScript error before you ever run the script.
* **Return types** flow through automatically. No need to specify a generic on each call.

::: info
Under the hood, the typed methods still call the same backend endpoint as `callFunction()`. The spec adds type information at compile time without changing what happens at runtime.
:::

## Receive Typed Events

Event subscriptions also benefit from the spec. Event names are autocompleted from the spec's `events` map, and the destructured payload is fully typed:

```ts
for await (const [event] of pkg.subscribeEvent("interaction:received")) {
  // event is typed as { sessionId: string; interactions: Interaction[] }
  if (event.sessionId !== session.value.id) continue;
  for (const interaction of event.interactions) {
    console.log(interaction);
  }
}
```

For more on event subscriptions (including multi-backend disambiguation and stopping a subscription), see [Receive Plugin Events](./receive_events.md). The mechanics are identical; the spec only adds types.

## When No Spec Package Exists

Not every plugin publishes a spec package. When one is not available, use the explicit forms instead:

* [Call a Plugin Function](./call_function.md) for `pkg.callFunction<T>({ name, arguments })`
* [Receive Plugin Events](./receive_events.md) for `pkg.subscribeEvent("name")` with manually cast payloads

You can still get the function and event names from the plugin's backend source code (look for `sdk.api.register(...)` and `sdk.api.send(...)` calls in its [caido-community](https://github.com/caido-community) repository).

## Examples

The script below uses the `@caido-community/quickssrf` spec to call functions and receive events with full type safety.

### index.ts

```ts
import { Client } from "@caido/sdk-client";
import type { Spec as QuickSSRFSpec } from "@caido-community/quickssrf";

async function main() {
  const client = new Client({
    url: process.env["CAIDO_INSTANCE_URL"] ?? "http://localhost:8080",
    auth: {
      pat: process.env["CAIDO_PAT"]!,
      cache: { file: ".caido-token.json" },
    },
  });

  await client.connect();

  const pkg = await client.plugin.pluginPackage<QuickSSRFSpec>("quickssrf");
  if (pkg === undefined) {
    throw new Error("quickssrf is not installed");
  }

  const providers = await pkg.getProviders();
  if (providers.kind === "Error") {
    throw new Error(`getProviders failed: ${providers.error}`);
  }

  const session = await pkg.createSession(providers.value[0]!.id);
  if (session.kind === "Error") {
    throw new Error(`createSession failed: ${session.error}`);
  }

  console.log("Listening for interactions on", session.value.url);

  for await (const [event] of pkg.subscribeEvent("interaction:received")) {
    if (event.sessionId !== session.value.id) continue;
    for (const interaction of event.interactions) {
      console.log("Interaction received:", interaction);
    }
  }
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});
```

Run it with:

```bash
export CAIDO_PAT=caido_xxxxx
npx tsx ./index.ts
```

Then trigger the SSRF URL printed at the start (for example, `curl <url>`) to see typed interactions arrive on the subscription.

---

---
url: /plugins/guides/ai.md
---
# Use AI in Your Plugin

You can integrate AI capabilities into your plugin using Caido's AI provider, which is compatible with the [ai](https://ai-sdk.dev/) library.

## Creating an AI Provider

To create an AI provider instance:

```ts
const provider = sdk.ai.createProvider();
```

This returns an `AIProvider` instance that can be used with the `ai` library.

## Getting Upstream Providers

To get information about available AI upstream providers and their configuration status:

```ts
const providers = sdk.ai.getUpstreamProviders();
```

This returns an array of `AIUpstreamProvider` objects, each containing:

* `id` - The provider ID (`"openai"`, `"anthropic"`, `"google"`, or `"openrouter"`)
* `status` - The configuration status (`"Ready"` or `"Missing"`)

This is useful for checking which AI providers are configured before attempting to use them:

```ts
const providers = sdk.ai.getUpstreamProviders();
const openaiProvider = providers.find((p) => p.id === "openai");

if (openaiProvider?.status === "Ready") {
  // OpenAI is configured and ready to use
  const provider = sdk.ai.createProvider();
  // Use the provider...
} else {
  sdk.window.showToast("OpenAI is not configured", { variant: "warning" });
}
```

::: tip
The AI provider is compatible with all features of the `ai` library, including text generation, streaming, tool calling, and more. Refer to the [ai SDK documentation](https://ai-sdk.dev/) for advanced usage.
:::

::: info
The AI provider uses Caido's configured AI settings. Users can configure their AI provider preferences in Caido's settings.
:::

::: warning
AI operations can be resource-intensive and may have rate limits. Consider implementing error handling and user feedback for long-running AI operations.
:::

## Examples

### Basic AI Integration

This example demonstrates the basic setup for using AI in your plugin. It creates an AI provider, uses it with the `ai` library to generate text from a prompt, and logs the response.

First, install the `ai` package:

```bash
npm install ai
```

Then use the provider in your plugin:

```ts
import type { Caido } from "@caido/sdk-frontend";
import { generateText } from "ai";

export type CaidoSDK = Caido;

export const init = async (sdk: CaidoSDK) => {
  const provider = sdk.ai.createProvider();

  // Use with the ai library
  const { text } = await generateText({
    model: provider,
    prompt: "Explain what HTTP is in one sentence.",
  });

  sdk.log.info("AI Response:", text);
};
```

### AI-Powered Code Generation

This example registers a command that uses AI to generate Caido plugin code based on a user's description. The command prompts for a description, generates code using AI, and logs the result.

```ts
import type { Caido } from "@caido/sdk-frontend";
import { generateText } from "ai";

export type CaidoSDK = Caido;

const generateCode = async (sdk: CaidoSDK, description: string): Promise<string> => {
  const provider = sdk.ai.createProvider();

  const { text } = await generateText({
    model: provider,
    prompt: `Generate a Caido plugin code snippet that: ${description}`,
  });

  return text;
};

export const init = (sdk: CaidoSDK) => {
  sdk.commands.register("ai-generate-code", {
    name: "AI: Generate Code",
    run: async () => {
      const description = prompt("What should the code do?");
      if (description) {
        const code = await generateCode(sdk, description);
        sdk.window.showToast("Code generated! Check console.", { variant: "success" });
        sdk.log.info("Generated code:", code);
      }
    },
  });

  sdk.commandPalette.register("ai-generate-code");
};
```

---

---
url: /plugins/guides/env.md
---
# Use Environment Variables

You may want to allow users to use environment variables set via the `Environment` page in your Caido plugin.

## Getting the Value: Frontend Call to Backend Function

::: info
[Learn more on how to create custom backend functions.](/plugins/guides/rpc.md)
:::

To securely access environment variables in Caido, the `sdk.env.getVar()` method can be used:

### /packages/backend/src/index.ts

```ts
import type { DefineAPI, SDK } from "caido:plugin";

export type API = DefineAPI<{
  getSession: () => Promise<string | undefined>;
}>;

export function init(sdk: SDK<API>) {
  // Register an API endpoint that frontend can call.
  sdk.api.register("getSession", async () => {
    return sdk.env.getVar("User A");
  });
}
```

### /packages/frontend/src/index.ts

```ts
const button = document.createElement("button");
button.textContent = "Check for Env Variable";
button.classList.add("bg-blue-500", "text-white", "p-2", "rounded");
button.addEventListener("click", async () => {
  const apiKey = await sdk.backend.getSession();
  // Display the message as text.
  statusText.textContent = apiKey ? "SESSION FOUND" : "NO SESSION SET";
});
```

## Getting the Value: Frontend Call

The method is also available to the frontend directly.

### /packages/frontend/src/index.ts

```ts
const button = document.createElement("button");
button.textContent = "Check for Env Variable";
button.classList.add("bg-blue-500", "text-white", "p-2", "rounded");
button.addEventListener("click", () => {
  const value = sdk.env.getVar("User A");
  statusText.textContent = value ? "SESSION FOUND" : "NO SESSION SET";
  });
```

## The Result

---

---
url: /plugins/guides/findings.md
---
# Use Findings

Any requests or responses can be parsed for notable characteristics based on conditional statements using [Findings](https://docs.caido.io/app/quickstart/findings). As Caido proxies traffic, if it detects what you are looking for, an alert will be generated to draw your attention.

## Creating Findings

To create a Finding, use `sdk.findings.create()`. The `title`, `reporter` and `request` properties are required:

```ts
await sdk.findings.create({
  title: "Title", // Label your Finding.
  description: "Description", // Add a description (optional).
  reporter: "Reporter", // Specify which plugin discovered the Finding.
  dedupeKey: `${request.getHost()}-${request.getPath()}`, // Prevents multiple alerts for request with matching characteristics (optional).
  request, // The associated request.
});
```

::: tip
The `dedupeKey` can be any value, including [request](/plugins/reference/sdks/backend/#request) or [response](/plugins/reference/sdks/backend/#response-3) object properties (*besides the body element*). If the value is detected a second time, the Finding will be considered a duplicate and an alert will not be generated.

```ts
// Dedupe based on a string.
dedupeKey: "Hello world!"
// Dedupe based on request path and method.
dedupeKey: `${request.getPath()}-${request.getMethod()}`
// Dedupe based on request path, response code and response header.
dedupeKey: `${request.getPath()}-${response.getCode()}-${response.getHeader("Content-Length")}`
```

:::

## Conditional Findings

You can then set conditions that must be met such as only creating a Finding if the request recieved a 200 response:

```ts
import type { DefineAPI, SDK } from "caido:plugin";
import type { Request, Response } from "caido:utils";

export type API = DefineAPI<{
  // No API methods needed for this passive functionality.
}>;

export function init(sdk: SDK<API>) {
  // Listen for intercepted responses.
  sdk.events.onInterceptResponse(
    async (
      sdk: SDK<API>, 
      request: Request, 
      response: Response
    ) => {
    try {
      // Only create Findings for 200 responses.
      if (response.getCode() === 200) {
        const dedupeKey = `${request.getPath()}-${response.getCode()}`;
        
        // Check if Finding already exists.
        const exists = await sdk.findings.exists(dedupeKey);
        if (!exists) {
          await sdk.findings.create({
            title: `Success Response ${response.getCode()}`,
            description: `Request ID: ${request.getId()}\nResponse Code: ${response.getCode()}`,
            reporter: "Response Logger Plugin",
            request: request,
            dedupeKey
          });

          // Verify the Finding was created.
          const created = await sdk.findings.exists(dedupeKey);
          if (created) {
            sdk.console.log(`Created and verified finding for request ${request.getId()}.`);
          }
        } else {
          sdk.console.log(`Finding already exists for ${dedupeKey}.`);
        }
      }
    } catch (err) {
      sdk.console.error(`Error handling finding: ${err}`);
    }
  });
}
```

## The Result

---

---
url: /plugins/guides/filters.md
---
# Use HTTPQL Queries

HTTPQL is Caido's query language for filtering HTTP requests. You can programmatically create, manage, and apply filters, as well as set HTTPQL queries on pages like HTTP History and Search.

## Managing Saved Filters

### Creating a Filter

To create a saved filter:

```ts
const filter = await sdk.filters.create({
  name: "My Filter",
  alias: "my-filter",
  query: "resp.code.eq:200",
});
```

* `name` - The display name of the filter
* `alias` - A short identifier used in HTTPQL queries (e.g., `preset:my-filter`)
* `query` - The HTTPQL query expression

::: tip
Use saved filters to create reusable query presets that can be referenced with the `preset:` prefix in HTTPQL queries.
:::

### Getting All Filters

To retrieve all saved filters:

```ts
const filters = await sdk.filters.getAll();
```

### Updating a Filter

To update an existing filter:

```ts
const updatedFilter = await sdk.filters.update(filterId, {
  name: "Updated Filter Name",
  query: "resp.code.eq:200 AND req.method.eq:\"GET\"",
});
```

### Deleting a Filter

To delete a filter:

```ts
await sdk.filters.delete(filterId);
```

### Getting the Current Filter

To get the currently selected filter:

```ts
const currentFilter = sdk.filters.getCurrentFilter();
```

Returns the currently selected filter, or `undefined` if no filter is selected.

### Subscribing to Filter Changes

To subscribe to changes in the currently selected filter:

```ts
const handler = sdk.filters.onCurrentFilterChange((event) => {
  console.log(`Filter ${event.filterId} got selected!`);
});

// Later, stop listening
handler.stop();
```

The callback receives an event object with a `filterId` property that contains the ID of the newly selected filter, or `undefined` if no filter is selected.

::: info
The subscription handler returns an object with a `stop()` method that can be called to unsubscribe from filter changes.
:::

## Adding Components to Filter Slots

You can add custom components to filter slots to extend the Filters page UI. Available slots are:

* `FilterSlot.CreateHeader` - The header area of the preset form create component
* `FilterSlot.UpdateHeader` - The header area of the preset form update component

### Adding a Button to a Slot

Add a button with a label, icon, and click handler:

```ts
import { FilterSlot } from "@caido/sdk-frontend";

sdk.filters.addToSlot(FilterSlot.UpdateHeader, {
  type: "Button",
  label: "My Button",
  icon: "my-icon",
  onClick: () => {
    console.log("Button clicked");
  },
});
```

### Adding a Command to a Slot

Add a button that triggers a registered command:

```ts
import { FilterSlot } from "@caido/sdk-frontend";

// First register the command
sdk.commands.register("my-command", {
  name: "My Command",
  run: () => {
    sdk.window.showToast("Command executed", { variant: "info" });
  },
});

// Then add to slot
sdk.filters.addToSlot(FilterSlot.UpdateHeader, {
  type: "Command",
  commandId: "my-command",
  icon: "my-icon",
});
```

### Adding a Custom Component to a Slot

Add a custom Vue component:

```ts
import { FilterSlot } from "@caido/sdk-frontend";
import MyComponent from "./MyComponent.vue";

sdk.filters.addToSlot(FilterSlot.CreateHeader, {
  type: "Custom",
  definition: MyComponent,
});
```

## Setting HTTPQL Queries on Pages

### HTTP History

You can get and set the current HTTPQL query on the HTTP History page:

```ts
// Get current query
const currentQuery = sdk.httpHistory.getQuery();

// Set query
sdk.httpHistory.setQuery("resp.code.eq:200 AND req.method.eq:\"GET\"");

// Scroll to a specific request by ID
sdk.httpHistory.scrollTo(requestId);
```

::: info
The `scrollTo()` method is useful for highlighting specific requests after applying a filter, making it easier for users to find relevant results.
:::

### Search

Similarly, you can manage queries on the Search page:

```ts
// Get current query
const currentQuery = sdk.search.getQuery();

// Set query
sdk.search.setQuery("resp.code.eq:404");

// Scroll to a specific request by ID
sdk.search.scrollTo(requestId);
```

## Examples

### Dynamic Query Building

This example creates a query builder interface with input fields for status code, HTTP method, and path. It dynamically constructs HTTPQL queries from the input values and applies them to HTTP History.

```ts
import { Classic } from "@caido/primevue";
import PrimeVue from "primevue/config";
import { createApp } from "vue";

import type { Caido } from "@caido/sdk-frontend";

import App from "./views/QueryBuilder.vue";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  const app = createApp(App);
  
  app.provide("sdk", sdk);
  
  app.use(PrimeVue, {
    unstyled: true,
    pt: Classic,
  });

  const root = document.createElement("div");
  Object.assign(root.style, {
    height: "100%",
    width: "100%",
  });

  app.mount(root);

  sdk.navigation.addPage("/query-builder", {
    body: root,
  });
};
```

```vue
<script setup lang="ts">
import Button from "primevue/button";
import InputText from "primevue/inputtext";
import InputNumber from "primevue/inputnumber";
import { inject, ref } from "vue";

import type { CaidoSDK } from "../index";

const sdk = inject<CaidoSDK>("sdk");
const status = ref<number | null>(null);
const method = ref<string>("");
const path = ref<string>("");

const buildQuery = (): string => {
  const parts: string[] = [];

  if (status.value) {
    parts.push(`resp.code.eq:${status.value}`);
  }
  if (method.value) {
    parts.push(`req.method.eq:"${method.value}"`);
  }
  if (path.value) {
    parts.push(`req.path.contains:"${path.value}"`);
  }

  return parts.join(" AND ");
};

const applyFilter = () => {
  if (!sdk) return;
  const query = buildQuery();

  if (query) {
    sdk.httpHistory.setQuery(query);
    sdk.navigation.goTo({ id: "http-history" });
    sdk.window.showToast("Filter applied", { variant: "success" });
  } else {
    sdk.window.showToast("Please enter at least one filter", { variant: "warning" });
  }
};
</script>

<template>
  <div class="h-full flex flex-col p-4 gap-4">
    <div class="flex flex-col gap-2">
      <label class="text-sm font-medium">Status Code</label>
      <InputNumber v-model="status" placeholder="e.g., 200" inputClass="w-full" />
    </div>
    <div class="flex flex-col gap-2">
      <label class="text-sm font-medium">Method</label>
      <InputText v-model="method" placeholder="e.g., GET" />
    </div>
    <div class="flex flex-col gap-2">
      <label class="text-sm font-medium">Path</label>
      <InputText v-model="path" placeholder="e.g., /api" />
    </div>
    <Button label="Apply Filter" @click="applyFilter" />
  </div>
</template>
```

### Using Filter Presets

This example demonstrates creating a filter with an alias and then using that filter as a preset in HTTPQL queries. The preset can be referenced using the `preset:` prefix followed by the alias.

```ts
// Create a filter with an alias
const filter = await sdk.filters.create({
  name: "Successful GET Requests",
  alias: "success-get",
  query: "resp.code.eq:200 AND req.method.eq:\"GET\"",
});

// Use the filter in a query
sdk.httpHistory.setQuery("preset:success-get");
```

### Tracking Current Filter Changes

This example subscribes to filter selection changes and logs information about the currently selected filter whenever it changes.

```ts
import type { Caido } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  const handler = sdk.filters.onCurrentFilterChange((event) => {
    if (event.filterId) {
      const filter = sdk.filters.getCurrentFilter();
      if (filter) {
        sdk.log.info(`Filter selected: ${filter.name} (${filter.alias})`);
        sdk.log.info(`Query: ${filter.query}`);
      }
    } else {
      sdk.log.info("No filter selected");
    }
  });

  // Store handler for cleanup if needed
  // handler.stop();
};
```

### Adding Custom Actions to Filter Slots

This example adds a custom button to the filter update header that duplicates the current filter when clicked.

```ts
import type { Caido } from "@caido/sdk-frontend";
import { FilterSlot } from "@caido/sdk-frontend";

export type CaidoSDK = Caido;

export const init = (sdk: CaidoSDK) => {
  sdk.filters.addToSlot(FilterSlot.UpdateHeader, {
    type: "Button",
    label: "Duplicate Filter",
    icon: "fas fa-copy",
    onClick: async () => {
      const currentFilter = sdk.filters.getCurrentFilter();
      if (currentFilter) {
        const duplicated = await sdk.filters.create({
          name: `${currentFilter.name} (Copy)`,
          alias: `${currentFilter.alias}-copy`,
          query: currentFilter.query,
        });
        sdk.window.showToast(`Filter "${duplicated.name}" created`, {
          variant: "success",
        });
      } else {
        sdk.window.showToast("No filter selected", { variant: "warning" });
      }
    },
  });
};
```

---

---
url: /plugins/guides/utf.md
---
# Use Invalid UTF-8

::: info
For conceptual information regarding this guide - click [here](/plugins/concepts/binary.md).
:::

## Using a Mutable Proxied Request

To use invalid UTF-8 in the path of a request that passes through Caido, follow these steps:

### /packages/backend/src/index.ts

First import the `SDK`, the interface used to interact with Caido.

```ts
import { SDK } from "caido:plugin";
```

Then create a function that takes proxied requests using `onInterceptRequest` and converts them into mutable, un-saved `RequestSpec` objects using the `.toSpec()` method. Next, store the path as a byte array using the spread operator `...`, and append the desired raw byte using `[...spec.getPath({raw: true}), 0x85];`. Update the request with the modified path using `.setPath()` and send the request.

```ts
export function init(sdk: SDK) {
  sdk.events.onInterceptRequest(async (sdk, request) => {
    const spec = request.toSpec();
    let path = [...spec.getPath({raw: true}), 0x85];
    spec.setPath(path);
    await sdk.requests.send(spec);
  });
}
```

## Using a Newly Created Request

To use invalid UTF-8 in the path of a `new RequestSpecRaw()` request, follow these steps:

### /packages/backend/src/index.ts

First, import the required dependencies. `SDK` is the interface used to interact with Caido. `DefineAPI` is used to structure the API: definining what methods or endpoints are available, the parameters those methods accept and what types of values they return. `RequestSpecRaw` is an object class that is used to create a request in raw byte format.

```ts
import { RequestSpecRaw } from "caido:utils";
import { SDK, DefineAPI } from "caido:plugin";
```

Next, define a function that will convert the path string into an array of bytes.

```ts
function stringToUint8Array(str: string): Uint8Array {
  const arr = new Uint8Array(str.length);
  for (let i = 0; i < str.length; i++) {
    arr[i] = str.charCodeAt(i);
  }
  return arr;
}
```

Create an instance of the `RequestSpecRaw` class, by supplying the target URL as the constructor.

```ts
async function testSendRequest(sdk: SDK): Promise<void> {
  console.log("Testing send request");
  const req = new RequestSpecRaw("http://localhost:5555");
```

Call the `stringToUint8Array` function on the request data to convert it into a byte array. Send the request and if a response is received, print it in plaintext.

```ts
  const rawRequest = "GET /admin\x85 HTTP/1.1\r\nHost: localhost:5555\r\n\r\n";
  req.setRaw(stringToUint8Array(rawRequest));

  const res = await sdk.requests.send(req);
  console.log(res?.response.getRaw().toText());
}
```

Since we are using a button on the frontend to issue this request, define the `testSendRequest` function as an API call and register it to the backend.

```ts
export type API = DefineAPI<{
  testSendRequest: typeof testSendRequest;
}>;

export function init(sdk: SDK<API>) {
  sdk.api.register("testSendRequest", testSendRequest);
}
```

### Calling from Frontend

To call the backend function from a Vue component:

```vue
<script setup lang="ts">
import Button from "primevue/button";
import { inject } from "vue";

const sdk = inject<CaidoSDK>("sdk");

const sendRequest = async () => {
  if (!sdk) return;
  await sdk.backend.testSendRequest();
};
</script>

<template>
  <div class="p-4">
    <Button label="Send Request" @click="sendRequest" />
  </div>
</template>
```

::: info
For information on creating pages and setting up Vue components, see [Create a Page](/plugins/guides/page.md).
:::

---

---
url: /plugins/guides/styling.md
---
# Use the Component Library

Caido plugins use [PrimeVue](https://tailwind.primevue.org/) as the component library, with custom styling to match the core application’s look and feel.

You can explore our **UI Kit** at [ui-kit.caido.io](https://ui-kit.caido.io), which showcases the available styled components, their usage examples, and source code snippets.

This guide covers how to integrate these components to ensure a seamless user experience.

## Starting from the VueJS Template

When running the `pnpm create @caido-community/plugin` command to initialize a new plugin project, you are given the option to use the [Vue.js](https://vuejs.org/) framework.

When using this option, instead of building the plugin page in the frontend `index.ts` file, now the `App.vue` file is responsible for the plugin page's layout, state, and user interactions.

However, the initialization, configuration, SDK setup, routing, and registration are still handled by `index.ts`.

::: info
[Learn about the concepts behind this.](/plugins/concepts/ui.md)
:::

## Adding the Toast Component

By default, the plugin template includes the core PrimeVue `Button` and `TextInput` components which are made available globally via `app.use(PrimeView)` in the `index.ts` file.

::: tip
All of the components and configuration options offered by the PrimeVue package can be viewed by visiting their [official documentation](https://tailwind.primevue.org/vite/). You can also view them in the `~\node_modules\.pnpm\primevue@4.1.0_vue@X.X.XX_typescript@X.X.X_` directory of your project.
:::

::: warning
Caido supports PrimeVue v4.1.0. If a style is not working properly, first try downgrading the `primevue` entry in the frontend `package.json` file. If this does not resolve the issue, please [let us know](https://docs.caido.io/app/troubleshooting/report_bug.html)!
:::

If you want to add additional components, simply import them. For example, if you wanted to display [Toast](https://primevue.org/toast/) messages:

### /packages/frontend/src/views/App.vue

```ts
<script setup lang="ts">
import Button from "primevue/button";
import InputText from "primevue/inputtext";
// Import both Toast and its hook function.
import Toast from "primevue/toast";
import { useToast } from "primevue/usetoast";

import { ref } from "vue";

// Add the hook to provide the API.
const toast = useToast();

const counter = ref(0);

const onIncrementClick = () => {
  // Configure the options for the Toast message.
  toast.add({
    severity: "info",
    summary: "Info",
    detail: "Counter incremented!",
    life: 3000
  });
  counter.value++;
};
</script>

<template>
  <div class="h-full flex justify-center items-center">
    <Toast /> // Add the component.
    <div class="flex flex-col gap-1">
      <Button label="Increment counter" @click="onIncrementClick" />
      <InputText :model-value="counter" readonly />
    </div>
  </div>
</template>
```

### /packages/frontend/src/index.ts

Since Toast is not included in the core components of PrimeVue, you will also need to add to the frontend `index.ts` file:

```ts
import ToastService from "primevue/toastservice";
```

Finally, register the `ToastService` globally:

```ts
app.use(ToastService);
```

## The Result

---

---
url: /client-sdk/tutorials/autorize.md
---
# Using the Autorize API

The goal of this tutorial is to drive the [Caido Autorize](https://github.com/caido-community/autorize) plugin from an external script using the [Client SDK](https://github.com/caido/sdk-js). By the end, you will be able to install Autorize against a Caido instance, configure user profiles that mutate authorization headers, run authorization tests against requests in your proxy history, and interpret the results to determine whether endpoints enforce proper access control.

This is useful for automated authorization testing across many endpoints, regression testing after access control changes, and any workflow where you need to verify that different user roles see the correct responses without manually replaying each request through the UI.

## 1. Prerequisites

::: info Requirements

* [Node.js](https://nodejs.org/en/) 18 or higher
* A running Caido instance with an open project
* A [Personal Access Token](https://docs.caido.io/dashboard/concepts/pat.html) (PAT) for your account
* At least one request in the project's HTTP history. This tutorial uses `caido.local` as the example target, so send any request through your Caido proxy to that host before starting (or substitute your own host throughout).
  :::

## 2. Setting up the script

### Initializing the project

Create a working directory for the script and initialize it:

```bash
mkdir caido-autorize-tutorial
cd caido-autorize-tutorial
pnpm init
```

Add `"type": "module"` to `package.json` so Node treats the `.ts` file as an ES module, which the `import` statements below require.

### Installing dependencies

Install the Client SDK and the Autorize spec package. The spec package is what makes the Autorize functions and events typed when you call them through the SDK:

```bash
pnpm add @caido/sdk-client @caido-community/autorize
```

::: info
The [`@caido-community/autorize`](https://www.npmjs.com/package/@caido-community/autorize) package is the spec for the Autorize plugin. The Client SDK uses it to type the calls in this tutorial. See [Use a Plugin's NPM Spec Package](/client-sdk/guides/spec_typing.md) for the broader concept.
:::

### Setting environment variables

Export your PAT and (optionally) the instance URL:

```bash
export CAIDO_PAT=caido_xxxxx
export CAIDO_INSTANCE_URL=http://localhost:8080
```

::: warning
Never commit the PAT to source control. Treat it like a password and store it in your shell's secret manager or a `.env` file that is gitignored.
:::

## 3. Connecting and installing Autorize

Create `index.ts`. The first thing the script does is connect to the Caido instance using the PAT from the environment, then either look up or install the Autorize plugin:

### index.ts

```ts
import { Client } from "@caido/sdk-client";
import type { Spec as AutorizeSpec } from "@caido-community/autorize";

async function main() {
  const client = new Client({
    url: process.env["CAIDO_INSTANCE_URL"] ?? "http://localhost:8080",
    auth: {
      pat: process.env["CAIDO_PAT"]!,
      cache: { file: ".caido-token.json" },
    },
  });

  await client.connect();
  console.log("Connected to Caido");

  // Look up the installed plugin, install if missing
  let pkg = await client.plugin.pluginPackage<AutorizeSpec>("autorize");
  if (pkg === undefined) {
    console.log("Installing Autorize...");
    pkg = await client.plugin.install<AutorizeSpec>({ manifestId: "autorize" });
  }
  console.log("Autorize ready");
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});
```

The `AutorizeSpec` generic on `pluginPackage` and `install` is what makes the rest of the script's calls typed: `pkg.createTemplate(...)`, `pkg.getTemplate(...)`, and so on, all autocomplete with the correct argument and return types. The lookup-then-install pattern is idiomatic: `pluginPackage()` returns `undefined` when the plugin is not present, and `install()` returns a fresh handle when it is invoked.

For more on installing plugins from a script, see the [Install a Plugin](/client-sdk/guides/install_plugin.md) guide.

## 4. Configuring user profiles

Autorize works by replaying each request with different authorization credentials to see if the endpoint enforces access control. You configure this through **user profiles**, where each profile defines a set of **mutations** that transform the original request before it is replayed.

Use `pkg.updateConfig()` to add one or more profiles. Each profile needs an `id`, a `name`, an `enabled` flag, and a list of `mutations`:

```ts
const updated = await pkg.updateConfig({
  userProfiles: [
    {
      id: "low-priv",
      name: "Low-Privilege User",
      enabled: true,
      mutations: [
        {
          kind: "HeaderReplace",
          header: "Authorization",
          value: "Bearer low-priv-token-xxx",
        },
      ],
    },
  ],
});

if (updated.kind === "Error") {
  throw new Error(updated.error);
}

// Read back the config to know how many results to expect later
const cfg = await pkg.getConfig();
if (cfg.kind === "Error") throw new Error(cfg.error);
```

The available mutation kinds are:

* `HeaderAdd`, `HeaderRemove`, `HeaderReplace`: add, remove, or replace an HTTP header.
* `CookieAdd`, `CookieRemove`, `CookieReplace`: add, remove, or replace a cookie.
* `RawMatchAndReplace`: match a string (or regex with `regex: true`) in the raw request and replace it.

When Autorize tests a request, it sends one replay per enabled profile using that profile's mutations, plus a **no-auth** replay that strips the `Authorization` header entirely. The results show whether each profile can still access the endpoint.

::: info
Autorize functions return an `APIResult<T>` envelope of the form `{ kind: "Ok"; value }` or `{ kind: "Error"; error }`. Always branch on `result.kind` before using the value. This convention is shared by other community plugins like Scanner.
:::

## 5. Finding a target request

Authorization tests run against existing requests in the project's HTTP history. To get the request ID for a target, use [`client.request.list()`](/client-sdk/guides/extract_requests.md) with an [HTTPQL](https://docs.caido.io/app/reference/httpql.html) filter on the host:

```ts
const page = await client.request
  .list()
  .filter('req.host.eq:"caido.local"')
  .first(1);

const target = page.edges[0]?.node.request;
if (target === undefined) {
  throw new Error(
    "No requests to caido.local found in this project. " +
    "Send a request through the Caido proxy to that host first.",
  );
}

console.log(`Target: ${target.method} ${target.host}${target.path} (id=${target.id})`);
```

The filter syntax is the same one you use in the Caido HTTP History UI. Adjust it for your own target host.

## 6. Creating a template

A **template** represents a single authorization test. Call `pkg.createTemplate(requestId)` with the ID of the request you want to test. Autorize replays the request with each enabled profile's mutations and collects the results:

```ts
const created = await pkg.createTemplate(target.id);
if (created.kind === "Error") {
  throw new Error(created.error);
}

const templateId = created.value.id;
console.log(`Template created: id=${templateId}`);
console.log(`  ${created.value.request.method} ${created.value.request.url}`);
```

The returned `Template` includes the template `id`, a deduplication `key` derived from the request's method, host, and path, and a `results` array that fills in as Autorize processes the replays.

## 7. Waiting for results

After creating a template, Autorize processes the replays asynchronously. Poll `pkg.getTemplate(id)` until the `results` array contains all expected entries. With one enabled user profile and `testNoAuth` enabled (the default), there are three results: one baseline, one mutated, and one no-auth:

```ts
let template = created.value;
const enabledProfiles = cfg.value.userProfiles.filter((p) => p.enabled);
const expectedResults = 1 + enabledProfiles.length + (cfg.value.testNoAuth ? 1 : 0);

while (template.results.length < expectedResults) {
  await new Promise((resolve) => setTimeout(resolve, 1500));
  const got = await pkg.getTemplate(templateId);
  if (got.kind === "Error") {
    throw new Error(got.error);
  }
  template = got.value;
  console.log(`  results: ${template.results.length}/${expectedResults}`);
}
```

::: tip
For scripts that create many templates, subscribe to the `template:completed` event instead of polling. See [Receive Plugin Events](/client-sdk/guides/receive_events.md). Polling is shown here because it keeps the example self-contained.
:::

## 8. Interpreting the results

Each result in the `results` array is tagged with a `type` and a `kind`. The `type` tells you which replay produced it:

* `"baseline"`: the original request, replayed without any mutations.
* `"mutated"`: the request replayed with a user profile's mutations applied. The `userProfileId` and `userProfileName` fields identify which profile was used.
* `"no-auth"`: the request replayed with the `Authorization` header stripped.

Each mutated and no-auth result carries an `accessState` with a `kind` field:

* `"authorized"`: the endpoint returned a response similar to the baseline, indicating the low-privilege or unauthenticated user can still access it. This is the finding you care about in authorization testing.
* `"unauthorized"`: the endpoint returned a different response, indicating access was properly denied.
* `"uncertain"`: Autorize could not determine whether access was granted or denied.

```ts
for (const result of template.results) {
  if (result.kind === "Error") {
    console.log(`  ERROR: ${result.error}`);
    continue;
  }

  if (result.type === "baseline") {
    console.log(
      `  [baseline] ${result.response.code} (${result.response.length} bytes)`,
    );
  } else if (result.type === "mutated") {
    console.log(
      `  [mutated] "${result.userProfileName}" -> ${result.response.code} access=${result.accessState.kind}`,
    );
  } else if (result.type === "no-auth") {
    console.log(
      `  [no-auth] -> ${result.response.code} access=${result.accessState.kind}`,
    );
  }
}
```

## 9. Cleaning up

Templates persist in the project until they are deleted. Remove the template at the end of the script to keep the project tidy:

::: warning
The `updateConfig` call below resets `userProfiles` to an empty array. If you already have Autorize profiles configured in this project, save them with `getConfig()` before the script runs and restore them here instead.
:::

```ts
await pkg.deleteTemplate(templateId);
await pkg.updateConfig({ userProfiles: [] });
console.log("Cleaned up");
```

## Examples

The script below combines every step into a single file. It connects, ensures Autorize is installed, configures a low-privilege user profile, finds the first `caido.local` request, creates a template, waits for the results, prints them, and cleans up.

### index.ts

```ts
import { Client } from "@caido/sdk-client";
import type { Spec as AutorizeSpec } from "@caido-community/autorize";

async function main() {
  const client = new Client({
    url: process.env["CAIDO_INSTANCE_URL"] ?? "http://localhost:8080",
    auth: {
      pat: process.env["CAIDO_PAT"]!,
      cache: { file: ".caido-token.json" },
    },
  });

  await client.connect();

  // 1. Look up or install Autorize
  let pkg = await client.plugin.pluginPackage<AutorizeSpec>("autorize");
  if (pkg === undefined) {
    pkg = await client.plugin.install<AutorizeSpec>({ manifestId: "autorize" });
  }

  // 2. Configure a low-privilege user profile
  const updated = await pkg.updateConfig({
    userProfiles: [
      {
        id: "low-priv",
        name: "Low-Privilege User",
        enabled: true,
        mutations: [
          {
            kind: "HeaderReplace",
            header: "Authorization",
            value: "Bearer low-priv-token-xxx",
          },
        ],
      },
    ],
  });
  if (updated.kind === "Error") throw new Error(updated.error);

  // 3. Read back the config to know how many results to expect
  const cfg = await pkg.getConfig();
  if (cfg.kind === "Error") throw new Error(cfg.error);

  // 4. Find a target request
  const page = await client.request
    .list()
    .filter('req.host.eq:"caido.local"')
    .first(1);
  const target = page.edges[0]?.node.request;
  if (target === undefined) {
    throw new Error("Send a request to caido.local through the Caido proxy first");
  }

  // 5. Create a template (starts authorization test)
  const created = await pkg.createTemplate(target.id);
  if (created.kind === "Error") throw new Error(created.error);
  const templateId = created.value.id;
  console.log(`Template created for ${created.value.request.method} ${created.value.request.url}`);

  // 6. Wait for all results
  let template = created.value;
  const enabledProfiles = cfg.value.userProfiles.filter((p) => p.enabled);
  const expectedResults = 1 + enabledProfiles.length + (cfg.value.testNoAuth ? 1 : 0);
  while (template.results.length < expectedResults) {
    await new Promise((resolve) => setTimeout(resolve, 1500));
    const got = await pkg.getTemplate(templateId);
    if (got.kind === "Error") throw new Error(got.error);
    template = got.value;
  }

  // 7. Print results
  console.log(`\nResults (${template.results.length}):`);
  for (const result of template.results) {
    if (result.kind === "Error") {
      console.log(`  ERROR: ${result.error}`);
      continue;
    }
    if (result.type === "baseline") {
      console.log(`  [baseline] ${result.response.code} (${result.response.length} bytes)`);
    } else if (result.type === "mutated") {
      console.log(`  [mutated] "${result.userProfileName}" -> ${result.response.code} access=${result.accessState.kind}`);
    } else if (result.type === "no-auth") {
      console.log(`  [no-auth] -> ${result.response.code} access=${result.accessState.kind}`);
    }
  }

  // 8. Cleanup
  await pkg.deleteTemplate(templateId);
  await pkg.updateConfig({ userProfiles: [] });
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});
```

Run it with:

```bash
export CAIDO_PAT=caido_xxxxx
npx tsx ./index.ts
```

A successful run against a `caido.local` target prints something like:

```txt
[caido] Loaded token from cache
Template created for GET http://caido.local/api/users

Results (3):
  [baseline] 200 (1842 bytes)
  [mutated] "Low-Privilege User" -> 200 (1842 bytes) access=authorized
  [no-auth] -> 200 (1842 bytes) access=authorized
```

In this example, both the low-privilege user and the unauthenticated request received the same 200 response as the baseline, so Autorize marked them as `authorized`. This means the endpoint does not enforce access control and any user can reach it.

## Script Breakdown

The script performs the following operations:

1. **Connect**: authenticates against the Caido instance using a PAT and caches the resulting tokens on disk so subsequent runs skip the auth flow. See [Base Setup](/client-sdk/guides/base_setup.md) for details.
2. **Plugin handle**: looks up Autorize by manifest ID, installing it via the SDK if it is not yet present. See [Install a Plugin](/client-sdk/guides/install_plugin.md).
3. **User profile**: configures a low-privilege user whose `Authorization` header is replaced with a different token. Autorize will replay every tested request with this profile's mutations applied.
4. **Target lookup**: queries the HTTP history with an HTTPQL filter to find a request to test. See [Extract Requests](/client-sdk/guides/extract_requests.md) and the [HTTPQL reference](https://docs.caido.io/app/reference/httpql.html).
5. **Template**: creates an authorization test template from the target request. Autorize replays the request as the baseline, once per enabled profile, and once without auth.
6. **Results**: polls until all expected results arrive, then prints each result's type, response code, and access state.
7. **Cleanup**: deletes the template and resets the user profiles so they do not interfere with future tests.

## Next Steps

You can extend this tutorial in several directions:

* Add multiple user profiles (admin, editor, viewer) to test role-based access control across several privilege levels.
* Create templates for many requests by looping over `client.request.list()` results, building an authorization matrix across your entire API surface.
* Subscribe to the `template:completed` event instead of polling, as described in [Receive Plugin Events](/client-sdk/guides/receive_events.md).
* Use `pkg.getTemplatesExportData(templateIds)` to export results for reporting or integration with other tools.

---

---
url: /client-sdk/tutorials/scanner.md
---
# Using the Scanner API

The goal of this tutorial is to drive the [Caido Scanner](https://github.com/caido-community/scanner) plugin from an external script using the [Client SDK](https://github.com/caido/sdk-js). By the end, you will be able to install Scanner against a Caido instance, run an active scan against a request already captured in your proxy history, and read the resulting findings, all without opening the Caido UI.

This is useful for security automation (running scans on a schedule, scanning batches of requests collected by another tool), CI/CD pipelines (checking new endpoints against a baseline), and any workflow where opening the Caido UI is not an option.

## 1. Prerequisites

::: info Requirements

* [Node.js](https://nodejs.org/en/) 18 or higher
* A running Caido instance with an open project
* A [Personal Access Token](https://docs.caido.io/dashboard/concepts/pat.html) (PAT) for your account
* At least one request to your target host in the project's HTTP history. This tutorial uses `caido.local` as the example target, so send any request through your Caido proxy to that host before starting (or substitute your own host throughout).
  :::

## 2. Setting up the script

### Initializing the project

Create a working directory for the script and initialize it:

```bash
mkdir caido-scanner-tutorial
cd caido-scanner-tutorial
pnpm init
```

Add `"type": "module"` to `package.json` so Node treats the `.ts` file as an ES module, which the `import` statements below require.

### Installing dependencies

Install the Client SDK and the Scanner spec package. The spec package is what makes the Scanner functions and events typed when you call them through the SDK:

```bash
pnpm add @caido/sdk-client @caido-community/scanner
```

::: info
The [`@caido-community/scanner`](https://www.npmjs.com/package/@caido-community/scanner) package is the spec for the Scanner plugin. The Client SDK uses it to type the calls in this tutorial. See [Use a Plugin's NPM Spec Package](/client-sdk/guides/spec_typing.md) for the broader concept.
:::

### Setting environment variables

Export your PAT and (optionally) the instance URL:

```bash
export CAIDO_PAT=caido_xxxxx
export CAIDO_INSTANCE_URL=http://localhost:8080
```

::: warning
Never commit the PAT to source control. Treat it like a password and store it in your shell's secret manager or a `.env` file that is gitignored.
:::

## 3. Connecting and installing Scanner

Create `index.ts`. The first thing the script does is connect to the Caido instance using the PAT from the environment, then either look up or install the Scanner plugin:

### index.ts

```ts
import { Client } from "@caido/sdk-client";
import type { Spec as ScannerSpec } from "@caido-community/scanner";

async function main() {
  const client = new Client({
    url: process.env["CAIDO_INSTANCE_URL"] ?? "http://localhost:8080",
    auth: {
      pat: process.env["CAIDO_PAT"]!,
      cache: { file: ".caido-token.json" },
    },
  });

  await client.connect();
  console.log("Connected to Caido");

  // Look up the installed plugin, install if missing
  let pkg = await client.plugin.pluginPackage<ScannerSpec>("scanner");
  if (pkg === undefined) {
    console.log("Installing Scanner...");
    pkg = await client.plugin.install<ScannerSpec>({ manifestId: "scanner" });
  }
  console.log("Scanner ready");
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});
```

Two things to note. The `ScannerSpec` generic on `pluginPackage` and `install` is what makes the rest of the script's calls typed: `pkg.startActiveScan(...)`, `pkg.getChecks()`, and so on, all autocomplete with the correct argument and return types. The lookup-then-install pattern is idiomatic: `pluginPackage()` returns `undefined` when the plugin is not present, and `install()` returns a fresh handle when it is invoked.

For more on installing plugins from a script, see the [Install a Plugin](/client-sdk/guides/install_plugin.md) guide.

## 4. Discovering available checks

Before running a scan, you can list the checks Scanner ships with. This is useful for picking which checks to include or exclude from your scan, and for understanding what Scanner can detect:

```ts
const checks = await pkg.getChecks();
if (checks.kind === "Error") {
  throw new Error(checks.error);
}

console.log(`Scanner ships with ${checks.value.length} checks`);
for (const check of checks.value.slice(0, 5)) {
  console.log(`  ${check.id} [${check.type}] - ${check.name}`);
}
```

Each check exposes its `id`, `name`, `description`, `type` (`"passive"` or `"active"`), `tags`, and `severities`. You can filter for specific types or IDs by passing options:

```ts
const activeOnly = await pkg.getChecks({ type: "active" });
const specific = await pkg.getChecks({ include: ["reflected-xss", "sql-injection"] });
```

::: info
Scanner functions return a `Result<T>` envelope of the form `{ kind: "Ok"; value }` or `{ kind: "Error"; error }`. Always branch on `result.kind` before using the value. This is a Scanner convention; other plugins may use different shapes.
:::

## 5. Finding a target request

Active scans run against existing requests in the project's HTTP history. To get the request ID for a target, use [`client.request.list()`](/client-sdk/guides/extract_requests.md) with an [HTTPQL](https://docs.caido.io/app/reference/httpql.html) filter on the host:

```ts
const page = await client.request
  .list()
  .filter('req.host.eq:"caido.local"')
  .first(1);

const target = page.edges[0]?.node.request;
if (target === undefined) {
  throw new Error(
    "No requests to caido.local found in this project. " +
    "Send a request through the Caido proxy to that host first.",
  );
}

console.log(`Target: ${target.method} ${target.host}${target.path} (id=${target.id})`);
```

The filter syntax is the same one you use in the Caido HTTP History UI. Adjust it for your own target host.

## 6. Configuring and starting the scan

The active scan is configured with a `ScanConfig` object. Each field controls a different aspect of the scan:

```ts
const start = await pkg.startActiveScan({
  requestIDs: [target.id],
  title: `Scan of ${target.host}${target.path}`,
  scanConfig: {
    aggressivity: "low",
    scopeIDs: [],
    concurrentChecks: 2,
    concurrentRequests: 3,
    concurrentTargets: 1,
    requestsDelayMs: 0,
    scanTimeout: 60000,
    checkTimeout: 30000,
    severities: ["info", "low", "medium", "high", "critical"],
  },
});

if (start.kind === "Error") {
  throw new Error(start.error);
}

const sessionId = start.value.id;
console.log(`Scan started: ${sessionId} (kind=${start.value.kind})`);
```

The fields:

* `aggressivity`: `"low"`, `"medium"`, or `"high"`. Higher aggressivity sends more probe requests per check.
* `scopeIDs`: limit the scan to requests within specific Caido scopes. An empty array means no scope restriction.
* `concurrentChecks`, `concurrentRequests`, `concurrentTargets`: parallelism knobs that trade speed for load on the target.
* `requestsDelayMs`: delay between requests, useful for rate-limited targets.
* `scanTimeout` and `checkTimeout`: timeouts in milliseconds.
* `severities`: which severities to surface in the results.

`startActiveScan` returns a `Session` in the `Pending` state. The scan starts asynchronously.

## 7. Tracking progress

The session transitions through states as the scan runs: `Pending → Running → Done` (or `Interrupted` / `Error`). The simplest way to track it is to poll `getScanSession` until the kind is no longer `Pending` or `Running`:

```ts
let session = start.value;
while (session.kind === "Pending" || session.kind === "Running") {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  const got = await pkg.getScanSession(sessionId);
  if (got.kind === "Error") {
    throw new Error(got.error);
  }
  session = got.value;
  const done = session.kind === "Running" ? session.progress.checksHistory.length : 0;
  const total = session.kind === "Running" ? session.progress.checksTotal : 0;
  console.log(`  status=${session.kind} progress=${done}/${total}`);
}

console.log(`Scan finished with status: ${session.kind}`);
```

::: tip
For long-running scans, subscribe to the `session:progress` event instead of polling. See [Receive Plugin Events](/client-sdk/guides/receive_events.md). Polling is shown here because it keeps the example self-contained.
:::

## 8. Reading the findings

When the session reaches `Done`, the `progress.checksHistory` array contains one `CheckExecution` for every check that ran. Each execution carries the findings it produced:

```ts
if (session.kind !== "Done") {
  console.log("Scan did not complete successfully:", session.kind);
  return;
}

const findings = [];
for (const execution of session.progress.checksHistory) {
  for (const finding of execution.findings) {
    findings.push({ checkID: execution.checkID, finding });
  }
}

console.log(`\nTotal findings: ${findings.length}`);
for (const { checkID, finding } of findings) {
  console.log(`  [${finding.severity}] ${finding.name} (${checkID})`);
  console.log(`    ${finding.description}`);
}
```

Each `Finding` has a `name`, `description`, `severity`, and a `correlation` block that pins the finding to a request and optionally a byte range within it.

## 9. Cleaning up

Scan sessions persist in the project until they are deleted. Remove the session at the end of the script to keep the project tidy:

```ts
await pkg.deleteScanSession(sessionId);
console.log("Scan session deleted");
```

## Examples

The script below combines every step into a single file. It connects, ensures Scanner is installed, finds the first `caido.local` request, runs an active scan, prints the findings, and cleans up.

### index.ts

```ts
import { Client } from "@caido/sdk-client";
import type { Spec as ScannerSpec } from "@caido-community/scanner";

async function main() {
  const client = new Client({
    url: process.env["CAIDO_INSTANCE_URL"] ?? "http://localhost:8080",
    auth: {
      pat: process.env["CAIDO_PAT"]!,
      cache: { file: ".caido-token.json" },
    },
  });

  await client.connect();

  // 1. Look up or install Scanner
  let pkg = await client.plugin.pluginPackage<ScannerSpec>("scanner");
  if (pkg === undefined) {
    pkg = await client.plugin.install<ScannerSpec>({ manifestId: "scanner" });
  }

  // 2. Find a target request
  const page = await client.request
    .list()
    .filter('req.host.eq:"caido.local"')
    .first(1);
  const target = page.edges[0]?.node.request;
  if (target === undefined) {
    throw new Error("Send a request to caido.local through the Caido proxy first");
  }

  // 3. Start the scan
  const start = await pkg.startActiveScan({
    requestIDs: [target.id],
    title: `Scan of ${target.host}${target.path}`,
    scanConfig: {
      aggressivity: "low",
      scopeIDs: [],
      concurrentChecks: 2,
      concurrentRequests: 3,
      concurrentTargets: 1,
      requestsDelayMs: 0,
      scanTimeout: 60000,
      checkTimeout: 30000,
      severities: ["info", "low", "medium", "high", "critical"],
    },
  });
  if (start.kind === "Error") {
    throw new Error(start.error);
  }
  const sessionId = start.value.id;
  console.log(`Scan started: ${sessionId}`);

  // 4. Wait for the scan to finish
  let session = start.value;
  while (session.kind === "Pending" || session.kind === "Running") {
    await new Promise((resolve) => setTimeout(resolve, 2000));
    const got = await pkg.getScanSession(sessionId);
    if (got.kind === "Error") {
      throw new Error(got.error);
    }
    session = got.value;
  }

  // 5. Print findings
  if (session.kind === "Done") {
    const findings = session.progress.checksHistory.flatMap((execution) =>
      execution.findings.map((finding) => ({
        checkID: execution.checkID,
        finding,
      })),
    );
    console.log(`Scan finished with ${findings.length} finding(s):`);
    for (const { checkID, finding } of findings) {
      console.log(`  [${finding.severity}] ${finding.name} (${checkID})`);
    }
  } else {
    console.log(`Scan ended with status: ${session.kind}`);
  }

  // 6. Cleanup
  await pkg.deleteScanSession(sessionId);
}

main().catch((error) => {
  console.error(error);
  process.exit(1);
});
```

Run it with:

```bash
export CAIDO_PAT=caido_xxxxx
npx tsx ./index.ts
```

A successful run against a `caido.local` target prints something like:

```txt
[caido] Attempting to load cached token
[caido] Loaded token from cache
Scan started: ascan-xxxxxxxxxxx
Scan finished with 1 finding(s):
  [medium] Missing X-Frame-Options Header (anti-clickjacking)
```

Exact findings will vary based on what the target's response contains.

## Script Breakdown

The script performs the following operations:

1. **Connect**: authenticates against the Caido instance using a PAT and caches the resulting tokens on disk so subsequent runs skip the auth flow. See [Base Setup](/client-sdk/guides/base_setup.md) for details.
2. **Plugin handle**: looks up Scanner by manifest ID, installing it via the SDK if it is not yet present. See [Install a Plugin](/client-sdk/guides/install_plugin.md).
3. **Target lookup**: queries the HTTP history with an HTTPQL filter to find a request to scan. See [Extract Requests](/client-sdk/guides/extract_requests.md) and the [HTTPQL reference](https://docs.caido.io/app/reference/httpql.html).
4. **Active scan**: builds a `ScanConfig`, calls `startActiveScan`, and polls the resulting `Session` until it transitions out of `Running`.
5. **Findings**: flattens `progress.checksHistory[*].findings` into a single list and prints each by severity and check ID.
6. **Cleanup**: deletes the session so it does not accumulate in the project.

## Next Steps

You can extend this tutorial in several directions:

* Subscribe to the `session:progress` event instead of polling, as described in [Receive Plugin Events](/client-sdk/guides/receive_events.md).
* Scan multiple requests in one session by passing more IDs to `requestIDs`.
* Persist findings to Caido as native [findings](/client-sdk/guides/manage_findings.md) tied to the original request.

---

---
url: /plugins/reference/sdks/frontend/utils.md
---
# Utils

### AddIndicatorOptions

> **AddIndicatorOptions** = `object`

Visual indicator displayed next to a item label in a tree component.
Includes an icon and an associated description.

#### Properties

##### description

> **description**: `string`

##### icon

> **icon**: [`Icon`](#icon)

***

### As

> **As**<`TType`> = `object`

Utility type that adds a type discriminator to a type.

#### Type Parameters

| Type Parameter |
| ------ |
| `TType` *extends* `string` |

#### Properties

##### type

> **type**: `TType`

***

### ComponentDefinition

> **ComponentDefinition** = `object`

A custom component that will be rendered in the UI.

#### Properties

##### component

> **component**: `VueComponent`

##### events?

> `optional` **events**: `Record`<`string`, (...`args`: `unknown`\[]) => `void`>

##### props?

> `optional` **props**: `Record`<`string`, `unknown`>

***

### HTTPQL

> **HTTPQL** = `string` & `object`

An HTTPQL expression.

#### Type Declaration

##### \_\_httpql?

> `optional` **\_\_httpql**: `never`

#### Example

```ts
`req.method.eq:"POST"`
```

***

### Icon

> **Icon** = `string` & `object`

A <https://fontawesome.com/icons|FontAwesome> icon class.

#### Type Declaration

##### \_\_icon?

> `optional` **\_\_icon**: `never`

#### Example

```ts
"fas fa-rocket"
```

***

### ID

> **ID** = `string` & `object`

A unique Caido identifier per type.

#### Type Declaration

##### \_\_id?

> `optional` **\_\_id**: `never`

***

### Indicator

> **Indicator** = `object`

Providing operations that can be performed on a item indicator.

#### Properties

##### remove()

> **remove**: () => `void`

###### Returns

`void`

***

### ListenerHandle

> **ListenerHandle** = `object`

A handle for a listener.

#### Properties

##### stop()

> **stop**: () => `void`

Stop the listener.

###### Returns

`void`

***

### Prettify

> **Prettify**<`T`> = `{ [K in keyof T]: T[K] }` & `object`

Utility type that prettifies complex types for better IDE display.

#### Type Parameters

| Type Parameter |
| ------ |
| `T` |

***

### PromisifiedReturnType

> **PromisifiedReturnType**<`T`> = `ReturnType`<`T`> *extends* `Promise`\<infer U> ? `Promise`<`U`> : `Promise`<`ReturnType`<`T`>>

Utility type for converting endpoint return types to promises.

#### Type Parameters

| Type Parameter |
| ------ |
| `T` *extends* (...`args`: `unknown`\[]) => `unknown` |

***

### Selection

> **Selection**<`TId`> = { `kind`: `"Empty"`; } | { `kind`: `"Selected"`; `main`: `TId`; `secondary`: `TId`\[]; }

Generic selection type with main and secondary items.
Main represents the primary selected item, secondary represents additional selected items.

#### Type Parameters

| Type Parameter |
| ------ |
| `TId` |

---

---
url: /plugins/reference/sdks/frontend/websockets.md
---
# Websockets

### WebsocketPageContext

> **WebsocketPageContext** = `object`

Certificate page context.

#### Properties

##### kind

> **kind**: `"Websocket"`

---

---
url: /plugins/reference/sdks/frontend/window.md
---
# Window

### Dialog

> **Dialog** = `object`

A dialog instance that can be closed programmatically.

#### Properties

##### close()

> **close**: () => `void`

###### Returns

`void`

***

### DialogOptions

> **DialogOptions** = `object`

Options for configuring a dialog.

#### Properties

##### closable?

> `optional` **closable**: `boolean`

##### closeOnEscape?

> `optional` **closeOnEscape**: `boolean`

##### draggable?

> `optional` **draggable**: `boolean`

##### modal?

> `optional` **modal**: `boolean`

##### position?

> `optional` **position**: `"left"` | `"right"` | `"top"` | `"bottom"` | `"center"` | `"topleft"` | `"topright"` | `"bottomleft"` | `"bottomright"`

##### title?

> `optional` **title**: `string`

***

### GlobalContext

> **GlobalContext** = `object`

Represents the global context of the application.

#### Properties

##### page?

> `optional` **page**: [`PageContext`](#pagecontext)

***

### PageContext

> **PageContext** = [`AssistantPageContext`](assistant.md#assistantpagecontext) | [`AutomatePageContext`](automate.md#automatepagecontext) | [`BackupsPageContext`](backups.md#backupspagecontext) | [`CertificatePageContext`](certificate.md#certificatepagecontext) | [`ExportsPageContext`](exports.md#exportspagecontext) | [`EnvironmentPageContext`](environment.md#environmentpagecontext) | [`FilterPageContext`](filters.md#filterpagecontext) | [`FindingsPageContext`](findings.md#findingspagecontext) | [`HTTPHistoryPageContext`](http-history.md#httphistorypagecontext) | [`ReplayPageContext`](replay.md#replaypagecontext) | [`ScopePageContext`](scopes.md#scopepagecontext) | [`SearchPageContext`](search.md#searchpagecontext) | [`WorkflowsPageContext`](workflows.md#workflowspagecontext) | [`ProjectsPageContext`](projects.md#projectspagecontext) | [`FilesPageContext`](files.md#filespagecontext) | [`MatchReplacePageContext`](match-and-replace.md#matchreplacepagecontext) | [`InterceptPageContext`](intercept.md#interceptpagecontext) | [`SitemapPageContext`](sitemap.md#sitemappagecontext) | [`WebsocketPageContext`](websockets.md#websocketpagecontext)

Represents the context of the current page.

***

### WindowSDK

> **WindowSDK** = `object`

Utilities to interact with the active page.

#### Properties

##### getActiveEditor()

> **getActiveEditor**: () => [`Editor`](editor.md#editor) | `undefined`

Get the active editor.

###### Returns

[`Editor`](editor.md#editor) | `undefined`

The active editor.

##### getContext()

> **getContext**: () => [`GlobalContext`](#globalcontext)

Get the current global context.

###### Returns

[`GlobalContext`](#globalcontext)

The current global context.

##### onContextChange()

> **onContextChange**: (`callback`: (`context`: [`GlobalContext`](#globalcontext)) => `void`) => [`ListenerHandle`](utils.md#listenerhandle)

Subscribe to global context changes.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `callback` | (`context`: [`GlobalContext`](#globalcontext)) => `void` | The callback to call when the context changes. |

###### Returns

[`ListenerHandle`](utils.md#listenerhandle)

An object with a `stop` method that can be called to stop listening to context changes.

##### showDialog()

> **showDialog**: (`component`: [`ComponentDefinition`](utils.md#componentdefinition), `options?`: [`DialogOptions`](#dialogoptions)) => [`Dialog`](#dialog)

Show a dialog component.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `component` | [`ComponentDefinition`](utils.md#componentdefinition) | The custom slot content to display in the dialog. |
| `options?` | [`DialogOptions`](#dialogoptions) | Options for the dialog. |

###### Returns

[`Dialog`](#dialog)

A dialog object that can be used to close the dialog.

##### showToast()

> **showToast**: (`message`: `string`, `options?`: `object`) => `void`

Show a toast message.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `message` | `string` | The message to show. |
| `options?` | { `duration?`: `number`; `variant?`: `"success"` | `"error"` | `"warning"` | `"info"`; } | Options for the toast message. |
| `options.duration?` | `number` | The duration of the toast message in milliseconds. |
| `options.variant?` | `"success"` | `"error"` | `"warning"` | `"info"` | The variant of the toast message. |

###### Returns

`void`

---

---
url: /plugins/reference/sdks/frontend/workflows.md
---
# Workflows

### OnCreatedWorkflowCallback()

> **OnCreatedWorkflowCallback** = (`event`: `object`) => `void`

Callback function called when a workflow is created.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | { `workflow`: [`Workflow`](#workflow); } |
| `event.workflow` | [`Workflow`](#workflow) |

#### Returns

`void`

***

### OnDeletedWorkflowCallback()

> **OnDeletedWorkflowCallback** = (`event`: `object`) => `void`

Callback function called when a workflow is deleted.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | { `id`: [`ID`](utils.md#id); } |
| `event.id` | [`ID`](utils.md#id) |

#### Returns

`void`

***

### OnUpdatedWorkflowCallback()

> **OnUpdatedWorkflowCallback** = (`event`: `object`) => `void`

Callback function called when a workflow is updated.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `event` | { `workflow`: [`Workflow`](#workflow); } |
| `event.workflow` | [`Workflow`](#workflow) |

#### Returns

`void`

***

### Workflow

> **Workflow** = `object`

A workflow

#### Properties

##### description

> **description**: `string`

##### id

> **id**: `string`

##### kind

> **kind**: [`WorkflowKind`](#workflowkind)

##### name

> **name**: `string`

***

### WorkflowKind

> **WorkflowKind** = `"Convert"` | `"Active"` | `"Passive"`

The kind of workflow.

***

### WorkflowSDK

> **WorkflowSDK** = `object`

Utilities to interact with workflows.

#### Properties

##### getWorkflows()

> **getWorkflows**: () => [`Workflow`](#workflow)\[]

Get all workflows.

###### Returns

[`Workflow`](#workflow)\[]

All workflows.

##### onCreatedWorkflow()

> **onCreatedWorkflow**: (`callback`: [`OnCreatedWorkflowCallback`](#oncreatedworkflowcallback)) => [`ListenerHandle`](utils.md#listenerhandle)

Register a callback to be called when a workflow is created.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `callback` | [`OnCreatedWorkflowCallback`](#oncreatedworkflowcallback) | The callback to be called. |

###### Returns

[`ListenerHandle`](utils.md#listenerhandle)

##### onDeletedWorkflow()

> **onDeletedWorkflow**: (`callback`: [`OnDeletedWorkflowCallback`](#ondeletedworkflowcallback)) => [`ListenerHandle`](utils.md#listenerhandle)

Register a callback to be called when a workflow is deleted.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `callback` | [`OnDeletedWorkflowCallback`](#ondeletedworkflowcallback) | The callback to be called. |

###### Returns

[`ListenerHandle`](utils.md#listenerhandle)

##### onUpdatedWorkflow()

> **onUpdatedWorkflow**: (`callback`: [`OnUpdatedWorkflowCallback`](#onupdatedworkflowcallback)) => [`ListenerHandle`](utils.md#listenerhandle)

Register a callback to be called when a workflow is updated.

###### Parameters

| Parameter | Type | Description |
| ------ | ------ | ------ |
| `callback` | [`OnUpdatedWorkflowCallback`](#onupdatedworkflowcallback) | The callback to be called. |

###### Returns

[`ListenerHandle`](utils.md#listenerhandle)

***

### WorkflowsPageContext

> **WorkflowsPageContext** = `object`

Workflows page context.

#### Properties

##### kind

> **kind**: `"Workflows"`