method

zlib.ZipFile.open

static open(
filename: string,
options?: ZipFileOpenOptions
): Promise<ZipFile>;

Throws an ERR_ZIP_ARCHIVE_TOO_LARGE error if the archive's central directory is too large to buffer in memory.

Referenced types

interface ZipFileOpenOptions

  • writable?: boolean

    Open the underlying file for both reading and writing ('r+'), enabling zipFile.addEntry(), zipFile.add(), and zipFile.delete().

class ZipFile

A random-access view over the entries of a ZIP archive on disk. Only the archive's tail and central directory are read up front; member content is read from disk lazily, on demand. Writable when opened with { writable: true }: zipFile.addEntry()/zipFile.add() append the new member's data where the central directory used to be, then rewrite the central directory immediately after it; zipFile.delete() just rewrites the central directory. Both mean the file is altered as soon as the method's returned Promise fulfills. Deleted or replaced members are left behind as dead space; zipFile.compact() produces a stream with none.

These in-place edits are not crash-atomic. Rewriting the central directory happens in place, so a write that fails partway - the disk fills, the device disconnects, the process is killed - can leave the archive on disk with a partial or missing central directory, i.e. unreadable, even though the member data before it is intact. The rejected call surfaces the underlying error and the ZipFile object is left usable (its in-memory view is not discarded, so a caller can attempt recovery - for example re-writing the entries elsewhere with zipFile.compact()), but that in-memory view may no longer match the bytes on disk. Write to a copy, or compact() into a fresh file, when durability across a failure matters.

As with the synchronous node:fs APIs, every *Sync method blocks the Node.js event loop and further JavaScript execution until the operation completes; use them only where synchronous execution is appropriate (for example, short-lived scripts or startup code), not in code that must stay responsive. A synchronous method throws ERR_INVALID_STATE if called while an asynchronous add(), addEntry(), delete(), or close() on the same ZipFile has not settled yet, since letting the two interleave could corrupt the archive.

  • readonly comment: string

    The archive-level comment, preserved byte-for-byte across zipFile.addEntry()/zipFile.delete() calls. The bytes are decoded as UTF-8 when they are valid UTF-8 and as CP437 otherwise (the field carries no encoding flag of its own).

  • readonly size: number

    The number of entries in the archive.

  • readonly writable: boolean

    Whether this ZipFile was opened with { writable: true }.

  • filename: string,
    data: ZipInputType,
    options?: ZipEntryCreateOptions
    ): Promise<ZipEntry>;

    Equivalent to zipFile.addEntry(await zlib.ZipEntry.create(filename, data, options)).

    @param filename

    The entry's name within the archive. A trailing / marks a directory entry.

    @param data

    The entry's complete, uncompressed content.

    @param options

    See zlib.ZipEntry.create().

    @returns

    Promise fulfilled with the created ZipEntry.

  • entry: ZipEntry
    ): Promise<ZipEntry>;

    Writes entry where the central directory currently starts, then rewrites the central directory to include it, replacing any existing entry of the same name. Throws ERR_ZIP_NOT_WRITABLE if the ZipFile was not opened with { writable: true }.

    The returned (same) entry is left readable: a streaming entry created with zlib.ZipEntry.createStream(), which would otherwise be spent once serialized, is promoted in place to a file-backed entry pointing at the copy just written (valid while this ZipFile is open). In-memory entries keep their own buffer unchanged.

    @returns

    Promise fulfilled with entry.

  • entry: ZipEntry

    The synchronous version of zipFile.addEntry(). entry must not be a pending streaming entry (one created with zlib.ZipEntry.createStream()) - there is no synchronous way to drain its asynchronous source.

    @returns

    entry

  • filename: string,
    data: ZipInputType,
    options?: ZipEntryCreateOptions

    The synchronous version of zipFile.add(). Equivalent to zipFile.addEntrySync(zlib.ZipEntry.createSync(filename, data, options)).

    @param filename

    The entry's name within the archive. A trailing / marks a directory entry.

    @param data

    The entry's complete, uncompressed content.

    @param options

    See zlib.ZipEntry.createSync().

    @returns

    The created entry.

  • close(): Promise<void>;

    Closes the underlying file handle.

  • closeSync(): void;

    The synchronous version of zipFile.close().

  • comment?: string

    Does not modify the open file; pipe the result into a new one.

    @param comment

    An archive comment.

    @returns

    A stream of the currently live entries, serialized as a fresh archive with no dead space left by prior zipFile.addEntry()/zipFile.delete() calls.

  • comment?: string
    ): NonSharedBuffer;

    The synchronous version of zipFile.compact(). Does not modify the open file.

    @param comment

    An archive comment.

    @returns

    The currently live entries, serialized as a fresh archive with no dead space left by prior zipFile.addEntry()/zipFile.delete() calls.

  • name: string
    ): Promise<boolean>;

    Rewrites the central directory without writing any new content - the archive does not grow. Throws ERR_ZIP_NOT_WRITABLE if the ZipFile was not opened with { writable: true }.

    @returns

    Promise fulfilled with true if an entry named name existed and was removed, false otherwise.

  • name: string
    ): boolean;

    The synchronous version of zipFile.delete().

    @returns

    true if an entry named name existed and was removed, false otherwise.

  • entries(): Iterator<[name: string, entry: Promise<ZipEntry>]>;
    @returns

    Iterator of [name, entry] pairs, where entry is a Promise fulfilled with a ZipEntry.

  • entriesSync(): Iterator<[name: string, entry: ZipEntry]>;

    The synchronous version of zipFile.entries().

    @returns

    Iterator of [name, entry] pairs, where entry is a resolved ZipEntry (not a Promise).

  • callback: (entry: Promise<ZipEntry>, name: string, zipFile: this) => void,
    thisArg?: any
    ): void;
  • callback: (entry: ZipEntry, name: string, zipFile: this) => void,
    thisArg?: any
    ): void;

    The synchronous version of zipFile.forEach(): callback is invoked with a resolved ZipEntry instead of a Promise.

  • name: string
    ): Promise<ZipEntry>;

    Returns a lazy, file-backed ZipEntry for name. Nothing is read from disk here and no content is buffered: the returned entry reads (and, for zipEntry.content(), decompresses) its member straight from the file on each access, and the ZipFile retains no member content. The entry is valid only while this ZipFile is open. Reading its content later may throw ERR_ZIP_ENTRY_TOO_LARGE if the member is too large to hold in a single buffer; use zipEntry.contentIterator() (or zipFile.stream()) instead. Throws ERR_ZIP_ENTRY_NOT_FOUND if the archive has no entry named name.

  • name: string

    The synchronous version of zipFile.get(). Like get(), it reads nothing up front and only builds the lazy handle, so it does not itself block on I/O - but reads performed later through the returned entry (such as zipEntry.contentSync()) do; see the ZipFile class documentation note on synchronous methods.

  • name: string
    ): boolean;
  • keys(): Iterator<string>;
    @returns

    Iterator of entry names.

  • name: string,
    options?: ZipEntryContentIterOptions
    ): Promise<Readable>;

    Convenience wrapper that resolves to a Readable over zipEntry.contentIterator() of zipFile.get(name); the compressed bytes are read from disk as the stream is consumed. The returned promise rejects with ERR_ZIP_ENTRY_NOT_FOUND if the archive has no entry named name.

    @returns

    Promise fulfilled with a stream.Readable of the member's decompressed content, without buffering the whole member in memory.

  • values(): Iterator<Promise<ZipEntry>>;
    @returns

    Iterator of Promise objects, each fulfilled with a ZipEntry.

  • valuesSync(): Iterator<ZipEntry>;

    The synchronous version of zipFile.values().

    @returns

    Iterator of resolved ZipEntry values (not Promises).

  • static open(
    filename: string,
    options?: ZipFileOpenOptions
    ): Promise<ZipFile>;

    Throws an ERR_ZIP_ARCHIVE_TOO_LARGE error if the archive's central directory is too large to buffer in memory.

  • static openSync(
    filename: string,
    options?: ZipFileOpenOptions

    The synchronous version of zlib.ZipFile.open().