@types/tar

Version 6.1.10
Published 7 days ago
29.8 kB
2 dependencies
MIT license

Install

npm i @types/tar

yarn add @types/tar

pnpm add @types/tar

Overview

TypeScript definitions for tar

Index

Variables

variable blockSize

const blockSize: number;

variable c

const c: {
    (
        options: CreateOptions,
        fileList: readonly string[],
        callback?: (err?: Error) => void
    ): stream.Readable;
    (
        options: CreateOptions & FileOptions,
        fileList: readonly string[]
    ): Promise<void>;
    (
        options: CreateOptions & FileOptions & { sync: true },
        fileList: readonly string[]
    ): void;
    (
        options: CreateOptions & FileOptions,
        fileList: readonly string[],
        callback: (err?: Error) => void
    ): void;
};

Alias for create

variable fieldEnds

const fieldEnds: number[];

variable fieldOffs

const fieldOffs: number[];

variable fieldSize

const fieldSize: number[];

variable headerSize

const headerSize: number;

variable knownExtended

const knownExtended: {
    atime: boolean;
    charset: boolean;
    comment: boolean;
    ctime: boolean;
    gid: boolean;
    gname: boolean;
    linkpat: boolean;
    mtime: boolean;
    path: boolean;
    realtime: boolean;
    security: boolean;
    size: boolean;
    uid: boolean;
    uname: boolean;
};

variable modes

const modes: {
    suid: number;
    sgid: number;
    svtx: number;
    uread: number;
    uwrite: number;
    uexec: number;
    gread: number;
    gwrite: number;
    gexec: number;
    oread: number;
    owrite: number;
    oexec: number;
};

Values for the mode field

variable numeric

const numeric: {
    mode: boolean;
    uid: boolean;
    gid: boolean;
    size: boolean;
    mtime: boolean;
    devmaj: boolean;
    devmin: boolean;
    cksum: boolean;
    atime: boolean;
    ctime: boolean;
    dev: boolean;
    ino: boolean;
    nlink: boolean;
};

variable Parse

const Parse: new (opt?: ParseOptions) => Parse;

variable r

const r: {
    (options: ReplaceOptions, fileList?: readonly string[]): Promise<void>;
    (
        options: ReplaceOptions,
        fileList: readonly string[],
        callback: (err?: Error) => void
    ): Promise<void>;
};

Alias for replace

variable t

const t: {
    (
        options: ListOptions & RequiredFileOptions,
        fileList?: readonly string[]
    ): Promise<void>;
    (
        options: ListOptions & RequiredFileOptions & { sync: true },
        fileList?: readonly string[]
    ): void;
    (callback?: (err?: Error) => void): Parse;
    (
        optionsOrFileList: readonly string[] | ListOptions,
        callback?: (err?: Error) => void
    ): Parse;
    (
        options: ListOptions,
        fileList: readonly string[],
        callback?: (err?: Error) => void
    ): Parse;
};

Alias for list

variable types

const types: {
    0: string;
    '\0': string;
    '': string;
    1: string;
    2: string;
    3: string;
    4: string;
    5: string;
    6: string;
    7: string;
    g: string;
    x: string;
    A: string;
    D: string;
    I: string;
    K: string;
    L: string;
    M: string;
    N: string;
    S: string;
    V: string;
    X: string;
    File: string;
    OldFile: string;
    Link: string;
    SymbolicLick: string;
    CharacterDevice: string;
    BlockDevice: string;
    Directory: string;
    FIFO: string;
    ContiguousFile: string;
    GlobalExtendedHeader: string;
    ExtendedHeader: string;
    SolarisACL: string;
    GNUDumpDir: string;
    INode: string;
    NextFileHasLonLinkPath: string;
    NextFileHasLongPath: string;
    ContinuationFile: string;
    TapeVolumeHeader: string;
    OldExtendedHeader: string;
};

Different values of the 'type' field paths match the values of Stats.isX() functions, where appropriate

variable u

const u: {
    (options: ReplaceOptions, fileList?: readonly string[]): Promise<void>;
    (
        options: ReplaceOptions,
        fileList: readonly string[],
        callback: (err?: Error) => void
    ): Promise<void>;
};

Alias for update

variable x

const x: {
    (
        options: ExtractOptions,
        fileList?: readonly string[],
        callback?: (err?: Error) => void
    ): stream.Writable;
    (
        options: ExtractOptions & FileOptions,
        fileList?: readonly string[]
    ): Promise<void>;
    (
        options: ExtractOptions & FileOptions & { sync: true },
        fileList?: readonly string[]
    ): void;
    (
        options: ExtractOptions & FileOptions,
        fileList: readonly string[],
        callback: (err?: Error) => void
    ): void;
};

Alias for extract

Functions

function create

create: {
    (
        options: CreateOptions,
        fileList: readonly string[],
        callback?: (err?: Error) => void
    ): stream.Readable;
    (
        options: CreateOptions & FileOptions,
        fileList: readonly string[]
    ): Promise<void>;
    (
        options: CreateOptions & FileOptions & { sync: true },
        fileList: readonly string[]
    ): void;
    (
        options: CreateOptions & FileOptions,
        fileList: readonly string[],
        callback: (err?: Error) => void
    ): void;
};

Create a tarball archive. The fileList is an array of paths to add to the tarball. Adding a directory also adds its children recursively. An entry in fileList that starts with an @ symbol is a tar archive whose entries will be added. To add a file that starts with @, prepend it with ./.
Archive data may be read from the returned stream.
Create a tarball archive. The fileList is an array of paths to add to the tarball. Adding a directory also adds its children recursively. An entry in fileList that starts with an @ symbol is a tar archive whose entries will be added. To add a file that starts with @, prepend it with ./.

function extract

extract: {
    (
        options: ExtractOptions,
        fileList?: readonly string[],
        callback?: (err?: Error) => void
    ): stream.Writable;
    (
        options: ExtractOptions & FileOptions,
        fileList?: readonly string[]
    ): Promise<void>;
    (
        options: ExtractOptions & FileOptions & { sync: true },
        fileList?: readonly string[]
    ): void;
    (
        options: ExtractOptions & FileOptions,
        fileList: readonly string[],
        callback: (err?: Error) => void
    ): void;
};

Extract a tarball archive. The fileList is an array of paths to extract from the tarball. If no paths are provided, then all the entries are extracted. If the archive is gzipped, then tar will detect this and unzip it. Note that all directories that are created will be forced to be writable, readable, and listable by their owner, to avoid cases where a directory prevents extraction of child entries by virtue of its mode. Most extraction errors will cause a warn event to be emitted. If the cwd is missing, or not a directory, then the extraction will fail completely.
Archive data should be written to the returned stream.
Extract a tarball archive. The fileList is an array of paths to extract from the tarball. If no paths are provided, then all the entries are extracted. If the archive is gzipped, then tar will detect this and unzip it. Note that all directories that are created will be forced to be writable, readable, and listable by their owner, to avoid cases where a directory prevents extraction of child entries by virtue of its mode. Most extraction errors will cause a warn event to be emitted. If the cwd is missing, or not a directory, then the extraction will fail completely.

function Extract

Extract: (opts: ExtractOptions | string) => ParseStream;

Returns a through stream. Write tar data to the stream and the files in the tarball will be extracted onto the filesystem. options can be:
{ path: '/path/to/extract/tar/into', strip: 0, // how many path segments to strip from the root when extracting }
options also get passed to the fstream.Writer instance that tar uses internally.

function list

list: {
    (
        options: ListOptions & RequiredFileOptions,
        fileList?: readonly string[]
    ): Promise<void>;
    (
        options: ListOptions & RequiredFileOptions & { sync: true },
        fileList?: readonly string[]
    ): void;
    (callback?: (err?: Error) => void): Parse;
    (
        optionsOrFileList: readonly string[] | ListOptions,
        callback?: (err?: Error) => void
    ): Parse;
    (
        options: ListOptions,
        fileList: readonly string[],
        callback?: (err?: Error) => void
    ): Parse;
};

List the contents of a tarball archive. The fileList is an array of paths to list from the tarball. If no paths are provided, then all the entries are listed. If the archive is gzipped, then tar will detect this and unzip it.

function replace

replace: {
    (options: ReplaceOptions, fileList?: readonly string[]): Promise<void>;
    (
        options: ReplaceOptions,
        fileList: readonly string[],
        callback: (err?: Error) => void
    ): Promise<void>;
};

Add files to an existing archive. Because later entries override earlier entries, this effectively replaces any existing entries. The fileList is an array of paths to add to the tarball. Adding a directory also adds its children recursively. An entry in fileList that starts with an @ symbol is a tar archive whose entries will be added. To add a file that starts with @, prepend it with ./.

function update

update: {
    (options: ReplaceOptions, fileList?: readonly string[]): Promise<void>;
    (
        options: ReplaceOptions,
        fileList: readonly string[],
        callback: (err?: Error) => void
    ): Promise<void>;
};

Add files to an archive if they are newer than the entry already in the tarball archive. The fileList is an array of paths to add to the tarball. Adding a directory also adds its children recursively. An entry in fileList that starts with an @ symbol is a tar archive whose entries will be added. To add a file that starts with @, prepend it with ./.

Classes

class Pack

class Pack extends MiniPass {}

Returns a through stream. Use fstream to write files into the pack stream and you will receive tar archive data from the pack stream. This only works with directories, it does not work with individual files. The optional properties object are used to set properties in the tar 'Global Extended Header'.

constructor

constructor(opt?: PackOptions);

property linkCache

linkCache: Map<string, string>;

property readdirCache

readdirCache: Map<string, string>;

property statCache

statCache: Map<string, string>;

property Sync

static Sync: typeof PackSync;

method add

add: (path: string) => this;

Interfaces

interface CreateOptions

interface CreateOptions {}

property C

C?: string | undefined;

Alias for cwd.

property cwd

cwd?: string | undefined;

The current working directory for creating the archive. Defaults to process.cwd().

property follow

follow?: boolean | undefined;

Set to true to pack the targets of symbolic links. Without this option, symbolic links are archived as such.

property gzip

gzip?: boolean | zlib.ZlibOptions | undefined;

Set to any truthy value to create a gzipped archive, or an object with settings for zlib.Gzip()

property h

h?: boolean | undefined;

Alias for follow.

property L

L?: boolean | undefined;

Alias for follow.

property mode

mode?: number | undefined;

The mode to set on the created file archive.

property noDirRecurse

noDirRecurse?: boolean | undefined;

Do not recursively archive the contents of directories.

property noPax

noPax?: boolean | undefined;

Suppress pax extended headers. Note that this means that long paths and linkpaths will be truncated, and large or negative numeric values may be interpreted incorrectly.

property P

P?: boolean | undefined;

Alias for presevePaths.

property portable

portable?: boolean | undefined;

Omit metadata that is system-specific: ctime, atime, uid, gid, uname, gname, dev, ino, and nlink. Note that mtime is still included, because this is necessary other time-based operations.

property prefix

prefix?: string | undefined;

A path portion to prefix onto the entries in the archive.

property preservePaths

preservePaths?: boolean | undefined;

Allow absolute paths. By default, / is stripped from absolute paths.

property strict

strict?: boolean | undefined;

Treat warnings as crash-worthy errors. Default false.

property z

z?: boolean | zlib.ZlibOptions | undefined;

Alias for gzip.

method filter

filter: (path: string, stat: fs.Stats) => boolean;

A function that gets called with (path, stat) for each entry being added. Return true to add the entry to the archive, or false to omit it.

method onwarn

onwarn: (code: string, message: string, data: Buffer) => void;

A function that will get called with (code, message, data) for any warnings encountered. (See "Warnings and Errors")

interface ExtractOptions

interface ExtractOptions {}

property Directory

Directory?: boolean | undefined;

property path

path?: string | undefined;

property strip

strip?: number | undefined;

property type

type?: string | undefined;

interface ExtractOptions

interface ExtractOptions {}

property "keep-existing"

'keep-existing'?: boolean | undefined;

Alias for keep.

property "keep-newer-files"

'keep-newer-files'?: boolean | undefined;

Alias for newer.

property "keep-newer"

'keep-newer'?: boolean | undefined;

Alias for newer.

property "no-mtime"

'no-mtime'?: boolean | undefined;

property "strip-components"

'strip-components'?: number | undefined;

Alias for strip.

property C

C?: string | undefined;

Alias for cwd.

property cwd

cwd?: string | undefined;

Extract files relative to the specified directory. Defaults to process.cwd(). If provided, this must exist and must be a directory.

property gid

gid?: number | undefined;

Set to a number to force ownership of all extracted files and folders, and all implicitly created directories, to be owned by the specified group id, regardless of the gid field in the archive. Cannot be used along with preserveOwner. Requires also setting a uid option

property k

k?: boolean | undefined;

Alias for keep.

property keep

keep?: boolean | undefined;

Do not overwrite existing files. In particular, if a file appears more than once in an archive, later copies will not overwrite earlier copies

property m

m?: boolean | undefined;

property maxMetaEntrySize

maxMetaEntrySize?: number | undefined;

The maximum size of meta entries that is supported. Defaults to 1 MB.

property maxReadSize

maxReadSize?: number | undefined;

The maximum buffer size for fs.read() operations (in bytes). Defaults to 16 MB.

property newer

newer?: boolean | undefined;

Set to true to keep the existing file on disk if it's newer than the file in the archive.

property noChmod

noChmod?: boolean | undefined;

Set to true to omit calling fs.chmod() to ensure that the extracted file matches the entry mode. This also suppresses the call to process.umask() to determine the default umask value, since tar will extract with whatever mode is provided, and let the process umask apply normally.

property noMtime

noMtime?: boolean | undefined;

Set to true to omit writing mtime value for extracted entries. [Alias: m, no-mtime]

property p

p?: boolean | undefined;

Alias for preserveOwner.

property preserveOwner

preserveOwner?: boolean | undefined;

If true, tar will set the uid and gid of extracted entries to the uid and gid fields in the archive. This defaults to true when run as root, and false otherwise. If false, then files and directories will be set with the owner and group of the user running the process. This is similar to -p in tar(1), but ACLs and other system-specific data is never unpacked in this implementation, and modes are set by default already.

property strict

strict?: boolean | undefined;

Treat warnings as crash-worthy errors. Default false.

property strip

strip?: number | undefined;

Remove the specified number of leading path elements. Pathnames with fewer elements will be silently skipped. Note that the pathname is edited after applying the filter, but before security checks.

property stripComponents

stripComponents?: number | undefined;

Alias for strip.

property uid

uid?: number | undefined;

Set to a number to force ownership of all extracted files and folders, and all implicitly created directories, to be owned by the specified user id, regardless of the uid field in the archive. Cannot be used along with preserveOwner. Requires also setting a gid option.

property unlink

unlink?: boolean | undefined;

Unlink files before creating them. Without this option, tar overwrites existing files, which preserves existing hardlinks. With this option, existing hardlinks will be broken, as will any symlink that would affect the location of an extracted file.

method filter

filter: (path: string, stat: FileStat) => boolean;

A function that gets called with (path, stat) for each entry being added. Return true to emit the entry from the archive, or false to skip it.

method onentry

onentry: (entry: ReadEntry) => void;

A function that gets called with (entry) for each entry that passes the filter.

method onwarn

onwarn: (code: string, message: string, data: Buffer) => void;

A function that will get called with (code, message, data) for any warnings encountered. (See "Warnings and Errors")

method transform

transform: (
    entry: ReadEntry
) => NodeJS.WritableStream | undefined | false | null;

Provide a function that takes an entry object, and returns a stream, or any falsey value. If a stream is provided, then that stream's data will be written instead of the contents of the archive entry. If a falsey value is provided, then the entry is written to disk as normal. (To exclude items from extraction, use the filter option described above.)

interface Fields

interface Fields {}

property cksum

cksum: number;

property devmaj

devmaj: number;

property devmin

devmin: number;

property fill

fill: number;

property gid

gid: number;

property gname

gname: number;

property linkpath

linkpath: number;

property mode

mode: number;

property mtime

mtime: number;

property path

path: number;

property prefix

prefix: number;

property size

size: number;

property type

type: number;

property uid

uid: number;

property uname

uname: number;

property ustar

ustar: number;

property ustarvar

ustarvar: number;

interface FileOptions

interface FileOptions {}

property f

f?: string | undefined;

Alias for file.

property file

file?: string | undefined;

Uses the given file as the input or output of this function.

interface FileStat

interface FileStat extends stream.Readable, Fields {}

property blockRemain

blockRemain: number;

header: HeaderProperties;

property ignore

ignore: boolean;

property meta

meta: boolean;

property remain

remain: number;

property size

size: number;

property startBlockSize

startBlockSize: number;

interface HeaderProperties

interface HeaderProperties {}

property devmaj

devmaj?: number | undefined;

property devmin

devmin?: number | undefined;

property gid

gid?: number | undefined;

property gname

gname?: string | undefined;

property mode

mode?: number | undefined;

property mtime

mtime?: number | undefined;

property noProprietary

noProprietary?: boolean | undefined;

property path

path: string;

property size

size?: number | undefined;

property type

type?: string | undefined;

property uid

uid?: number | undefined;

property uname

uname?: string | undefined;

interface ListOptions

interface ListOptions {}

property C

C?: string | undefined;

Alias for cwd.

property cwd

cwd?: string | undefined;

Extract files relative to the specified directory. Defaults to process.cwd(). If provided, this must exist and must be a directory.

property maxReadSize

maxReadSize?: number | undefined;

The maximum buffer size for fs.read() operations. Defaults to 16 MB.

property noResume

noResume?: boolean | undefined;

By default, entry streams are resumed immediately after the call to onentry. Set noResume: true to suppress this behavior. Note that by opting into this, the stream will never complete until the entry data is consumed.

property strict

strict?: boolean | undefined;

Treat warnings as crash-worthy errors. Default false.

method filter

filter: (path: string, entry: FileStat) => boolean;

A function that gets called with (path, stat) for each entry being added. Return true to emit the entry from the archive, or false to skip it.

method onentry

onentry: (entry: ReadEntry) => void;

A function that gets called with (entry) for each entry that passes the filter. This is important for when both file and sync are set, because it will be called synchronously.

interface PackOptions

interface PackOptions {}

property cwd

cwd?: string;

The current working directory for creating the archive.
process.cwd()

property follow

follow?: boolean;

Set to true to pack the targets of symbolic links. Without this option, symbolic links are archived as such.

property gzip

gzip?: boolean | zlib.ZlibOptions;

Set to any truthy value to create a gzipped archive, or an object with settings for zlib.Gzip()

property jobs

jobs?: number;

A number specifying how many concurrent jobs to run.
4

property linkCache

linkCache?: Map<string, string>;

A Map object containing the device and inode value for any file whose nlink is > 1, to identify hard links.

property maxReadSize

maxReadSize?: number;

The maximum buffer size for fs.read() operations.
16 MB

property mtime

mtime?: number;

Set to a Date object to force a specific mtime for everything added to the archive. Overridden by noMtime.

property noDirRecurse

noDirRecurse?: boolean;

Do not recursively archive the contents of directories.

property noMtime

noMtime?: boolean;

Set to true to omit writing mtime values for entries. Note that this prevents using other mtime-based features like tar.update or the keepNewer option with the resulting tar archive.

property noPax

noPax?: boolean;

Suppress pax extended headers. Note that this means that long paths and linkpaths will be truncated, and large or negative numeric values may be interpreted incorrectly.

property portable

portable?: boolean;

Omit metadata that is system-specific: ctime, atime, uid, gid, uname, gname, dev, ino, and nlink. Note that mtime is still included, because this is necessary for other time-based operations. Additionally, mode is set to a "reasonable default" for most unix systems, based on a umask value of 0o22.

property prefix

prefix?: string;

A path portion to prefix onto the entries in the archive.

property preservePaths

preservePaths?: boolean;

Allow absolute paths. By default, / is stripped from absolute paths.

property readdirCache

readdirCache?: Map<string, string>;

A Map object that caches calls to readdir.

property statCache

statCache?: Map<string, string>;

A Map object that caches calls lstat.

property strict

strict?: boolean;

Treat warnings as crash-worthy errors.
false

method filter

filter: (path: string, stat: fs.Stats) => boolean;

A function that gets called with (path, stat) for each entry being added. Return true to add the entry to the archive, or false to omit it.

method onwarn

onwarn: (code: string, message: string, data: Buffer) => void;

A function that will get called with (code, message, data) for any warnings encountered. (See "Warnings and Errors")

interface PackStream

interface PackStream extends NodeJS.ReadWriteStream {}

property readable

readable: boolean;

property writable

writable: boolean;

method add

add: (stream: stream.Stream) => boolean;

method addGlobal

addGlobal: (props: HeaderProperties) => void;

method destroy

destroy: () => void;

interface Parse

interface Parse extends ParseStream {}

A writable stream. Write tar data to it and it will emit entry events for each entry parsed from the tarball. This is used by tar.Extract.

method on

on: {
    (event: 'end' | 'close', listener: () => void): this;
    (event: 'entry', listener: (entry: ReadEntry) => void): this;
};

interface ParseOptions

interface ParseOptions {}

property filter

filter?: (path: string, entry: ReadEntry) => boolean;

property onentry

onentry?: (entry: ReadEntry) => void;

property onwarn

onwarn?: (code: string, message: string, data: Buffer) => void;

property strict

strict?: boolean;

interface ParseStream

interface ParseStream extends NodeJS.ReadWriteStream {}

property position

position: number;

interface ReadEntry

interface ReadEntry extends MiniPass, HeaderProperties {}

property blockRemain

blockRemain: number;

The number of 512-byte blocks remaining to be written into the stream.

property extended

extended: any;

The extended metadata object provided to the constructor.

property globalExtended

globalExtended: any;

The global extended metadata object provided to the constructor.

property ignore

ignore: boolean;

Whether this entry should be ignored.

property meta

meta: boolean;

True if this represents metadata about the next entry, false if it represents a filesystem object.

property remain

remain: number;

The number of bytes remaining to be written into the stream.

interface ReplaceOptions

interface ReplaceOptions {}

property C

C?: string | undefined;

Alias for cwd.

property cwd

cwd?: string | undefined;

Extract files relative to the specified directory. Defaults to process.cwd(). If provided, this must exist and must be a directory.

property file

file: string;

Required. Write the tarball archive to the specified filename.

property follow

follow?: boolean | undefined;

Set to true to pack the targets of symbolic links. Without this option, symbolic links are archived as such.

property gzip

gzip?: boolean | zlib.ZlibOptions | undefined;

Set to any truthy value to create a gzipped archive, or an object with settings for zlib.Gzip()

property h

h?: boolean | undefined;

Alias for follow.

property L

L?: boolean | undefined;

Alias for follow.

property maxReadSize

maxReadSize?: number | undefined;

The maximum buffer size for fs.read() operations. Defaults to 16 MB.

property noDirRecurse

noDirRecurse?: boolean | undefined;

Do not recursively archive the contents of directories.

property noPax

noPax?: boolean | undefined;

uppress pax extended headers. Note that this means that long paths and linkpaths will be truncated, and large or negative numeric values may be interpreted incorrectly.

property prefix

prefix?: string | undefined;

A path portion to prefix onto the entries in the archive.

property preservePaths

preservePaths?: boolean | undefined;

Allow absolute paths. By default, / is stripped from absolute paths.

property strict

strict?: boolean | undefined;

Treat warnings as crash-worthy errors. Default false.

property sync

sync?: boolean | undefined;

Act synchronously. If this is set, then any provided file will be fully written after the call to tar.c.

method filter

filter: (path: string, stat: fs.Stats) => boolean;

A function that gets called with (path, stat) for each entry being added. Return true to emit the entry from the archive, or false to skip it.

method onwarn

onwarn: (code: string, message: string, data: Buffer) => void;

A function that will get called with (code, message, data) for any warnings encountered. (See "Warnings and Errors")

Type Aliases

type fields

type fields = Fields;

type RequiredFileOptions

type RequiredFileOptions =
    | {
          /**
           * Uses the given file as the input or output of this function.
           */
          file: string;
      }
    | {
          /**
           * Alias for file.
           */
          f: string;
      };

Package Files (1)

index.d.ts

Dependencies (2)

Dev Dependencies (0)

No dev dependencies.

Peer Dependencies (0)

No peer dependencies.

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/@types/tar.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/@types/tar)

HTML

<a href="https://www.jsdocs.io/package/@types/tar"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated just now.
Package analyzed in 5060 ms.
Missing or incorrect documentation? Open an issue for this package.