archive

format?: ArchiveFormat

Override format detection from the archive file extension.

Use this when the path does not end with .zip, .tar, .tar.gz, or .tgz. Unsupported values are rejected by TypeScript and should not be supplied dynamically.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.data', { format: 'zip' });
await archive.write('README.md', 'hello');
await archive.close();

readOnly?: boolean

Prevent write operations on the opened archive.

Read-only handles can list, read, and extract entries. Mutating methods such as write(), remove(), rename(), and save() throw.

import { Archive } from 'fino:archive';

const archive = await Archive.open('bundle.zip', { readOnly: true });
const entries = await archive.entries();
await archive.close();

maxEntries?: number

Maximum number of regular file entries to extract.

maxTotalBytes?: number

Maximum total uncompressed bytes to extract across regular files.

kind?: ArchiveKind

Whether the entry should be stored as a file or directory.

When omitted, names ending with / are directories and all other entries are files. Directory entries read back as empty byte arrays.

import { Archive } from 'fino:archive';

const archive = await Archive.create('site.tar');
await archive.write('assets/', new Uint8Array(), { kind: 'directory' });
await archive.close();

compression?: ZipCompression

ZIP compression mode.

Tar archives ignore this option. deflate is the default for file entries; store writes uncompressed ZIP file data.

import { Archive } from 'fino:archive';

const archive = await Archive.create('assets.zip');
await archive.write('image.bin', new Uint8Array([1, 2, 3]), { compression: 'store' });
await archive.close();

mtime?: Date | number

Modification timestamp stored in the archive entry.

A Date is used directly; a number is interpreted by Date as milliseconds since the Unix epoch. ZIP timestamps are stored in DOS date form and may lose precision.

import { Archive } from 'fino:archive';

const archive = await Archive.create('snapshot.zip');
await archive.write('README.md', 'hello', {
  mtime: new Date('2026-01-01T00:00:00Z'),
});
await archive.close();

mode?: number

POSIX file mode stored in tar or ZIP metadata.

Only metadata is stored; extraction currently writes file contents and directories but does not apply every archived mode bit.

import { Archive } from 'fino:archive';

const archive = await Archive.create('tools.tar');
await archive.write('bin/run.sh', '#!/bin/sh\n', { mode: 0o755 });
await archive.close();

name: string

Normalized archive path.

Names use / separators and omit leading slashes. Empty names are not valid for writable entries.

import { listArchive } from 'fino:archive';

const readme = (await listArchive('bundle.zip'))
  .find((entry) => entry.name === 'README.md');

kind: ArchiveKind

Entry kind.

Directory entries do not carry file payloads and read as empty byte arrays.

import { listArchive } from 'fino:archive';

const directories = (await listArchive('bundle.tar'))
  .filter((entry) => entry.kind === 'directory');

size: number

Uncompressed entry size in bytes.

Directory entries report 0. ZIP entries may load data lazily, but this value is available from archive metadata.

import { listArchive } from 'fino:archive';

const largeFiles = (await listArchive('bundle.zip'))
  .filter((entry) => entry.kind === 'file' && entry.size > 1_000_000);

compressedSize: number

Compressed size in bytes.

For tar entries this is the same as size. For ZIP entries it reflects the stored compressed payload size.

import { listArchive } from 'fino:archive';

const compressedFiles = (await listArchive('bundle.zip'))
  .filter((entry) => entry.compressedSize < entry.size);

mtime: Date | null

Modification time stored in the archive, when available.

Some archive entries do not carry a timestamp and return null.

import { listArchive } from 'fino:archive';

const cutoff = new Date('2026-01-01T00:00:00Z');
const recentEntries = (await listArchive('bundle.zip'))
  .filter((entry) => entry.mtime !== null && entry.mtime >= cutoff);

mode: number | null

POSIX mode stored in archive metadata, when available.

The value may be null when the source archive did not provide usable mode metadata.

import { listArchive } from 'fino:archive';

const executableEntries = (await listArchive('tools.tar'))
  .filter((entry) => entry.mode !== null && (entry.mode & 0o111) !== 0);

entries: number

Number of file entries written to disk.

Directory entries are not counted. If extraction throws partway through, no ExtractResult is returned and previously written files remain on disk.

import { extractArchive } from 'fino:archive';

const result = await extractArchive('bundle.zip', 'out');
if (result.entries > 1000) throw new Error('unexpectedly large archive');

constructor(archive: Archive, name: string)

Create an entry handle bound to an archive and normalized entry name.

Application code normally obtains handles through Archive.entry().

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
await archive.write('file.txt', 'ok');
const handle = await archive.entry('file.txt');
console.log(handle?.name);
await archive.close();

get name(): string

Normalized archive entry name.

Names use forward slashes and have no leading slash.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
await archive.write('docs/readme.txt', 'ok');
console.log((await archive.entry('docs/readme.txt'))?.name);
await archive.close();

get kind(): ArchiveKind

Current entry kind.

Returns 'file' or 'directory'. Throws if the backing archive is closed or the entry no longer exists.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
await archive.write('docs/', new Uint8Array(), { kind: 'directory' });
console.log((await archive.entry('docs'))?.kind);
await archive.close();

get size(): number

Current uncompressed entry size in bytes.

Directories report 0. Throws if the archive is closed or the entry has been removed.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
await archive.write('file.txt', 'hello');
console.log((await archive.entry('file.txt'))?.size);
await archive.close();

get compressedSize(): number

Current compressed size in bytes.

For tar entries this matches size; for ZIP entries it reflects the compressed payload size when known.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
await archive.write('file.txt', 'hello');
console.log((await archive.entry('file.txt'))?.compressedSize);
await archive.close();

get mtime(): Date | null

Current entry modification time, when available.

Returns null when the archive entry has no timestamp metadata.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
await archive.write('file.txt', 'hello', { mtime: new Date() });
console.log((await archive.entry('file.txt'))?.mtime);
await archive.close();

get mode(): number | null

Current entry mode, when available.

Returns POSIX mode metadata or null. Extraction does not guarantee every archived mode bit is applied on disk.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
await archive.write('file.txt', 'hello', { mode: 0o600 });
console.log((await archive.entry('file.txt'))?.mode);
await archive.close();

async bytes(): Promise<Uint8Array>

Read this entry as bytes.

Directory entries return an empty byte array. Missing entries or closed archives throw.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
await archive.write('file.txt', new Uint8Array([1, 2]));
console.log((await archive.entry('file.txt')) && await (await archive.entry('file.txt'))!.bytes());
await archive.close();

async text(): Promise<string>

Read this entry as UTF-8 text.

Directory entries decode as an empty string. Invalid UTF-8 is handled by TextDecoder replacement behavior.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
await archive.write('README.md', 'hello');
console.log(await (await archive.entry('README.md'))!.text());
await archive.close();

async write(data: ArchiveInput, options?: ArchiveWriteOptions): Promise<void>

Replace this entry's data and metadata.

This delegates to Archive.write() using the handle's current name. Read-only or closed archives throw.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
await archive.write('file.txt', 'old');
await (await archive.entry('file.txt'))!.write('new');
await archive.close();

async remove(): Promise<void>

Remove this entry from the archive.

Removing a missing entry is a no-op when called through Archive.remove(), but this handle can throw if the archive has been closed. Changes are persisted on save() or writable close().

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
await archive.write('file.txt', 'hello');
await (await archive.entry('file.txt'))!.remove();
await archive.close();

constructor(path: string, format: ArchiveFormat, options: ArchiveOpenOptions = {})

Create an archive handle with an explicit format.

This constructor does not read or write the archive file. Prefer Archive.create() or Archive.open() for extension-based format detection and parsing.

import { Archive } from 'fino:archive';

const archive = new Archive('bundle.zip', 'zip');
await archive.close();

get path(): string

Filesystem path backing this archive.

Writable save() and close() serialize to this path. The value is the string provided to the constructor or factory.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
console.log(archive.path);
await archive.close();

get format(): ArchiveFormat

Archive format in use after extension or option detection.

The value is 'zip', 'tar', or 'tar.gz'.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.tar.gz');
console.log(archive.format);
await archive.close();

get closed(): boolean

Whether the archive handle has been closed.

Closed archives reject all operations that require an open handle. Calling close() more than once is allowed.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
await archive.close();
console.log(archive.closed);

static async create(path: string, options: ArchiveOpenOptions = {}): Promise<Archive>

Create a new empty archive handle without reading an existing file.

The archive is written when save() is called or when a dirty writable handle is closed. Existing files at path are replaced on save.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
await archive.write('README.md', 'hello');
await archive.close();

static async open(path: string, options: ArchiveOpenOptions = {}): Promise<Archive>

Open and parse an existing archive from disk.

ZIP file payloads may be loaded lazily; tar payloads are parsed from the archive bytes. Throws when the file cannot be read, the format cannot be inferred, or the archive structure is invalid.

import { Archive } from 'fino:archive';

const archive = await Archive.open('bundle.zip', { readOnly: true });
console.log(await archive.entries());
await archive.close();

async entries(): Promise<ArchiveEntryInfo[]>

List archive entries in normalized path order.

Returns metadata only; file payloads are not decoded unless already loaded. Throws if the archive is closed.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
await archive.write('README.md', 'hello');
console.log((await archive.entries())[0].name);
await archive.close();

async entry(name: string): Promise<ArchiveEntryHandle | null>

Return a handle for an entry, or null if no entry exists at that path.

The lookup name is normalized before matching, so docs/./README.md and docs/README.md refer to the same archive entry. Throws if the archive is closed.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
await archive.write('README.md', 'hello');
const entry = await archive.entry('./README.md');
console.log(entry?.size);
await archive.close();

async read(name: string): Promise<Uint8Array>

Read one file entry as bytes.

Directory entries return an empty byte array. ZIP entries compressed with unsupported methods throw when read. Missing entries and closed archives throw.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
await archive.write('data.bin', new Uint8Array([1, 2, 3]));
console.log((await archive.read('data.bin')).byteLength);
await archive.close();

async readText(name: string): Promise<string>

Read one file entry as UTF-8 text.

This decodes read(name) with TextDecoder. Directory entries decode as an empty string. Invalid UTF-8 uses replacement behavior.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
await archive.write('README.md', 'hello');
console.log(await archive.readText('README.md'));
await archive.close();

async write(name: string, data: ArchiveInput, options: ArchiveWriteOptions = {}): Promise<void>

Create or replace one archive entry.

Entry names are normalized to archive paths; empty names throw. Data may be a Uint8Array, an ArrayBuffer, or a string encoded as UTF-8. Writable archives are marked dirty and are persisted by save() or close(). Read-only and closed archives throw.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
await archive.write('README.md', '# Project\n', { mode: 0o644 });
await archive.close();

async addFile( srcPath: string, archivePath: string | null = null, options: ArchiveWriteOptions = { } ): Promise<void>

Add a host filesystem file to the archive.

Reads the entire source file into memory and stores it under archivePath or the source basename when archivePath is null. Source mtime and mode are copied unless overridden. Throws on source read/stat errors, read-only archives, or closed archives.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
await archive.addFile('dist/app.js', 'app.js');
await archive.close();

async addDirectory(srcPath: string, archivePath: string = ''): Promise<void>

Recursively add the contents of a host directory to the archive.

Directory contents are walked through the Fino filesystem APIs. Regular files are added; directories are traversed. Symlinks and special files are skipped by the current implementation. Added entries are stored under the archivePath prefix when one is provided, otherwise relative to srcPath. Throws on directory read failures or when the archive is not writable.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.tar.gz');
await archive.addDirectory('dist', 'package');
await archive.close();

async remove(name: string): Promise<void>

Remove an entry if it exists.

Missing entries are ignored. Removing an existing entry marks the archive dirty. Read-only and closed archives throw.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
await archive.write('old.txt', 'old');
await archive.remove('old.txt');
await archive.close();

async rename(oldName: string, newName: string): Promise<void>

Rename an existing entry, failing if the target name already exists.

Both names are normalized before lookup. Throws if the source is missing, the target exists, the archive is read-only, or the archive is closed.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
await archive.write('draft.txt', 'hello');
await archive.rename('draft.txt', 'README.txt');
await archive.close();

async extract(destination: string, options: ArchiveExtractOptions = {}): Promise<ExtractResult>

Extract all entries to destination.

Extraction rejects absolute archive paths and parent-directory escapes, removes pre-existing symlinks at output file paths, creates directories as needed, and counts only file entries in the result. Existing regular files are overwritten. ArchiveExtractOptions.maxEntries and maxTotalBytes add opt-in policy limits; exceeding either throws mid-extraction. Whenever extraction throws, previously written files remain on disk.

import { Archive } from 'fino:archive';

const archive = await Archive.open('bundle.zip', { readOnly: true });
const result = await archive.extract('unpacked', { maxEntries: 10_000 });
console.log(result.entries);
await archive.close();

async save(): Promise<void>

Serialize the archive to disk atomically through a temporary file.

The parent directory is created when needed. The archive is written to a unique temporary path, then renamed into place. Read-only and closed archives throw. Successful saves clear the dirty flag.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
await archive.write('README.md', 'hello');
await archive.save();
await archive.close();

async close(): Promise<void>

Save pending changes when writable, then mark the handle closed.

Calling close() more than once is allowed. Dirty writable archives are saved automatically; read-only archives are simply closed.

import { Archive } from 'fino:archive';

const archive = await Archive.create('bundle.zip');
await archive.write('README.md', 'hello');
await archive.close();