Azion `Storage` library

The Edge Storage library provides methods to interact with the Edge Storage API, allowing you to manage buckets and objects. This client is configurable and supports both debug mode and environment variable-based configuration.

Go to Azion Libraries Overview

You can interact with the API using a client or calling the methods directly from the library. When making direct calls, you can use the environment variables to configure the client without passing the token and debug parameters directly.

This is an example of how a .env file with your environment variables may look like:

AZION_TOKEN=<your-api-token>
AZION_DEBUG=true

Variable	Description
`AZION_TOKEN`	Your Azion API token.
`AZION_DEBUG`	Enable debug mode (true/false).

If you want to create a specific client for interacting with Storage, do it by calling the createClient method from the library:

import { createClient } from 'azion/storage';
import type { AzionStorageClient, AzionStorageResponse, AzionStorage } from 'azion/storage';

const client: AzionStorageClient = createClient({ token: 'your-api-token', options: { debug: true } });

const { data, error } = await client.createBucket('my-new-bucket');
if (data) {
  console.log(`Bucket created with ID: ${data.id}`);
} else {
  console.error('Failed to create bucket', error);
}

The createClient method has the following parameters and return value:

Parameters:

Parameter	Type	Description
`config`	`Partial<{ token: string; options?: OptionsParams }>`	Configuration options for the Storage client.

Returns:

Return Type	Description
`AzionStorageClient`	An object with methods to interact with Storage.

Usage

`createBucket`

Creates a new bucket.

Example:

import { createBucket } from 'azion/storage';
import type { AzionStorageResponse, AzionBucket } from 'azion/storage';
const { data, error }: AzionStorageResponse<AzionBucket> = await createBucket({
  name: 'my-new-bucket',
  edge_access: 'public',
});
if (data) {
  console.log(`Bucket created with name: ${data.name}`);
} else {
  console.error('Failed to create bucket', error);
}

Parameters:

Parameter	Type	Description
`name`	`string`	The name of the new bucket.
`edge_access`	`string`	The `edge access` configuration for the bucket.
`options?`	`AzionClientOptions`	Optional parameters for the request.

Returns:

Return Type	Description
`Promise<AzionStorageResponse<AzionBucket>>`	The created bucket object or error.

`deleteBucket`

Deletes a bucket by its name.

Example:

import { deleteBucket, AzionDeletedBucket, AzionStorageResponse } from 'azion/storage';

const { data, error }: AzionStorageResponse<AzionDeletedBucket> = await deleteBucket({ name: 'my-bucket' });
if (data) {
  console.log(`Bucket ${data.name} deleted successfully`);
} else {
  console.error('Failed to delete bucket', error);
}

Parameters:

Parameter	Type	Description
`name`	`string`	The name of the bucket to be deleted.
`debug?`	`boolean`	Enables debug mode for detailed logging.

Returns:

Return Type	Description
`Promise<AzionStorageResponse<AzionDeletedBucket>>`	Object confirming deletion or error.

`getBuckets`

Retrieves a list of buckets with optional filtering and pagination.

Example:

import { getBuckets, AzionStorageResponse, AzionBucketCollection } from 'azion/storage';

const { data: buckets, error }: AzionStorageResponse<AzionBucketCollection> = await getBuckets({
  params: { page: 1, page_size: 10 },
});
if (buckets) {
  console.log(`Retrieved ${buckets.count} buckets`);
} else {
  console.error('Failed to retrieve buckets', error);
}

Parameters:

Parameter	Type	Description
`options?`	`AzionBucketCollectionOptions`	Optional parameters for filtering and pagination.
`page?`	`number`	The page number for pagination.
`page_size?`	`number`	The number of items per page.
`debug?`	`boolean`	Enables debug mode for detailed logging.

Returns:

Return Type	Description
`Promise<AzionStorageResponse<AzionBucketCollection>>`	Array of bucket objects or error.

`getBucket`

Retrieves a bucket by its name.

Example:

import { getBucket, AzionBucket } from 'azion/storage';

const { data: bucket, error }: AzionStorageResponse<AzionBucket> = await getBucket({ name: 'my-bucket' });
if (bucket) {
  console.log(`Retrieved bucket: ${bucket.name}`);
} else {
  console.error('Bucket not found', error);
}

Parameters:

Parameter	Type	Description
`name`	`string`	The name of the bucket to be retrieved.
`debug?`	`boolean`	Enables debug mode for detailed logging.

Returns:

Return Type	Description
`Promise<AzionStorageResponse<AzionBucket>>`	The retrieved bucket object or error if not found.

`updateBucket`

Updates an existing bucket.

Example:

import { updateBucket, AzionBucket, AzionStorageResponse } from 'azion/storage';

const { data: updatedBucket, error }: AzionStorageResponse<AzionBucket> | null = await updateBucket({
  name: 'my-bucket',
  edge_access: 'private',
});
if (updatedBucket) {
  console.log(`Bucket updated: ${updatedBucket.name}`);
} else {
  console.error('Failed to update bucket', error);
}

Parameters:

Parameter	Type	Description
`name`	`string`	The name of the bucket to be updated.
`edge_access`	`string`	The new `edge access` configuration for the bucket.
`debug?`	`boolean`	Enables debug mode for detailed logging.

Returns:

Return Type	Description
`Promise<AzionStorageResponse<AzionBucket>>`	The updated bucket object or error if update failed.

`createObject`

Creates a new object in a specific bucket.

Example:

import { createObject, AzionBucketObject, AzionStorageResponse } from 'azion/storage';

const { data: newObject, error }: AzionStorageResponse<AzionBucketObject> = await createObject({
  bucketName: 'my-bucket',
  key: 'new-file.txt',
  file: 'File content',
});
if (newObject) {
  console.log(`Object created with key: ${newObject.key}`);
  console.log(`Object content: ${newObject.content}`);
} else {
  console.error('Failed to create object', error);
}

Parameters:

Parameter	Type	Description
`bucketName`	`string`	The name of the bucket to create the object in.
`objectKey`	`string`	Key (name) of the object to be created.
`file`	`string`	The content of the file to be uploaded.
`debug?`	`boolean`	Enables debug mode for detailed logging.

Returns:

Return Type	Description
`Promise< AzionBucketObject \| null>`	The created object or null if creation failed.

`getObjectByKey`

Retrieves an object from a specific bucket by its key.

Example:

import { getObjectByKey, AzionBucketObject, AzionStorageResponse } from 'azion/storage';

const { data: object, error }: AzionStorageResponse<AzionBucketObject> = await getObjectByKey({
  bucketName: 'my-bucket',
  key: 'file.txt',
});
if (object) {
  console.log(`Retrieved object: ${object.key}`);
} else {
  console.error('Object not found', error);
}

Parameters:

Parameter	Type	Description
`bucketName`	`string`	The name of the bucket containing the object.
`objectKey`	`string`	The key of the object to be retrieved.
`debug?`	`boolean`	Enables debug mode for detailed logging.

Returns:

Return Type	Description
`Promise< AzionBucketObject	null>`

`getObjects`

Retrieves a list of objects in a specific bucket.

Example:

import { getObjects, AzionBucketObject, AzionStorageResponse } from 'azion/storage';

const { data: objectResult, error }: AzionStorageResponse<AzionBucketObjects> = await getObjects({
  bucketName: 'my-bucket',
});
if (objectResult) {
  console.log(`Retrieved ${objectResult.count} objects from the bucket`);
} else {
  console.error('Failed to retrieve objects', error);
}

Parameters:

Parameter	Type	Description
`bucketName`	`string`	The name of the bucket to retrieve objects from.
`debug?`	`boolean`	Enables debug mode for detailed logging.

Returns:

Return Type	Description
`Promise<AzionStorageResponse<AzionBucketObjects>>`	Array of bucket objects or error.

`updateObject`

Updates an existing object in a specific bucket.

Example:

import { updateObject, AzionBucketObject } from 'azion/storage';

const { data: updatedObject, error }: AzionStorageResponse<AzionBucketObject> = await updateObject({
  bucketName: 'my-bucket',
  key: 'file.txt',
  file: 'Updated content',
});
if (updatedObject) {
  console.log(`Object updated: ${updatedObject.key}`);
  console.log(`New content: ${updatedObject.content}`);
} else {
  console.error('Failed to update object', error);
}

Parameters:

Parameter	Type	Description
`bucketName`	`string`	The name of the bucket containing the object.
`objectKey`	`string`	The key of the object to be updated.
`file`	`string`	The new content of the file.
`debug?`	`boolean`	Enables debug mode for detailed logging.

Returns:

Return Type	Description
`Promise<AzionStorageResponse<AzionBucketObject>>`	The updated object or error if update failed.

`deleteObject`

Deletes an object from a specific bucket.

Example:

import { deleteObject, AzionDeletedBucketObject, AzionStorageResponse } from 'azion/storage';

const { data: result, error }: AzionStorageResponse<AzionDeletedBucketObject> = await deleteObject({
  bucketName: 'my-bucket',
  key: 'file.txt',
});
if (result) {
  console.log(`Object ${result.key} deleted successfully`);
} else {
  console.error('Failed to delete object', error);
}

Parameters:

Parameter	Type	Description
`bucketName`	`string`	The name of the bucket containing the object.
`objectKey`	`string`	The key of the object to be deleted.
`debug?`	`boolean`	Enables debug mode for detailed logging.

Returns:

Return Type	Description
`Promise<AzionStorageResponse<AzionDeletedBucketObject>>`	Confirmation of deletion or error if deletion failed.

Types

These are the types used by the Storage library and its methods:

`ClientConfig`

Configuration options for the Storage client.

Parameter	Type	Description
`token?`	`string`	Your Azion API token.
`debug?`	`boolean`	Enables debug mode for detailed logging.

`StorageClient`

An object with methods to interact with Storage.

Method	Parameters	Return Type
`getBuckets`	`options?: BucketCollectionOptions`	`Promise<AzionStorageResponse<AzionBucketCollection>>`
`createBucket`	`name: string, edge_access: string`	`Promise<AzionStorageResponse<AzionBucket>>`
`updateBucket`	`name: string, edge_access: string`	`Promise<AzionStorageResponse<AzionBucket>>`
`deleteBucket`	`name: string`	`Promise<AzionStorageResponse<AzionDeletedBucket>>`
`getBucket`	`name: string`	`Promise<AzionStorageResponse<AzionBucket>>`

`AzionStorageResponse<T>`

The response object from a bucket operation.

Property	Type	Description
`data`	`T` (optional)	The data generic object.
`error`	`{ message: string; operation: string; }` (optional)	The error details if the operation fails.

`AzionBucket`

The bucket object.

Property	Type	Description
`name`	`string`	The name of the bucket.
`edge_access`	`string` (optional)	The `edge access` of the bucket.
`state`	`'executed' \| 'pending'` (optional)	The state of the bucket.
`getObjects`	`() => Promise<AzionStorageResponse<AzionBucketObjects>>` (optional)	A method to get all objects in the bucket.
`getObjectByKey`	`(objectKey: string) => Promise<AzionStorageResponse<AzionBucketObject>>` (optional)	A method to get an object by its key.
`createObject`	`(objectKey: string, file: string) => Promise<AzionStorageResponse<AzionBucketObject>>` (optional)	A method to create a new object in the bucket.
`updateObject`	`(objectKey: string, file: string) => Promise<AzionStorageResponse<AzionBucketObject>>` (optional)	A method to update an existing object in the bucket.
`deleteObject`	`(objectKey: string) => Promise<AzionStorageResponse<AzionDeletedBucketObject>>` (optional)	A method to delete an object from the bucket.

`AzionBucketObject`

The bucket object.

Property	Type	Description
`key`	`string`	The key of the object.
`state`	`'executed' \| 'pending'` (optional)	The state of the object.
`size`	`number` (optional)	The size of the object.
`last_modified`	`string` (optional)	The last modified date of the object.
`content_type`	`string` (optional)	The content type of the object.
`content`	`string` (optional)	The content of the object.

`AzionDeletedBucket`

The response object from a delete bucket request.

Property	Type	Description
`name`	`string`	The name of the bucket.
`state`	`‘executed'	'pending’`

`AzionDeletedBucketObject`

The response object from a delete object request.

Property	Type	Description
`key`	`string`	The key of the deleted object.
`state`	`‘executed'	'pending’`