blit_web library

Web-specific entry point: OPFS, IndexedDB, and Blob.

Classes

Blit
Simple top-level API.
BlitFile
Simple random-access file facade.
Bytes
Immutable view over [offset, offset + length) of a Uint8List.
BytesLike
BytesMut
BytesReader
BytesWriter
FileOptions
OpfsWorkerPool
Page-wide pool: one manifest writer worker plus N chunk workers.
Uint64
Exact unsigned 64-bit value.
WebBlobBytesFile
A read-only BytesFile over an immutable Web Blob.
WebFileManifest
Immutable, read-only view of a web file's manifest.
WebIndexedDbBytesFile
A BytesFile backed by records in one shared IndexedDB object store.
WebOpfsBytesFile
A BytesFile backed by Origin Private File System chunks.
WebStorageCapabilities
Snapshot of the Web storage capabilities of the current page.

Extensions

BytesLikeBytes on BytesLike
Converts a BytesLike implementation to a zero-copy Bytes view.
TypedDataBytes on TypedData
Converts any TypedData to a zero-copy Bytes view.

Constants

blit → const Blit
The default "just works" API.
kDefaultChunkSize → const int
Default chunk size: 16 MiB.
kIdbDatabaseName → const String
Default database name; shared by all logical files.
kIdbDefaultChunkSize → const int
Default IndexedDB chunk size (64 KiB).
kIdbMaxChunkSize → const int
Largest accepted chunk size.
kIdbMinChunkSize → const int
Smallest accepted chunk size (tiny values are useful in tests).
kIdbStoreName → const String
Default object store; shared by all logical files.
kMaxLogicalLength → const int
Largest exact integer web offset: 2^53-1 bytes (8 PiB).
kMobileChunkSize → const int
Conservative default chunk size for mobile (iOS memory pressure).

Functions

chunkCountFor(int logicalLength, int chunkSize) → int
Number of chunks needed to hold logicalLength bytes.
chunkDirPathFor(String path) → String
OPFS path of the chunk directory for path.
chunkFilesFor(int logicalLength, {int chunkSize = kDefaultChunkSize}) → int
Number of chunk files for a logical length, for planning/UI estimates.
chunkLogicalLength(int index, int chunkSize, int logicalLength) → int
Logical length of chunk index for a file of logicalLength bytes.
chunkPathFor(String path, int index) → String
OPFS path of chunk index for path.
decodeIdbMeta(Uint8List bytes) → IdbMeta?
Decodes a metadata record, returning null on bad magic/version/size.
deleteIdbFile(String path, {String databaseName = kIdbDatabaseName, String storeName = kIdbStoreName}) → Future<void>
Deletes every record belonging to path from the shared store.
deleteOpfsFile(String path) → Future<void>
Deletes the logical file at path and every OPFS entry it owns.
encodeIdbMeta(int logicalLength, int chunkSize) → Uint8List
Encodes logical length and chunk size into a 20-byte metadata record.
idbChunkKey(String path, int index) → String
Chunk record key for path, index.
idbFileKey(String path) → String
Stable key prefix for path.
idbMetaKey(String path) → String
Metadata record key for path.
listOpfsDirectory(String path) → Future<List<String>>
Lists entry names of an OPFS directory (diagnostics/tests).
normalizeLogicalPath(String path) → String
Validates and normalizes a logical path.
openBlob(JSObject blob, {int cacheLimit = 8 << 20}) → Future<BlitFile>
Opens an immutable Web Blob/File through the simple facade.
openBlobBytesFile(JSObject blob, {int cacheLimit = 8 << 20}) → Future<BytesFile>
Opens a read-only BytesFile over a Web Blob/File.
openBlobBytesFileTyped(JSObject blob, {int cacheLimit = 8 << 20}) → Future<WebBlobBytesFile>
Opens a read-only BytesFile over a Web Blob/File.
openIdbBytesFile(String path, {bool create = true, bool readOnly = false, int chunkSize = kIdbDefaultChunkSize, String databaseName = kIdbDatabaseName, String storeName = kIdbStoreName}) → Future<BytesFile>
Opens an IndexedDB-backed file as a BytesFile.
openIdbBytesFileTyped(String path, {bool create = true, bool readOnly = false, int chunkSize = kIdbDefaultChunkSize, String databaseName = kIdbDatabaseName, String storeName = kIdbStoreName}) → Future<WebIndexedDbBytesFile>
Opens an IndexedDB-backed file in the shared blit-bytes store.
openIndexedDb(String path, {bool create = true, bool readOnly = false, int chunkSize = web.kIdbDefaultChunkSize, String databaseName = web.kIdbDatabaseName, String storeName = web.kIdbStoreName}) → Future<BlitFile>
Opens an IndexedDB-backed file through the simple facade.
openOpfsBytesFile(String path, {bool create = true, bool readOnly = false, int chunkSize = kDefaultChunkSize, int? workers}) → Future<BytesFile>
Opens (or creates) a logical file backed by OPFS chunks.
openOpfsBytesFileTyped(String path, {bool create = true, bool readOnly = false, int chunkSize = kDefaultChunkSize, int? workers}) → Future<WebOpfsBytesFile>
Opener with the concrete WebOpfsBytesFile type (for diagnostics such as WebOpfsBytesFile.debugPhysicalChunkSize).
probeWebStorageCapabilities({bool requestPersist = false}) → Future<WebStorageCapabilities>
Probes OPFS, worker sync handles, quota and optional Chromium-only APIs.
readWebFileManifest(String path) → Future<WebFileManifest?>
Reads and decodes the newest valid manifest for path (null if none).
requestPersistentStorage() → Future<bool>
Requests persistent storage (navigator.storage.persist()).
shutdownIdbBackend() → Future<void>
Closes cached IndexedDB connections (tests/hot restart).
shutdownWebBackend() → void
Shuts the page-wide OPFS worker down and releases every handle.
storePathFor(String path) → String
OPFS path of the directory that stores path's manifest and chunks.

Typedefs

IdbMeta = ({int chunkSize, int logicalLength})
Decoded metadata.

Exceptions / Errors

BlitException
BlitIOException
CancelledException
ClosedException
EndOfFileException
PermissionException
QuotaExceededException
UnsupportedException
WebFileSystemException
A failure reported by the browser File System API / OPFS layer.
WebIndexedDbException
IndexedDB failure.
WebQuotaExceededException
Thrown when OPFS reports QuotaExceededError.