@tigrisdata/storage

Tigris is a high-performance object storage system designed for multi-cloud environments. Tigris Storage SDK provides a simple interface and minimal configuration that lets you get started quickly and integrate Tigris into your application. It is built on top of Tigris Object Storage API and offers all the functionality of Tigris.

Installation

``bash


NPM

npm install @tigrisdata/storage

YARN

yarn add @tigrisdata/storage
`

Getting Started

Getting started with Tigris Storage SDK is easy. First, you need to create a Tigris account and create a bucket.

$3

1. Create a Tigris account at storage.new
2. Create a bucket at console.tigris.dev/createbucket
3. Create an access key at console.tigris.dev/createaccesskey

$3

In your project root, create a .env file if it doesn't exist already and put the following content in it. Replace the values with actual values you obtained from above steps.

`bash
TIGRIS_STORAGE_ACCESS_KEY_ID=tid_access_key_id
TIGRIS_STORAGE_SECRET_ACCESS_KEY=tsec_secret_access_key
TIGRIS_STORAGE_BUCKET=bucket_name
`

Authentication

After you have created an access key, you can set the environment variables in your .env file:

`bash
TIGRIS_STORAGE_ACCESS_KEY_ID=tid_access_key_id
TIGRIS_STORAGE_SECRET_ACCESS_KEY=tsec_secret_access_key
TIGRIS_STORAGE_BUCKET=bucket_name
`

Alternatively, all methods accept an optional config parameter that allows you to override the default environment configuration:

`ts
type TigrisStorageConfig = {
bucket?: string;
accessKeyId?: string;
secretAccessKey?: string;
endpoint?: string;
};
`

$3

#### Use environment variables (default)

`ts
const result = await list();
`

#### Override with custom config

`ts
const result = await list({
config: {
bucket: 'my-bucket-name',
accessKeyId: 'tigris-access-key',
secretAccessKey: 'tigris-secret-key',
},
});
`

#### Override only specific values

`ts
const result = await get('object.txt', 'string', {
config: {
bucket: 'different-bucket',
},
});
`

Responses

All methods return a generic response of type TigrisStorageResponse. If there is an error, the error property will be set. If there is a successful response, the data property will be set. This allows for a better type safety and error handling.

`ts
type TigrisStorageResponse = {
data?: T;
error?: E;
};
`

$3

`ts
const objectResult = await get('photo.jpg', 'file');
if (objectResult.error) {
console.error('Error downloading object:', objectResult.error);
} else {
console.log('Object name:', objectResult.data?.name);
console.log('Object size:', objectResult.data?.size);
console.log('Object type:', objectResult.data?.type);
}
`

Uploading an object

put function can be used to upload a object to a bucket.

$3

`ts
put(path: string, body: string | ReadableStream | Blob | Buffer, options?: PutOptions): Promise>;
`

put accepts the following parameters:

- path: (Required) A string specifying the base value of the return URL
- body: (Required) A blob object as ReadableStream, String, ArrayBuffer or Blob based on these supported body types
- options: (Optional) A JSON object with the following optional parameters:

#### options

| Parameter | Required | Values |
| ------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| access | No | The access level for the object. Possible values are public and private. |
| addRandomSuffix | No | Whether to add a random suffix to the object name. Default is false. |
| allowOverwrite | No | Whether to allow overwriting the object. Default is true. |
| contentType | No | Set the content type of the object. If not provided, the content type will be inferred from the extension of the path. |
| contentDisposition | No | Set the content disposition of the object. Possible values are inline and attachment. Default is inline. Use attachment for downloadable files. |
| multipart | No | Pass multipart: true when uploading large objects. It will split the object into multiple parts and upload them in parallel. |
| abortController | No | An AbortController instance to abort the upload. |
| onUploadProgress | No | Callback to track upload progress: onUploadProgress({loaded: number, total: number, percentage: number}). |
| config | No | A configuration object to override the default configuration. |

In case of successful upload, the data property will be set to the upload and contains the following properties:

- contentDisposition: content disposition of the object
- contentType: content type of the object
- modified: Last modified date of the object
- path: Path to the object
- size: Size of the object
- url: A presigned URL to the object if the object is uploaded with access set to private, otherwise unsigned public URL for the object

$3

#### Simple upload

`ts
const result = await put('simple.txt', 'Hello, World!');
if (result.error) {
console.error('Error uploading object:', result.error);
} else {
console.log('Object uploaded successfully:', result.data);
}
`

#### Uploading a large object

`ts
const result = await put('large.mp4', fileStream, {
multipart: true,
onUploadProgress: ({ loaded, total, percentage }) => {
console.log(Uploaded ${loaded} of ${total} bytes (${percentage}%));
},
});
`

#### Prevent overwriting

`ts
const result = await put('config.json', configuration, {
allowOverwrite: false,
});
`

#### Cancel an upload

`ts
const abortController = new AbortController();

const result = await put('large.mp4', fileStream, {
abortController: abortController,
});

function cancelUpload() {
abortController.abort();
}

// Cancel Upload
`

Downloading an object

get function can be used to get/download a object from a bucket.

$3

`ts
get(path: string, format: "string" | "file" | "stream", options?: GetOptions): Promise>;
`

get accepts the following parameters:

- path: (Required) A string specifying the path to the object
- format: (Required) A string specifying the format of the object. Possible values are string, file, and stream.
- options: (Optional) A JSON object with the following optional parameters:

#### options

| Parameter | Required | Values |
| ------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| contentDisposition | No | Set the content disposition of the object. Possible values are inline and attachment. Default is inline. Use attachment for downloadable files. |
| contentType | No | Set the content type of the object. If not provided, content type set when the object is uploaded will be used. |
| encoding | No | Set the encoding of the object. Default is utf-8. |
| snapshotVersion | No | Snapshot version of the bucket. |
| config | No | A configuration object to override the default configuration. |

In case of successful get, the data contains the object in the format specified by the format parameter.

$3

#### Get an object as a string

`ts
const result = await get('object.txt', 'string');

if (result.error) {
console.error('Error getting object:', result.error);
} else {
console.log('Object:', result.data);
// output: "Hello, World!"
}
`

#### Get an object as a file

`ts
const result = await get('object.pdf', 'file', {
contentDisposition: 'attachment',
contentType: 'application/pdf',
encoding: 'utf-8',
});

if (result.error) {
console.error('Error getting object:', result.error);
} else {
console.log('Object:', result.data);
}
`

#### Get an object as a stream

`ts
const result = await get('video.mp4', 'stream', {
contentDisposition: 'attachment',
contentType: 'video/mp4',
encoding: 'utf-8',
});

if (result.error) {
console.error('Error getting object:', result.error);
} else {
const reader = result.data?.getReader();
// Process stream...
reader?.read().then((result) => {
console.log(result);
});
}
`

Object metadata

head function can be used to get the metadata of an object from a bucket.

$3

`ts
head(path: string, options?: HeadOptions): Promise>
`

head accepts the following parameters:

- path: (Required) A string specifying the path to the object
- options: (Optional) A JSON object with the following optional parameters:

#### options

| Parameter | Required | Values |
| --------------- | ------------ | -------------------------------------------------------------------------------- |
| snapshotVersion | No | Snapshot version of the bucket. |
| config | No | A configuration object to override the default configuration. |

In case of successful head, the data property will be set to the metadata of the object and contains the following properties:

- contentDisposition: content disposition of the object
- contentType: content type of the object
- modified: Last modified date of the object
- path: Path to the object
- size: Size of the object
- url: A presigned URL to the object if the object is downloaded with access set to private, otherwise unsigned public URL for the object

$3

#### Get object metadata

`ts
const result = await head('object.txt');

if (result.error) {
console.error('Error getting object metadata:', result.error);
} else {
console.log('Object metadata:', result.data);
// output: {
// contentDisposition: "inline",
// contentType: "text/plain",
// modified: "2023-01-15T08:30:00Z",
// path: "object.txt",
// size: 12,
// url: "https://tigris-example.t3.storage.dev/object.txt",
// }
}
`

Deleting an object

remove function can be used to delete an object from a bucket.

$3

`ts
remove(path: string, options?: RemoveOptions): Promise>;
`

remove accepts the following parameters:

- path: (Required) A string specifying the path to the object
- options: (Optional) A JSON object with the following optional parameters:

#### options

| Parameter | Required | Values |
| ------------- | ------------ | -------------------------------------------------------------------------------- |
| config | No | A configuration object to override the default configuration. |

In case of successful remove, the data property will be set to undefined and the object will be deleted.

$3

#### Delete an object

`ts
const result = await remove('object.txt');

if (result.error) {
console.error('Error deleting object:', result.error);
} else {
console.log('Object deleted successfully');
}
`

Presigning an object

getPresignedUrl function can be used to presign an object from a bucket and retreive the presigned URL.

$3

`ts
getPresignedUrl(path: string, options: GetPresignedUrlOptions): Promise>
`

getPresignedUrl accepts the following parameters:

- path: (Required) A string specifying the path to the object
- options: (Optional) A JSON object with the following optional parameters:

#### options

| Parameter | Required | Values |
| ------------- | ------------ | ---------------------------------------------------------------------------------------- |
| operation | No | Specify the operation to use for the presigned URL. Possible values are get and put. |
| expiresIn | No | The expiration time of the presigned URL in seconds. Default is 3600 seconds (1 hour). |
| contentType | No | The content type of the object. |
| config | No | A configuration object to override the default configuration. |

In case of successful getPresignedUrl, the data property will be set to the presigned URL and contains the following properties:

- url: The presigned URL
- method: The method used to get the presigned URL
- expiresIn: The expiration time of the presigned URL

$3

#### Get a presigned URL for a GET operation

`ts
const result = await getPresignedUrl('object.txt', { operation: 'get' });

if (result.error) {
console.error('Error getting presigned URL:', result.error);
} else {
console.log('Presigned URL:', result.data.url);
}
`

#### Get a presigned URL for a PUT operation

`ts
const result = await getPresignedUrl('object.txt', { operation: 'put' });
`

Listing objects

list function can be used to list objects from a bucket.

$3

`ts
list(options?: ListOptions): Promise>;
`

list accepts the following parameters:

- options: (Optional) A JSON object with the following optional parameters:

#### options

| Parameter | Required | Values |
| --------------- | ------------ | -------------------------------------------------------------------------------- |
| delimiter | No | A delimiter is a character that you use to group keys. |
| prefix | No | Limits the items to keys that begin with the specified prefix. |
| limit | No | The maximum number of objects to return. By default, returns up to 100 objects. |
| paginationToken | No | The pagination token to continue listing objects from the previous request. |
| snapshotVersion | No | Snapshot version of the bucket. |
| config | No | A configuration object to override the default configuration. |

In case of successful list, the data property will be set to the list of objects and contains the following properties:

- items: The list of objects
- paginationToken: The pagination token to continue listing objects for next page.
- hasMore: Whether there are more objects to list.

$3

#### List objects

`ts
const result = await list();

if (result.error) {
console.error('Error listing objects:', result.error);
} else {
console.log('Objects:', result.data);
}
`

#### List objects with pagination

`ts
const allFiles: Item[] = [];
let currentPage = await list({ limit: 10 });

if (currentPage.data) {
allFiles.push(...currentPage.data.items);

while (currentPage.data?.hasMore && currentPage.data?.paginationToken) {
currentPage = await list({
limit: 10,
paginationToken: currentPage.data?.paginationToken,
});

if (currentPage.data) {
allFiles.push(...currentPage.data.items);
} else if (currentPage.error) {
console.error('Error during pagination:', currentPage.error);
break;
}
}
}

console.log(allFiles);
`

Creating a bucket

createBucket function can be used to create a new bucket.

$3

`ts
createBucket(bucketName: string, options?: CreateBucketOptions): Promise>;
`

createBucket accepts the following parameters:

- bucketName: (Required) A string specifying the name of the bucket to create
- options: (Optional) A JSON object with the following optional parameters:

#### options

| Parameter | Required | Values |
| -------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| access | No | public or private. If set to public, objects in this bucket will be publicly readable. Default value is private |
| consistency | No | default or strict. Default value is default. You can read more about consistency here |
| defaultTier | No | STANDARD, STANDARD_IA, GLACIER or GLACIER_IR. This is default object tier for all objects uploaded to it. Default is STANDARD |
| enableSnapshot | No | Enable snapshot functionality for the bucket. Default is false. Please note only the Standard storage tier is supported for snapshot-enabled buckets |
| region | No | By default, Global. Read more about Bucket Regions here |
| sourceBucketName | No | The name of the source bucket to fork from. |
| sourceBucketSnapshot | No | The snapshot version of the source bucket to fork from. |
| config | No | A configuration object to override the default configuration. |

In case of successful createBucket, the data property will be set and contains the following properties:

- isSnapshotEnabled: Whether snapshot functionality is enabled for the bucket
- hasForks: Whether the bucket has forks
- sourceBucketName: The name of the source bucket (if this is a fork bucket)
- sourceBucketSnapshot: The snapshot version of the source bucket (if this is a fork bucket)

$3

#### Create a regular bucket

`ts
const result = await createBucket('my-new-bucket');

if (result.error) {
console.error('Error creating bucket:', result.error);
} else {
console.log('Bucket created successfully:', result.data);
}
`

#### Create a bucket with snapshot enabled

`ts
const result = await createBucket('my-snapshot-bucket', {
enableSnapshot: true,
});

if (result.error) {
console.error('Error creating bucket:', result.error);
} else {
console.log('Bucket created with snapshot enabled:', result.data);
}
`

#### Create a bucket as a fork of another bucket

`ts
const result = await createBucket('my-forked-bucket', {
sourceBucketName: 'parent-bucket',
sourceBucketSnapshot: '1751631910169675092',
});

if (result.error) {
console.error('Error creating forked bucket:', result.error);
} else {
console.log('Forked bucket created:', result.data);
}
`

Getting bucket information

getBucketInfo function can be used to retrieve information about a specific bucket.

$3

`ts
getBucketInfo(bucketName: string, options?: GetBucketInfoOptions): Promise>;
`

getBucketInfo accepts the following parameters:

- bucketName: (Required) A string specifying the name of the bucket
- options: (Optional) A JSON object with the following optional parameters:

#### options

| Parameter | Required | Values |
| ------------- | ------------ | -------------------------------------------------------------------------------- |
| config | No | A configuration object to override the default configuration. |

In case of successful getBucketInfo, the data property will be set and contains the following properties:

- isSnapshotEnabled: Whether snapshot is enabled for the bucket
- hasForks: Whether the bucket has forks
- sourceBucketName: The name of the source bucket (if the bucket is a fork)
- sourceBucketSnapshot: The snapshot version of the source bucket (if the bucket is a fork)

$3

#### Get bucket information

`ts
const result = await getBucketInfo('my-bucket');

if (result.error) {
console.error('Error getting bucket info:', result.error);
} else {
console.log('Bucket info:', result.data);
// output: {
// isSnapshotEnabled: true,
// hasForks: false,
// sourceBucketName: undefined,
// sourceBucketSnapshot: undefined
// }
}
`

Listing buckets

listBuckets function can be used to list all buckets that the user has access to.

$3

`ts
listBuckets(options?: ListBucketsOptions): Promise>;
`

listBuckets accepts the following parameters

- options: (Optional) A JSON object with the following optional parameters:

#### options

| Parameter | Required | Values |
| --------------- | ------------ | -------------------------------------------------------------------------------- |
| limit | No | The maximum number of buckets to return. |
| paginationToken | No | The pagination token to continue listing buckets from the previous request. |
| config | No | A configuration object to override the default configuration. |

In case of successful list, the data property will be set to the list of buckets and contains the following properties:

- buckets: The list of buckets
- owner: The owner of the buckets
- paginationToken: The pagination token to continue listing objects for next page.

$3

#### List buckets

`ts
const result = await listBuckets();

if (result.error) {
console.error('Error listing buckets:', result.error);
} else {
console.log('Buckets:', result.data);
}
`

Deleting a bucket

removeBucket function can be used to delete a bucket.

$3

`ts
removeBucket(bucketName: string, options?: RemoveBucketOptions): Promise>;
`

removeBucket accepts the following parameters:

- bucketName: (Required) A string specifying the name of the bucket
- options: (Optional) A JSON object with the following optional parameters:

#### options

| Parameter | Required | Values |
| ------------- | ------------ | -------------------------------------------------------------------------------- |
| force | No | When provided, forcefully delete the bucket. |
| config | No | A configuration object to override the default configuration. |

In case of successful removeBucket, the data property will be set to undefined and the bucket will be deleted.

$3

#### Delete a bucket

`ts
const result = await removeBucket('my-bucket');

if (result.error) {
console.error('Error deleting bucket:', result.error);
} else {
console.log('Bucket deleted successfully');
}
`

Creating a bucket snapshot

createBucketSnapshot function can be used to create a snapshot of a bucket at a specific point in time.

$3

`ts
createBucketSnapshot(options?: CreateBucketSnapshotOptions): Promise>;
createBucketSnapshot(sourceBucketName?: string, options?: CreateBucketSnapshotOptions): Promise>;
`

createBucketSnapshot accepts the following parameters:

- sourceBucketName: (Optional) A string specifying the name of the bucket to snapshot. If not provided, uses the bucket from environment configuration.
- options: (Optional) A JSON object with the following optional parameters:

#### options

| Parameter | Required | Values |
| ------------- | ------------ | -------------------------------------------------------------------------------- |
| name | No | A name for the snapshot. |
| config | No | A configuration object to override the default configuration. |

In case of successful createBucketSnapshot, the data property will be set and contains the following properties:

- snapshotVersion: The version identifier of the created snapshot

$3

#### Create a snapshot

`ts
const result = await createBucketSnapshot();

if (result.error) {
console.error('Error creating snapshot:', result.error);
} else {
console.log('Snapshot created:', result.data);
// output: { snapshotVersion: "1751631910169675092" }
}
`

#### Create a named snapshot for a specific bucket

`ts
const result = await createBucketSnapshot('my-bucket', {
name: 'backup-before-migration',
});

if (result.error) {
console.error('Error creating snapshot:', result.error);
} else {
console.log('Named snapshot created:', result.data);
}
`

Listing bucket snapshots

listBucketSnapshots function can be used to list all snapshots for a bucket.

$3

`ts
listBucketSnapshots(options?: ListBucketSnapshotsOptions): Promise>;
listBucketSnapshots(sourceBucketName?: string, options?: ListBucketSnapshotsOptions): Promise>;
`

listBucketSnapshots accepts the following parameters:

- sourceBucketName: (Optional) A string specifying the name of the bucket. If not provided, uses the bucket from environment configuration.
- options: (Optional) A JSON object with the following optional parameters:

#### options

| Parameter | Required | Values |
| ------------- | ------------ | -------------------------------------------------------------------------------- |
| config | No | A configuration object to override the default configuration. |

In case of successful listBucketSnapshots, the data property will be set to an array of snapshots, each containing:

- name: The name of the snapshot (if provided when created)
- version: The version identifier of the snapshot
- creationDate: The date when the snapshot was created

$3

#### List snapshots for the default bucket

`ts
const result = await listBucketSnapshots();

if (result.error) {
console.error('Error listing snapshots:', result.error);
} else {
console.log('Snapshots:', result.data);
// output: [
// {
// name: "backup-before-migration",
// version: "1751631910169675092",
// creationDate: Date("2023-01-15T08:30:00Z")
// }
// ]
}
`

#### List snapshots for a specific bucket

`ts
const result = await listBucketSnapshots('my-bucket');

if (result.error) {
console.error('Error listing snapshots:', result.error);
} else {
console.log('Snapshots for my-bucket:', result.data);
}
`

Client Uploads

Amongst all the other great features of Tigris, free egress fees is another example of what makes us stand out from other providers. We care about the bandwidth costs and we want to make it as cheap as possible for you to use Tigris. That's why we've made it so that you can upload files directly to Tigris from the client side.

We leverage the presigned URLs features to allow you to upload files directly to Tigris from the client side.

Client side uploads are a great way to upload objects to a bucket directly from the browser as it allows you to upload objects to a bucket without having to proxy the objects through your server saving costs on bandwidth.

$3

You can use the upload method from client package to upload objects directly to Tigris from the client side.

`ts
import { upload } from '@tigrisdata/storage/client';
`

upload accepts the following parameters:

- name: (Required) A string specifying the name of object
- body: (Required) A blob object as File or Blob
- options: (Optional) A JSON object with the following optional parameters:

#### options

| Parameter | Required | Values |
| ------------------ | ------------ | ------------------------------------------------------------------------------------------------------------- |
| url | Yes | The URL of your upload endpoint that handles client uploads. |
| access | No | The access level for the object. Possible values are public and private. |
| addRandomSuffix | No | Whether to add a random suffix to the object name. Default is false. |
| allowOverwrite | No | Whether to allow overwriting the object. Default is true. |
| contentType | No | Set the content type of the object. If not provided, inferred from the file. |
| contentDisposition | No | Set the content disposition. Possible values are inline and attachment. |
| multipart | No | Enable multipart upload for large files. Default is false. |
| partSize | No | Part size in bytes for multipart uploads. Default is 5MB. |
| concurrency | No | Maximum number of concurrent part uploads for multipart uploads. Default is 4. |
| onUploadProgress | No | Callback to track upload progress: onUploadProgress({loaded: number, total: number, percentage: number}). |

In case of successful upload, the data property will be set to the upload and contains the following properties:

- contentDisposition: content disposition of the object
- contentType: content type of the object
- modified: Last modified date of the object
- name: Name of the object
- size: Size of the object
- url: A presigned URL to the object

$3

`html



``

You can see a full example here.

More Examples

If you want to see it the Storage SDK used with your tool of choice, we have some ready examples available at our community repo. Something missing there that you you'd like to see? Open an issue and we'll be more than happy to add in examples.