@ayonli/jsext
Version:
A JavaScript extension package for building strong and modern applications.
210 lines (209 loc) • 6.99 kB
TypeScript
import { Ensured } from "../types.ts";
declare const _bodyUsed: unique symbol;
/**
* Information about a file in a tar archive.
*/
export interface TarEntry {
name: string;
kind: "file" | "link" | "symlink" | "character-device" | "block-device" | "directory" | "fifo" | "contiguous-file";
/**
* The relative path of the entry.
*
* NOTE: The path separator is always `/` regardless of the platform.
*/
relativePath: string;
/**
* The size of the file in bytes. This value may be `0` if this is a
* directory.
*/
size: number;
/**
* The last modified time of the file.
*/
mtime: Date;
/**
* The permission mode of the file. This value may be `0` on unsupported
* platforms.
*/
mode: number;
/**
* User ID of the owner of the file. This value may be `0` on unsupported
* platforms.
*/
uid: number;
/**
* Group ID of the owner of the file. This value may be `0` on unsupported
* platforms.
*/
gid: number;
/**
* The owner's name of the file. This value may be an empty string on
* unsupported platforms.
*/
owner: string;
/**
* The group's name of the file. This value may be an empty string on
* unsupported platforms.
*/
group: string;
}
export interface TarTree extends TarEntry {
children?: TarTree[];
}
export declare const HEADER_LENGTH = 512;
export interface USTarFileHeader {
name: string;
mode: string;
uid: string;
gid: string;
size: string;
mtime: string;
checksum: string;
typeflag: string;
linkname: string;
magic: string;
version: string;
uname: string;
gname: string;
devmajor: string;
devminor: string;
prefix: string;
}
export declare function parseHeader(header: Uint8Array): [USTarFileHeader, header: Uint8Array, leftChunk: Uint8Array] | null;
export declare function createEntry(headerInfo: USTarFileHeader): TarEntry;
export declare const _entries: unique symbol;
/**
* A `Tarball` instance represents a tar archive.
*
* @example
* ```ts
* // 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
* ```ts
* // 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);
* }
* ```
*/
export default class Tarball {
private [_entries];
private [_bodyUsed];
constructor();
private constructEntry;
/**
* Appends a file to the archive.
* @param data The file data, can be `null` if the file info represents a directory.
*/
append(data: File): void;
append(data: string | ArrayBuffer | ArrayBufferView | Blob | ReadableStream<Uint8Array> | null, info: Ensured<Partial<TarEntry>, "relativePath">): void;
/**
* 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.
*/
retrieve(relativePath: string): (TarEntry & {
readonly stream: ReadableStream<Uint8Array>;
}) | null;
/**
* 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.
*/
remove(relativePath: string): 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.
*/
replace(relativePath: string, data: string | ArrayBuffer | ArrayBufferView | ReadableStream<Uint8Array> | Blob | null, info?: Partial<Omit<TarEntry, "relativePath">>): boolean;
[Symbol.iterator](): IterableIterator<TarEntry>;
/**
* Iterates over the entries in the archive.
*/
entries(): IterableIterator<TarEntry>;
/**
* 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.
*/
treeView(): TarTree;
/**
* 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 {@link load} method.
*/
get size(): number;
/**
* Indicates whether the body of the tarball has been used. This property
* will be set to `true` after the `stream()` method is called.
*/
get bodyUsed(): boolean;
/**
* 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.
*/
stream(options?: {
/**
* Compress the archive with gzip.
*/
gzip?: boolean;
}): ReadableStream<Uint8Array>;
/**
* 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.
*/
static load(stream: ReadableStream<Uint8Array>, options?: {
/**
* Decompress the archive with gzip.
*/
gzip?: boolean;
}): Promise<Tarball>;
}
export {};