Complete API Reference

API reference for @tigrisdata/storage v3.16.0.

For usage examples and guides, see Using the SDK.

Contents

• Client API
• Object Operations
• Presigned URLs
• Bucket Management
• Bucket Configuration
• Snapshots
• Multipart Upload
• Client Upload Handling
• Statistics
• Common Types

Client API

Functions and types exported from @tigrisdata/storage/client for browser-side uploads.

upload

function upload(
  name: string,
  data: File | Blob,
  options?: UploadOptions,
): Promise<TigrisStorageResponse<UploadResponse, Error>>;

executeWithConcurrency

Executes an array of task functions with a concurrency limit. Each task is a function that returns a Promise.

function executeWithConcurrency<T>(
  tasks: (() => Promise<T>)[],
  concurrency: number,
): Promise<T[]>;

Types

UploadOptions

type UploadOptions = {
  access?: "public" | "private";
  addRandomSuffix?: boolean;
  allowOverwrite?: boolean;
  contentType?: string;
  contentDisposition?: "attachment" | "inline";
  url?: string;
  multipart?: boolean;
  partSize?: number;
  /**
   * Maximum number of concurrent part uploads for multipart uploads
   * @default 4
   */
  concurrency?: number;
  onUploadProgress?: (progress: UploadProgress) => void;
};

Property	Type	Required	Description
access	'public' | 'private'	No
addRandomSuffix	boolean	No
allowOverwrite	boolean	No
contentType	string	No
contentDisposition	'attachment' | 'inline'	No
url	string	No
multipart	boolean	No
partSize	number	No
concurrency	number	No	Maximum number of concurrent part uploads for multipart uploads
onUploadProgress	(progress: UploadProgress) => void	No

UploadProgress

type UploadProgress = {
  loaded: number;
  total: number;
  percentage: number;
};

Property	Type	Required	Description
loaded	number	Yes
total	number	Yes
percentage	number	Yes

UploadResponse

type UploadResponse = {
  contentDisposition?: string;
  contentType?: string;
  modified: Date;
  name: string;
  size: number;
  url: string;
};

Property	Type	Required	Description
contentDisposition	string	No
contentType	string	No
modified	Date	Yes
name	string	Yes
size	number	Yes
url	string	Yes

Object Operations

Create, read, update, and delete objects in a bucket.

put

function put(
  path: string,
  body: string | ReadableStream | Blob | Buffer,
  options?: PutOptions,
): Promise<TigrisStorageResponse<PutResponse, Error>>;

get

Overloads:

function get(
  path: string,
  format: "string",
  options: GetOptions & {
    includeMetadata: true;
  },
): Promise<TigrisStorageResponse<GetResponseWithMetadata<string>, Error>>;

function get(
  path: string,
  format: "file",
  options: GetOptions & {
    includeMetadata: true;
  },
): Promise<TigrisStorageResponse<GetResponseWithMetadata<File>, Error>>;

function get(
  path: string,
  format: "stream",
  options: GetOptions & {
    includeMetadata: true;
  },
): Promise<
  TigrisStorageResponse<GetResponseWithMetadata<ReadableStream>, Error>
>;

function get(
  path: string,
  format: "string",
  options?: GetOptions,
): Promise<TigrisStorageResponse<string, Error>>;

function get(
  path: string,
  format: "file",
  options?: GetOptions,
): Promise<TigrisStorageResponse<File, Error>>;

function get(
  path: string,
  format: "stream",
  options?: GetOptions,
): Promise<TigrisStorageResponse<ReadableStream, Error>>;

head

function head(
  path: string,
  options?: HeadOptions,
): Promise<TigrisStorageResponse<HeadResponse | undefined, Error>>;

list

function list(
  options?: ListOptions,
): Promise<TigrisStorageResponse<ListResponse, Error>>;

remove

function remove(
  path: string,
  options?: RemoveOptions,
): Promise<TigrisStorageResponse<void, Error>>;

updateObject

Deprecated Use setObjectAccess to change object ACLs, or the dedicated rename helper to change an object's key. updateObject will be removed in a future major version.

function updateObject(
  path: string,
  options?: UpdateObjectOptions,
): Promise<TigrisStorageResponse<UpdateObjectResponse, Error>>;

Types

PutOptions

type PutOptions = {
  access?: "public" | "private";
  addRandomSuffix?: boolean;
  allowOverwrite?: boolean;
  contentType?: string;
  contentDisposition?: "attachment" | "inline";
  metadata?: Record<string, string>;
  multipart?: boolean;
  partSize?: number;
  queueSize?: number;
  abortController?: AbortController;
  onUploadProgress?: PutOnUploadProgress;
  config?: TigrisStorageConfig;
};

Property	Type	Required	Description
access	'public' | 'private'	No
addRandomSuffix	boolean	No
allowOverwrite	boolean	No
contentType	string	No
contentDisposition	'attachment' | 'inline'	No
metadata	Record<string, string>	No
multipart	boolean	No
partSize	number	No
queueSize	number	No
abortController	AbortController	No
onUploadProgress	PutOnUploadProgress	No
config	TigrisStorageConfig	No

PutResponse

type PutResponse = {
  contentDisposition: string | undefined;
  contentType: string | undefined;
  etag: string;
  metadata: Record<string, string> | undefined;
  modified: Date;
  path: string;
  size: number;
  url: string;
};

Property	Type	Required	Description
contentDisposition	string | undefined	Yes
contentType	string | undefined	Yes
etag	string	Yes
metadata	Record<string, string> | undefined	Yes
modified	Date	Yes
path	string	Yes
size	number	Yes
url	string	Yes

PutOnUploadProgress

type PutOnUploadProgress = ({
  loaded,
  total,
  percentage,
}: {
  loaded: number;
  total: number;
  percentage: number;
}) => void;

GetOptions

type GetOptions = {
  config?: TigrisStorageConfig;
  contentDisposition?: "attachment" | "inline";
  contentType?: string;
  encoding?: string;
  /**
   * When true, `get` returns `{ body, metadata }` instead of the bare
   * body, surfacing the object's etag, content metadata, user metadata,
   * and (when `range` is used) `Content-Range` — all read from the same
   * S3 response, no extra round-trip.
   */
  includeMetadata?: boolean;
  /**
   * Byte range to read. Both bounds are inclusive and 0-based, matching
   * the HTTP `Range: bytes=…` semantics. Omit `end` to read from `start`
   * to the end of the object. A range that falls entirely outside the
   * object returns an error (HTTP 416). The returned body is the partial
   * content only.
   */
  range?: {
    start: number;
    end?: number;
  };
  snapshotVersion?: string;
  versionId?: string;
};

Property	Type	Required	Description
config	TigrisStorageConfig	No
contentDisposition	'attachment' | 'inline'	No
contentType	string	No
encoding	string	No
includeMetadata	boolean	No	When true, get returns { body, metadata } instead of the bare

body, surfacing the object's etag, content metadata, user metadata, and (when range is used) Content-Range — all read from the same S3 response, no extra round-trip. | | range | \{ start: number; end?: number; \} | No | Byte range to read. Both bounds are inclusive and 0-based, matching the HTTP Range: bytes=… semantics. Omit end to read from start to the end of the object. A range that falls entirely outside the object returns an error (HTTP 416). The returned body is the partial content only. | | snapshotVersion | string | No | | | versionId | string | No | |

GetResponse

type GetResponse = string | File | ReadableStream;

HeadOptions

type HeadOptions = {
  snapshotVersion?: string;
  versionId?: string;
  config?: TigrisStorageConfig;
};

Property	Type	Required	Description
snapshotVersion	string	No
versionId	string	No
config	TigrisStorageConfig	No

HeadResponse

type HeadResponse = {
  contentDisposition: string;
  contentType: string;
  etag: string;
  metadata: Record<string, string>;
  modified: Date;
  path: string;
  size: number;
  url: string;
};

Property	Type	Required	Description
contentDisposition	string	Yes
contentType	string	Yes
etag	string	Yes
metadata	Record<string, string>	Yes
modified	Date	Yes
path	string	Yes
size	number	Yes
url	string	Yes

ListOptions

type ListOptions = {
  delimiter?: string;
  prefix?: string;
  limit?: number;
  paginationToken?: string;
  snapshotVersion?: string;
  source?: "tigris" | "shadow";
  config?: TigrisStorageConfig;
};

Property	Type	Required	Description
delimiter	string	No
prefix	string	No
limit	number	No
paginationToken	string	No
snapshotVersion	string	No
source	'tigris' | 'shadow'	No
config	TigrisStorageConfig	No

ListItem

type ListItem = {
  id: string;
  name: string;
  size: number;
  lastModified: Date;
  etag: string;
};

Property	Type	Required	Description
id	string	Yes
name	string	Yes
size	number	Yes
lastModified	Date	Yes
etag	string	Yes

ListResponse

type ListResponse = {
  items: ListItem[];
  commonPrefixes: string[];
  paginationToken: string | undefined;
  hasMore: boolean;
};

Property	Type	Required	Description
items	ListItem[]	Yes
commonPrefixes	string[]	Yes
paginationToken	string | undefined	Yes
hasMore	boolean	Yes

RemoveOptions

type RemoveOptions = {
  config?: TigrisStorageConfig;
  versionId?: string;
};

Property	Type	Required	Description
config	TigrisStorageConfig	No
versionId	string	No

UpdateObjectOptions

type UpdateObjectOptions = {
  config?: TigrisStorageConfig;
  key?: string;
  access?: "public" | "private";
};

Property	Type	Required	Description
config	TigrisStorageConfig	No
key	string	No
access	'public' | 'private'	No

UpdateObjectResponse

type UpdateObjectResponse = {
  path: string;
};

Property	Type	Required	Description
path	string	Yes

Presigned URLs

Generate presigned URLs for time-limited access to objects.

getPresignedUrl

function getPresignedUrl(
  path: string,
  options: GetPresignedUrlOptions,
): Promise<TigrisStorageResponse<GetPresignedUrlResponse, Error>>;

Types

GetPresignedUrlOptions

type GetPresignedUrlOptions = {
  /**
   * The access key ID to use for the presigned URL.
   * If not provided, the access key ID from the config will be used.
   */
  accessKeyId?: string;
  /**
   * The expiration time of the presigned URL in seconds.
   * Default is 3600 seconds (1 hour).
   */
  expiresIn?: number;
  /**
   * Snapshot version to read from. When set, the presigned URL is
   * pinned to the object version that was current at the time of the
   * snapshot.
   *
   * The gateway's presign endpoint accepts a literal object versionId
   * (not a snapshot version), so this function resolves the snapshot
   * to the correct versionId client-side: lists the key's versions
   * (and delete markers) and selects the newest entry with
   * `versionId <= snapshotVersion`.
   *
   * Only valid with `operation: 'get'`. Returns an error if the object
   * did not exist at the snapshot time (either never written, or
   * deleted before the snapshot).
   */
  snapshotVersion?: string;
  config?: TigrisStorageConfig;
} & MethodOrOperation;

Property	Type	Required	Description
accessKeyId	string	No	The access key ID to use for the presigned URL.
If not provided, the access key ID from the config will be used.
expiresIn	number	No	The expiration time of the presigned URL in seconds.
Default is 3600 seconds (1 hour).
snapshotVersion	string	No	Snapshot version to read from. When set, the presigned URL is

pinned to the object version that was current at the time of the snapshot.

The gateway's presign endpoint accepts a literal object versionId (not a snapshot version), so this function resolves the snapshot to the correct versionId client-side: lists the key's versions (and delete markers) and selects the newest entry with versionId <= snapshotVersion.

Only valid with operation: 'get'. Returns an error if the object did not exist at the snapshot time (either never written, or deleted before the snapshot). | | config | TigrisStorageConfig | No | |

GetPresignedUrlResponse

type GetPresignedUrlResponse = {
  url: string;
  expiresIn: number;
} & MethodOrOperation;

Property	Type	Required	Description
url	string	Yes
expiresIn	number	Yes

GetPresignedUrlOperation

type GetPresignedUrlOperation = "get" | "put";

MethodOrOperation

type MethodOrOperation =
  | {
      method: GetPresignedUrlOperation;
      operation?: never;
    }
  | {
      operation: GetPresignedUrlOperation;
      method?: never;
    };

Property	Type	Required	Description
method	GetPresignedUrlOperation	Yes
operation	never	No
operation	GetPresignedUrlOperation	Yes
method	never	No

Bucket Management

Create, list, update, and delete buckets.

createBucket

function createBucket(
  bucketName: string,
  options?: CreateBucketOptions,
): Promise<TigrisStorageResponse<CreateBucketResponse, Error>>;

getBucketInfo

function getBucketInfo(
  bucketName: string,
  options?: GetBucketInfoOptions,
): Promise<TigrisStorageResponse<BucketInfoResponse, Error>>;

listBuckets

function listBuckets(
  options?: ListBucketsOptions,
): Promise<TigrisStorageResponse<ListBucketsResponse, Error>>;

updateBucket

function updateBucket(
  bucketName: string,
  options?: UpdateBucketOptions,
): Promise<TigrisStorageResponse<UpdateBucketResponse, Error>>;

removeBucket

function removeBucket(
  bucketName: string,
  options?: RemoveBucketOptions,
): Promise<TigrisStorageResponse<void, Error>>;

Types

CreateBucketOptions

type CreateBucketOptions = {
  enableSnapshot?: boolean;
  sourceBucketName?: string;
  sourceBucketSnapshot?: string;
  access?: "public" | "private";
  defaultTier?: StorageClass;
  locations?: BucketLocations;
  enableDirectoryListing?: boolean;
  allowObjectAcl?: boolean;
  config?: Omit<TigrisStorageConfig, "bucket">;
};

Property	Type	Required	Description
enableSnapshot	boolean	No
sourceBucketName	string	No
sourceBucketSnapshot	string	No
access	'public' | 'private'	No
defaultTier	StorageClass	No
locations	BucketLocations	No
enableDirectoryListing	boolean	No
allowObjectAcl	boolean	No
config	Omit<TigrisStorageConfig, 'bucket'>	No

CreateBucketResponse

type CreateBucketResponse = {
  isSnapshotEnabled: boolean;
  hasForks: boolean;
  sourceBucketName?: string;
  sourceBucketSnapshot?: string;
};

Property	Type	Required	Description
isSnapshotEnabled	boolean	Yes
hasForks	boolean	Yes
sourceBucketName	string	No
sourceBucketSnapshot	string	No

GetBucketInfoOptions

type GetBucketInfoOptions = {
  config?: TigrisStorageConfig;
};

Property	Type	Required	Description
config	TigrisStorageConfig	No

BucketInfoResponse

type BucketInfoResponse = {
  /**
   * @deprecated Use `locations` instead — it carries the same data with
   * a structured `BucketLocations` shape that distinguishes `global` /
   * `multi` / `single` / `dual`. `regions` will be removed in the next
   * major version.
   *
   * Note: for region codes the SDK does not recognize, `regions` passes
   * the raw value through (e.g. `['mars']`) while `locations` falls back
   * defensively to `{ type: 'global' }`. The two fields can therefore
   * disagree when the gateway returns a region code newer than the SDK.
   */
  regions: string[];
  locations: BucketLocations;
  isSnapshotEnabled: boolean;
  forkInfo:
    | {
        hasChildren: boolean;
        parents: Array<{
          bucketName: string;
          forkCreatedAt: Date;
          snapshot: string;
          snapshotCreatedAt: Date;
        }>;
      }
    | undefined;
  settings: {
    allowObjectAcl: boolean;
    defaultTier: StorageClass;
    lifecycleRules?: BucketLifecycleRule[];
    dataMigration?: Omit<BucketMigration, "enabled">;
    /**
     * @deprecated Use `lifecycleRules` instead. This field is no longer
     * populated — read the rule with only `expiration` (no transition,
     * no filter) from `lifecycleRules` if you need the bucket-wide TTL.
     */
    ttlConfig?: BucketTtl;
    customDomain?: string;
    softDelete:
      | {
          enabled: true;
          retentionDays: number;
        }
      | {
          enabled: false;
        };
    /**
     * @deprecated Use `softDelete` instead.
     */
    deleteProtection: boolean;
    corsRules: BucketCorsRule[];
    additionalHeaders?: GetBucketInfoApiResponseBody["additional_http_headers"];
    notifications?: BucketNotification;
  };
  sizeInfo: {
    numberOfObjects: number | undefined;
    size: number | undefined;
    numberOfObjectsAllVersions: number | undefined;
  };
};

Property	Type	Required	Description
regions	string[]	Yes	Deprecated. Use locations instead — it carries the same data with

a structured BucketLocations shape that distinguishes global / multi / single / dual. regions will be removed in the next major version.

Note: for region codes the SDK does not recognize, regions passes the raw value through (e.g. ['mars']) while locations falls back defensively to { type: 'global' }. The two fields can therefore disagree when the gateway returns a region code newer than the SDK. | | locations | BucketLocations | Yes | | | isSnapshotEnabled | boolean | Yes | | | forkInfo | \{ hasChildren: boolean; parents: Array<\{ bucketName: string; forkCreatedAt: Date; snapshot: string; snapshotCreatedAt: Date; \}>; \} \| undefined | Yes | | | settings | \{ allowObjectAcl: boolean; defaultTier: StorageClass; lifecycleRules?: BucketLifecycleRule[]; dataMigration?: Omit<BucketMigration, 'enabled'>; /** * @deprecated Use lifecycleRulesinstead. This field is no longer * populated — read the rule with onlyexpiration(no transition, * no filter) fromlifecycleRulesif you need the bucket-wide TTL. */ ttlConfig?: BucketTtl; customDomain?: string; softDelete: \{ enabled: true; retentionDays: number; \} \| \{ enabled: false; \}; /** * @deprecated UsesoftDelete instead. */ deleteProtection: boolean; corsRules: BucketCorsRule[]; additionalHeaders?: GetBucketInfoApiResponseBody['additional_http_headers']; notifications?: BucketNotification; \} | Yes | | | sizeInfo | \{ numberOfObjects: number \| undefined; size: number \| undefined; numberOfObjectsAllVersions: number \| undefined; \} | Yes | |

ListBucketsOptions

type ListBucketsOptions = {
  config?: TigrisStorageConfig;
  paginationToken?: string;
  limit?: number;
  deleted?: boolean;
};

Property	Type	Required	Description
config	TigrisStorageConfig	No
paginationToken	string	No
limit	number	No
deleted	boolean	No

ListBucketsResponse

type ListBucketsResponse = {
  buckets: Bucket[];
  owner?: BucketOwner;
  paginationToken?: string;
};

Property	Type	Required	Description
buckets	Bucket[]	Yes
owner	BucketOwner	No
paginationToken	string	No

Bucket

type Bucket = {
  name: string;
  creationDate: Date;
  regions?: string[];
  type?: BucketType;
  visibility?: BucketVisibility;
  softDeleteInfo?: {
    enabled: boolean;
    retentionDays: number;
  };
  forkInfo?: {
    hasChildren: boolean;
    parents: Array<{
      bucketName: string;
      forkCreatedAt: Date;
      snapshot: string;
      snapshotCreatedAt: Date;
    }>;
  };
};

Property	Type	Required	Description
name	string	Yes
creationDate	Date	Yes
regions	string[]	No
type	BucketType	No
visibility	BucketVisibility	No
softDeleteInfo	\{ enabled: boolean; retentionDays: number; \}	No
forkInfo	\{ hasChildren: boolean; parents: Array<\{ bucketName: string; forkCreatedAt: Date; snapshot: string; snapshotCreatedAt: Date; \}>; \}	No

BucketOwner

type BucketOwner = {
  name: string;
  id: string;
};

Property	Type	Required	Description
name	string	Yes
id	string	Yes

UpdateBucketOptions

type UpdateBucketOptions = {
  access?: "public" | "private";
  allowObjectAcl?: boolean;
  disableDirectoryListing?: boolean;
  locations?: BucketLocations;
  cacheControl?: string;
  customDomain?: string;
  enableAdditionalHeaders?: boolean;
  softDelete?:
    | {
        enabled: true;
        retentionDays: number;
      }
    | {
        enabled: false;
      };
  /**
   * @deprecated Use `softDelete` instead.
   */
  enableDeleteProtection?: boolean;
  config?: Omit<TigrisStorageConfig, "bucket">;
};

Property	Type	Required	Description
access	'public' | 'private'	No
allowObjectAcl	boolean	No
disableDirectoryListing	boolean	No
locations	BucketLocations	No
cacheControl	string	No
customDomain	string	No
enableAdditionalHeaders	boolean	No
softDelete	\{ enabled: true; retentionDays: number; \} | \{ enabled: false; \}	No
enableDeleteProtection	boolean	No	Deprecated. Use softDelete instead.
config	Omit<TigrisStorageConfig, 'bucket'>	No

UpdateBucketResponse

type UpdateBucketResponse = {
  bucket: string;
  updated: boolean;
};

Property	Type	Required	Description
bucket	string	Yes
updated	boolean	Yes

RemoveBucketOptions

type RemoveBucketOptions = {
  force?: boolean;
  config?: TigrisStorageConfig;
};

Property	Type	Required	Description
force	boolean	No
config	TigrisStorageConfig	No

Bucket Configuration

Configure CORS, lifecycle rules, TTL, migration, and notifications for a bucket.

setBucketCors

function setBucketCors(
  bucketName: string,
  options?: SetBucketCorsOptions,
): Promise<TigrisStorageResponse<UpdateBucketResponse, Error>>;

setBucketLifecycle

function setBucketLifecycle(
  bucketName: string,
  options?: SetBucketLifecycleOptions,
): Promise<TigrisStorageResponse<UpdateBucketResponse, Error>>;

setBucketTtl

function setBucketTtl(
  bucketName: string,
  options?: SetBucketTtlOptions,
): Promise<TigrisStorageResponse<UpdateBucketResponse, Error>>;

setBucketMigration

function setBucketMigration(
  bucketName: string,
  options?: SetBucketMigrationOptions,
): Promise<TigrisStorageResponse<UpdateBucketResponse, Error>>;

setBucketNotifications

Configure webhook notifications for object events on a bucket.

Scenarios:

1. If notificationConfig is empty ({}), sends it as-is to clear notifications.

2. If only enabled is provided, fetches the existing config and merges with the new enabled value. Errors if no existing config is found.

3. If config is provided without enabled, fetches existing config and merges, retaining the existing enabled value.

4. url is validated when provided (must be a valid http/https URL).

5. auth.username and auth.password are validated when provided.

6. auth.token is validated when provided.

7. auth.token and auth.username/auth.password cannot be provided together.

8. override replaces the existing config when true. When false (default), merges with the existing config.

function setBucketNotifications(
  bucketName: string,
  options: SetBucketNotificationsOptions,
): Promise<TigrisStorageResponse<UpdateBucketResponse, Error>>;

Types

SetBucketCorsOptions

type SetBucketCorsOptions = {
  config?: Omit<TigrisStorageConfig, "bucket">;
  override?: boolean;
  rules: BucketCorsRule[];
};

Property	Type	Required	Description
config	Omit<TigrisStorageConfig, 'bucket'>	No
override	boolean	No
rules	BucketCorsRule[]	Yes

SetBucketLifecycleOptions

type SetBucketLifecycleOptions = {
  lifecycleRules: BucketLifecycleRule[];
  config?: Omit<TigrisStorageConfig, "bucket">;
};

Property	Type	Required	Description
lifecycleRules	BucketLifecycleRule[]	Yes
config	Omit<TigrisStorageConfig, 'bucket'>	No

SetBucketTtlOptions

type SetBucketTtlOptions = {
  ttlConfig?: BucketTtl;
  config?: Omit<TigrisStorageConfig, "bucket">;
};

Property	Type	Required	Description
ttlConfig	BucketTtl	No
config	Omit<TigrisStorageConfig, 'bucket'>	No

SetBucketMigrationOptions

type SetBucketMigrationOptions = {
  dataMigration?: BucketMigration;
  config?: Omit<TigrisStorageConfig, "bucket">;
};

Property	Type	Required	Description
dataMigration	BucketMigration	No
config	Omit<TigrisStorageConfig, 'bucket'>	No

SetBucketNotificationsOptions

type SetBucketNotificationsOptions = {
  config?: Omit<TigrisStorageConfig, "bucket">;
  notificationConfig: BucketNotification;
  override?: boolean;
};

Property	Type	Required	Description
config	Omit<TigrisStorageConfig, 'bucket'>	No
notificationConfig	BucketNotification	Yes
override	boolean	No

BucketCorsRule

type BucketCorsRule = {
  allowedOrigins: string | string[];
  allowedMethods?: string | string[];
  allowedHeaders?: string | string[];
  exposeHeaders?: string | string[];
  maxAge?: number;
};

Property	Type	Required	Description
allowedOrigins	string | string[]	Yes
allowedMethods	string | string[]	No
allowedHeaders	string | string[]	No
exposeHeaders	string | string[]	No
maxAge	number	No

BucketLifecycleRule

A bucket lifecycle rule. A rule can have at most one transition (top-level storageClass + days/date) and/or one expiration, optionally scoped to a key prefix via filter.prefix. At least one of transition or expiration must be present.

/**
 * A bucket lifecycle rule. A rule can have at most one transition
 * (top-level `storageClass` + `days`/`date`) and/or one `expiration`,
 * optionally scoped to a key prefix via `filter.prefix`. At least one
 * of transition or expiration must be present.
 */
type BucketLifecycleRule = {
  id?: string;
  enabled?: boolean;
  storageClass?: Exclude<StorageClass, "STANDARD">;
  days?: number;
  date?: string;
  expiration?: BucketLifecycleExpiration;
  filter?: BucketLifecycleFilter;
};

Property	Type	Required	Description
id	string	No
enabled	boolean	No
storageClass	Exclude<StorageClass, 'STANDARD'>	No
days	number	No
date	string	No
expiration	BucketLifecycleExpiration	No
filter	BucketLifecycleFilter	No

BucketTtl

Bucket-wide TTL configuration. Kept for back-compat with setBucketTtl, which manages a lifecycle rule with only expiration (no transition, no filter). New code should configure expirations via BucketLifecycleRule.expiration on setBucketLifecycle instead. This shape is expected to be removed in the next major version.

/**
 * Bucket-wide TTL configuration. Kept for back-compat with `setBucketTtl`,
 * which manages a lifecycle rule with only `expiration` (no transition,
 * no filter). New code should configure expirations via
 * `BucketLifecycleRule.expiration` on `setBucketLifecycle` instead. This
 * shape is expected to be removed in the next major version.
 */
type BucketTtl = {
  id?: string;
  enabled?: boolean;
  days?: number;
  date?: string;
};

Property	Type	Required	Description
id	string	No
enabled	boolean	No
days	number	No
date	string	No

BucketMigration

type BucketMigration = {
  enabled: boolean;
  accessKey?: string;
  secretKey?: string;
  region?: string;
  name?: string;
  endpoint?: string;
  writeThrough?: boolean;
};

Property	Type	Required	Description
enabled	boolean	Yes
accessKey	string	No
secretKey	string	No
region	string	No
name	string	No
endpoint	string	No
writeThrough	boolean	No

BucketNotification

type BucketNotification =
  | BucketNotificationBase
  | BucketNotificationBasicAuth
  | BucketNotificationTokenAuth;

BucketNotificationBase

type BucketNotificationBase = {
  enabled?: boolean;
  url?: string;
  filter?: string;
};

Property	Type	Required	Description
enabled	boolean	No
url	string	No
filter	string	No

BucketNotificationBasicAuth

type BucketNotificationBasicAuth = BucketNotificationBase & {
  auth: {
    username: string;
    password: string;
    token?: never;
  };
};

Property	Type	Required	Description
auth	\{ username: string; password: string; token?: never; \}	Yes

BucketNotificationTokenAuth

type BucketNotificationTokenAuth = BucketNotificationBase & {
  auth: {
    token: string;
    username?: never;
    password?: never;
  };
};

Property	Type	Required	Description
auth	\{ token: string; username?: never; password?: never; \}	Yes

Snapshots

Create and list bucket snapshots.

createBucketSnapshot

Overloads:

function createBucketSnapshot(
  options?: CreateBucketSnapshotOptions,
): Promise<TigrisStorageResponse<CreateBucketSnapshotResponse, Error>>;

function createBucketSnapshot(
  sourceBucketName?: string,
  options?: CreateBucketSnapshotOptions,
): Promise<TigrisStorageResponse<CreateBucketSnapshotResponse, Error>>;

listBucketSnapshots

Overloads:

function listBucketSnapshots(
  options?: ListBucketSnapshotsOptions,
): Promise<TigrisStorageResponse<ListBucketSnapshotsResponse, Error>>;

function listBucketSnapshots(
  sourceBucketName?: string,
  options?: ListBucketSnapshotsOptions,
): Promise<TigrisStorageResponse<ListBucketSnapshotsResponse, Error>>;

Types

CreateBucketSnapshotOptions

type CreateBucketSnapshotOptions = {
  name?: string;
  config?: Omit<TigrisStorageConfig, "bucket">;
};

Property	Type	Required	Description
name	string	No
config	Omit<TigrisStorageConfig, 'bucket'>	No

CreateBucketSnapshotResponse

type CreateBucketSnapshotResponse = {
  snapshotVersion: string;
};

Property	Type	Required	Description
snapshotVersion	string	Yes

ListBucketSnapshotsOptions

type ListBucketSnapshotsOptions = {
  config?: Omit<TigrisStorageConfig, "bucket">;
  paginationToken?: string;
  limit?: number;
};

Property	Type	Required	Description
config	Omit<TigrisStorageConfig, 'bucket'>	No
paginationToken	string	No
limit	number	No

ListBucketSnapshotsResponse

type ListBucketSnapshotsResponse = {
  snapshots: BucketSnapshot[];
  paginationToken?: string;
};

Property	Type	Required	Description
snapshots	BucketSnapshot[]	Yes
paginationToken	string	No

Multipart Upload

Low-level multipart upload operations for advanced use cases.

initMultipartUpload

function initMultipartUpload(
  path: string,
  options?: InitMultipartUploadOptions,
): Promise<TigrisStorageResponse<InitMultipartUploadResponse, Error>>;

getPartsPresignedUrls

function getPartsPresignedUrls(
  path: string,
  parts: number[],
  uploadId: string,
  options?: GetPartsPresignedUrlsOptions,
): Promise<TigrisStorageResponse<GetPartsPresignedUrlsResponse, Error>>;

completeMultipartUpload

function completeMultipartUpload(
  path: string,
  uploadId: string,
  partIds: Array<{
    [key: number]: string;
  }>,
  options?: CompleteMultipartUploadOptions,
): Promise<TigrisStorageResponse<CompleteMultipartUploadResponse, Error>>;

Types

InitMultipartUploadOptions

type InitMultipartUploadOptions = {
  config?: TigrisStorageConfig;
};

Property	Type	Required	Description
config	TigrisStorageConfig	No

InitMultipartUploadResponse

type InitMultipartUploadResponse = {
  uploadId: string;
};

Property	Type	Required	Description
uploadId	string	Yes

GetPartsPresignedUrlsOptions

type GetPartsPresignedUrlsOptions = {
  config?: TigrisStorageConfig;
};

Property	Type	Required	Description
config	TigrisStorageConfig	No

GetPartsPresignedUrlsResponse

type GetPartsPresignedUrlsResponse = Array<{
  part: number;
  url: string;
}>;

CompleteMultipartUploadOptions

type CompleteMultipartUploadOptions = {
  config?: TigrisStorageConfig;
};

Property	Type	Required	Description
config	TigrisStorageConfig	No

CompleteMultipartUploadResponse

type CompleteMultipartUploadResponse = {
  path: string;
  url: string;
};

Property	Type	Required	Description
path	string	Yes
url	string	Yes

Client Upload Handling

Server-side handler for processing client upload requests (pairs with the Client API upload function).

handleClientUpload

function handleClientUpload(
  request: ClientUploadRequest,
  config?: TigrisStorageConfig,
): Promise<TigrisStorageResponse<unknown, Error>>;

Types

ClientUploadRequest

interface ClientUploadRequest {
  action: UploadAction;
  name: string;
  /** @deprecated This property is no longer used by the server handler. Will be removed in the next major version. */
  contentType?: string;
  uploadId?: string;
  parts?: number[];
  partIds?: Array<{
    [key: number]: string;
  }>;
}

Property	Type	Required	Description
action	UploadAction	Yes
name	string	Yes
contentType	string	No	Deprecated. This property is no longer used by the server handler. Will be removed in the next major version.
uploadId	string	No
parts	number[]	No
partIds	Array<\{ [key: number]: string; \}>	No

UploadAction

enum UploadAction {
  SinglepartInit = "singlepart-init",
  MultipartInit = "multipart-init",
  MultipartGetParts = "multipart-get-parts",
  MultipartComplete = "multipart-complete",
}

Statistics

Retrieve account and bucket-level storage statistics.

getStats

function getStats(
  options?: GetStatsOptions,
): Promise<TigrisStorageResponse<StatsResponse, Error>>;

Types

GetStatsOptions

type GetStatsOptions = {
  paginationToken?: string;
  config?: TigrisStorageConfig;
};

Property	Type	Required	Description
paginationToken	string	No
config	TigrisStorageConfig	No

StatsResponse

type StatsResponse = {
  paginationToken?: string;
  stats: BucketsStats;
  buckets: Bucket[];
};

Property	Type	Required	Description
paginationToken	string	No
stats	BucketsStats	Yes
buckets	Bucket[]	Yes

BucketType

type BucketType = "Regular" | "Snapshot";

BucketVisibility

type BucketVisibility = "public" | "private";

Common Types

Shared configuration and response types used across all API methods.

Types

TigrisStorageConfig

type TigrisStorageConfig = {
  bucket?: string;
  forcePathStyle?: boolean;
} & TigrisConfig;

Property	Type	Required	Description
bucket	string	No
forcePathStyle	boolean	No

TigrisStorageResponse

type TigrisStorageResponse<T, E = Error> = TigrisResponse<T, E>;

TigrisResponse

type TigrisResponse<T, E = Error> =
  | {
      data: T;
      error?: never;
    }
  | {
      error: E;
      data?: never;
    };

Property	Type	Required	Description
data	T	Yes
error	never	No
error	E	Yes
data	never	No

StorageClass

type StorageClass = "STANDARD" | "STANDARD_IA" | "GLACIER" | "GLACIER_IR";

BucketLocations

type BucketLocations =
  | {
      type: "multi";
      values: BucketLocationMulti;
    }
  | {
      type: "dual";
      values: BucketLocationDualOrSingle | BucketLocationDualOrSingle[];
    }
  | {
      type: "single";
      values: BucketLocationDualOrSingle;
    }
  | {
      type: "global";
      values?: never;
    };

Property	Type	Required	Description
type	'multi'	Yes
values	BucketLocationMulti	Yes
type	'dual'	Yes
values	BucketLocationDualOrSingle | BucketLocationDualOrSingle[]	Yes
type	'single'	Yes
values	BucketLocationDualOrSingle	Yes
type	'global'	Yes
values	never	No

BucketLocationMulti

type BucketLocationMulti = (typeof multiRegions)[number];

BucketLocationDualOrSingle

type BucketLocationDualOrSingle = (typeof singleOrDualRegions)[number];

multiRegions

const multiRegions: readonly ["usa", "eur"];

singleOrDualRegions

const singleOrDualRegions: readonly [
  "ams",
  "fra",
  "gru",
  "iad",
  "jnb",
  "lhr",
  "nrt",
  "ord",
  "sin",
  "sjc",
  "syd",
];