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

    Class ZipDirectoryEntry

    Represents a directory entry in the zip (Filesystem API).

    The name passed to an {@link ZipDirectoryEntry}#add*() method is split into path components, exactly like the filename of an imported entry, so addText("a/b.txt", text) adds "b.txt" to the "a" directory and creates that directory when it does not exist. Empty components and "." components are ignored. The directories created that way are navigable like any other entry but are not written when the tree is exported, so the zip file holds the same entries whichever way the path was built.

    Hierarchy (View Summary)

    Index
    constructor
    children data? directory id name options? parent? uncompressedSize
    addBlob addData64URI addDirectory addFile addFileSystemEntry addFileSystemHandle addHttpContent addReadable addText addUint8Array checkPassword clone exportBlob exportData64URI exportFileSystemHandle exportUint8Array exportWritable exportZip getChildByName getChildren getExportedSize getFullname getRelativeName importBlob importData64URI importHttpContent importReadable importUint8Array importZip isDescendantOf isPasswordProtected rename setOptions
    children: ZipEntry[]

    The children of the entry.

    data?: EntryMetaData

    The underlying EntryMetaData instance.

    directory: true

    true for ZipDirectoryEntry instances.

    id: number

    The ID of the instance.

    name: string

    The relative filename of the entry.

    options?: ZipWriterAddDataOptions

    The options applied to the entry when the zip file is exported.

    These are the options passed when the entry was added to the filesystem, updated by ZipEntry#setOptions. An entry imported from a zip file has none until ZipEntry#setOptions is called.

    parent?: ZipEntry

    The parent directory of the entry.

    uncompressedSize: number

    The uncompressed size of the content.

    It is the size of the raw compressed content when the entry has been imported with the passThrough option set to true, since the entry holds the compressed data in that case. The uncompressed size of the original entry remains available in ZipEntry#data.

    It is updated by the {@link ZipFileEntry}#replace*() methods, and it is 0 for an entry holding a ReadableStream instance, whose size is only known once the entry has been read.

    • Adds a entry entry with content provided via a ReadableStream instance

      Parameters

      • name: string

        The relative filename of the entry.

      • readable: ReadableStream

        The ReadableStream instance.

      • Optionaloptions: ZipWriterAddDataOptions

        The options.

      Returns ZipFileEntry<ReadableStream<any>, void>

      A ZipFileEntry instance.

    • Adds an entry with content provided as a Uint8Array instance

      Parameters

      • name: string

        The relative filename of the entry.

      • array: Uint8Array

        The Uint8Array instance.

      • Optionaloptions: ZipWriterAddDataOptions

        The options.

      Returns ZipFileEntry<Uint8Array<ArrayBufferLike>, Uint8Array<ArrayBufferLike>>

      A ZipFileEntry instance.

    • 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.

    • Returns a Uint8Array instance containing a zip file of the entry and its descendants

      Parameters

      Returns Promise<Uint8Array<ArrayBufferLike>>

      A promise resolving to the Uint8Array instance.

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

      Parameters

      Returns Promise<WritableStream<any>>

      A promise resolving to the Uint8Array instance.

    • 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.

    • Set the name of the entry

      Parameters

      • name: string

        The new name of the entry.

      Returns void

      A name holding "/" is split into path components, like the name passed to a {@link ZipDirectoryEntry}#add*() method, so it moves the entry into the directories it names, creating them when they do not exist. Renaming an entry to the name it already has does nothing. Renaming it onto an existing sibling throws an ERR_ENTRY_EXISTS error, and renaming it into itself or into one of its descendants throws.

    Settings
    Member Visibility

    On This Page
    Constructors
    Properties
    Methods