📼 nanotar

Tiny and fast tar utils for any JavaScript runtime!

🌳 Tiny (~1KB minified + gzipped with all utils) and tree-shakable!

✨ Written with modern TypeScript and ESM format

✅ Works in any JavaScript runtime Node.js (18+), Bun, Deno, Browsers, and Edge Workers

🌐 Web Standard Compatible

🗜️ Built-in compression and decompression support

Installation

Install package:

# npm
npm install nanotar

# yarn
yarn add nanotar

# pnpm
pnpm install nanotar

# bun
bun install nanotar

Import:

// ESM
import { createTar, createTarGzip, createTarGzipStream, parseTar, parseTarGzip } from "nanotar";

// CommonJS
const { createTar } = require("nanotar");

Creating a tar archive

Easily create a new tar archive using the createTar utility.

The first argument is an array of files to archive:

• name field is required and you can use / to specify files within sub-directories.
• data field is optional for directories and can be either a String, ArrayBuffer or Uint8Array.
• attrs field is optional for file attributes.

The second argument is for archive options. You can use attrs to set default attributes for all files (can still be overridden per file).

Possible attributes are:

• mtime: Last modification time. The default is Date.now()
• uid: Owner user id. The default is 1000
• gid: Owner group id. The default is 1000
• user: Owner user name. The default is ""
• group: Owner user group. The default is ""
• mode: file mode (permissions). Default is 664 (-rw-rw-r--) for files and 775 (-rwxrwxr-x) for directories

Example:

import { createTar } from "nanotar";

const data = createTar(
  [
    { name: "README.md", data: "# Hello World!" },
    { name: "test", attrs: { mode: "777", mtime: 0 } },
    { name: "src/index.js", data: "console.log('wow!')" },
  ],
  { attrs: { user: "js", group: "js" } },
);

// Data is a Uint8Array view you can send or write to a file

Compression

You can optionally use createTarGzip or createTarGzipStream to create a compressed tar data stream (returned value is a Promise<Uint8Array> or ReadableStream piped to CompressionStream)

import { createTarGzip, createTarGzipStream } from "nanotar";

createTarGzip([]); // Promise<Uint8Array>

createTarGzipStream([]); // ReadableStream

Parsing a tar archive

Easily parse a tar archive using parseTar utility.

Example:

import { parseTar } from "nanotar";

// Read tar data from file or other sources into an ArrayBuffer or Uint8Array

const files = parseTar(data);

/**
[
  {
    "type": "file",
    "name": "hello.txt",
    "size": 12,
    "data": Uint8Array [ ... ],
    "text": "Hello World!",
    "attrs": {
      "gid": 1750,
      "group": "",
      "mode": "0000664",
      "mtime": 1702076997,
      "uid": 1750,
      "user": "root",
    },
  },
  ...
]
 */

Parsed files array has two additional properties: size file size and text, a lazy getter that decodes data view as a string.

You can filter iterms to read using filter option:

const files = parseTar(data, {
  filter: (file) => file.name.starsWith("dir/"),
});

Additionally, you can use metaOnly option to skip reading file data and listing purposes:

const fileMetas = parseTar(data, {
  metaOnly: true,
});

Decompression

If input is compressed, you can use parseTarGzip utility instead to parse it (it used DecompressionStream internally and return a Promise<Uint8Array> value)

import { parseTarGzip } from "nanotar";

parseTarGzip(data); // Promise<Uint8Array>

Development

• Clone this repository
• Install the latest LTS version of Node.js
• Enable Corepack using corepack enable
• Install dependencies using pnpm install
• Run interactive tests using pnpm dev

License

Made with 💛

Inspired by ankitrohatgi/tarballjs

Published under the MIT License.