Storage

The @aziontech/storage package is the Azion Lib library for Object Storage. Its functions create, list, read, update, and delete buckets and the objects inside them through Azion API v4. Each function takes one object argument and returns a response envelope instead of throwing.

Install the package:

The samples on this page are TypeScript ES modules that use top-level await, and they run in Node.js. They import types with import type, which keeps them loadable when the type annotations are stripped.

Authentication

The functions read your personal token from the AZION_TOKEN environment variable. A client created with createClient takes the token in its token field instead.

For how the Azion Lib packages resolve the token and the debug setting, refer to How Azion Lib works.

Response envelope

Every function returns an AzionStorageResponse object, { data?, error? }. On success, data holds the bucket, the object, or the list. On failure, error holds { message, operation }, where operation names the call that failed, such as create bucket or get object by key.

A successful deleteBucket or deleteObject returns no data: the envelope holds only error, set to undefined. Check error after a delete, not data.

createClient

Creates a client that holds a token and request options and exposes the bucket functions as methods. createClient is also the default export of the package.

Returns an AzionStorageClient. Its methods take the same object as the matching function on this page, without options. The client has no object methods: read and write objects with the object functions or the bucket methods.

This sample creates a client and a bucket with it:

Output:

setupStorage

Returns a bucket by its name, and creates it first when it does not exist. The function reads the bucket, and only when that read finds nothing does it create one with the workloads_access you pass.

Returns data as an AzionBucket, existing or created. The bucket carries the bucket methods, so you can write to it right away.

This sample gets a bucket that exists and writes a JSON object to it:

Output:

createBucket

Creates a bucket.

Returns data as the created AzionBucket. A bucket has no id: every other function finds it by name.

Output:

getBuckets

Lists the buckets of the account, one page at a time.

Returns data as an AzionBucketCollection: buckets holds the page, and count holds the number of buckets in the account, not the length of the page.

Output:

getBucket

Returns one bucket by its name.

Returns data as an AzionBucket, with the bucket methods. A name that matches no bucket returns error with the message The specified bucket does not exist..

Output:

updateBucket

Changes the access level of a bucket.

Returns data as the updated AzionBucket.

Output:

deleteBucket

Deletes a bucket by its name. The API deletes a bucket only while it holds no objects, and not within 24 hours of the last object deletion in it. A bucket that never held an object is deleted at once.

On success, the envelope holds no data, so the sample checks error. A refused delete fills error; the messages are in Errors.

Output:

createObject

Creates an object in a bucket.

Returns data as an AzionBucketObject with key, content_type, and state. The created object carries no content; read it back with getObjectByKey.

Output:

getObjectByKey

Returns one object, with its content, by its key.

Returns data as an AzionBucketObject with key and content. A key that matches no object returns error with the message The specified bucket object does not exist..

Output:

getObjects

Lists the objects of a bucket.

Returns data as an AzionBucketObjects: objects and count. Each listed object carries key, size, and last_modified. The API also returns is_folder on each object, which the type does not declare.

Output:

updateObject

Replaces the content of an object.

Returns data as the updated AzionBucketObject, with key and content.

Output:

deleteObject

Deletes an object from a bucket.

On success, the envelope holds no data, so the sample checks error. A key that matches no object fills error with The specified bucket object does not exist.. Deleting an object also blocks deleteBucket on that bucket for 24 hours.

Output:

Bucket methods

A bucket that getBucket, setupStorage, or createBucket returns carries five methods that act on that bucket. Each takes one object and returns the same envelope as the matching function:

This sample reads a bucket, then lists, reads, updates, and deletes an object through its methods:

Output:

Errors

A failed call returns these messages in error.message. error.operation names the call, such as get all buckets or delete bucket.

Types

The package exports these types. Import them with import type.

AzionStorageClient

The client that createClient returns. Every method takes one object.

AzionClientOptions

Request options that every function takes in options, and createClient takes for all its calls.

AzionEnvironment

The environment a client calls.

AzionStorageResponse

The envelope every function returns. For how to read it, refer to Response envelope.

AzionBucket

A bucket.

AzionBucketCollection

A page of buckets.

AzionBucketCollectionParams

Pagination and filtering for getBuckets.

AzionBucketObject

An object in a bucket.

AzionBucketObjects

A list of objects.

AzionObjectCollectionParams

The limit for getObjects.

AzionDeletedBucket

The type deleteBucket declares for data. A successful delete returns no data.

AzionDeletedBucketObject

The type deleteObject declares for data. A successful delete returns no data.

ContentObjectStorage

The content an object takes.

EdgeAccessType

The access level of a bucket: what the Azion platform may do with it when an application serves it. For what each value allows, refer to Access levels.

Related resources