# encore.dev/storage/objects

## Classes

### Bucket

Defines a new Object Storage bucket infrastructure resource.

#### Extends

- [`BucketPerms`](#bucketperms)

#### Implements

- [`Uploader`](#uploader)
- [`SignedUploader`](#signeduploader)
- [`Downloader`](#downloader)
- [`SignedDownloader`](#signeddownloader)
- [`Attrser`](#attrser)
- [`Lister`](#lister)
- [`Remover`](#remover)
- [`PublicUrler`](#publicurler)

#### Constructors

##### Constructor

`new Bucket(name, cfg?): Bucket`

Creates a new bucket with the given name and configuration

###### Parameters

###### name

`string`

###### cfg?

[`BucketConfig`](#bucketconfig)

###### Returns

[`Bucket`](#bucket)

###### Overrides

`BucketPerms.constructor`

#### Properties

##### impl

`impl: Bucket`

#### Methods

##### attrs()

`attrs(name, options?): Promise<ObjectAttrs>`

Returns the object's attributes.
Throws an error if the object does not exist.

###### Parameters

###### name

`string`

###### options?

[`AttrsOptions`](#attrsoptions)

###### Returns

`Promise`\<[`ObjectAttrs`](#objectattrs)\>

###### Implementation of

[`Attrser`](#attrser).[`attrs`](#attrs-1)

##### download()

`download(name, options?): Promise<Buffer>`

Downloads an object from the bucket and returns its contents.

###### Parameters

###### name

`string`

###### options?

[`DownloadOptions`](#downloadoptions)

###### Returns

`Promise`\<`Buffer`\>

###### Implementation of

[`Downloader`](#downloader).[`download`](#download-1)

##### exists()

`exists(name, options?): Promise<boolean>`

Returns whether the object exists in the bucket.
Throws an error on network failure.

###### Parameters

###### name

`string`

###### options?

[`ExistsOptions`](#existsoptions)

###### Returns

`Promise`\<`boolean`\>

###### Implementation of

[`Attrser`](#attrser).[`exists`](#exists-1)

##### list()

`list(options): AsyncGenerator<ListEntry>`

###### Parameters

###### options

[`ListOptions`](#listoptions)

###### Returns

`AsyncGenerator`\<[`ListEntry`](#listentry)\>

###### Implementation of

[`Lister`](#lister).[`list`](#list-1)

##### publicUrl()

`publicUrl(name): string`

Returns the public URL for accessing the object with the given name.
Throws an error if the bucket is not public.

###### Parameters

###### name

`string`

###### Returns

`string`

###### Implementation of

[`PublicUrler`](#publicurler).[`publicUrl`](#publicurl-1)

##### ref()

`ref<P>(): P`

###### Type Parameters

###### P

`P` *extends* [`BucketPerms`](#bucketperms)

###### Returns

`P`

##### remove()

`remove(name, options?): Promise<void>`

Removes an object from the bucket.
Throws an error on network failure.

###### Parameters

###### name

`string`

###### options?

[`DeleteOptions`](#deleteoptions)

###### Returns

`Promise`\<`void`\>

###### Implementation of

[`Remover`](#remover).[`remove`](#remove-1)

##### signedDownloadUrl()

`signedDownloadUrl(name, options?): Promise<SignedDownloadUrl>`

Generate an external URL to allow downloading an object from the bucket.

Anyone with possession of the URL can download the given object without
any additional auth.

###### Parameters

###### name

`string`

###### options?

[`DownloadUrlOptions`](#downloadurloptions)

###### Returns

`Promise`\<[`SignedDownloadUrl`](#signeddownloadurl-2)\>

###### Implementation of

[`SignedDownloader`](#signeddownloader).[`signedDownloadUrl`](#signeddownloadurl-1)

##### signedUploadUrl()

`signedUploadUrl(name, options?): Promise<SignedUploadUrl>`

Generate an external URL to allow uploading an object to the bucket.

Anyone with possession of the URL can write to the given object name
without any additional auth.

###### Parameters

###### name

`string`

###### options?

[`UploadUrlOptions`](#uploadurloptions)

###### Returns

`Promise`\<[`SignedUploadUrl`](#signeduploadurl-2)\>

###### Implementation of

[`SignedUploader`](#signeduploader).[`signedUploadUrl`](#signeduploadurl-1)

##### upload()

```ts
upload(
   name, 
   data, 
options?): Promise<ObjectAttrs>;
```

Uploads an object to the bucket.

###### Parameters

###### name

`string`

###### data

`Buffer`

###### options?

[`UploadOptions`](#uploadoptions)

###### Returns

`Promise`\<[`ObjectAttrs`](#objectattrs)\>

###### Implementation of

[`Uploader`](#uploader).[`upload`](#upload-1)

##### named()

`static named<name>(name): Bucket`

Reference an existing bucket by name.
To create a new storage bucket, use `new StorageBucket(...)` instead.

###### Type Parameters

###### name

`name` *extends* `string`

###### Parameters

###### name

`StringLiteral`\<`name`\>

###### Returns

[`Bucket`](#bucket)

***

### ObjectNotFound

#### Extends

- [`ObjectsError`](#objectserror)

#### Constructors

##### Constructor

`new ObjectNotFound(msg): ObjectNotFound`

###### Parameters

###### msg

`string`

###### Returns

[`ObjectNotFound`](#objectnotfound)

###### Overrides

[`ObjectsError`](#objectserror).[`constructor`](#constructor-2)

***

### ObjectsError

#### Extends

- `Error`

#### Extended by

- [`ObjectNotFound`](#objectnotfound)
- [`PreconditionFailed`](#preconditionfailed)

#### Constructors

##### Constructor

`new ObjectsError(msg): ObjectsError`

###### Parameters

###### msg

`string`

###### Returns

[`ObjectsError`](#objectserror)

###### Overrides

`Error.constructor`

***

### PreconditionFailed

#### Extends

- [`ObjectsError`](#objectserror)

#### Constructors

##### Constructor

`new PreconditionFailed(msg): PreconditionFailed`

###### Parameters

###### msg

`string`

###### Returns

[`PreconditionFailed`](#preconditionfailed)

###### Overrides

[`ObjectsError`](#objectserror).[`constructor`](#constructor-2)

## Interfaces

### Attrser

#### Extends

- [`BucketPerms`](#bucketperms)

#### Methods

##### attrs()

`abstract attrs(name, options?): Promise<ObjectAttrs>`

###### Parameters

###### name

`string`

###### options?

[`AttrsOptions`](#attrsoptions)

###### Returns

`Promise`\<[`ObjectAttrs`](#objectattrs)\>

##### exists()

`abstract exists(name, options?): Promise<boolean>`

###### Parameters

###### name

`string`

###### options?

[`ExistsOptions`](#existsoptions)

###### Returns

`Promise`\<`boolean`\>

***

### AttrsOptions

Options for retrieving the attributes of an object.

#### Properties

##### version?

`optional version?: string`

The object version to retrieve attributes for.
Defaults to the lastest version if unset.

If bucket versioning is not enabled, this option is ignored.

***

### BucketConfig

Configuration options for declaring a Bucket.

#### Properties

##### public?

`optional public?: boolean`

Whether the objects in the bucket should be publicly
accessible, via CDN. Defaults to false if unset.

##### versioned?

`optional versioned?: boolean`

Whether to enable versioning of the objects in the bucket.
Defaults to false if unset.

***

### BucketPerms

#### Extended by

- [`Bucket`](#bucket)
- [`Uploader`](#uploader)
- [`SignedUploader`](#signeduploader)
- [`Downloader`](#downloader)
- [`SignedDownloader`](#signeddownloader)
- [`Attrser`](#attrser)
- [`Lister`](#lister)
- [`PublicUrler`](#publicurler)
- [`Remover`](#remover)

***

### DeleteOptions

Options for deleting an object from a bucket.

#### Properties

##### version?

`optional version?: string`

The object version to delete.
Defaults to the lastest version if unset.

If bucket versioning is not enabled, this option is ignored.

***

### Downloader

#### Extends

- [`BucketPerms`](#bucketperms)

#### Methods

##### download()

`abstract download(name, options?): Promise<Buffer>`

###### Parameters

###### name

`string`

###### options?

[`DownloadOptions`](#downloadoptions)

###### Returns

`Promise`\<`Buffer`\>

***

### DownloadOptions

Options for downloading an object from a bucket.

#### Properties

##### version?

`optional version?: string`

The object version to download.
Defaults to the lastest version if unset.

If bucket versioning is not enabled, this option is ignored.

***

### DownloadUrlOptions

Options for generating a signed download URL.

#### Properties

##### ttl?

`optional ttl?: number`

The expiration time of the url, in seconds from signing. The maximum
value is seven days. If no value is given, a default of one hour is
used.

***

### ExistsOptions

Options for checking the existence of an object.

#### Properties

##### version?

`optional version?: string`

The object version to check for existence.
Defaults to the lastest version if unset.

If bucket versioning is not enabled, this option is ignored.

***

### ListEntry

A single entry returned when listing objects in a bucket.

#### Properties

##### etag

`etag: string`

##### name

`name: string`

##### size

`size: number`

***

### Lister

#### Extends

- [`BucketPerms`](#bucketperms)

#### Methods

##### list()

`abstract list(options): AsyncGenerator<ListEntry>`

###### Parameters

###### options

[`ListOptions`](#listoptions)

###### Returns

`AsyncGenerator`\<[`ListEntry`](#listentry)\>

***

### ListOptions

Options for listing objects in a bucket.

#### Properties

##### limit?

`optional limit?: number`

Maximum number of objects to return. Defaults to no limit.

##### prefix?

`optional prefix?: string`

Only include objects with this prefix in the listing.
If unset, all objects are included.

***

### ObjectAttrs

Describes the attributes of an object stored in a bucket.

#### Properties

##### contentType?

`optional contentType?: string`

##### etag

`etag: string`

##### name

`name: string`

##### size

`size: number`

##### version?

`optional version?: string`

The version of the object, if bucket versioning is enabled.

***

### PublicUrler

#### Extends

- [`BucketPerms`](#bucketperms)

#### Methods

##### publicUrl()

`abstract publicUrl(name): string`

###### Parameters

###### name

`string`

###### Returns

`string`

***

### Remover

#### Extends

- [`BucketPerms`](#bucketperms)

#### Methods

##### remove()

`abstract remove(name, options?): Promise<void>`

###### Parameters

###### name

`string`

###### options?

[`DeleteOptions`](#deleteoptions)

###### Returns

`Promise`\<`void`\>

***

### SignedDownloader

#### Extends

- [`BucketPerms`](#bucketperms)

#### Methods

##### signedDownloadUrl()

`abstract signedDownloadUrl(name, options?): Promise<SignedDownloadUrl>`

###### Parameters

###### name

`string`

###### options?

[`DownloadUrlOptions`](#downloadurloptions)

###### Returns

`Promise`\<[`SignedDownloadUrl`](#signeddownloadurl-2)\>

***

### SignedDownloadUrl

A signed URL that allows downloading an object without additional auth.

#### Properties

##### url

`url: string`

***

### SignedUploader

#### Extends

- [`BucketPerms`](#bucketperms)

#### Methods

##### signedUploadUrl()

`abstract signedUploadUrl(name, options?): Promise<SignedUploadUrl>`

###### Parameters

###### name

`string`

###### options?

[`UploadUrlOptions`](#uploadurloptions)

###### Returns

`Promise`\<[`SignedUploadUrl`](#signeduploadurl-2)\>

***

### SignedUploadUrl

A signed URL that allows uploading an object without additional auth.

#### Properties

##### url

`url: string`

***

### Uploader

#### Extends

- [`BucketPerms`](#bucketperms)

#### Methods

##### upload()

```ts
abstract upload(
   name, 
   data, 
options?): Promise<ObjectAttrs>;
```

###### Parameters

###### name

`string`

###### data

`Buffer`

###### options?

[`UploadOptions`](#uploadoptions)

###### Returns

`Promise`\<[`ObjectAttrs`](#objectattrs)\>

***

### UploadOptions

Options for uploading an object to a bucket.

#### Properties

##### contentType?

`optional contentType?: string`

##### preconditions?

```ts
optional preconditions?: {
  notExists?: boolean;
};
```

###### notExists?

`optional notExists?: boolean`

***

### UploadUrlOptions

Options for generating a signed upload URL.

#### Properties

##### ttl?

`optional ttl?: number`

The expiration time of the url, in seconds from signing. The maximum
value is seven days. If no value is given, a default of one hour is
used.

## Type Aliases

### ReadWriter

`type ReadWriter = Uploader & SignedUploader & Downloader & SignedDownloader & Attrser & Lister & Remover`
