flutter_smart_upload library
Backend-agnostic, memory-efficient file uploads for Flutter.
flutter_smart_upload orchestrates uploads — chunking, retries, pause and
resume, a concurrency-limited queue, progress, compression and persistence
— and delegates the actual transport to an UploadAdapter you implement
for your backend. It is not an HTTP client and has no opinion about your
server.
final SmartUploader uploader = SmartUploader(
adapter: MyApiUploadAdapter(),
config: SmartUploadConfig(
chunkSize: 2 * 1024 * 1024,
maxConcurrentUploads: 2,
maxRetries: 3,
),
);
final UploadTask task = await uploader.upload(
file: File('/path/to/image.jpg'),
options: const UploadOptions(compress: true, quality: 80),
onProgress: (UploadProgress p) => print('${p.percentage}%'),
);
final UploadResult result = await task.done;
print(result.url);
Classes
- AlwaysOnlineNetworkMonitor
- The default monitor: assumes the device is always online and lets adapter errors drive retries.
- ChecksumProvider
- Computes integrity digests for files and chunks.
- ChunkUploadResult
- What an adapter reports back after storing one chunk.
- CompressionResult
- What a Compressor produced.
- Compressor
- Transforms a file before it is uploaded.
- ExponentialBackoffRetryPolicy
- The default policy: exponential backoff with optional jitter, skipping errors that cannot succeed on a retry.
- FileStatChecksumProvider
- A provider that fingerprints a file from its path, size and modification time instead of its contents.
- FileUploadStorage
- Stores one JSON file per upload inside a directory.
- ImageCompressor
- Resizes and re-encodes images before upload, in a background isolate.
- InMemoryUploadAdapter
- A fake backend that keeps uploads in memory.
- ManualNetworkMonitor
- A monitor whose state is set manually. Intended for tests and for apps that already track connectivity in their own state management.
- Md5Base64ChecksumProvider
-
Base64-encoded MD5, the form S3 and GCS want in
Content-MD5. - Md5ChecksumProvider
-
MD5 digests, hex encoded. Fast, and what most upload APIs expect for
Content-MD5. - MemoryUploadStorage
- In-process storage. The default.
- NetworkMonitor
- Tells the orchestrator whether the device currently has connectivity.
- NoopCompressor
- A compressor that never changes anything. The default.
- NoRetryPolicy
- A policy that never retries. Useful in tests and for fire-and-forget uploads where the caller wants to handle failure itself.
- RetryContext
- Everything a RetryPolicy needs to decide what happens after a failure.
- RetryPolicy
- Decides whether and when a failed operation is tried again.
- Sha256ChecksumProvider
- SHA-256 digests, hex encoded. Slower than MD5, collision resistant.
- SmartUploadConfig
- Global settings for a SmartUploader.
- SmartUploader
- The entry point of the package.
- StreamNetworkMonitor
- A monitor driven by an external Stream of connectivity states.
- UploadAdapter
- The seam between this package and your backend.
- UploadCancelledEvent
- The upload was cancelled by the caller.
- UploadChunk
- A single slice of the source file, already read into memory.
- UploadChunkCompletedEvent
- One chunk was stored successfully.
- UploadCompletedEvent
- The upload finished successfully.
- UploadCompressedEvent
- Compression finished. Reports how much was saved.
- UploadCompressingEvent
- The compression pipeline is running.
- UploadEvent
-
Base class for everything published on
SmartUploader.events. - UploadFailedEvent
- The upload gave up after exhausting retries, or hit a permanent error.
- UploadOptions
- Per-upload settings: compression, naming, metadata and overrides of the global SmartUploadConfig.
- UploadPausedEvent
- The upload was suspended.
- UploadPreparingEvent
- The file is being validated, hashed and split into chunks.
- UploadProgress
- A point-in-time snapshot of an upload's transfer progress.
- UploadProgressEvent
- Bytes were acknowledged by the adapter.
- UploadQueuedEvent
- The upload was accepted and is waiting for a concurrency slot.
- UploadRecord
- The persisted form of an upload — everything needed to pick it up again after the app was killed mid-transfer.
- UploadRequest
- Everything an UploadAdapter needs to open a server-side session.
- UploadResult
-
The outcome of a successful upload, returned by
UploadAdapter.completeand surfaced onUploadTask.done. - UploadResumedEvent
- The upload left the paused state.
- UploadRetryEvent
- A failed operation is about to be retried.
- UploadSession
-
The adapter's handle on a server-side upload, returned by
UploadAdapter.initialize. - UploadStartedEvent
- The adapter opened a session and the first chunk is about to be sent.
- UploadStorage
- Where upload state is kept between attempts — and between app launches.
- UploadTask
- A handle on one upload.
Enums
- ChecksumMode
- How aggressively integrity checksums should be computed.
- ImageOutputFormat
- Output container for image re-encoding.
- UploadErrorCode
- Canonical error codes emitted by the package.
- UploadStatus
- The lifecycle state of a single upload.
Typedefs
- ProgressCallback = void Function(UploadProgress progress)
- Called whenever transfer progress advances.
- StatusCallback = void Function(UploadStatus status)
- Called whenever an upload changes state.
Exceptions / Errors
- SmartUploadException
-
The single exception type thrown by
flutter_smart_upload.