@zip.js/zip.js
    Preparing search index...

    Class ZipFS

    Hierarchy

    • Pick<
          ZipDirectoryEntry,
          | "getChildByName"
          | "getChildren"
          | "addDirectory"
          | "addText"
          | "addBlob"
          | "addData64URI"
          | "addUint8Array"
          | "addHttpContent"
          | "addReadable"
          | "addFile"
          | "addFileSystemEntry"
          | "addFileSystemHandle"
          | "importBlob"
          | "importData64URI"
          | "importUint8Array"
          | "importHttpContent"
          | "importReadable"
          | "importZip"
          | "exportBlob"
          | "exportData64URI"
          | "exportUint8Array"
          | "exportWritable"
          | "exportFileSystemHandle"
          | "exportZip"
          | "getExportedSize"
          | "isPasswordProtected"
          | "checkPassword",
      >
      • ZipFS
    Index
    constructor
    children entries root
    addBlob addData64URI addDirectory addFile addFileSystemEntry addFileSystemHandle addHttpContent addReadable addText addUint8Array checkPassword exportBlob exportData64URI exportFileSystemHandle exportUint8Array exportWritable exportZip find getById getChildByName getChildren getExportedSize importBlob importData64URI importHttpContent importReadable importUint8Array importZip isPasswordProtected move remove

    • Returns ZipFS

    children: ZipEntry[]

    The children of the root directory.

    entries: (ZipEntry | null)[]

    The array of all the ZipEntry instances indexed by ZipEntry#id.

    root: ZipDirectoryEntry

    The root directory.

    • Writes the entry and its descendants into a directory as files and sub-directories via the File System Access API (e.g. the Origin Private File System). Files are streamed and directories are merged into the target; colliding files are overwritten. This is the inverse of ZipDirectoryEntry#addFileSystemHandle.

      If an entry cannot be written, the original error is rethrown unmodified as an EntryError, whose EntryError#entryName is the name of the entry that failed, relative to this entry.

      The export is not atomic and nothing is rolled back, because the target is merged into rather than replaced: a file that already existed cannot be restored once overwritten. On failure the target is left as follows, and EntryError#exportedEntryNames lists the files that completed:

      • files written before the failure are left in place, complete and valid;
      • a file whose write started but did not finish is left empty, because it is created before its content is streamed; this includes the entry that failed and, with concurrent, every entry cancelled alongside it;
      • files that already existed in the target keep their previous content unless they were overwritten in full;
      • entries not started yet are missing, as are the directories that would have held them.

      Running the same export again is the supported way to recover, since directories are merged and files are overwritten.

      Parameters

      Returns Promise<FileSystemDirectoryHandle>

      A promise resolving to the target FileSystemDirectoryHandle instance.

      An entry flagged as a symbolic link by EntryMetaData#symlink is written as a regular file whose content is the path of the link target, because the File System Access API cannot create symbolic links.

    • Creates a zip file via a custom Writer instance containing the entry and its descendants

      Parameters

      Returns Promise<unknown>

      A promise resolving to the data, or to the ZipWriter instance it was passed.

      A ZipWriter instance can be passed instead of a Writer, the symmetric counterpart of passing a ZipReader to ZipDirectoryEntry#importZip. The entries are added to that writer and the archive is left open, so the caller closes it with ZipWriter#close and can add entries of its own before or after, export several trees into one archive, and read ZipWriter#warnings, which is otherwise unreachable through the filesystem API. The options of that writer keep governing the entries, exactly as they do for a direct call to ZipWriter#add, and the options passed here take precedence over them. The options that only apply when the writer is created are ignored. bufferedWrite is not one of them, it is honored here as it is on ZipWriter#add; what differs is its default, which the export sets to true only for a writer it creates itself. A supplied writer therefore buffers only when the option is passed here or to its own constructor.

      The archive is closed by the caller, so everything that happens at close time is the caller's to pass to ZipWriter#close, and passing it here instead does nothing. That covers ZipDirectoryEntryExportOptions#globalComment, which is the first argument of that method, and ZipWriterCloseOptions#signCentralDirectory, which is one of its options. Both describe the whole archive rather than the exported tree, so an archive composed of several trees carries one of each, written by the single ZipWriter#close call that finalizes it.

    • Gets the children of the directory

      Parameters

      Returns ZipEntry[]

      The array of ZipEntry instances.

      The returned array is a snapshot taken when the method is called: entries added or removed afterwards are not reflected, and an entry removed while the array is being iterated is still present but detached from the filesystem.

      With recursive, the descendants are ordered level by level, i.e. the children of a directory come before the children of its subdirectories, like the result of readdir(path, { recursive: true }) in Node.js. This is also the order in which {@link ZipDirectoryEntry}#export*() writes them.

      Unlike ZipFS#entries, the directory itself is not included and removed entries leave no empty slot.

    • Computes the exact size in bytes of the zip file that export*() would produce for the entry and its descendants, without reading or compressing any data.

      Pass the same options object that will be passed to the export method, otherwise the result will not match. The computation assumes the export creates the writer, where bufferedWrite defaults to true; a ZipWriter passed to ZipDirectoryEntry#exportZip defaults it to false instead, which adds a data descriptor to every entry, so pass the value that writer uses here too. The size is only determinable when every descendant is stored (i.e. level is set to 0) or passed through, and has a known size; ERR_UNDETERMINED_SIZE is thrown otherwise. Encryption does not prevent it, the overhead of ZipCrypto and AES being fixed.

      The intended use is setting the Content-Length header of a zip file streamed over HTTP.

      Parameters

      Returns Promise<number>

      A promise resolving to the size in bytes.

      Entries added with ZipDirectoryEntry#addReadable never have a known size, and entries added with ZipDirectoryEntry#addHttpContent only get one once their content has been read. The returned size assumes a single output file, it does not apply to split zip files.

      ERR_UNDETERMINED_SIZE is also thrown when the size depends on the order in which the entries are physically written, which the buffered write path only determines at write time. This happens when usdz is set, since the alignment padding depends on the offset of each entry, and when the archive exceeds 4GB and the order could change the result, since the offsets recorded in the central directory are then extended to 64 bits. Entries of equal size put the same entries past 4GB whatever the order, so they stay determinable unless they differ in whether they already carry a zip64 field, which changes the cost of crossing that boundary. Passing bufferedWrite: false makes both determinable again, as does exporting a tree holding no directory that was added explicitly and has children: the directories a name holding "/" creates are exempt, so addText("a/b.txt", text) stays determinable, while addDirectory("a") followed by two addText calls on it does not. It is thrown as well when signCentralDirectory is set, the length of the signature being unknown until it is computed.

      An entry asking for compression is stored instead when no deflate implementation is reachable, which is what the export writes as well. Its size is determinable then, so the same call throws on a platform carrying deflate and returns a size on one that does not.

      ERR_UNDETERMINED_SIZE if the size cannot be determined.

    • Extracts a zip file provided via a custom Reader instance or a ZipReader instance into the entry

      Parameters

      Returns Promise<ZipEntry[]>

      A promise resolving to an array of the ZipFileEntry and ZipDirectoryEntry instances created by the import, which includes the directories created for the path components of the filenames.

      The filename of each entry is split into path components to build the tree of entries. Empty components and "." components are ignored, so "a//b.txt", "./a/b.txt" and "a/./b.txt" all produce the same "a/b.txt" entry. Filenames are normalized and validated beforehand, see GetEntriesOptions#normalizeFilename and GetEntriesOptions#filenameValidation.

      The directories created that way are navigable like any other entry but are not written back when the tree is exported: only the directories carried by the source zip file and the ones created with ZipDirectoryEntry#addDirectory are written. A zip file storing no directory entry therefore round-trips to a zip file storing no directory entry, instead of gaining one entry per path component.

      Passing a ZipReader instance is the way to read the data of the zip file itself, e.g. its ZipReader#prependedData or its ZipReader#comment property, since the instance created otherwise is not exposed. Its options are used as defaults for the options passed here, and it must not have read its entries yet when it is created over a ReadableStream instance, which can only be read once.

      Like the ZipReader constructor, a ReadableStream input is buffered entirely in memory, see its remarks and the Reader examples for reading large seekable resources with random access.

    Settings
    Member Visibility

    On This Page
    Constructors
    Properties
    Methods