@types/tar-stream

What is @types/tar-stream?

@types/tar-stream provides TypeScript type definitions for the tar-stream package, which is a streaming tar parser and generator. It allows you to create and extract tar archives in a streaming fashion, making it suitable for handling large files or integrating with other streaming APIs.

What are @types/tar-stream's main functionalities?

Creating a tar archive

This feature allows you to create a tar archive by adding entries to it. The example demonstrates how to create a tarball with a single file named 'my-file.txt' containing the text 'Hello, world!'.

const tar = require('tar-stream');
const pack = tar.pack();
const fs = require('fs');

pack.entry({ name: 'my-file.txt' }, 'Hello, world!');
pack.finalize();

pack.pipe(fs.createWriteStream('my-tarball.tar'));

Extracting a tar archive

This feature allows you to extract files from a tar archive. The example demonstrates how to read a tarball and handle each entry as it is extracted.

const tar = require('tar-stream');
const extract = tar.extract();
const fs = require('fs');

extract.on('entry', function(header, stream, next) {
  stream.on('end', next);
  stream.resume();
});

fs.createReadStream('my-tarball.tar').pipe(extract);

Appending files to an existing tar archive

This feature allows you to append new files to an existing tar archive. The example demonstrates how to read an existing tarball, add a new file to it, and write the updated tarball to a new file.

const tar = require('tar-stream');
const fs = require('fs');
const pack = tar.pack();

pack.entry({ name: 'new-file.txt' }, 'New content');
pack.finalize();

const extract = tar.extract();
extract.on('entry', function(header, stream, next) {
  pack.entry(header, function(err, entry) {
    stream.pipe(entry);
    stream.on('end', next);
  });
});

fs.createReadStream('existing-tarball.tar').pipe(extract);
pack.pipe(fs.createWriteStream('updated-tarball.tar'));

Other packages similar to @types/tar-stream

tar

The 'tar' package provides high-level APIs for creating and extracting tar archives. It is more user-friendly and offers additional features like compression support. However, it may not be as efficient for streaming large files as tar-stream.

node-tar

The 'node-tar' package is another popular library for working with tar archives. It provides both high-level and low-level APIs, making it versatile for different use cases. Compared to tar-stream, it offers more built-in utilities but may not be as lightweight.

archiver

The 'archiver' package is a general-purpose archive generation library that supports various formats, including tar. It provides a simple API for creating archives and supports compression. While it is more versatile, it may not be as specialized for tar archives as tar-stream.

README

Installation

npm install --save @types/tar-stream

Summary

This package contains type definitions for tar-stream (https://github.com/mafintosh/tar-stream).

Details

Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/tar-stream.

index.d.ts

/// <reference types="node" />

import stream = require("stream");

export type Callback = (err?: Error | null) => any;

// see https://github.com/mafintosh/tar-stream/blob/master/headers.js
export interface Headers {
    name: string;
    mode?: number | undefined;
    uid?: number | undefined;
    gid?: number | undefined;
    size?: number | undefined;
    mtime?: Date | undefined;
    linkname?: string | null | undefined;
    type?:
        | "file"
        | "link"
        | "symlink"
        | "character-device"
        | "block-device"
        | "directory"
        | "fifo"
        | "contiguous-file"
        | "pax-header"
        | "pax-global-header"
        | "gnu-long-link-path"
        | "gnu-long-path"
        | null
        | undefined;
    uname?: string | undefined;
    gname?: string | undefined;
    devmajor?: number | undefined;
    devminor?: number | undefined;
}

export interface Pack extends stream.Readable {
    /**
     * To create a pack stream use tar.pack() and call pack.entry(header, [callback]) to add tar entries.
     */
    entry(headers: Headers, callback?: Callback): stream.Writable;
    entry(headers: Headers, buffer?: string | Buffer, callback?: Callback): stream.Writable;
    finalize(): void;
    [Symbol.asyncIterator](): AsyncIterableIterator<Buffer>;
}

export interface Entry extends stream.Readable {
    header: Headers;
    [Symbol.asyncIterator](): AsyncIterableIterator<Buffer>;
}

export interface Extract extends stream.Writable {
    on(event: string, listener: (...args: any[]) => void): this;
    on(
        event: "entry",
        listener: (headers: Headers, stream: stream.PassThrough, next: (error?: unknown) => void) => void,
    ): this;
    [Symbol.asyncIterator](): AsyncIterator<Entry>;
}

export interface ExtractOptions extends stream.WritableOptions {
    /**
     * Whether or not to attempt to extract a file that does not have an
     * officially supported format in the `magic` header, such as `ustar`.
     */
    allowUnknownFormat?: boolean | undefined;
    /**
     * The encoding of the file name header.
     */
    filenameEncoding?: BufferEncoding | undefined;
}
export function extract(opts?: ExtractOptions): Extract;

export function pack(opts?: stream.ReadableOptions): Pack;

Additional Details

• Last updated: Tue, 07 Nov 2023 20:08:00 GMT
• Dependencies: @types/node

Credits

These definitions were written by Guy Lichtman, Piotr Błażejewicz, Kevin Lindsay, and Christian Rackerseder.