or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

bucket.md client.md cluster.md image.md index.md multipart.md object.md rtmp.md sts.md

tile.json

Object Operations

Object operations provide comprehensive functionality for managing files in OSS, including upload, download, listing, metadata management, access control, and URL generation.

Core Object Operations

Object Upload

async function put(name: string, file: ObjectSource, options?: PutObjectOptions): Promise<PutObjectResult>;
async function putStream(name: string, stream: ReadableStream, options?: PutObjectOptions): Promise<PutObjectResult>;
async function append(name: string, file: ObjectSource, options?: AppendObjectOptions): Promise<AppendObjectResult>;

type ObjectSource = string | Buffer | ReadableStream | File;

interface PutObjectOptions {
  timeout?: number | number[];
  mime?: string;
  meta?: Record<string, string>;
  headers?: Record<string, string>;
  callback?: CallbackConfig;
  progress?: (percentage: number, checkpoint?: any, res?: any) => void;
}

interface PutObjectResult {
  name: string;
  url: string;
  res: ResponseInfo;
  size?: number;
  aborted?: boolean;
  rt?: number;
  timing?: TimingInfo;
}

interface AppendObjectOptions extends PutObjectOptions {
  position?: number;
}

interface AppendObjectResult extends PutObjectResult {
  nextAppendPosition: number;
}

Object Download

async function get(name: string, file?: string | WriteStream, options?: GetObjectOptions): Promise<GetObjectResult>;
async function getStream(name: string, options?: GetObjectOptions): Promise<GetStreamResult>;

interface GetObjectOptions {
  timeout?: number | number[];
  headers?: Record<string, string>;
  process?: string;
  response?: ResponseConfig;
  range?: string;
  responseCacheControl?: string;
  responseContentDisposition?: string;
  responseContentEncoding?: string;
  responseContentLanguage?: string;
  responseContentType?: string;
  responseExpires?: string;
  versionId?: string;
}

interface GetObjectResult {
  content: Buffer;
  res: ResponseInfo;
  size?: number;
  aborted?: boolean;
  rt?: number;
}

interface GetStreamResult {
  stream: ReadableStream;
  res: ResponseInfo;
  size?: number;
  aborted?: boolean;
  rt?: number;
}

Object Deletion

async function delete(name: string, options?: RequestOptions): Promise<DeleteObjectResult>;
async function deleteMulti(names: string[], options?: DeleteMultiOptions): Promise<DeleteMultiResult>;

interface DeleteMultiOptions extends RequestOptions {
  quiet?: boolean;
  encoding?: string;
}

interface DeleteObjectResult {
  res: ResponseInfo;
  size?: number;
  rt?: number;
}

interface DeleteMultiResult {
  deleted: string[];
  failed: DeleteError[];
  res: ResponseInfo;
}

interface DeleteError {
  Key: string;
  Code: string;
  Message: string;
}

Object Listing

List Objects

async function list(query?: ListObjectsQuery, options?: RequestOptions): Promise<ListObjectsResult>;
async function listV2(query?: ListObjectsV2Query, options?: RequestOptions): Promise<ListObjectsV2Result>;

interface ListObjectsQuery {
  prefix?: string;
  marker?: string;
  delimiter?: string;
  'max-keys'?: number;
}

interface ListObjectsV2Query {
  prefix?: string;
  'continuation-token'?: string;
  delimiter?: string;
  'max-keys'?: number;
  'start-after'?: string;
  'fetch-owner'?: boolean;
}

interface ListObjectsResult {
  objects: ObjectInfo[];
  prefixes: string[];
  isTruncated: boolean;
  nextMarker?: string;
  res: ResponseInfo;
}

interface ListObjectsV2Result {
  objects: ObjectInfo[];
  prefixes: string[];
  isTruncated: boolean;
  continuationToken?: string;
  nextContinuationToken?: string;
  keyCount: number;
  res: ResponseInfo;
}

interface ObjectInfo {
  name: string;
  url: string;
  lastModified: Date;
  etag: string;
  type: string;
  size: number;
  storageClass: string;
  owner?: Owner;
}

Versioned Object Listing

async function getBucketVersions(query?: GetVersionsQuery, options?: RequestOptions): Promise<GetVersionsResult>;

interface GetVersionsQuery {
  prefix?: string;
  'key-marker'?: string;
  'version-id-marker'?: string;
  delimiter?: string;
  'max-keys'?: number;
}

interface GetVersionsResult {
  objects: VersionInfo[];
  deleteMarkers: DeleteMarkerInfo[];
  prefixes: string[];
  isTruncated: boolean;
  nextKeyMarker?: string;
  nextVersionIdMarker?: string;
  res: ResponseInfo;
}

interface VersionInfo extends ObjectInfo {
  versionId: string;
  isLatest: boolean;
}

Object Metadata

Metadata Operations

async function head(name: string, options?: HeadObjectOptions): Promise<HeadObjectResult>;
async function getObjectMeta(name: string, options?: RequestOptions): Promise<GetObjectMetaResult>;
async function putMeta(name: string, meta: Record<string, string>, options?: RequestOptions): Promise<PutMetaResult>;

interface HeadObjectOptions extends RequestOptions {
  versionId?: string;
}

interface HeadObjectResult {
  status: number;
  meta: Record<string, string>;
  res: ResponseInfo;
  size?: number;
}

interface GetObjectMetaResult {
  status: number;
  res: ResponseInfo;
  size?: number;
}

interface PutMetaResult {
  res: ResponseInfo;
  size?: number;
}

Object Copying

Copy Operations

async function copyObject(name: string, sourceName: string, options?: CopyObjectOptions): Promise<CopyObjectResult>;

interface CopyObjectOptions extends RequestOptions {
  meta?: Record<string, string>;
  headers?: Record<string, string>;
  sourceBucket?: string;
  metadataDirective?: 'COPY' | 'REPLACE';
  sourceVersionId?: string;
  versionId?: string;
}

interface CopyObjectResult {
  lastModified: Date;
  etag: string;
  res: ResponseInfo;
}

Object Access Control

ACL Management

async function putACL(name: string, acl: string, options?: RequestOptions): Promise<PutACLResult>;
async function getACL(name: string, options?: RequestOptions): Promise<GetACLResult>;

interface GetACLResult {
  acl: string;
  owner: Owner;
  grants?: Grant[];
  res: ResponseInfo;
}

Object Tagging

Tag Management

async function putObjectTagging(name: string, tags: ObjectTag[], options?: RequestOptions): Promise<PutObjectTaggingResult>;
async function getObjectTagging(name: string, options?: RequestOptions): Promise<GetObjectTaggingResult>;
async function deleteObjectTagging(name: string, options?: RequestOptions): Promise<DeleteObjectTaggingResult>;

interface ObjectTag {
  key: string;
  value: string;
}

interface GetObjectTaggingResult {
  tags: ObjectTag[];
  res: ResponseInfo;
}

Symbolic Links

Symlink Operations

async function putSymlink(name: string, targetName: string, options?: PutSymlinkOptions): Promise<PutSymlinkResult>;
async function getSymlink(name: string, options?: RequestOptions): Promise<GetSymlinkResult>;

interface PutSymlinkOptions extends RequestOptions {
  meta?: Record<string, string>;
  headers?: Record<string, string>;
}

interface GetSymlinkResult {
  targetName: string;
  res: ResponseInfo;
}

Object Restoration

Archive Object Restoration

async function restore(name: string, options?: RestoreOptions): Promise<RestoreResult>;

interface RestoreOptions extends RequestOptions {
  days?: number;
  type?: 'Archive' | 'ColdArchive' | 'DeepColdArchive';
  tier?: 'Expedited' | 'Standard' | 'Bulk';
  jobParameters?: JobParameters;
}

interface JobParameters {
  tier?: 'Expedited' | 'Standard' | 'Bulk';
}

interface RestoreResult {
  res: ResponseInfo;
}

URL Generation

Object URL Generation

function generateObjectUrl(name: string, baseUrl?: string): string;
function getObjectUrl(name: string, baseUrl?: string): string;

Signed URLs

function signatureUrl(name: string, options?: SignatureUrlOptions): string;
async function asyncSignatureUrl(name: string, options?: SignatureUrlOptions): Promise<string>;
function signatureUrlV4(method: string, expires: number, request: V4SignRequest, objectName?: string, additionalHeaders?: Record<string, string>): string;

interface SignatureUrlOptions {
  expires?: number;
  method?: string;
  'Content-Type'?: string;
  process?: string;
  response?: ResponseConfig;
  callback?: CallbackConfig;
}

interface V4SignRequest {
  headers: Record<string, string>;
  queries: Record<string, string>;
}

// Generate signed URL for download (valid for 1 hour)
const downloadUrl = client.signatureUrl('my-file.pdf', {
  expires: 3600,
  method: 'GET'
});

// Generate signed URL for upload
const uploadUrl = client.signatureUrl('upload/new-file.jpg', {
  expires: 1800,
  method: 'PUT',
  'Content-Type': 'image/jpeg'
});

Browser POST Signatures

POST Form Signatures

function calculatePostSignature(policy: string): string;
function signPostObjectPolicyV4(policy: PolicyV4, date: Date): string;

interface PolicyV4 {
  expiration: string;
  conditions: Array<any>;
}

Async Fetch Operations

External URL Fetch

async function postAsyncFetch(name: string, options: AsyncFetchOptions): Promise<AsyncFetchResult>;
async function getAsyncFetch(name: string, options?: RequestOptions): Promise<GetAsyncFetchResult>;

interface AsyncFetchOptions extends RequestOptions {
  url: string;
  contentMd5?: string;
  callback?: CallbackConfig;
  ignoreSameKey?: boolean;
}

interface AsyncFetchResult {
  res: ResponseInfo;
}

interface GetAsyncFetchResult {
  state: 'Running' | 'Success' | 'Failed';
  res: ResponseInfo;
}

Utility Methods

Internal Utilities

_objectUrl(name: string, baseUrl?: string): string;
_objectName(name: string): string;
_getFileSize(file: ObjectSource): number;
_convertMetaToHeaders(meta: Record<string, string>): Record<string, string>;

These utility methods are exposed on the client instance for advanced use cases but are primarily intended for internal use.

Common Types and Interfaces

Response Information

interface ResponseInfo {
  status: number;
  headers: Record<string, string>;
  size: number;
  aborted: boolean;
  rt: number;
  keepAliveSocket: boolean;
  data?: Buffer;
  requestUrls?: string[];
  timing?: TimingInfo;
}

interface TimingInfo {
  queuing: number;
  dnslookup: number;
  connected: number;
  requestSent: number;
  waiting: number;
  contentDownload: number;
}

Callback Configuration

interface CallbackConfig {
  url: string;
  host?: string;
  body?: string;
  contentType?: string;
  customValue?: Record<string, string>;
}

Response Configuration

interface ResponseConfig {
  'content-type'?: string;
  'cache-control'?: string;
  'content-disposition'?: string;
  'content-encoding'?: string;
  'expires'?: string;
}

Owner Information

interface Owner {
  id: string;
  displayName: string;
}

interface Grant {
  grantee: Grantee;
  permission: string;
}

interface Grantee {
  id?: string;
  displayName?: string;
  type: 'CanonicalUser' | 'Group';
  uri?: string;
}

Usage Examples

Basic File Operations

// Upload a file
const result = await client.put('documents/report.pdf', buffer, {
  meta: { author: 'John Doe', category: 'report' },
  headers: { 'Cache-Control': 'max-age=3600' }
});

// Download a file
const object = await client.get('documents/report.pdf');
console.log('File size:', object.content.length);

// List files with prefix
const list = await client.list({
  prefix: 'documents/',
  'max-keys': 100
});
console.log('Found files:', list.objects.length);

// Delete multiple files
await client.deleteMulti(['old-file1.txt', 'old-file2.txt']);

Advanced Operations

// Copy with metadata replacement
await client.copyObject('backup/report.pdf', 'documents/report.pdf', {
  metadataDirective: 'REPLACE',
  meta: { 'backup-date': new Date().toISOString() }
});

// Create signed URL for temporary access
const signedUrl = client.signatureUrl('private/document.pdf', {
  expires: 3600, // 1 hour
  method: 'GET'
});

// Set object tags
await client.putObjectTagging('report.pdf', [
  { key: 'department', value: 'finance' },
  { key: 'confidential', value: 'true' }
]);