web library
Browser sugar for the koni_archive facade: explicit opt-in import for the web, compiling under both dart2js and dart2wasm. Re-exports the platform-neutral facade, so a web program needs only this one import.
Classes
- Archive
- An opened archive, presented as a read-only virtual filesystem: callers stream files out of it and never need to know which format is underneath.
- ArchiveCompression
- The compression method an entry's content is stored with.
- ArchiveEntry
- One entry of an archive, deeply immutable and isolate-transferable.
- ArchiveEntrySpec
- Immutable description of an entry to write (Phase 2), the input mirror of ArchiveEntry.
- ArchiveFormat
- Descriptor for one archive format: how to detect it and how to open it. Format packages implement one of these; third parties can implement their own and register it: the format set is open, never a closed enum.
- ArchiveFormatRegistry
- Ordered, mutable registry of ArchiveFormats, what makes koni_archive an ecosystem: new formats plug in without touching core.
- ArchiveReader
-
Format-reader SPI: what a format package implements to expose one opened
archive. Application code uses the
Archivefacade inpackage:koni_archiveinstead; this interface is for format implementers. - ArchiveReadOptions
-
Options honored by format readers, passed through
Archive.open/ArchiveFormatRegistry.openReader. - ArchiveWriteFormat
- Descriptor for one writable archive format (Phase 2): its name and how to open a writer over a sink. Unlike reading there is no detection; writing always names the format explicitly.
- ArchiveWriteOptions
-
Options honored by archive writers, passed through
Archive.create/ArchiveWriteFormat.openWriter. - ArchiveWriter
-
Writes entries to a ByteSink in one archive format, the SPI a format
package implements for writing, and what application code drives via the
Archive.createfacade. The write mirror ofArchiveReader. - BlobByteSource
-
A ByteSource over a browser
web.Blob(orFile, which extends Blob). - BytesBuilderSink
- A ByteSink that accumulates output in memory.
- ByteSink
- Sequential, append-only byte sink, the output abstraction every archive writer targets (Phase 2). The write mirror of ByteSource, but there is no seeking: archive writing is inherently sequential (TAR is pure append; ZIP streams its data and appends the central directory at the end, tracking offsets via length).
- ByteSource
- Random-access byte source, the input abstraction every archive reader consumes. Never a file path, never a raw stream.
- MemoryByteSource
- A ByteSource over an in-memory byte buffer.
- SevenZWriteFormat
-
The 7z write format. Pass to
Archive.create: - TarWriteFormat
-
The TAR write format (POSIX ustar + PAX). Pass to
Archive.create: - ZipWriteFormat
-
The ZIP write format (including CBZ comic archives). Pass to
Archive.create:
Enums
- ArchiveEntryType
- What kind of filesystem object an archive entry represents.
Properties
- builtInFormats → ArchiveFormatRegistry
-
Registry pre-populated with every built-in format, in detection order.
final
Functions
-
normalizeEntryPath(
String rawPath) → NormalizedEntryPath - Normalizes a path as stored in an archive:
-
openArchiveBlob(
Blob blob, {ArchiveFormatRegistry? registry, ArchiveFormat? format, ArchiveReadOptions options = const ArchiveReadOptions()}) → Future< Archive> -
Opens
blob(a browserBlob, includingFilefrom an<input type=file>or drag-and-drop) as an archive, auto-detecting its format. -
validateWritePath(
String rawPath) → String - Validates and normalizes a caller-supplied path for writing (Phase 2). Unlike normalizeEntryPath, which silently sanitizes hostile input on read, this rejects a bad path with an ArgumentError: the writer's caller is a programmer, and silently rewriting their requested path would be surprising.
Typedefs
- NormalizedEntryPath = ({bool escapedRoot, String path})
-
Result of normalizeEntryPath: the sanitized
pathplus whether the original attempted to escape the archive root.
Exceptions / Errors
- ArchiveClosedException
-
An operation was attempted on an archive or byte source that has been
closed, or
close()cancelled an in-flight read. - ArchiveException
- Root of the typed exception hierarchy for archive-content problems.
- ChecksumMismatchException
- Decoded data does not match the checksum recorded in the archive.
- CorruptArchiveException
- The input matched a format but its structure is invalid.
- EncryptedArchiveException
-
The archive (or the requested entry) is encrypted and no password was
supplied, or it uses an encryption scheme this implementation does not
support (
doc/encryption-scope.md, e.g. ZIP strong encryption, RAR4 encrypted headers). - EntryNotFoundException
-
A path-based lookup did not match any entry (e.g.
openReadPathon an absent path). - InvalidHeaderException
- A header record is structurally invalid (bad magic, checksum, or field).
- InvalidPasswordException
- The supplied password failed the format's password check.
- SizeLimitExceededException
-
A caller-supplied or format-derived size or count limit was exceeded
(decompression-bomb / directory-bomb protection): a decoded entry grew
past ArchiveReadOptions.maxEntrySize (or
Archive.readBytes'smaxSize), or an archive declared more entries than ArchiveReadOptions.maxEntryCount. - UnexpectedEofException
- The input ended before a structure that should be present was complete.
- UnsupportedCompressionException
- An entry is compressed with a method this implementation does not support. Always names the method (and raw id where the format records one) so diagnostics can identify it.
- UnsupportedFeatureException
- The archive uses a feature this implementation does not (yet) support (e.g. ZIP64 before M7, GNU sparse tars, multi-volume archives).
- UnsupportedFormatException
- No registered format matches the input, or the input is not an archive.