> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bijection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Module: files

> File locators, shared by server functions and clients: which file to read, and the relationship that authorizes the read.

File locators, shared by server functions and clients: which file to read,
and the relationship that authorizes the read.

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { attachment } from "bijection/files";

const source = attachment(document, "source");
```

## References

### FileInfo

Re-exports [FileInfo](/api/modules/values#fileinfo)

***

### FileRef

Re-exports [FileRef](/api/modules/values#fileref)

***

### StagedFileRef

Re-exports [StagedFileRef](/api/modules/values#stagedfileref)

## Type Aliases

### SeriesOccurrence

Ƭ **SeriesOccurrence**: `Readonly`\<\{ `table`: `string` ; `id`: `string` ; `key`: `string` ; `time`: `string`  }>

The exact occurrence of a native series whose declared file property an
attachment names. Decimal time preserves every signed 64-bit instant.

***

### RecordRef

Ƭ **RecordRef**: `string` | `Readonly`\<\{ `series`: [`SeriesOccurrence`](/api/modules/files#seriesoccurrence)  }>

The record an attachment belongs to: a document ID, or a series
occurrence.

***

### GrantRef

Ƭ **GrantRef**: `string` & \{ `__grantRef`: unique `symbol`  }

A grant's lookup identity. It is not a bearer secret: the server checks
its recipient on every read.

***

### AttachmentLocator

Ƭ **AttachmentLocator**: `Readonly`\<\{ `kind`: `"attachment"` ; `record`: [`RecordRef`](/api/modules/files#recordref) ; `field`: `string` ; `file`: [`FileRef`](/api/modules/values#fileref)  }>

A file read through the record field that attaches it. `field` is the
field's path, its segments joined by `/` (JSON pointer escaping, without
the leading slash), such as `source` or `files/0/file`. The locator names
the expected `file` too: a read refuses with `FileAttachmentChanged` when
the field now names another file. It carries no permission; the server
evaluates the route on every new read.

***

### GrantLocator

Ƭ **GrantLocator**: `Readonly`\<\{ `kind`: `"grant"` ; `grant`: [`GrantRef`](/api/modules/files#grantref) ; `file`: [`FileRef`](/api/modules/values#fileref)  }>

A file read through a grant to its recipient.

***

### FileLocator

Ƭ **FileLocator**: [`AttachmentLocator`](/api/modules/files#attachmentlocator) | [`GrantLocator`](/api/modules/files#grantlocator)

Which file to read, and the relationship that authorizes the read.

***

### FileGrant

Ƭ **FileGrant**: [`GrantLocator`](/api/modules/files#grantlocator)

A grant `ctx.files.grant` issued: itself the locator its recipient reads
the file with.

***

### FileFieldPath

Ƭ **FileFieldPath**\<`T`, `Depth`>: `0` extends `1` & `T` ? `string` : `Depth`\[`"length"`] extends `8` ? `never` : `NonNullable`\<`T`> extends [`FileRef`](/api/modules/values#fileref) ? `never` : `NonNullable`\<`T`> extends `string` | `number` | `boolean` | `bigint` | `ArrayBuffer` ? `never` : `NonNullable`\<`T`> extends readonly infer Element\[] ? `NonNullable`\<`Element`> extends [`FileRef`](/api/modules/values#fileref) ? \`$\{number}\` : \`$\{number}/$\{FileFieldPath\<Element, [...Depth, unknown]\>}\` : `NonNullable`\<`T`\> extends `object` ? \{ [Key in keyof NonNullable\<T\> & string]: NonNullable\<NonNullable\<T\>[Key]\> extends FileRef ? FilePointerSegment\<Key\> : \`$\{FilePointerSegment\<Key>}/\$\{FileFieldPath\<NonNullable\<T>\[Key], \[...Depth, unknown]>}\` }\[keyof `NonNullable`\<`T`> & `string`] : `never`

A record's file field paths, inferred from its value type: `source`,
`files/${number}/file`.

#### Type parameters

| Name | Type |
| :- | :- |
| `T` | `T` |
| `Depth` | extends `unknown`\[] = \[] |

## Functions

### attachment

▸ **attachment**\<`Document`>(`document`, `field`): [`AttachmentLocator`](/api/modules/files#attachmentlocator)

Locate the file a record's field attaches, read from the record itself:
`attachment(document, "source")`. The record must hold a file there.

#### Type parameters

| Name | Type |
| :- | :- |
| `Document` | extends `Object` |

#### Parameters

| Name | Type |
| :- | :- |
| `document` | `Document` |
| `field` | [`FileFieldPath`](/api/modules/files#filefieldpath)\<`Document`> |

#### Returns

[`AttachmentLocator`](/api/modules/files#attachmentlocator)

▸ **attachment**(`record`, `field`, `file`): [`AttachmentLocator`](/api/modules/files#attachmentlocator)

Locate a file by its record, field path and expected file, such as a
series occurrence's file property:
`attachment({ series: seriesOccurrence("footage", event) }, "values/file", file)`.

#### Parameters

| Name | Type |
| :- | :- |
| `record` | [`RecordRef`](/api/modules/files#recordref) |
| `field` | `string` |
| `file` | [`FileRef`](/api/modules/values#fileref) |

#### Returns

[`AttachmentLocator`](/api/modules/files#attachmentlocator)

***

### seriesOccurrence

▸ **seriesOccurrence**(`table`, `event`): [`SeriesOccurrence`](/api/modules/files#seriesoccurrence)

A series occurrence as an attachment's record, from the event just read.

#### Parameters

| Name | Type |
| :- | :- |
| `table` | `string` |
| `event` | `Object` |
| `event.seriesId` | `string` |
| `event.eventKey` | `string` |
| `event.time` | `bigint` |

#### Returns

[`SeriesOccurrence`](/api/modules/files#seriesoccurrence)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.