nanotar Tar Utilities

0.3.0 · active · verified Sun Apr 19

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.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'byteLength') or 'Invalid tar header'
```
cause 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
```
cause 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`.

Warnings

breaking The `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.
gotcha Starting 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.
gotcha The `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.

Install

npm install nanotar npm
yarn add nanotar yarn
pnpm add nanotar pnpm

Imports

createTar
wrong:
```
const { createTar } = require('nanotar')
```
correct:
```
import { createTar } from 'nanotar'
```
nanotar is primarily an ESM-first package. Use named imports for `createTar`.
parseTar
wrong:
```
import parseTar from 'nanotar'
```
correct:
```
import { parseTar } from 'nanotar'
```
Both `createTar` and `parseTar` are named exports. Do not attempt a default import.
TarFileItem
wrong:
```
import { TarFileItem } from 'nanotar'
```
correct:
```
import type { TarFileItem } from 'nanotar'
```
Import types using `import type` for clarity and to avoid bundling type-only declarations.

Quickstart

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);

view raw JSON →