# Volume

> Volumes: a persistent filesystem you mount into sandboxes and agents.

```python
vol = noclick.Volume.from_name("datasets", create_if_missing=True)
vol.write("/raw/orders.csv", csv_bytes)
with noclick.Sandbox.create(volumes={"/data": vol}) as sb:
    sb.exec("python train.py --data /data/raw")
```

Paths start at the volume's root (`/raw/orders.csv`). Folders are real folders,
made as files are written into them. What a sandbox or an agent's turn writes is
saved every few seconds while it runs, and all of it when it ends; two writers to one
file at once: the last one to finish wins.

## Volume

```typescript
class Volume
```

A persistent filesystem: files by path, in folders, that outlive the sandbox or agent turn
that wrote them. Mount it with `Sandbox.create({ volumes: { "/data": vol } })` or an agent's
`volumes`, or read and write it from your own code. What a sandbox or an agent's turn writes is
saved every few seconds while it runs, and all of it when it ends; two writers to one file at once:
the last one to finish wins.

| Attribute | Type | Description |
| --- | --- | --- |
| `id` | `string` |  |
| `name` | `string` |  |
| `sizeBytes` | `number | null` |  |
| `fileCount` | `number | null` |  |
| `mountedBy` | `VolumeMount[]` | The running sandboxes, the agents and the machines that mount it, and at which path. |
| `region` | `RegionName | null` | Always null for now: volumes aren't placed by region yet (`region` is in invite-only beta). |
| `userId` | `string | null` |  |
| `createdAt` | `Date | null` |  |
| `consoleUrl` | `string | null` | This volume in the developer console (null off the hosted API). |

Types:

```typescript
/** A running sandbox, an agent or a machine that mounts a volume, and where. */
interface VolumeMount {
  kind: "sandbox" | "agent" | "machine";
  id: string;
  /** An agent's or a machine's name (null for a sandbox). */
  name: string | null;
  /** Where it's mounted: `/data`. */
  path: string;
}

type RegionName = "us-east" | "us-west" | "eu" | "ap" | "in";
```

### Volume.create

```typescript
static create(
  name: string,
  options?: CallOptions & PlacementOptions & AllowExisting,
): Promise<Volume>
```

Create an empty volume (1-64 letters, digits and `. _ -`), unique by name per user (a taken name
throws `Conflict` with `existingId`, or with `allowExisting: true` returns the volume already there,
files and all). `region` is in invite-only beta: the sandbox provider's volumes take no location, so
passing one throws `NotAvailable`.

Parameters:

- `name` (`string`, required)
- `options.region` (`RegionName`, invite-only beta): Where it runs or keeps its data (`regions()`); omitted, your account's default region.
- `options.allowExisting` (`boolean`): A taken name returns the object already there, as it is: nothing about it changes.
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: The new, empty volume.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

type RegionName = "us-east" | "us-west" | "eu" | "ap" | "in";
```

### Volume.fromName

```typescript
static fromName(
  name: string,
  options?: CallOptions & PlacementOptions & { createIfMissing?: boolean },
): Volume
```

A lazy reference to the volume called `name`. Acting for a user, that user's own volume is
found first, then the account's. With `createIfMissing` the current (or given) user's is
created on first use.

Parameters:

- `name` (`string`, required)
- `options.createIfMissing` (`boolean`)
- `options.region` (`RegionName`, invite-only beta): Where it runs or keeps its data (`regions()`); omitted, your account's default region.
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: A volume that loads (or is created) the first time it's used. Nothing is sent yet.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

type RegionName = "us-east" | "us-west" | "eu" | "ap" | "in";
```

### Volume.fromId

```typescript
static fromId(volumeId: string, options?: CallOptions): Volume
```

A lazy reference to a volume by id.

Parameters:

- `volumeId` (`string`, required)
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.

Returns: A volume that loads the first time you read a field. Nothing is sent yet.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Volume.get

```typescript
static get(volumeId: string, options?: CallOptions): Promise<Volume>
```

Load a volume by id now; an unknown id raises `noclick.NotFound`.

Parameters:

- `volumeId` (`string`, required)
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: The volume, loaded: its size, how many files it holds, and who mounts it.

Types:

```typescript
/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}
```

### Volume.list

```typescript
static list(options?: ReadOptions & { limit?: number }): Promise<Volume[]>
```

The current user's volumes and the account's (or those `userFilter` covers).

Parameters:

- `options.limit` (`number`): Return at most this many.
- `options.userFilter` (`UserFilter`): Which users the read covers (`user_id` query), instead of acting as one (`user`).
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: Every matching volume, newest first, fetched page by page.

Types:

```typescript
/**
 * Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
 * `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
 */
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
```

### Volume.listPage

```typescript
static listPage(options?: ReadOptions & PageOptions): Promise<Page<Volume>>
```

One page of volumes; pass `nextCursor` back as `cursor`.

Parameters:

- `options.cursor` (`string | null`): The `next_cursor` of the page before; omit it for the first page.
- `options.limit` (`number`): Return at most this many.
- `options.userFilter` (`UserFilter`): Which users the read covers (`user_id` query), instead of acting as one (`user`).
- `options.user` (`UserOption`, default: the current user): `undefined` = the ambient user (`asUser`), `null` = the account itself.
- `options.client` (`NoClick`): The client to send with; defaults to the module client built from `NOCLICK_API_KEY`.

Returns: A page whose `data` holds the volumes and whose `next_cursor` is `None` on the last page.

Types:

```typescript
/**
 * Which users a read covers: `ALL_USERS`, `NO_USER`, a `User` or your id for one. Sent as the
 * `user_id` query parameter, never as the `NoClick-User` header, so it filters without acting as the user.
 */
type UserFilter = typeof ALL_USERS | typeof NO_USER | UserRef;

/** A `User` or your own id for the user. */
type UserRef = string | UserLike;

/** Anything that can name a user lazily (a `User`). */
interface UserLike {
  _userId(): Promise<string>;
}

/** `undefined` = the ambient user (from `asUser`), `null` = the account itself. */
type UserOption = UserRef | null | undefined;
```

### Volume.write

```typescript
write(path: string, data: VolumeData): Promise<VolumeEntry>
```

Write `data` to `path`, replacing the file and making any folders it needs (up to 100 MB).

Parameters:

- `path` (`string`, required)
- `data` (`VolumeData`, required)

Returns: The file as written, with its `size`.

Types:

```typescript
/** Bytes, text (sent as UTF-8), an `ArrayBuffer` or a `Blob`. */
type VolumeData = string | Uint8Array | ArrayBuffer | Blob;
```

### Volume.read

```typescript
read(path: string): Promise<Uint8Array>
```

The file's bytes (up to 100 MB), as the volume last saved it; a missing file throws `NotFound`.

Parameters:

- `path` (`string`, required)

Returns: The file's bytes, exactly as stored; decode text yourself.

### Volume.listdir

```typescript
listdir(
  path?,
  options?: VolumeListdirOptions & { limit?: number },
): Promise<VolumeEntry[]>
```

What's in the folder at `path` (everything below it with `recursive`), in path order, fetched page by page.

Parameters:

- `path` (`string`, default `"/"`)
- `options.recursive` (`boolean`): Everything below the folder, not just what's in it.
- `options.limit` (`number`): Return at most this many.

Returns: Every entry (or the first `limit`), fetched page by page.

### Volume.listdirPage

```typescript
listdirPage(
  path?,
  options?: VolumeListdirOptions & PageOptions,
): Promise<Page<VolumeEntry>>
```

One page of `listdir`; pass `nextCursor` back as `cursor`.

Parameters:

- `path` (`string`, default `"/"`)
- `options.recursive` (`boolean`): Everything below the folder, not just what's in it.
- `options.cursor` (`string | null`): The `next_cursor` of the page before; omit it for the first page.
- `options.limit` (`number`): Return at most this many.

Returns: A page whose `data` holds `VolumeEntry`s and whose `next_cursor` is `None` on the last page.

### Volume.remove

```typescript
remove(path: string, options?: { recursive?: boolean }): Promise<void>
```

Delete the file or folder at `path`; a folder that isn't empty needs `recursive`. A missing path is fine.

Parameters:

- `path` (`string`, required)
- `options.recursive` (`boolean`)

### Volume.copy

```typescript
copy(src: string, dst: string): Promise<VolumeEntry>
```

Copy the file or folder at `src` to `dst` in this volume, replacing what `dst` held.

Parameters:

- `src` (`string`, required)
- `dst` (`string`, required)

Returns: The copy at `dst`.

### Volume.export

```typescript
export(): Promise<Operation<ExportBundle>>
```

Export every file, so the volume can move anywhere: a zip holding them in their folders (under
`volumes/<name>/files/`), with `index.jsonl` listing each path, its size and when it last
changed. `wait()` resolves to an `ExportBundle`: the zip at `url`, valid 7 days.

Returns: An operation whose `wait()` gives an `ExportBundle`: the zip at `url`, valid 7 days.

### Volume.delete

```typescript
delete(): Promise<TrashItem>
```

Delete the volume and its files: it goes to the trash, restorable for 30 days. While a running
sandbox or an agent mounts it, this throws `Conflict`, and a user can't delete the account's
(`PermissionDenied`). Returns its `TrashItem`.

Returns: Its `TrashItem`: `restore()` puts it back.

## VolumeEntry

```typescript
interface VolumeEntry
```

A file or folder in a volume: its `path` from the volume's root, its `type`, a file's `size`
in bytes (null for a folder) and when it last changed.

| Attribute | Type | Description |
| --- | --- | --- |
| `path` | `string` |  |
| `type` | `"file" | "directory"` |  |
| `size` | `number | null` |  |
| `updatedAt` | `Date | null` |  |
| `raw` | `JsonObject` | The response JSON exactly as the API sent it. |

Types:

```typescript
type JsonObject = { [key: string]: unknown };
```
