# Files (/docs/products/dash-dots/reference/dash-api/files)

A dot's own data, kept on this device for the signed-in Dash user only. It's never backed up or moved to a new phone, and another user who signs in sees none of it. Keep what matters on the dot's server, and treat this as a copy you can fetch again.

Files live in the dot's own folder, which no other dot sees. Paths are relative to it, such as "receipts/42.pdf", and '' is the folder itself. A call on a path with nothing there fails with `missing`, while `stat` gives null for it.

## `dash.storage.file.read`

```ts
dash.storage.file.read(path: string, options?: ReadOptions, callOptions?: CallOptions): DashRequest<string>
```

Reads the file at `path`, up to 5 MB, as text or base64. Fails with `missing` if there's no file there.

Types: [`ReadOptions`](/docs/products/dash-dots/reference/dash-api/files#readoptions)

## `dash.storage.file.write`

```ts
dash.storage.file.write(path: string, data: string, options?: WriteOptions, callOptions?: CallOptions): DashRequest<FileEntry>
```

Writes `data` to the file at `path`, as text or base64, and creates any missing folders above it. Pass `{ append: true }` to add to the end of the file.

Types: [`WriteOptions`](/docs/products/dash-dots/reference/dash-api/files#writeoptions), [`FileEntry`](/docs/products/dash-dots/reference/dash-api/files#fileentry)

## `dash.storage.file.stat`

```ts
dash.storage.file.stat(path: string, callOptions?: CallOptions): DashRequest<FileEntry | null>
```

Details of the file or folder at `path`: its kind, size and when it last changed. Gives null if there's nothing there.

Types: [`FileEntry`](/docs/products/dash-dots/reference/dash-api/files#fileentry)

## `dash.storage.file.list`

```ts
dash.storage.file.list(path?: string, options?: { recursive?: boolean }, callOptions?: CallOptions): DashRequest<FileEntry[]>
```

What a folder holds, sorted by path. Pass `{ recursive: true }` to include everything in its subfolders.

Types: [`FileEntry`](/docs/products/dash-dots/reference/dash-api/files#fileentry)

## `dash.storage.file.createFolder`

```ts
dash.storage.file.createFolder(path: string, callOptions?: CallOptions): DashRequest<FileEntry>
```

Creates a folder at `path`, with any folders above it that are missing.

Types: [`FileEntry`](/docs/products/dash-dots/reference/dash-api/files#fileentry)

## `dash.storage.file.move`

```ts
dash.storage.file.move(from: string, to: string, options?: ReplaceOptions, callOptions?: CallOptions): DashRequest<FileEntry>
```

Moves or renames a file or folder. Pass `{ overwrite: true }` to replace what's already at `to`.

Types: [`ReplaceOptions`](/docs/products/dash-dots/reference/dash-api/files#replaceoptions), [`FileEntry`](/docs/products/dash-dots/reference/dash-api/files#fileentry)

## `dash.storage.file.copy`

```ts
dash.storage.file.copy(from: string, to: string, options?: ReplaceOptions, callOptions?: CallOptions): DashRequest<FileEntry>
```

Copies a file or folder. Pass `{ overwrite: true }` to replace what's already at `to`.

Types: [`ReplaceOptions`](/docs/products/dash-dots/reference/dash-api/files#replaceoptions), [`FileEntry`](/docs/products/dash-dots/reference/dash-api/files#fileentry)

## `dash.storage.file.remove`

```ts
dash.storage.file.remove(path: string, options?: { recursive?: boolean }, callOptions?: CallOptions): DashRequest<void>
```

Deletes the file or folder at `path`. A folder with anything in it needs `{ recursive: true }`.

## `dash.storage.file.save`

```ts
dash.storage.file.save(file: DotFile, path: string, options?: ReplaceOptions, callOptions?: CallOptions): DashRequest<FileEntry>
```

Keeps a temporary file, such as a download, at `path`.

Types: [`DotFile`](/docs/products/dash-dots/reference/dash-api/files#dotfile), [`ReplaceOptions`](/docs/products/dash-dots/reference/dash-api/files#replaceoptions), [`FileEntry`](/docs/products/dash-dots/reference/dash-api/files#fileentry)

## `dash.storage.file.open`

```ts
dash.storage.file.open(path: string, callOptions?: CallOptions): DashRequest<DotFile>
```

A stored file as a DotFile, to show with its `url` or send with `http.upload`.

Types: [`DotFile`](/docs/products/dash-dots/reference/dash-api/files#dotfile)

## `dash.storage.file.usage`

```ts
dash.storage.file.usage(callOptions?: CallOptions): DashRequest<StorageUsage>
```

How many bytes the dot's files take, and the most they may take.

Types: [`StorageUsage`](/docs/products/dash-dots/reference/dash-api/files#storageusage)

## Types

### `FileEntry`

| Field                    | Type                 | What it is                                                                       |
| ------------------------ | -------------------- | -------------------------------------------------------------------------------- |
| `name`                   | `string`             |                                                                                  |
| `path`                   | `string`             |                                                                                  |
| `size`                   | `number`             | In bytes, and 0 for a folder.                                                    |
| `kind`                   | `'file' \| 'folder'` |                                                                                  |
| `modifiedAt`             | `number`             | When it last changed, in milliseconds since 1 January 1970, as Date.now() gives. |
| `contentType` (optional) | `string`             |                                                                                  |

### `FileEncoding`

```ts
type FileEncoding = 'text' | 'base64';
```

### `StorageUsage`

In bytes: what the dot's files take, and the most they may take.

| Field   | Type     | What it is |
| ------- | -------- | ---------- |
| `used`  | `number` |            |
| `quota` | `number` |            |

### `ReadOptions`

| Field           | Type                                                                             | What it is       |
| --------------- | -------------------------------------------------------------------------------- | ---------------- |
| `as` (optional) | [`FileEncoding`](/docs/products/dash-dots/reference/dash-api/files#fileencoding) | Default: `text`. |

### `WriteOptions`

| Field               | Type                                                                             | What it is                                                              |
| ------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `as` (optional)     | [`FileEncoding`](/docs/products/dash-dots/reference/dash-api/files#fileencoding) | How `data` is written. Default: `text`.                                 |
| `append` (optional) | `boolean`                                                                        | Adds to the end of the file in place of replacing it. Default: `false`. |

### `ReplaceOptions`

| Field                  | Type      | What it is                                             |
| ---------------------- | --------- | ------------------------------------------------------ |
| `overwrite` (optional) | `boolean` | Replaces what's already at the path. Default: `false`. |

### `DotFile`

A file Dash gives your dot, such as a download or a photo. It lasts until the dot closes, unless you save it with `dash.storage.file.save`.

| Field         | Type     | What it is                                                                                   |
| ------------- | -------- | -------------------------------------------------------------------------------------------- |
| `id`          | `string` | Identifies the file to Dash. Pass the whole `DotFile` to calls, not just its `id`.           |
| `name`        | `string` |                                                                                              |
| `size`        | `number` | In bytes.                                                                                    |
| `contentType` | `string` |                                                                                              |
| `url`         | `string` | An address to show the file with, such as an `Image`'s `src`. It works until the dot closes. |