CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-minio

S3 Compatible Cloud Storage client for JavaScript/TypeScript

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

types-and-errors.mddocs/

Types and Errors

This document provides a comprehensive reference for all error classes, TypeScript interfaces, enums, and type definitions in the MinIO JavaScript client library.

Error Classes

All error classes extend ExtendableError, which extends the native JavaScript Error class. Each error provides specific context for different failure scenarios.

Error Class Hierarchy

// Base error class (internal)
abstract class ExtendableError extends Error {
  constructor(message?: string, opt?: ErrorOptions)
}

Validation Errors

AnonymousRequestError

class AnonymousRequestError extends ExtendableError {}

Usage: Generated for anonymous keys on APIs that require authentication. Presigned URL generation always requires access keys.

InvalidArgumentError

class InvalidArgumentError extends ExtendableError {}

Usage: Generated for all invalid arguments passed to methods.

InvalidPortError

class InvalidPortError extends ExtendableError {}

Usage: Generated when a non-integer value is provided for port numbers.

InvalidEndpointError

class InvalidEndpointError extends ExtendableError {}

Usage: Generated when an invalid endpoint value is provided that doesn't follow domain standards.

InvalidBucketNameError

class InvalidBucketNameError extends ExtendableError {}

Usage: Generated for bucket names that don't follow AWS S3 specifications.

InvalidObjectNameError

class InvalidObjectNameError extends ExtendableError {}

Usage: Generated for object names that don't follow AWS S3 specifications.

Authentication Errors

AccessKeyRequiredError

class AccessKeyRequiredError extends ExtendableError {}

Usage: Generated by signature methods when access key is not found.

SecretKeyRequiredError

class SecretKeyRequiredError extends ExtendableError {}

Usage: Generated by signature methods when secret key is not found.

Parameter Errors

ExpiresParamError

class ExpiresParamError extends ExtendableError {}

Usage: Generated when expires parameter value is outside stipulated limits.

InvalidDateError

class InvalidDateError extends ExtendableError {}

Usage: Generated for invalid date values.

InvalidPrefixError

class InvalidPrefixError extends ExtendableError {}

Usage: Generated for invalid object prefixes.

InvalidBucketPolicyError

class InvalidBucketPolicyError extends ExtendableError {}

Usage: Generated for invalid bucket policy configurations.

Data Errors

IncorrectSizeError

class IncorrectSizeError extends ExtendableError {}

Usage: Generated when read data size doesn't match the input size parameter.

InvalidXMLError

class InvalidXMLError extends ExtendableError {}

Usage: Generated for unknown or malformed XML responses from the server.

Server Errors

S3Error

class S3Error extends ExtendableError {
  code: string       // S3 error code (e.g., 'NoSuchBucket', 'AccessDenied')
  region?: string    // AWS region where error occurred
}

Usage: Generated for errors returned from S3-compatible servers. Contains specific error codes and optional region information.

Utility Errors

IsValidBucketNameError

class IsValidBucketNameError extends ExtendableError {}

Usage: Generated during bucket name validation errors.

Core Type Definitions

Basic Types

Binary

type Binary = string | Buffer

Usage: Represents data that can be either a string or Buffer.

Region

type Region = string

Usage: AWS region identifier (e.g., 'us-east-1', 'eu-west-1').

Transport

type Transport = Pick<typeof http, 'request'>

Usage: HTTP transport interface for custom request handling.

Metadata Types

ObjectMetaData

type ObjectMetaData = Record<string, string | number>

Usage: Object metadata where keys are metadata names and values are string or number.

ResponseHeader

type ResponseHeader = Record<string, string>

Usage: HTTP response headers as key-value pairs.

RequestHeaders

type RequestHeaders = Record<string, string | boolean | number | undefined>

Usage: HTTP request headers with various value types.

Configuration Interfaces

ClientOptions

interface ClientOptions {
  endPoint: string                      // MinIO server endpoint
  accessKey?: string                   // Access key for authentication
  secretKey?: string                   // Secret key for authentication
  useSSL?: boolean                    // Use HTTPS (default: true for port 443)
  port?: number                       // Server port
  region?: Region                     // AWS region
  transport?: Transport              // Custom HTTP transport
  sessionToken?: string              // Temporary session token
  partSize?: number                  // Multipart upload part size
  pathStyle?: boolean               // Use path-style URLs
  credentialsProvider?: CredentialProvider // Dynamic credential provider
  s3AccelerateEndpoint?: string     // S3 transfer acceleration endpoint
  transportAgent?: http.Agent       // HTTP agent for connection pooling
}

Bucket Options

MakeBucketOpt

interface MakeBucketOpt {
  ObjectLocking?: boolean  // Enable object locking (cannot be changed later)
}

Object Operation Interfaces

Object Retrieval Options

GetObjectOpts

interface GetObjectOpts {
  versionId?: string              // Specific version ID
  SSECustomerAlgorithm?: string  // Server-side encryption algorithm
  SSECustomerKey?: string        // Server-side encryption key
  SSECustomerKeyMD5?: string     // MD5 hash of encryption key
}

StatObjectOpts

interface StatObjectOpts {
  versionId?: string              // Specific version ID
  SSECustomerAlgorithm?: string  // Server-side encryption algorithm
  SSECustomerKey?: string        // Server-side encryption key
  SSECustomerKeyMD5?: string     // MD5 hash of encryption key
}

Object Metadata

ItemBucketMetadata

interface ItemBucketMetadata {
  [key: string]: any  // Custom metadata and HTTP headers
}

ItemBucketMetadataList

interface ItemBucketMetadataList {
  Items: MetadataItem[]
}

interface MetadataItem {
  Key: string    // Metadata key
  Value: string  // Metadata value
}

Object Information

BucketItemStat

interface BucketItemStat {
  size: number                 // Object size in bytes
  etag: string                // Object ETag
  lastModified: Date          // Last modified timestamp
  metaData: ResponseHeader    // Object metadata and headers
  versionId?: string          // Version ID (if versioning enabled)
  isDeleteMarker?: boolean    // True if this is a delete marker
}

ObjectInfo

interface ObjectInfo {
  name: string              // Object name/key
  prefix?: string          // Object prefix (for grouped results)
  size: number            // Object size in bytes
  etag?: string          // Object ETag
  lastModified: Date     // Last modified timestamp
  storageClass?: string  // Storage class
  isDir?: boolean       // True if this represents a directory
}

BucketItemFromList

interface BucketItemFromList {
  name: string          // Bucket name
  creationDate: Date    // Bucket creation timestamp
}

Object Operations Results

UploadedObjectInfo

interface UploadedObjectInfo {
  etag: string          // Object ETag after upload
  versionId?: string    // Version ID (if versioning enabled)
}

CopyObjectResult

interface CopyObjectResult {
  etag: string          // Copied object ETag
  lastModified: Date    // Last modified timestamp
  versionId?: string    // Version ID (if versioning enabled)
}

Delete Operations

RemoveOptions

interface RemoveOptions {
  versionId?: string        // Specific version to delete
  governanceBypass?: boolean // Bypass governance retention
}

RemoveObjectsParam

type RemoveObjectsParam = string[] | RemoveObjectsRequestEntry[]

interface RemoveObjectsRequestEntry {
  name: string              // Object name
  versionId?: string        // Version ID (optional)
}

RemoveObjectsResponse

interface RemoveObjectsResponse {
  name?: string                    // Object name
  versionId?: string               // Version ID  
  deleteMarker?: boolean           // True if delete marker created
  deleteMarkerVersionId?: string   // Delete marker version ID
  
  // Error information (if deletion failed)
  errorCode?: string              // Error code
  errorMessage?: string           // Error message
}

Copy Operations Interfaces

ICopySourceOptions

interface ICopySourceOptions {
  Bucket: string                    // Source bucket name
  Object: string                    // Source object name
  VersionID?: string               // Source version ID
  MatchETag?: string               // Copy only if ETag matches
  NoMatchETag?: string             // Copy only if ETag doesn't match
  MatchModifiedSince?: string | null     // Copy if modified since date
  MatchUnmodifiedSince?: string | null   // Copy if unmodified since date
  MatchRange?: boolean             // Enable byte range matching
  Start?: number                   // Start byte for range
  End?: number                     // End byte for range
  Encryption?: Encryption          // Source object encryption
}

ICopyDestinationOptions

interface ICopyDestinationOptions {
  Bucket: string                      // Destination bucket name
  Object: string                      // Destination object name
  Encryption?: Encryption             // Destination object encryption
  UserMetadata?: ObjectMetaData       // Custom metadata
  UserTags?: Record<string, string> | string // Object tags
  LegalHold?: 'on' | 'off'           // Legal hold status
  RetainUntilDate?: string           // Retention until date
  Mode?: RETENTION_MODES             // Retention mode
  MetadataDirective?: 'COPY' | 'REPLACE' // Metadata handling
  Headers?: Record<string, string>    // Additional headers
}

Encryption Types

Encryption Interface

type Encryption = 
  | {
      type: ENCRYPTION_TYPES.SSEC     // Server-side encryption with customer keys
      SSECustomerKey?: string         // Base64 encoded 256-bit key
      SSECustomerKeyMD5?: string      // MD5 hash of the key
    }
  | {
      type: ENCRYPTION_TYPES.KMS      // Server-side encryption with KMS
      SSEAlgorithm?: string          // Encryption algorithm
      KMSMasterKeyID?: string        // KMS key ID
    }

ENCRYPTION_TYPES Enum

enum ENCRYPTION_TYPES {
  /**
   * SSEC represents server-side-encryption with customer provided keys
   */
  SSEC = 'SSE-C',
  
  /**
   * KMS represents server-side-encryption with managed keys
   */
  KMS = 'KMS'
}

Retention and Legal Hold

RETENTION_MODES Enum

enum RETENTION_MODES {
  GOVERNANCE = 'GOVERNANCE',    // Can be bypassed with proper permissions
  COMPLIANCE = 'COMPLIANCE'     // Cannot be bypassed or shortened
}

RETENTION_VALIDITY_UNITS Enum

enum RETENTION_VALIDITY_UNITS {
  DAYS = 'Days',     // Retention period in days
  YEARS = 'Years'    // Retention period in years
}

LEGAL_HOLD_STATUS Enum

enum LEGAL_HOLD_STATUS {
  ENABLED = 'ON',     // Legal hold is active
  DISABLED = 'OFF'    // Legal hold is inactive
}

Retention Interfaces

ObjectRetentionInfo

interface ObjectRetentionInfo {
  mode: RETENTION_MODES     // Retention mode
  retainUntilDate: Date    // Retention expiry date
}

Retention

interface Retention {
  mode: RETENTION_MODES           // Retention mode
  retainUntilDate: Date          // Retention until date
  governanceBypass?: boolean      // Bypass governance retention (requires permission)
}

GetObjectRetentionOpts

interface GetObjectRetentionOpts {
  versionId?: string  // Specific version ID
}

Legal Hold Interfaces

GetObjectLegalHoldOptions

interface GetObjectLegalHoldOptions {
  versionId?: string  // Specific version ID
}

PutObjectLegalHoldOptions

interface PutObjectLegalHoldOptions {
  versionId?: string              // Specific version ID
  status: LEGAL_HOLD_STATUS      // Legal hold status (ON/OFF)
}

Tagging Interfaces

Tag

interface Tag {
  Key: string      // Tag key
  Value: string    // Tag value
}

Tags

type Tags = Record<string, string> | Tag[] | TagList

interface TagList {
  TagSet: Tag[]
}

TaggingOpts

interface TaggingOpts {
  versionId?: string  // Specific version ID
}

Listing and Query Options

ListObjectQueryOpts

interface ListObjectQueryOpts {
  delimiter?: string      // Delimiter for grouping objects
  encodingType?: string   // Encoding type for object keys
  maxKeys?: number       // Maximum number of objects to return
  prefix?: string        // Object prefix filter
}

S3 Select Types

SelectOptions

interface SelectOptions {
  expression: string           // SQL-like query expression
  expressionType: 'SQL'       // Query language (currently only SQL)
  inputSerialization: {       // Input format configuration
    CSV?: {
      FileHeaderInfo?: 'USE' | 'IGNORE' | 'NONE'
      RecordDelimiter?: string      // Record separator
      FieldDelimiter?: string       // Field separator
      QuoteCharacter?: string       // Quote character
      QuoteEscapeCharacter?: string // Quote escape character
      Comments?: string            // Comment prefix
      AllowQuotedRecordDelimiter?: boolean
    }
    JSON?: {
      Type: 'DOCUMENT' | 'LINES'   // JSON format type
    }
    Parquet?: {}                   // Parquet format
    CompressionType?: 'NONE' | 'GZIP' | 'BZIP2' // Compression type
  }
  outputSerialization: {         // Output format configuration
    CSV?: {
      RecordDelimiter?: string     // Record separator
      FieldDelimiter?: string      // Field separator
      QuoteCharacter?: string      // Quote character
      QuoteEscapeCharacter?: string // Quote escape character
      QuoteFields?: 'ALWAYS' | 'ASNEEDED' // When to quote fields
    }
    JSON?: {
      RecordDelimiter?: string     // Record separator
    }
  }
  requestProgress?: boolean        // Include progress information
}

Bucket Configuration Types

BucketVersioningConfiguration

interface BucketVersioningConfiguration {
  Status?: 'Enabled' | 'Suspended'  // Versioning status
  MfaDelete?: 'Enabled' | 'Disabled' // MFA delete requirement
}

EncryptionConfig

interface EncryptionConfig {
  Rule: EncryptionRule[]
}

interface EncryptionRule {
  ApplyServerSideEncryptionByDefault: {
    SSEAlgorithm: 'AES256' | 'aws:kms'  // Encryption algorithm
    KMSMasterKeyID?: string             // KMS key ID (for KMS encryption)
  }
}

ObjectLockInfo

interface ObjectLockInfo {
  objectLockEnabled: 'Enabled' | 'Disabled'  // Object lock status
  rule?: {                                   // Default retention rule
    defaultRetention: {
      mode: RETENTION_MODES                   // Governance or Compliance
      days?: number                          // Retention period in days
      years?: number                         // Retention period in years
      validity?: RETENTION_VALIDITY_UNITS    // DAYS or YEARS
    }
  }
}

Lifecycle Configuration

LifeCycleConfigParam

interface LifeCycleConfigParam {
  Rule: LifecycleRule[]
}

interface LifecycleRule {
  ID?: string                    // Rule identifier
  Status: 'Enabled' | 'Disabled' // Rule status
  Filter?: {                     // Object filter
    Prefix?: string              // Prefix filter
    Tag?: Tag                    // Tag filter
    And?: {                      // Multiple filters
      Prefix?: string
      Tags?: Tag[]
    }
  }
  Expiration?: {                 // Object expiration
    Days?: number                // Days after creation
    Date?: string                // Specific date
    ExpiredObjectDeleteMarker?: boolean
  }
  NoncurrentVersionExpiration?: { // Non-current version expiration
    NoncurrentDays: number       // Days after becoming non-current
  }
  AbortIncompleteMultipartUpload?: { // Cleanup incomplete uploads
    DaysAfterInitiation: number  // Days after upload initiation
  }
  Transition?: {                 // Storage class transition
    Days?: number                // Days after creation
    Date?: string                // Specific date
    StorageClass: string         // Target storage class
  }
  NoncurrentVersionTransition?: { // Non-current version transition
    NoncurrentDays: number       // Days after becoming non-current
    StorageClass: string         // Target storage class
  }
}

Replication Configuration

ReplicationConfigOpts

interface ReplicationConfigOpts {
  Role: string              // IAM role for replication
  Rule: ReplicationRule[]   // Replication rules
}

interface ReplicationRule {
  ID?: string              // Rule identifier
  Status: 'Enabled' | 'Disabled' // Rule status
  Priority?: number        // Rule priority
  DeleteMarkerReplication?: {
    Status: 'Enabled' | 'Disabled'
  }
  Filter?: {               // Object filter
    Prefix?: string        // Prefix filter
    Tag?: Tag             // Tag filter
    And?: {               // Multiple filters
      Prefix?: string
      Tags?: Tag[]
    }
  }
  Destination: {
    Bucket: string         // Destination bucket ARN
    StorageClass?: string  // Storage class in destination
    ReplicationTime?: {    // Replication time control
      Status: 'Enabled' | 'Disabled'
      Time: { Minutes: number }
    }
    Metrics?: {            // Replication metrics
      Status: 'Enabled' | 'Disabled'
      EventThreshold: { Minutes: number }
    }
  }
}

Presigned Operations Types

PreSignRequestParams

interface PreSignRequestParams {
  [key: string]: string | undefined
  
  // Response override parameters
  'response-content-type'?: string
  'response-content-language'?: string
  'response-expires'?: string
  'response-cache-control'?: string
  'response-content-disposition'?: string
  'response-content-encoding'?: string
  
  // Version selection
  'versionId'?: string
}

PostPolicyResult

interface PostPolicyResult {
  postURL: string                    // URL to POST to
  formData: Record<string, string>   // Form fields to include in POST
}

Internal Types

IRequest

interface IRequest {
  protocol: string          // HTTP protocol
  port?: number | string   // Port number
  method: string           // HTTP method
  path: string            // Request path
  headers: RequestHeaders // Request headers
}

ICanonicalRequest

type ICanonicalRequest = string  // Canonical request string for signing

IncompleteUploadedBucketItem

interface IncompleteUploadedBucketItem {
  key: string       // Object key
  uploadId: string  // Upload ID
  size: number     // Current upload size
}

Constants

Helper Constants

const DEFAULT_REGION: string = 'us-east-1'
const PRESIGN_EXPIRY_DAYS_MAX: number = 604800  // 7 days in seconds

Status Types

type EnabledOrDisabledStatus = 'Enabled' | 'Disabled'

Version Identificator

type VersionIdentificator = {
  versionId?: string
}

Usage Examples

Error Handling Example

import { 
  S3Error,
  InvalidBucketNameError,
  AccessKeyRequiredError,
  ExpiresParamError
} from 'minio'

try {
  await client.makeBucket('invalid..bucket..name')
} catch (error) {
  if (error instanceof InvalidBucketNameError) {
    console.error('Invalid bucket name:', error.message)
  } else if (error instanceof S3Error) {
    console.error(`S3 Error [${error.code}]:`, error.message)
    if (error.region) {
      console.error('Region:', error.region)
    }
  } else {
    console.error('Unexpected error:', error)
  }
}

Type-Safe Configuration

import { 
  ClientOptions,
  ENCRYPTION_TYPES,
  RETENTION_MODES,
  LEGAL_HOLD_STATUS
} from 'minio'

// Type-safe client configuration
const clientConfig: ClientOptions = {
  endPoint: 'play.min.io',
  port: 9000,
  useSSL: true,
  accessKey: 'access-key',
  secretKey: 'secret-key',
  region: 'us-east-1',
  pathStyle: false
}

// Type-safe encryption configuration
const encryption: Encryption = {
  type: ENCRYPTION_TYPES.SSEC,
  SSECustomerKey: 'your-32-character-key-here!!!!!!',
  SSECustomerKeyMD5: 'md5-hash-of-key'
}

// Type-safe retention configuration  
const retention: Retention = {
  mode: RETENTION_MODES.GOVERNANCE,
  retainUntilDate: new Date('2024-01-01'),
  governanceBypass: false
}

Utility Functions

removeDirAndFiles (Deprecated)

function removeDirAndFiles(dirPath: string, removeSelf?: boolean): void

Usage: Removes a directory and all its contents.

Parameters:

  • dirPath: string - Path to the directory to remove
  • removeSelf?: boolean - Whether to remove the directory itself (default: true)

Note: This function is deprecated. Use Node.js fs module methods like fs.rmSync() instead.

Example:

import { removeDirAndFiles } from 'minio'

// ⚠️ Deprecated - use fs.rmSync instead
removeDirAndFiles('/path/to/temp/dir', true)

// ✅ Recommended approach
import * as fs from 'node:fs'
fs.rmSync('/path/to/temp/dir', { recursive: true, force: true })

This comprehensive type reference covers all interfaces, enums, error classes, and type definitions available in the MinIO JavaScript client library, providing complete type safety and documentation for TypeScript development.

Related Documentation:

  • Client Setup - Client configuration and initialization
  • Object Operations - Basic object operations using these types
  • Advanced Objects - Advanced features using complex types
  • Bucket Operations - Bucket management with configuration types

docs

advanced-objects.md

bucket-operations.md

client-setup.md

index.md

notifications.md

object-operations.md

presigned-operations.md

types-and-errors.md

tile.json