Tiny and fast Tar utils for any JavaScript runtime!
npm install nanotar[![npm version][npm-version-src]][npm-version-href]
[![bundle][bundle-src]][bundle-href]
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
Install package:
``shnpm
npm install nanotar
Import:
`js
// 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 directoriesExample:
`ts
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
`$3
You can optionally use
createTarGzip or createTarGzipStream to create a compressed tar data stream (returned value is a Promise or ReadableStream piped to CompressionStream)`js
import { createTarGzip, createTarGzipStream } from "nanotar";createTarGzip([]); // Promise
createTarGzipStream([]); // ReadableStream
`Parsing a tar archive
Easily parse a tar archive using
parseTar utility.Example:
`ts
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:`ts
const files = parseTar(data, {
filter: (file) => file.name.starsWith("dir/"),
});
`Additionally, you can use
metaOnly option to skip reading file data and listing purposes:`ts
const fileMetas = parseTar(data, {
metaOnly: true,
});
`$3
If input is compressed, you can use
parseTarGzip utility instead to parse it (it used DecompressionStream internally and return a Promise value)`js
import { parseTarGzip } from "nanotar";parseTarGzip(data); // Promise
`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`Made with š
Inspired by ankitrohatgi/tarballjs
Published under the MIT License.
[npm-version-src]: https://img.shields.io/npm/v/nanotar?style=flat&colorA=18181B&colorB=F0DB4F
[npm-version-href]: https://npmjs.com/package/nanotar
[npm-downloads-src]: https://img.shields.io/npm/dm/nanotar?style=flat&colorA=18181B&colorB=F0DB4F
[npm-downloads-href]: https://npmjs.com/package/nanotar
[codecov-src]: https://img.shields.io/codecov/c/gh/unjs/nanotar/main?style=flat&colorA=18181B&colorB=F0DB4F
[codecov-href]: https://codecov.io/gh/unjs/nanotar
[bundle-src]: https://img.shields.io/bundlephobia/minzip/nanotar?style=flat&colorA=18181B&colorB=F0DB4F
[bundle-href]: https://bundlephobia.com/result?p=nanotar