MinIO JavaScript Client Library

Package: minio
Version: 8.0.5
Type: JavaScript/TypeScript library for S3-compatible cloud storage
License: Apache 2.0

The MinIO JavaScript client library provides comprehensive functionality for interacting with MinIO and Amazon S3 compatible cloud storage services. It offers both callback-based and Promise-based APIs, supporting Node.js and browser environments.

Installation

npm install minio

Core Imports

// Main client class
import { Client } from 'minio'

// Helper classes for advanced operations
import { CopySourceOptions, CopyDestinationOptions } from 'minio'

// Policy and conditions
import { PostPolicy, CopyConditions } from 'minio'

// Notification system
import { NotificationConfig, TopicConfig, QueueConfig, CloudFunctionConfig } from 'minio'

// Credential providers
import { CredentialProvider, AssumeRoleProvider, IamAwsProvider } from 'minio'

// Error classes
import { 
  S3Error, 
  InvalidArgumentError, 
  InvalidBucketNameError,
  InvalidObjectNameError 
} from 'minio'

// Types and enums
import { 
  ENCRYPTION_TYPES, 
  LEGAL_HOLD_STATUS, 
  RETENTION_MODES,
  RETENTION_VALIDITY_UNITS 
} from 'minio'

Quick Start

import { Client } from 'minio'

// Create client instance
const minioClient = new Client({
  endPoint: 'play.min.io',
  port: 9000,
  useSSL: true,
  accessKey: 'your-access-key',
  secretKey: 'your-secret-key'
})

// Basic operations
async function basicOperations() {
  // Create bucket
  await minioClient.makeBucket('test-bucket', 'us-east-1')
  
  // Upload object
  const uploadInfo = await minioClient.putObject(
    'test-bucket', 
    'test.txt', 
    'Hello MinIO!'
  )
  
  // Download object
  const stream = await minioClient.getObject('test-bucket', 'test.txt')
  
  // Get object metadata
  const stat = await minioClient.statObject('test-bucket', 'test.txt')
  
  // List objects
  const objectStream = minioClient.listObjects('test-bucket')
  objectStream.on('data', obj => console.log(obj))
}

Architecture Overview

The MinIO JavaScript client follows a modular architecture:

Core Components

1. Client Class - Main entry point extending TypedClient

   • Bucket operations (create, delete, list, policies)
   • Object operations (put, get, copy, delete)
   • Presigned URL generation
   • Notification management

2. Credential Management - Flexible authentication

   • Static credentials (access/secret key)
   • Credential providers (IAM, STS AssumeRole)
   • Session tokens and temporary credentials

3. Helper Classes - Advanced functionality

   • Copy operations with conditions and metadata
   • Post policy generation for browser uploads
   • Notification configuration and polling

4. Error Handling - Comprehensive error types

   • S3-specific errors with codes and regions
   • Validation errors for parameters
   • Network and authentication errors

Environment Support

• Node.js - Full functionality with streams and file system access
• Browser - Core operations with limitations (no file system operations)
• TypeScript - Complete type definitions and intellisense support

Capabilities

Bucket Management

• Create, delete, and list buckets
• Bucket policies and access control
• Versioning configuration
• Lifecycle management
• Encryption settings
• Replication configuration
• Notification setup

Object Operations

• Upload/download with streams or files
• Metadata and tags management
• Server-side encryption support
• Object versioning and retention
• Legal hold functionality
• Multipart upload for large files

Advanced Features

• Presigned URLs for secure access
• S3 Select for querying object content
• Event notifications with polling
• Copy operations with conditions
• Compose multiple objects into one

Security Features

• Multiple encryption types (SSE-C, KMS)
• Access control through policies
• Temporary credentials and STS
• Request signing and authentication

Documentation Structure

This documentation is organized into focused sections:

• Client Setup - Client initialization, configuration options, credential providers
• Bucket Operations - Complete bucket management functionality
• Object Operations - Basic object CRUD operations and metadata
• Advanced Objects - Multipart uploads, composition, retention, S3 Select
• Presigned Operations - Presigned URLs and POST policies for secure access
• Notifications - Event notification system and polling mechanisms
• Types and Errors - Complete type definitions, error classes, and enums

Compatibility

S3 Compatibility

The client is compatible with:

• Amazon S3
• MinIO Server
• Google Cloud Storage (S3 compatibility mode)
• Other S3-compatible storage services

API Patterns

The library supports both patterns:

// Promise-based (recommended)
const result = await minioClient.listBuckets()

// Callback-based (legacy support)
minioClient.listBuckets((err, buckets) => {
  if (err) throw err
  console.log(buckets)
})

Performance Considerations

• Streaming Support - Efficient handling of large files
• Connection Pooling - Configurable HTTP agents
• Multipart Uploads - Automatic handling for large objects
• Presigned URLs - Offload uploads/downloads to clients
• Request Tracing - Built-in debugging capabilities

Next Steps

1. Start with Client Setup to configure your client
2. Explore Bucket Operations for bucket management
3. Learn Object Operations for basic file handling
4. Check Advanced Objects for complex scenarios
5. Review Types and Errors for comprehensive API reference