nanotar

library0.3.0jsnpmunverified

nanotar is a compact and efficient utility library designed for creating and parsing Tar archives across various JavaScript environments, including Node.js, browsers, and edge runtimes. It prioritizes performance and a minimal footprint, making it suitable for resource-constrained applications. The current stable version is 0.3.0, with releases occurring as needed for enhancements and fixes, as demonstrated by recent updates to 0.2.0 and 0.3.0. A key differentiator is its universal JavaScript runtime compatibility and the inclusion of TypeScript types, ensuring robust development. It offers core functionalities for both generating `.tar` files and extracting their contents, supporting common Tar specifications. Unlike some alternatives, it aims to be dependency-free and focuses purely on the Tar format without additional compression (like gzip) built-in, allowing users to combine it with other compression libraries as needed.

serialization

npm install nanotar

github ↗package ↗

INSTALL

IMPORT

SIG · NANOTAR

nanotar

serializationjavascriptv0.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createTar

✓ import { createTar } from 'nanotar'

✗ const { createTar } = require('nanotar')

nanotar is primarily an ESM-first package. Use named imports for `createTar`.

parseTar

✓ import { parseTar } from 'nanotar'

✗ import parseTar from 'nanotar'

Both `createTar` and `parseTar` are named exports. Do not attempt a default import.

TarFileItem

✓ import type { TarFileItem } from 'nanotar'

✗ import { TarFileItem } from 'nanotar'

Import types using `import type` for clarity and to avoid bundling type-only declarations.

Demonstrates how to create a Tar archive from an array of files and then parse its contents back into individual items, showing basic file and folder handling.

import { createTar, parseTar } from 'nanotar'; async function main() { const files = [ { name: 'file1.txt', data: new TextEncoder().encode('Hello, nanotar!') }, { name: 'folder/file2.json', data: new TextEncoder().encode('{"key": "value"}') } ]; // Create a tar archive const tarBuffer = await createTar(files); console.log('Created tar archive with size:', tarBuffer.byteLength, 'bytes'); // Simulate writing to disk and reading back (e.g., using Node.js fs) // For browser/edge, this would be a Blob or similar. // Example: fs.writeFileSync('archive.tar', Buffer.from(tarBuffer)); // const readTarBuffer = new Uint8Array(fs.readFileSync('archive.tar')); // Parse the tar archive const parsedItems = []; for await (const item of parseTar(tarBuffer)) { parsedItems.push(item); console.log(`Parsed item: ${item.name} (type: ${item.type}, size: ${item.size})`); if (item.data) { console.log(' Content:', new TextDecoder().decode(item.data)); } } console.log('Total items parsed:', parsedItems.length); } main().catch(console.error);

Debug

Known issues

breakingThe `parseTar` function in v0.3.0 now supports extended item types and headers. While an enhancement, this may alter the structure or available metadata of `TarFileItem` objects for complex archives, potentially affecting existing parsing logic that expects only basic tar headers.

fix

Review any code that consumes `parseTar` output, especially for archives using extended headers or less common file types, and adapt to potentially richer item metadata or type handling.

affects: >=0.3.0

gotchaStarting with v0.3.0, paths are sanitized when creating and parsing tar archives. This is a security improvement (fixing path traversal vulnerabilities) but might change the exact string of file paths if your application relied on specific, potentially unsafe, path representations.

fix

Ensure your application does not rely on unsanitized path formats from tar archives. Validate paths after parsing if your application has specific requirements beyond what `nanotar`'s sanitization provides.

affects: >=0.3.0

gotchaThe `parseTar` function in v0.2.0 introduced `filter` and `metaOnly` options. If upgrading from pre-0.2.0 versions and custom parsing logic was in place, these new options might provide more efficient ways to handle specific parsing needs, but could also subtly change behavior if not understood.

fix

Consider migrating custom filtering/metadata extraction logic to utilize the built-in `filter` and `metaOnly` options for potentially improved performance and clarity.

affects: >=0.2.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'byteLength') or 'Invalid tar header'

Attempting to parse an input that is not a valid `Uint8Array` or a malformed tar archive. This can happen if the input is `null`, `undefined`, a `string`, or an invalid buffer type.

fix

Ensure the input to `parseTar` is a `Uint8Array` instance representing a valid tar archive. Verify file reading or network fetching produces the correct binary data.

ReferenceError: Buffer is not defined

Attempting to use `Buffer` objects in a non-Node.js environment (e.g., browser or Edge runtime) without a polyfill. `nanotar` expects `Uint8Array` for universal compatibility.

fix

Convert `Buffer` instances to `Uint8Array` before passing them to `createTar` or `parseTar` (e.g., `new Uint8Array(buffer)`). Ensure all binary data is handled as `Uint8Array`.

Upgrade

Version history

0.3.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/unjs/nanotar ↗

packagehttps://www.npmjs.com/package/nanotar ↗