s3-dart-lite

A lightweight S3 client for Dart, ported from the excellent TypeScript s3-lite-client.

Features

• Lightweight: Minimal dependencies, focused on core S3 functionality.
• S3 Compatible: Works with AWS S3, MinIO, DigitalOcean Spaces, and other S3-compatible storage providers.
• Dart Native: Built with Dart idioms, supporting Stream<List<int>> for efficient uploads and downloads.

Documentation

• API Reference (Generated via dart doc)
• Project Documentation (Guides and Tutorials)

To view the full project documentation website locally with MkDocs:

# Install mkdocs-material
pip install mkdocs-material

# Serve the site
mkdocs serve

Project Structure

• lib/src/client.dart: The main Client class handling request orchestration and configuration.
• lib/src/signing.dart: Implementation of AWS Signature V4 for request signing.
• lib/src/object_uploader.dart: Handles smart uploads (automatically switching between single-part and multipart based on stream analysis).
• lib/src/helpers.dart: Validation and formatting utilities.
• lib/src/errors.dart: Custom error types and XML error response parsing.

Installation

Add this to your pubspec.yaml:

dependencies:
  s3_dart_lite:
    path: /path/to/s3-dart-lite # Temporarily local or git dependency

Usage

Initialization

import 'package:s3_dart_lite/s3_dart_lite.dart';

final client = Client(
  ClientOptions(
    endPoint: 's3.us-east-1.amazonaws.com', // or your custom endpoint
    region: 'us-east-1',
    accessKey: 'YOUR_ACCESS_KEY',
    secretKey: 'YOUR_SECRET_KEY',
    useSSL: true, // defaults to true
  ),
);

Uploading a File

You can upload files using Stream<List<int>>, List<int> bytes, or String content.

import 'dart:io';

// ... client init ...

final file = File('hello.txt');
final stream = file.openRead();

try {
  await client.putObject(
    'hello.txt',
    stream,
    bucketName: 'my-bucket',
  );
  print('Upload complete');
} catch (e) {
  print('Upload failed: $e');
}

Downloading a File

import 'dart:io';

// ... client init ...

try {
  final response = await client.getObject(
    'hello.txt', 
    bucketName: 'my-bucket'
  );
  
  // Save to file
  await File('downloaded_hello.txt').writeAsBytes(response.bodyBytes);
  print('Download complete');
} catch (e) {
  print('Download failed: $e');
}

Credits

This project is a port of s3-lite-client by Braden MacDonald. Huge thanks to the original authors for the solid foundation and design.

License

MIT