initial commit

.editorconfig

@@ -0,0 +1,15 @@
+root = true
+
+[*]
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+charset = utf-8
+
+[*.js]
+indent_style = space
+indent_size = 2
+
+[{package.json,*.yml,*.cjson}]
+indent_style = space
+indent_size = 2

.eslintignore

@@ -0,0 +1,3 @@
+node_modules
+coverage
+dist

.eslintrc

@@ -0,0 +1,7 @@
+{
+  "extends": ["eslint-config-unjs"],
+  "rules": {
+    "@typescript-eslint/no-non-null-assertion": 0,
+    "unicorn/prefer-top-level-await": 0
+  }
+}

.github/workflows/autofix.yml

@@ -0,0 +1,26 @@
+name: autofix.ci # needed to securely identify the workflow
+
+on:
+  pull_request:
+  push:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+jobs:
+  autofix:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: corepack enable
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: "pnpm"
+      - run: pnpm install
+      - name: Fix lint issues
+        run: pnpm run lint:fix
+      - uses: autofix-ci/action@bee19d72e71787c12ca0f29de72f2833e437e4c9
+        with:
+          commit-message: "chore: apply automated fixes"

.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: ci
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: corepack enable
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 18
+          cache: "pnpm"
+      - run: pnpm install
+      - run: pnpm lint
+      - run: pnpm test:types
+      - run: pnpm build
+      - run: pnpm vitest --coverage
+      - uses: codecov/codecov-action@v3

.gitignore

@@ -0,0 +1,8 @@
+node_modules
+coverage
+dist
+.vscode
+.DS_Store
+.eslintcache
+*.log*
+*.env*

.prettierrc

@@ -0,0 +1 @@
+{}

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Pooya Parsa <[email protected]>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,143 @@
+# 📼 mircrotar
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![bundle][bundle-src]][bundle-href]
+[![Codecov][codecov-src]][codecov-href]
+
+Tiny and fast [Tar](<https://en.wikipedia.org/wiki/Tar_(computing)>) utils for any JavaScript runtime!
+
+- 🌳 Tiny (less than 2KB gzip) and tree-shakable
+- ✨ Written in modern TypeScript and ESM format
+- ✅ Works in any JavaScript runtime Node.js (18+), Bun, Deno, Browsers and Edge Workers
+- 🌐 Web Standard Compatible
+
+## Installation
+
+Install package:
+
+```sh
+# npm
+npm install mircrotar
+
+# yarn
+yarn add mircrotar
+
+# pnpm
+pnpm install mircrotar
+
+# bun
+bun install mircrotar
+```
+
+Import:
+
+```js
+// ESM
+import { parseTar, createTar } from "mircrotar";
+
+// CommonJS
+const { parseTar, createTar } = require("mircrotar");
+```
+
+## Creating a tar archive
+
+Easily create a new tar archive using `createTar` utility.
+
+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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String), [`ArrayBuffer`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer) or [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array).
+- `attrs` field is optional for file attributes.
+
+Second argument is for archive options. You can use `attrs` to set default attributes for all files (can be still overriden per file).
+
+Possible attributes are:
+
+- `mtime`: Last modification time. Default is `Date.now()`
+- `uid`: Owner user id. Default is `1000`
+- `gid`: Owner group id. Default is `1000`
+- `user`: Owner user name. Default is `""`
+- `grouop`: Owner user group. Default is `""`
+- `mode`: file mode (permissions). Default is `664` (`-rw-rw-r--`) for files and `775` (`-rwxrwxr-x`) for directories
+
+**Example:**
+
+```ts
+import { createTar } from "mircrotar";
+
+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
+```
+
+## Parsing a tar archive
+
+Easily parse a tar archive using `parseTar` utility.
+
+**Example:**
+
+```ts
+import { parseTar } from "mircrotar";
+
+// 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` which is file size and `text` which is a lazy getter that decodes `data` view as string.
+
+## Development
+
+- Clone this repository
+- Install latest LTS version of [Node.js](https://nodejs.org/en/)
+- Enable [Corepack](https://github.com/nodejs/corepack) using `corepack enable`
+- Install dependencies using `pnpm install`
+- Run interactive tests using `pnpm dev`
+
+## License
+
+Made with 💛
+
+Inspired by [ankitrohatgi/tarballjs](https://github.com/ankitrohatgi/tarballjs)
+
+Published under [MIT License](./LICENSE).
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/mircrotar?style=flat&colorA=18181B&colorB=F0DB4F
+[npm-version-href]: https://npmjs.com/package/mircrotar
+[npm-downloads-src]: https://img.shields.io/npm/dm/mircrotar?style=flat&colorA=18181B&colorB=F0DB4F
+[npm-downloads-href]: https://npmjs.com/package/mircrotar
+[codecov-src]: https://img.shields.io/codecov/c/gh/unjs/mircrotar/main?style=flat&colorA=18181B&colorB=F0DB4F
+[codecov-href]: https://codecov.io/gh/unjs/mircrotar
+[bundle-src]: https://img.shields.io/bundlephobia/minzip/mircrotar?style=flat&colorA=18181B&colorB=F0DB4F
+[bundle-href]: https://bundlephobia.com/result?p=mircrotar

build.config.ts

@@ -0,0 +1,3 @@
+import { defineBuildConfig } from "unbuild";
+
+export default defineBuildConfig({});

package.json

@@ -0,0 +1,46 @@
+{
+  "name": "mircrotar",
+  "version": "0.1.0",
+  "description": "Tiny and fast Tar utils for any JavaScript runtime!",
+  "repository": "unjs/mircrotar",
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "unbuild",
+    "dev": "vitest dev",
+    "play": "jiti playground",
+    "lint": "eslint --cache --ext .ts,.js,.mjs,.cjs . && prettier -c src test",
+    "lint:fix": "eslint --cache --ext .ts,.js,.mjs,.cjs . --fix && prettier -c src test -w",
+    "prepack": "pnpm run build",
+    "release": "pnpm test && changelogen --release && npm publish && git push --follow-tags",
+    "test": "pnpm lint && pnpm test:types && vitest run --coverage",
+    "test:types": "tsc --noEmit --skipLibCheck"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.3",
+    "@vitest/coverage-v8": "^1.0.1",
+    "changelogen": "^0.5.5",
+    "eslint": "^8.55.0",
+    "eslint-config-unjs": "^0.2.1",
+    "jiti": "^1.21.0",
+    "prettier": "^3.1.0",
+    "typescript": "^5.3.2",
+    "unbuild": "^2.0.0",
+    "vitest": "^1.0.1"
+  },
+  "packageManager": "[email protected]"
+}

playground/index.ts

@@ -0,0 +1,14 @@
+import { execSync } from 'node:child_process'
+import { parseTar, createTar } from '../src'
+
+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" } }
+)
+
+console.log(execSync("tar -tvf-", { input: data }).toString())
+
+console.log(parseTar(data))