Read TAR archives from streams or filesystem paths, with support for sequential iteration, seekable indexing, PAX metadata, GNU long-name records, ACL sideband entries, and GNU sparse-file reconstruction.

This module is designed for archive inspection and extraction workflows rather than archive creation. Use tar.open for one-pass reading from any readable stream, tar.openSeekable when the stream also supports seeking, or tar.openPath to open a TAR file directly from disk. Sequential readers expose raw parser entries through TarReader:nextEntry and higher-level normalized members through TarReader:nextMember. Seekable readers can additionally build a TarIndex for path-based lookups and lazy content reads. Readers that wrap open handles should be closed explicitly with reader:close() when you are finished with them, especially those created through tar.openPath.

Returned members preserve both normalized fields such as kind, path, and linkPath, and lower-level format details such as the original header, merged PAX attributes, stored payload size, and sparse-file metadata. This makes the module suitable both for straightforward unpacking and for tooling that needs to inspect TAR format behavior more closely.

Summary

Classes

Functions

API Reference

Classes

TarReader

Sequential TAR reader returned by tar.open. It walks the archive in stream order and exposes raw entries or normalized members one at a time.

Implements: TarReaderState

Properties

stream: stream.StreamThatCanRead

Byte-oriented source being decoded.

closed: boolean

true once the reader has been closed and can no longer read from the archive.

globalPax: { [string]: string }

PAX attributes inherited by subsequent entries until replaced.

nextPax: { [string]: string }?

PAX attributes queued for only the next entry.

longPath: string?

GNU long path captured from a preceding L record.

longLinkPath: string?

GNU long link path captured from a preceding K record.

pendingAcl: string?

ACL text captured from a preceding A record.

TarReader.new

Create a sequential TAR reader over an already-open readable stream. The reader consumes the stream progressively and cannot seek backwards unless the supplied stream object also supports that capability separately.

TarReader.new(stream_: stream.StreamThatCanRead) → ()

Parameters

stream_: stream.StreamThatCanRead

Readable stream positioned at the start of a TAR archive.

TarReader:close

Close the reader and, when supported, close the wrapped stream. This is especially important for readers opened from tar.openPath, because the underlying file handle otherwise remains open until garbage collection. Calling close more than once is safe. @param self Reader instance.

TarReader:close() → ()

TarReader:closeSync

Non-yielding variant of close when the wrapped stream supports closeSync. If only close exists, this falls back to that implementation. @param self Reader instance.

TarReader:closeSync() → ()

TarReader:nextEntry

Read the next raw TAR entry from the stream. This exposes parser-level details, including metadata-only extension entries such as PAX records when they survive normalization, and returns nil at end of archive. @param self Reader instance.

TarReader:nextEntry() → TarEntry?

Returns

TarEntry?

Next parsed entry, or nil when the archive is exhausted.

TarReader:nextMember

Read the next normalized archive member from the stream. Metadata-only records used to describe subsequent entries are consumed internally so callers receive a cleaner member-oriented view of the archive. @param self Reader instance.

TarReader:nextMember() → TarMember?

Returns

TarMember?

Next normalized member, or nil when no members remain.

SeekableTarReader

Seek-capable TAR reader returned by tar.openSeekable and tar.openPath. In addition to sequential reads, this variant can rewind and build a random access index because its underlying stream supports seeking.

Implements: TarReaderState

Properties

stream: stream.StreamThatCanRead & stream.StreamThatCanSeek

closed: boolean

true once the reader has been closed and can no longer read from the archive.

globalPax: { [string]: string }

PAX attributes inherited by subsequent entries until replaced.

nextPax: { [string]: string }?

PAX attributes queued for only the next entry.

longPath: string?

GNU long path captured from a preceding L record.

longLinkPath: string?

GNU long link path captured from a preceding K record.

pendingAcl: string?

ACL text captured from a preceding A record.

SeekableTarReader.new

Create a TAR reader backed by a seekable stream. Use this when you want to rewind, build an index, or lazily re-read member payloads later without reopening the archive.

SeekableTarReader.new(stream_: stream.StreamThatCanRead & stream.StreamThatCanSeek) → ()

Parameters

stream_: stream.StreamThatCanRead & stream.StreamThatCanSeek

Readable seekable stream at the archive start.

SeekableTarReader:rewind

Seek back to the start of the archive and discard all in-flight extended metadata state such as global PAX records, queued long paths, and pending ACLs.

SeekableTarReader:rewind() → number

Returns

number

Absolute stream offset returned by the underlying seek call.

SeekableTarReader:index

Scan the entire archive and build a random-access index over its members. The reader is rewound before and after indexing so the caller can continue from a clean start position once the index has been created. @param self Seekable TAR reader instance.

SeekableTarReader:index() → TarIndex

Returns

TarIndex

Random-access index for the archive.

TarIndex

Random-access index built from a seekable TAR stream. It caches every member in archive order and exposes path lookups plus lazy payload reads.

Properties

reader: SeekableTarReader

Reader used to build and service the index.

entries: { TarIndexEntry }

Members in archive order.

byPath: { [string]: TarIndexEntry }

Last member seen for each archive path.

TarIndex.new

Create an immutable TAR index from a seekable reader and precomputed lookup tables. This constructor is primarily used internally by SeekableTarReader:index.

TarIndex.new(reader: SeekableTarReader, entries: { TarIndexEntry }, byPath: { [string]: TarIndexEntry }) → TarIndex

Parameters

reader: SeekableTarReader

Reader the index will use for lazy payload reads.

entries: { TarIndexEntry }

Members in archive order.

byPath: { [string]: TarIndexEntry }

Path lookup table for indexed members.

Returns

TarIndex

Random-access TAR index.

TarIndex:list

Return a shallow copy of the indexed members in archive order. Mutating the returned array will not affect the index internals. @param self TAR index instance.

TarIndex:list() → { TarIndexEntry }

Returns

{ TarIndexEntry }

Indexed members in archive order.

TarIndex:get

Look up a member by its archive path. If the archive contains duplicate paths, the last indexed occurrence wins. @param self TAR index instance.

TarIndex:get(path: string) → TarIndexEntry?

Parameters

path: string

Exact archive path to find.

Returns

TarIndexEntry?

Indexed member metadata, or nil when absent.

TarIndex:read

Read and return the stored contents for a file-like indexed member. Only regular files and hardlinks are readable through this helper; directories and other non-data entries return nil. Sparse members are reconstructed into their full logical contents before being returned. @param self TAR index instance.

TarIndex:read(path: string) → string?

Parameters

path: string

Exact archive path to read.

Returns

string?

Member contents, or nil when the path is missing or not readable as file data.

Functions

tar.open

Open a TAR archive from an already-open readable stream. Use this for one-pass iteration when random access is not required.

tar.open(stream_: stream.StreamThatCanRead) → TarReader

Parameters

stream_: stream.StreamThatCanRead

Readable stream positioned at the start of a TAR archive.

Returns

TarReader

Sequential TAR reader.

tar.openSeekable

Open a TAR archive from a readable, seekable stream. This variant can rewind, build an index, and lazily re-read payloads later.

tar.openSeekable(stream_: stream.StreamThatCanRead & stream.StreamThatCanSeek) → SeekableTarReader

Parameters

stream_: stream.StreamThatCanRead & stream.StreamThatCanSeek

Readable seekable stream positioned at the archive start.

Returns

SeekableTarReader

Seek-capable TAR reader.

tar.openPath

Open a TAR archive directly from a filesystem path in read mode. The returned reader is seekable because it wraps a filesystem stream. Call reader:close() when finished so the file handle is released promptly.

tar.openPath(path: path.PathLike) → SeekableTarReader

Parameters

path: path.PathLike

Path to the TAR archive on disk.

Returns

SeekableTarReader

Seek-capable TAR reader for the file.

Types

TarMember

Normalized archive member returned by TarReader:nextMember and stored inside TarIndex. This is the main consumer-facing representation of TAR contents.

type TarMember = { path: string, kind: string, typeflag: string, header: TarEntryHeader, data: string, dataOffset: number?, storedSize: number, size: number, linkPath: string?, attributes: { [string]: string }, acl: string?, sparse: TarSparseInfo? }

path: string

Final archive path for the member.

kind: string

High-level member kind such as file, directory, or symlink.

typeflag: string

Original TAR type flag for callers that need format-level detail.

header: TarEntryHeader

Parsed header metadata.

data: string

Stored payload bytes captured while reading sequentially.

dataOffset: number?

Byte offset where the stored payload begins, when known.

storedSize: number

Number of payload bytes physically present in the archive.

size: number

Logical content size after accounting for sparse metadata.

linkPath: string?

Link target for symlink and hardlink members.

attributes: { [string]: string }

Effective merged PAX attribute map.

acl: string?

Access-control payload attached from a preceding ACL record.

sparse: TarSparseInfo?

Sparse reconstruction metadata when present.

TarIndexEntry

type TarIndexEntry = TarMember

Implements: TarMember