winche_storage

Dart SDK for the WincheStorage file management backend. Provides resumable, multipart-aware upload and download tasks behind a reference-based API, with an optional durable offline cache and auto-resume layer.

Features

Reference-based ChildReference API (storage.child('a/b/c.jpg')).
Resumable, multipart-aware uploads from a file path or raw bytes.
Resumable downloads with HTTP Range support.
Pause / resume / cancel on both upload and download tasks, with progress streams.
Offline cache: keep files available offline — cache: true on upload (no download roundtrip) or makeAvailableOffline() after. Server reads (getSnapshot/listChildren) and cache reads (offlineSnapshot/ offlineChildren) are separate; content-aware freshness via offlineCopyStatus().
Durable transfers: enqueue: true queues an upload/download so it survives an app restart and retries with backoff — start it while offline and just await it. Reattach a progress UI after a restart with uploadFor/downloadFor.
Per-operation control: enqueue (durable) and cache (keep-offline) flags; transfers expose a queued state and resolve only on the terminal outcome.
Pure Dart — no Flutter dependency. Persistence via sembast (file on native, IndexedDB on web), or fully in-memory.
Pluggable backend via the WincheStorageApi interface (WincheStorageHttpApi ships by default).
Typed exceptions (WincheStorageException and subclasses).

Installation

dart pub add winche_storage

Or add it to pubspec.yaml:

dependencies:
  winche_storage: ^4.0.0

Setup

WincheStorage is ready to use as soon as it's constructed — there is no initialize step. The durable transfer queue and offline cache are enabled simply by configuring a store (see the note under the example).

import 'package:winche_storage/winche_storage.dart';

final storage = WincheStorage(
  WincheStorageConfig(
    uri: Uri.parse('https://your-api.example.com/files'),

    // Optional. Returns the current auth token, re-read on every request, so a
    // rotated token is picked up automatically. Sent as `Authorization: Bearer`.
    tokenProvider: () async => currentToken,

    // Required unless `inMemory: true`. Scopes all local state to one identity
    // — return the signed-in user's id. See "Multi-user" below.
    namespaceResolver: () => currentUserId,

    // Resolves the parent directory the identity-scoped root is created in.
    // Its presence (or `inMemory`, or web) enables the durable transfer queue
    // and offline cache — there are no separate enable flags.
    directoryResolver: () async {
      final dir = await getApplicationDocumentsDirectory(); // from path_provider
      return '${dir.path}/winche_files';
    },

    // Optional. Files larger than this are uploaded in parts. Defaults to 5 MiB.
    multipartThreshold: 5 * 1024 * 1024,

    // Optional. Use an in-memory index (catalog + transfer queue) instead of
    // sembast — files still go to disk. Handy for tests. Defaults to false.
    inMemory: false,

    // Optional. Backoff tuning for the durable transfer queue's retries.
    retryBaseDelay: Duration(seconds: 1),
    retryMaxDelay: Duration(seconds: 30),
    retryMaxAttempts: 5,
    retryPollInterval: Duration(seconds: 30),
  ),
);

Store presence enables the subsystems. The durable transfer queue and offline cache exist whenever there's somewhere to put a store: a directoryResolver (native), inMemory: true, or web (IndexedDB). With none of those configured on native the SDK is fully stateless — basic upload/ download still work (download takes an explicit path), and durable/offline operations throw StateError at call time.

Call await storage.close() when you're done. It aborts in-flight transfers, cancels the retry timers and closes the local store, in that order. It is idempotent and never waits on the network: durable transfers are left resumable, while one-shot transfers fail with StorageCancelledException.

Multi-user

Local state is single-tenant. The offline catalog, the cached bytes and the durable transfer queue carry no identity of their own, so one store shared between two users means the second user reads the first user's pinned files, and the first user's queued uploads replay under the second user's token.

namespaceResolver is therefore required for a persistent store, and gives each identity its own directory:

<directoryResolver()>/winche_storage_<namespace>/index.db   sembast: catalog + queue
<directoryResolver()>/winche_storage_<namespace>/cache/…    cached bytes
<directoryResolver()>/winche_storage_<namespace>/staging/…  pinned uploads in flight

On the web there are no files; the namespace becomes the IndexedDB database name.

It resolves lazily on first store access and is then cached — it pins the identity for the lifetime of that WincheStorage. Returning a different value later does not migrate a live instance. Switching users is:

await storage.close();
storage = WincheStorage(WincheStorageConfig(
  uri: uri,
  namespaceResolver: () => newUserId,
  directoryResolver: directoryResolver,
));

Await the close() before building the replacement — it resolves only once the store is really closed. The previous user's queued transfers stay on disk and resume when they sign back in.

The resolved namespace must match [A-Za-z0-9._-]+ (it becomes a directory name). It is validated, not sanitised: quietly rewriting a user id could collapse two identities onto one store, which is exactly the leak this prevents.

With inMemory: true there is no persistence to scope, so namespaceResolver must be omitted.

How a transfer flows

The two per-call flags (cache, enqueue) and the durable lifecycle at a glance:

flowchart TD
    Start(["uploadPath / uploadBytes / download"]) --> Cache{"cache: true?<br/>(uploads)"}
    Cache -->|yes| Stage["stage source into the offline cache,<br/>upload from the staged copy"]
    Cache -->|no| Enq{"enqueue: true?<br/>(uploadPath / download)"}
    Stage --> Enq

    Enq -->|no| Direct["one-shot task → running"]
    Direct --> DirOut{"success?"}
    DirOut -->|yes| Done(["complete"])
    DirOut -->|"no (e.g. offline)"| Failed(["failed"])

    Enq -->|yes| Queued["tracked handle: queued"]
    Queued --> Attempt["controller drives one attempt → running"]
    Attempt --> Outcome{"outcome"}
    Outcome -->|success| Done2(["complete · dropped from queue<br/>offline copy finalized if cache:true"])
    Outcome -->|"transient / offline"| Backoff["back to queued · backoff"]
    Backoff --> Attempt
    Outcome -->|"retries exhausted / permanent"| Failed2(["failed"])

A tracked (enqueue: true) handle survives an app restart: on construction the controller rehydrates the queue and re-drives each transfer from queued. Its whenDone resolves only at a terminal node (complete / failed), so you can start a transfer offline and just await it.

Usage

References

ChildReference points to a file by its slash-separated path. References compose via .child().

final userRoot = storage.child('userFiles/user-123');
final photoRef = userRoot.child('photo.jpg');
// equivalent to storage.child('userFiles/user-123/photo.jpg')

photoRef.name;     // 'photo.jpg'  — last path segment
photoRef.path;     // 'userFiles/user-123/photo.jpg'
photoRef.parent;   // ChildReference('userFiles/user-123')

Upload

Upload from a local file path with uploadPath, or from bytes with uploadBytes.

final task = photoRef.uploadPath(
  '/local/path/photo.jpg',
  mimeType: 'image/jpeg',     // optional — inferred from the extension if omitted
  metadata: {'label': 'cover'},
);

// Or from bytes (mimeType is required, as it can't be inferred):
final task = photoRef.uploadBytes(
  bytes,
  'image/jpeg',
  metadata: {'label': 'cover'},
);

// Stream progress
task.stateStream.listen((UploadTaskState state) {
  print('${state.status} — ${(state.progress * 100).toStringAsFixed(1)}%');
});

final FileSnapshot? snapshot = await task.whenDone; // null if cancelled

Uploading to a path that already has a file:

Completed file, identical size + MIME — skipped; the existing record is returned without re-uploading.
Completed file, different size or MIME — replaced (the old object is deleted and the new content uploaded).
Interrupted upload, identical size + MIME — resumed from the last completed part.
Interrupted upload, different size or MIME — discarded and re-uploaded from scratch (so a previously failed attempt never blocks the path).

Files at or below multipartThreshold upload in a single request; larger files are uploaded in parts.

Per-call flags: `enqueue` and `cache`

Two optional flags make an upload robust:

enqueue: true — durable: the upload joins the transfer queue, is deduped by path, survives an app restart, and retries until it succeeds (so it can be started while offline). File-backed only (uploadPath); requires a configured store. Without it, the upload is a one-shot.
cache: true — keep it available offline: the source is staged, uploaded from that staged copy, then moved into the id-keyed offline cache on success — no separate download. Best-effort (a caching failure leaves the upload successful and records a stale pin). Requires a configured offline cache.

// Durable AND offline-kept — start it even while offline; await it; it
// completes once the server is reachable.
final task = photoRef.uploadPath(
  '/local/path/photo.jpg',
  enqueue: true,
  cache: true,
);
await task.whenDone;

A flag whose subsystem isn't configured throws StateError (see Setup). uploadBytes accepts cache (it stages the bytes to disk first) but not enqueue — byte uploads aren't durable; write the bytes to a file and use uploadPath(enqueue: true) for that. The cache upload is the upload-time counterpart to makeAvailableOffline(): same result, reusing the bytes you already have instead of downloading them back.

Download

download writes the file's bytes to an explicit path. For a managed, offline-cached copy that needs no path, use makeAvailableOffline instead.

final task = photoRef.download('/local/photos/photo.jpg');

task.stateStream.listen((DownloadTaskState state) {
  print('${state.status} — ${(state.progress * 100).toStringAsFixed(1)}%');
});

await task.whenDone;

Pass enqueue: true to make the download durable — it joins the transfer queue and resumes after an app restart, retrying until it succeeds (requires a configured store; throws StateError otherwise). Without it the download is a one-shot.

Pause / resume / cancel

Both UploadTask and DownloadTask support mid-flight control:

task.pause();
task.resume(); // resumes from the last completed part / byte offset

// Upload cancel — also deletes the remote file record
await task.cancel();

// Download cancel — deletes any partially written local file
task.cancel();

Offline cache

Requires a configured store (see Setup). Pin a file to download it into a managed, id-keyed cache directory and track it so it stays available offline.

If you're the one uploading the file, prefer uploadPath(..., cache: true) (see Upload) — it populates the cache from the bytes you already have, skipping the download this method would otherwise perform.

// Download + pin for offline use. Completes when the file is on disk.
await photoRef.makeAvailableOffline();

// On a directory path it pins every file directly under it (one level — the
// server lists a single level, so nested sub-directories aren't included):
await storage.child('userFiles/user-123').makeAvailableOffline();

// What changed about the pinned copy? (content overwrite vs deleted vs current)
switch (await photoRef.offlineCopyStatus()) {
  case OfflineCopyStatus.contentChanged:
    await photoRef.refreshOfflineCopy(); // bytes changed — re-download
  case OfflineCopyStatus.remoteDeleted:
    await photoRef.removeOfflineCopy();  // gone — drop the local copy
  case OfflineCopyStatus.upToDate:
  case OfflineCopyStatus.notPinned:
  case OfflineCopyStatus.unknown:        // offline / no fingerprint — leave as-is
    break;
}

// Drop the local copy and catalog entry.
await photoRef.removeOfflineCopy();

// Remove every pinned file.
await storage.clearOfflineCache();

Reads split cleanly into server and cache — each call has one source:

getSnapshot() / listChildren() are server-only: they return the authoritative server record(s) and throw StorageUnavailableException when the server is unreachable. They never consult the cache, so their fromCache is always false and they don't carry isCached / localPath.
offlineSnapshot() / offlineChildren() are cache-only: they read the local catalog without contacting the server (fromCache == true), so they keep working offline. Both require a configured store. offlineSnapshot() returns a missing snapshot when the file isn't pinned; offlineChildren() returns the pinned files directly under the path (a partial view, possibly empty).

// Server-only: authoritative, throws when offline.
final FileSnapshot snap = await photoRef.getSnapshot();
if (snap.exists) print('server size: ${snap.data!.sizeBytes}');

// Cache-only: the local copy, no network.
final FileSnapshot offline = await photoRef.offlineSnapshot();
if (offline.exists) {
  print('available offline at: ${offline.data!.localPath}'); // <cacheDir>/<id>.jpg
}

Compose them yourself for a remote-first-with-fallback read:

Future<FileSnapshot> read(ChildReference ref) async {
  try {
    return await ref.getSnapshot();      // server first
  } on StorageUnavailableException {
    return await ref.offlineSnapshot();  // fall back to the cached copy
  }
}

The directory counterpart — annotate a live listing with offline state by cross-referencing the cache-only read:

final live = await userRoot.listChildren();     // full server listing (throws offline)
final cached = await userRoot.offlineChildren(); // pinned-only, works offline
final cachedPaths = {for (final f in cached.files) f.reference.path};
for (final snap in live.files) {
  final badge = cachedPaths.contains(snap.reference.path) ? '✓ offline' : '';
  print('${snap.reference.path} $badge');
}

On a cache-only snapshot, data.localPath is the absolute path to the local copy and data.isCached is true when its content is downloaded. Server-only reads don't carry these — use the offline* reads or offlineCopyStatus().

Cached files are stored at <directoryResolver()>/winche_storage_<namespace>/cache/<fileId><.ext> — keyed by the immutable file id (so they survive path/metadata changes), with an extension derived from the name or MIME type. Pins are explicit and never auto-evicted.

Auto-resume

Available when a store is configured (see Setup). Uploads and downloads started with enqueue: true are persisted to a durable queue, resumed when the SDK is constructed, and retried on failure with exponential backoff (configurable via the retry* fields on WincheStorageConfig).

// `enqueue: true` makes it durable — queued, resumed after a restart, retried.
final task = photoRef.download('/local/photos/photo.jpg', enqueue: true);

// On app start, the SDK auto-resumes pending transfers. You can also trigger
// drains explicitly (e.g. when connectivity returns):
await storage.resumeDownloads();
await storage.resumeUploads();

// Resume a single path's transfer.
await photoRef.resumeTransfer();

// Observe lifecycle events as the queue drains.
storage.transferEvents.listen((TransferEvent e) {
  // started | completed | failed | retrying | paused
  print('${e.type} ${e.kind} ${e.path}');
});

How a failed attempt is handled

A durable transfer's response to failure depends on what failed. One uniform "count an attempt, then give up" policy would let an expired token or a flat network destroy queued work in a couple of minutes.

Failure	Behaviour
`unauthenticated`, `unavailable`	Paused. The record and the handle both survive, and no attempt is counted — a paused transfer can wait indefinitely without exhausting its budget. It keeps probing on the usual backoff, so a brief blip recovers in about a second. Emits `TransferEventType.paused`; the record's status becomes `TransferStatus.paused` with the reason in `lastError`.
`internal`, `deadlineExceeded`, `unknown`, and any non-`WincheStorageException`	Retried with exponential backoff, up to `retryMaxAttempts`. Past the cap the handle fails; the record stays in the queue as `failed` so `pendingTransfers()` still surfaces it.
`permissionDenied`, `notFound`, `invalidArgument`, `failedPrecondition`	Terminal. The record is dropped and the handle fails. The `failed` event carries the full `TransferRecord` in `record`, so the work is recoverable — a path and an error alone would lose the source `localPath`, `mimeType` and `metadata`.

After refreshing an auth token, call storage.resumeTransfers() to re-drive everything that paused, rather than waiting out the retryPollInterval backstop:

await refreshMyToken();
await storage.resumeTransfers();

Note that a paused transfer's whenDone does not settle while it is paused — that is the point of the stable handle: you can start an upload while offline and simply await it.

When a transfer's whenDone resolves, it has fully landed: the durable record is already gone from pendingTransfers(), the completed event has already been emitted, and a cache: true upload's offline copy is already committed. You can read any of them on the next line without waiting.

A durable (enqueue: true) transfer is tracked and deduped by path: calling uploadPath/download again for the same path returns the existing handle rather than starting a duplicate. After a restart the original handle object is gone, so reattach a progress UI with storage.uploadFor(path) / downloadFor(path). Per-byte progress stays on the handle's stateStream, which also reports the queued state while it waits to (re)start.

List a directory

final DirectorySnapshot dir = await storage.child('userFiles/user-123').listChildren(
  mimeType: 'image/jpeg', // optional filter
);

for (final snapshot in dir.files) {
  print('${snapshot.reference.path} — ${snapshot.data?.sizeBytes} bytes');
}

listChildren() is server-only — it throws StorageUnavailableException when offline. For the locally pinned files, use offlineChildren() (see Offline cache).

Get file metadata

getSnapshot() always returns a FileSnapshot. Check exists to know whether the file is present; data is null when it isn't. It's server-only (throws when offline); for the cached copy use offlineSnapshot() — see the Offline cache section.

final FileSnapshot snapshot = await photoRef.getSnapshot();

if (snapshot.exists) {
  final data = snapshot.data!;
  print(data.id);
  print(data.path);
  print(data.directory);
  print(data.mimeType);
  print(data.sizeBytes);
  print(data.uploadStatus); // UploadStatus.pending | .complete | .failed
  print(data.metadata);
  print(data.version);
  print(data.createdAt);
  print(data.updatedAt);
}

Update metadata

final FileSnapshot updated = await photoRef.updateMetadata({'label': 'hero'});

Delete

final bool deleted = await photoRef.delete(); // false if the file didn't exist

API reference

`WincheStorageConfig`

Field	Type	Default	Description
`uri`	`Uri`	required	Base URI of the WincheStorage REST backend
`tokenProvider`	`FutureOr<String> Function()?`	null	Returns the auth token, re-read per request and sent as `Authorization: Bearer`
`multipartThreshold`	`int`	`5 * 1024 * 1024`	File size (bytes) above which multipart upload is used
`inMemory`	`bool`	`false`	Use an in-memory index (catalog + queue) instead of sembast; files still go to disk. Also enables the subsystems
`namespaceResolver`	`FutureOr<String> Function()?`	null	Required unless `inMemory` (and must be omitted when it is). Scopes all local state to one identity (lazy, cached). Must match `[A-Za-z0-9._-]+`. See Multi-user
`directoryResolver`	`Future<String> Function()?`	null	Resolves the parent directory the identity-scoped root is created in (lazy, cached). Its presence (or `inMemory`/web) enables the durable queue + offline cache
`retryBaseDelay`	`Duration`	`1s`	Initial backoff before the first durable-transfer retry
`retryMaxDelay`	`Duration`	`30s`	Cap on the exponential backoff between retries
`retryMaxAttempts`	`int`	`5`	Retries before a transfer fails permanently
`retryPollInterval`	`Duration`	`30s`	Backstop poll interval that re-drives still-retryable failed transfers, and every paused one

`WincheStorage`

Member	Description
`WincheStorage(config)`	Creates the SDK. Ready to use immediately; auto-resumes pending transfers when a store is configured.
`WincheStorage.withStore(api, store, {...})`	Advanced/testing: build over an explicit `WincheStorageApi` and `StorageLocalStore` (subsystems always available).
`child(path)`	Returns a `ChildReference` for the given path.
`resumeTransfers()`	Re-drives every transfer halted by a pause (expired token, unreachable server). Call after refreshing an auth token. Throws `StateError` when no store is configured.
`resumeDownloads()`	Drains all queued downloads. Throws `StateError` when no store is configured.
`resumeUploads()`	Drains all queued uploads. Throws `StateError` when no store is configured.
`pendingTransfers({kind})`	Snapshot of the durable queue (pending/running/paused/failed `TransferRecord`s), optionally filtered by `TransferKind`. Throws `StateError` when no store is configured.
`transferEvents`	`Stream<TransferEvent>` of queue lifecycle events. Throws `StateError` when no store is configured.
`uploadFor(path)` / `downloadFor(path)`	The live tracked transfer handle for `path` (or `null`), to reattach a progress UI after a restart. Throws `StateError` when no store is configured.
`clearOfflineCache()`	Evicts every pinned file. Throws `StateError` when no store is configured.
`close()`	Aborts in-flight transfers, cancels the retry timers and closes the local store, in that order. Idempotent, never waits on the network. Durable transfers stay resumable; one-shot ones fail with `StorageCancelledException`. Every member above throws `StateError` afterwards.
`isClosed`	Whether `close()` has been called.

`ChildReference`

Member	Description
`path`	The file's slash-separated path string.
`name`	The last path segment (e.g. `photo.jpg`).
`parent`	The parent reference, or `null` at a single-segment path.
`child(path)`	Returns a new `ChildReference` at `this.path/path`.
`getSnapshot()`	Fetches metadata from the server only; throws `StorageUnavailableException` when offline.
`listChildren({mimeType})`	Lists files under this path from the server only, returning a `DirectorySnapshot` (its `.files` holds a `FileSnapshot` each); throws when offline.
`offlineSnapshot()`	The cached copy's metadata, read from the local catalog only (`fromCache: true`); missing snapshot when not pinned. Requires a store.
`offlineChildren({mimeType})`	The locally pinned files directly under this path, read from the local catalog only (`fromCache: true`, partial, may be empty). Requires a store.
`uploadPath(localPath, {mimeType, metadata, multipartThreshold, enqueue, cache})`	Starts an `UploadTask` from a local file. `enqueue: true` → durable/queued; `cache: true` → also kept offline (stage-first). Each requires its subsystem, else `StateError`.
`uploadBytes(bytes, mimeType, {metadata, multipartThreshold, cache})`	Starts an `UploadTask` from raw bytes. `cache: true` keeps it offline. Not durable — use `uploadPath(enqueue: true)` for that.
`download(saveTo, {enqueue})`	Starts a `DownloadTask` to the explicit path `saveTo`. `enqueue: true` → durable/queued (else one-shot).
`makeAvailableOffline()`	Pins + downloads the file for offline use; on a directory path, pins every file directly under it (one level). Requires a configured store.
`refreshOfflineCopy()`	Re-downloads the current remote version into the cache. Requires a configured store.
`offlineCopyStatus()`	`Future<OfflineCopyStatus>` — `upToDate` / `contentChanged` / `remoteDeleted` / `notPinned` / `unknown` (offline or no fingerprint). Requires a configured store.
`removeOfflineCopy()`	Removes the local copy + catalog entry. Requires a configured store.
`resumeTransfer()`	Resumes this path's queued/paused durable transfer. Requires a configured store.
`updateMetadata(metadata)`	Updates server-side metadata. Returns a `FileSnapshot`. If the file is pinned offline, its cached metadata is updated too (content fingerprint preserved).
`delete()`	Deletes the file. Returns `bool`.

Offline / durable-transfer methods throw StateError when no store is configured (no directoryResolver, no inMemory, on native).

`UploadTask`

Member	Type	Description
`state`	`UploadTaskState`	Current synchronous snapshot of status + progress.
`stateStream`	`Stream<UploadTaskState>`	Broadcast stream of state changes.
`whenDone`	`Future<FileSnapshot?>`	Completes with the confirmed `FileSnapshot`, or `null` if cancelled.
`pause()`	—	Cancels the in-flight request; preserves uploaded parts.
`resume()`	—	Restarts from the last completed part.
`cancel()`	`Future<void>`	Cancels the upload and deletes the remote file record.

UploadTaskStatus: queued, running, paused, complete, failed, cancelled. A durable (enqueue: true) task starts queued; its whenDone resolves only on the terminal outcome (success or permanent failure), surviving offline retries.

`DownloadTask`

Member	Type	Description
`state`	`DownloadTaskState`	Current synchronous snapshot of status + progress.
`stateStream`	`Stream<DownloadTaskState>`	Broadcast stream of state changes.
`whenDone`	`Future<void>`	Completes when the download finishes, or throws on failure.
`saveTo`	`String`	The absolute destination path the file is written to.
`pause()`	—	Cancels the in-flight request; the partial file is kept for resume.
`resume()`	—	Resumes from the byte offset already written (HTTP `Range` request).
`cancel()`	—	Cancels and deletes any partial local file.

DownloadTaskStatus: queued, running, paused, complete, failed, cancelled (same semantics as UploadTaskStatus).

`FileSnapshot`

An immutable snapshot of a file's metadata at a point in time.

Member	Type	Description
`exists`	`bool`	Whether the file is present.
`data`	`FileData?`	The file record, or `null` when `exists` is false.
`fromCache`	`bool`	True when the snapshot came from a cache-only read (`offlineSnapshot()`); always false for the server-only `getSnapshot()`.
`reference`	`ChildReference`	The reference this snapshot belongs to (use `reference.path` for the full path).
`name`	`String`	The last path segment.
`timestamp`	`DateTime`	When the snapshot was taken.

FileData fields: id, directory, path, mimeType, sizeBytes, uploadStatus, metadata, version, createdAt, updatedAt, contentHash, plus two client-side offline fields:

contentHash — the server's content fingerprint (object ETag), used by offlineCopyStatus(); null when the backend hasn't recorded one.

Field	Type	Description
`localPath`	`String?`	Absolute path to the local copy, when pinned/registered.
`isCached`	`bool`	True when the content is fully downloaded locally and ready for offline use.

`DirectorySnapshot`

An immutable snapshot of a directory listing, returned by listChildren() (server) or offlineChildren() (cache).

Member	Type	Description
`files`	`List<FileSnapshot>`	One snapshot per child file (unmodifiable).
`fromCache`	`bool`	True when the listing came from `offlineChildren()` (a cache-only, partial, pinned-only view); false for the server-only `listChildren()`.
`reference`	`ChildReference`	The directory this snapshot lists.
`name`	`String`	The directory's last path segment.
`length` / `isEmpty` / `isNotEmpty`	—	Convenience over `files`.
`timestamp`	`DateTime`	When the snapshot was taken.

Offline / auto-resume types

Type	Description
`TransferEvent`	`{type, kind, path, error, record}` emitted on `transferEvents`. `record` is the `TransferRecord` on a `failed` event, so dropped work can be re-enqueued.
`TransferEventType`	`started`, `completed`, `failed`, `retrying`, `paused`.
`TransferKind`	`upload`, `download`.
`TransferRecord` / `TransferStatus`	A persisted queue entry returned by `pendingTransfers` — `{seq, kind, path, status, attempt, lastError, …}`; status is `pending`, `running`, `paused`, or `failed`. A `paused` transfer is waiting on a token or the network and has spent no attempts.
`CatalogEntry` / `CatalogStatus`	A pinned file record (`downloading`, `ready`, `stale`).
`OfflineCopyStatus`	`notPinned`, `upToDate`, `contentChanged`, `remoteDeleted`, `unknown` — result of `offlineCopyStatus()`.
`StorageLocalStore`	Persistence interface; `MemoryStorageLocalStore` and `SembastStorageLocalStore` ship by default.

`WincheStorageException`

A sealed exception hierarchy thrown on API errors. Each carries a semantic status (StorageErrorStatus), a message, optional details, and the originating statusCode.

try {
  await photoRef.updateMetadata({'label': 'hero'});
} on StorageNotFoundException catch (e) {
  print('not found: ${e.message}');
} on WincheStorageException catch (e) {
  print('${e.statusCode}: ${e.message}');
}

Subclasses: StorageNotFoundException, StoragePermissionDeniedException, StorageUnauthenticatedException, StorageInvalidArgumentException, StorageFailedPreconditionException, StorageDeadlineExceededException, StorageUnavailableException, StorageCancelledException, StorageInternalException, StorageUnknownException.

Dependencies

dio — HTTP client used by WincheStorageHttpApi, UploadTask, and DownloadTask
mime — MIME type inference from file extension in ChildReference.uploadPath
path — platform-correct path joining for the offline cache
sembast / sembast_web — pure-Dart durable store for the offline catalog and transfer queue (native file / web IndexedDB)

License

MIT

winche_storage

Features

Installation

Setup

Multi-user

How a transfer flows

Usage

References

Upload

Per-call flags: `enqueue` and `cache`

Download

Pause / resume / cancel

Offline cache

Auto-resume

How a failed attempt is handled

List a directory

Get file metadata

Update metadata

Delete

API reference

`WincheStorageConfig`

`WincheStorage`

`ChildReference`

`UploadTask`

`DownloadTask`

`FileSnapshot`

`DirectorySnapshot`

Offline / auto-resume types

`WincheStorageException`

Dependencies

License

Libraries

winche_storage package

winche_storage

Features

Installation

Setup

Multi-user

How a transfer flows

Usage

References

Upload

Per-call flags: enqueue and cache

Download

Pause / resume / cancel

Offline cache

Auto-resume

How a failed attempt is handled

List a directory

Get file metadata

Update metadata

Delete

API reference

WincheStorageConfig

WincheStorage

ChildReference

UploadTask

DownloadTask

FileSnapshot

DirectorySnapshot

Offline / auto-resume types

WincheStorageException

Dependencies

License

Libraries

winche_storage package

Per-call flags: `enqueue` and `cache`

`WincheStorageConfig`

`WincheStorage`

`ChildReference`

`UploadTask`

`DownloadTask`

`FileSnapshot`

`DirectorySnapshot`

`WincheStorageException`