TarStream

import { TarStream } from "jsr:@ende/tar";

class ยท experimental

class TarStream implements TransformStream<TarStreamInput, Uint8Array_>

Overview

A TransformStream to create a tar archive. Tar archives allow for storing multiple files in a single file (called an archive, or sometimes a tarball). These archives typically have a single '.tar' extension. This implementation follows the FreeBSD 15.0 spec.

File Format & Limitations

The ustar file format is used for creating the tar archive. While this format is compatible with most tar readers, the format has several limitations, including:

  • Paths must be at most 256 bytes.
  • Symlink target paths (linkname) must be at most 100 bytes.
  • Files must be at most 8 GiBs in size, or 64 GiBs if sizeExtension is set to true.
  • Sparse files are not supported.

Usage

TarStream may throw an error for several reasons. A few of those are:

  • The path is invalid.
  • The size provided does not match that of the iterable's length.

Compression

Tar archives are not compressed by default. If you'd like to compress the archive, you may do so by piping it through a compression stream.

Example: Usage

import { TarStream, type TarStreamInput } from "@ende/tar/tar-stream";

await ReadableStream.from<TarStreamInput>([
  {
    type: "directory",
    path: 'potato/'
  },
  {
    type: "file",
    path: 'ende.json',
    size: (await Ende.stat('ende.json')).size,
    readable: (await Ende.open('ende.json')).readable
  },
  {
    type: "file",
    path: '.vscode/settings.json',
    size: (await Ende.stat('.vscode/settings.json')).size,
    readable: (await Ende.open('.vscode/settings.json')).readable
  }
])
  .pipeThrough(new TarStream())
  .pipeThrough(new CompressionStream('gzip'))
  .pipeTo((await Ende.create('./out.tar.gz')).writable)

Constructors

constructor

new TarStream()

Constructs a new instance.

Methods

readable

get readable(): ReadableStream<Uint8Array_>

The ReadableStream

Returns

ReadableStream

Example: Usage

import { TarStream } from "@ende/tar/tar-stream";

await ReadableStream.from([
  {
    type: "directory",
    path: 'potato/'
  },
  {
    type: "file",
    path: 'ende.json',
    size: (await Ende.stat('ende.json')).size,
    readable: (await Ende.open('ende.json')).readable
  },
  {
    type: "file",
    path: '.vscode/settings.json',
    size: (await Ende.stat('.vscode/settings.json')).size,
    readable: (await Ende.open('.vscode/settings.json')).readable
  }
])
  .pipeThrough(new TarStream())
  .pipeThrough(new CompressionStream('gzip'))
  .pipeTo((await Ende.create('./out.tar.gz')).writable)

writable

get writable(): WritableStream<TarStreamInput>

The WritableStream

Returns

WritableStream

Example: Usage

import { TarStream } from "@ende/tar/tar-stream";

await ReadableStream.from([
  {
    type: "directory",
    path: 'potato/'
  },
  {
    type: "file",
    path: 'ende.json',
    size: (await Ende.stat('ende.json')).size,
    readable: (await Ende.open('ende.json')).readable
  },
  {
    type: "file",
    path: '.vscode/settings.json',
    size: (await Ende.stat('.vscode/settings.json')).size,
    readable: (await Ende.open('.vscode/settings.json')).readable
  }
])
  .pipeThrough(new TarStream())
  .pipeThrough(new CompressionStream('gzip'))
  .pipeTo((await Ende.create('./out.tar.gz')).writable)

Source