Skip to main content
Deno 2 is finally here 🎉️
Learn more
Module

x/ayonli_jsext/archive.ts>Tarball

A JavaScript extension package for building strong and modern applications.
ayonli/jsext
Latest
class Tarball
Re-export
import { Tarball } from "https://deno.land/x/ayonli_jsext@v0.9.72/archive.ts";

A Tarball instance represents a tar archive.

Examples

Example 1

// create a tarball
import { stat, createReadableStream, createWriteableStream } from "@ayonli/jsext/fs";
import { Tarball } from "@ayonli/jsext/archive";

const tarball = new Tarball();

const file1 = await stat("foo.txt");
const stream1 = createReadableStream("foo.txt");
tarball.append(stream1, { relativePath: "foo.txt", size: file1.size });

const file2 = await stat("bar.txt");
const stream2 = createReadableStream("bar.txt");
tarball.append(stream2, { relativePath: "bar.txt", size: file2.size });

const output = createWritableStream("archive.tar");
await tarball.stream().pipeTo(output);

Example 2

// load a tarball
import { createReadableStream } from "@ayonli/jsext/fs";
import { Tarball } from "@ayonli/jsext/archive";

const input = createReadableStream("archive.tar");
const tarball = await Tarball.load(input);

for (const entry of tarball) {
    console.log(entry);
}

Constructors

new
Tarball()

Properties

private
[_bodyUsed]: boolean
private
[_entries]: TarEntryWithData[]
readonly
bodyUsed: boolean

Indicates whether the body of the tarball has been used. This property will be set to true after the stream() method is called.

readonly
size: number

Returns the approximate size of the archive in bytes.

NOTE: This value may not reflect the actual size of the archive file when constructed via the load method.

Methods

private
constructEntry(
relativePath: string,
data:
| string
| ArrayBuffer
| ArrayBufferView
| ReadableStream<Uint8Array>
| Blob
| null
,
info: Partial<Omit<TarEntry, "relativePath">>,
): TarEntryWithData
append(data: File): void

Appends a file to the archive.

append(data:
| string
| ArrayBuffer
| ArrayBufferView
| Blob
| ReadableStream<Uint8Array>
| null
, info: Ensured<Partial<TarEntry>, "relativePath">): void
entries(): IterableIterator<TarEntry>

Iterates over the entries in the archive.

remove(relativePath: string): boolean

Removes an entry from the archive by its relative path.

This function returns true if the entry is successfully removed, or false if the entry does not exist.

replace(
relativePath: string,
data:
| string
| ArrayBuffer
| ArrayBufferView
| ReadableStream<Uint8Array>
| Blob
| null
,
info?: Partial<Omit<TarEntry, "relativePath">>,
): boolean

Replaces an entry in the archive with new data.

This function returns true if the entry is successfully replaced, or false if the entry does not exist or the entry kind of the new data is incompatible with the old one.

retrieve(relativePath: string): (TarEntry & { readonly stream: ReadableStream<Uint8Array>; }) | null

Retrieves an entry in the archive by its relative path.

The returned entry object contains a stream property which is a copy of the entry's data, and since it's a copy, the data in the archive is still available even after the stream property is consumed.

However, due to the nature of the ReadableStream.tee() API, if the copy is consumed, the data will be loaded and cached in memory until the tarball's stream is consumed or dropped. This may cause memory issues for large files, so it is recommended not to use the stream property unless necessary.

stream(options?: { gzip?: boolean; }): ReadableStream<Uint8Array>

Returns a readable stream of the archive that can be piped to a writable target.

This method can only be called once per instance, as after the stream has been consumed, the underlying data of the archive's entries will no longer be available, and subsequent calls to this method will throw an error.

To reuse the stream, use the tee() method of the stream to create a copy of the stream instead.

treeView(): TarTree

Returns a tree view of the entries in the archive.

NOTE: The entries returned by this function are reordered first by kind (directories before files), then by names alphabetically.

[Symbol.iterator](): IterableIterator<TarEntry>

Static Methods

load(stream: ReadableStream<Uint8Array>, options?: { gzip?: boolean; }): Promise<Tarball>

Loads a tar archive from a readable stream.

NOTE: This function loads the entire archive into memory, so it is not suitable for large archives. For large archives, use the untar function to extract files to the file system instead.