v7: Port to TypeScript, provide hybrid cjs/esm interface

.github/workflows/ci.yml

@@ -6,7 +6,7 @@ jobs:
   build:
     strategy:
       matrix:
-        node-version: [16.x, 18.x, 20.x]
+        node-version: [18.x, 20.x, 21.x]
         platform:
         - os: ubuntu-latest
           shell: bash
@@ -21,15 +21,15 @@ jobs:
 
     steps:
       - name: Checkout Repository
-        uses: actions/checkout@v1.1.0
+        uses: actions/checkout@v4
 
       - name: Use Nodejs ${{ matrix.node-version }}
-        uses: actions/setup-node@v1
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
 
       - name: Install dependencies
         run: npm install
 
       - name: Run Tests
-        run: npm test -- -c -t0
+        run: npm test -- -c

.github/workflows/typedoc.yml

@@ -0,0 +1,50 @@
+# Simple workflow for deploying static content to GitHub Pages
+name: Deploy static content to Pages
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  # Single deploy job since we're just deploying
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+      - name: Use Nodejs ${{ matrix.node-version }}
+        uses: actions/setup-node@v3
+        with:
+          node-version: 18.x
+      - name: Install dependencies
+        run: npm install
+      - name: Generate typedocs
+        run: npm run typedoc
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v3
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v1
+        with:
+          path: './docs'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1

.gitignore

@@ -5,6 +5,7 @@
 
 # keep these
 !**/.gitignore
+!/src
 !/.commitlintrc.js
 !/.eslintrc.js
 !/.eslintrc.local.*
@@ -15,7 +16,6 @@
 !/bin/
 !/CHANGELOG*
 !/CODE_OF_CONDUCT.md
-!/docs/
 !/index.js
 !/lib/
 !/LICENSE*

CHANGELOG.md

@@ -1,43 +1,51 @@
 # Changelog
 
-## 6.2
-
-* Add support for brotli compression
-
-## [6.1.13](https://github.com/npm/node-tar/compare/v6.1.12...v6.1.13) (2022-12-07)
-
-### Dependencies
+## 7.0
+
+- Rewrite in TypeScript, provide ESM and CommonJS hybrid
+  interface
+- Add tree-shake friendly exports, like `import('tar/create')`
+  and `import('tar/read-entry')` to get individual functions or
+  classes.
+- Add `chmod` option that defaults to false, and deprecate
+  `noChmod`. That is, reverse the default option regarding
+  explicitly setting file system modes to match tar entry
+  settings.
+- Add `processUmask` option to avoid having to call
+  `process.umask()` when `chmod: true` (or `noChmod: false`) is
+  set.
 
-* [`cc4e0dd`](https://github.com/npm/node-tar/commit/cc4e0ddfe523a0bce383846a67442c637a65d486) [#343](https://github.com/npm/node-tar/pull/343) bump minipass from 3.3.6 to 4.0.0
-
-## [6.1.12](https://github.com/npm/node-tar/compare/v6.1.11...v6.1.12) (2022-10-31)
-
-### Bug Fixes
+## 6.2
 
-* [`57493ee`](https://github.com/npm/node-tar/commit/57493ee66ece50d62114e02914282fc37be3a91a) [#332](https://github.com/npm/node-tar/pull/332) ensuring close event is emited after stream has ended (@webark)
-* [`b003c64`](https://github.com/npm/node-tar/commit/b003c64f624332e24e19b30dc011069bb6708680) [#314](https://github.com/npm/node-tar/pull/314) replace deprecated String.prototype.substr() (#314) (@CommanderRoot, @lukekarrys)
+- Add support for brotli compression
+- Add `maxDepth` option to prevent extraction into excessively
+  deep folders.
 
-### Documentation
+## 6.1
 
-* [`f129929`](https://github.com/npm/node-tar/commit/f12992932f171ea248b27fad95e7d489a56d31ed) [#313](https://github.com/npm/node-tar/pull/313) remove dead link to benchmarks (#313) (@yetzt)
-* [`c1faa9f`](https://github.com/npm/node-tar/commit/c1faa9f44001dfb0bc7638b2850eb6058bd56a4a) add examples/explanation of using tar.t (@isaacs)
+- remove dead link to benchmarks (#313) (@yetzt)
+- add examples/explanation of using tar.t (@isaacs)
+- ensure close event is emited after stream has ended (@webark)
+- replace deprecated String.prototype.substr() (@CommanderRoot,
+  @lukekarrys)
 
 ## 6.0
 
 - Drop support for node 6 and 8
-- fix symlinks and hardlinks on windows being packed with `\`-style path
-  targets
+- fix symlinks and hardlinks on windows being packed with
+  `\`-style path targets
 
 ## 5.0
 
 - Address unpack race conditions using path reservations
 - Change large-numbers errors from TypeError to Error
 - Add `TAR_*` error codes
-- Raise `TAR_BAD_ARCHIVE` warning/error when there are no valid entries
-  found in an archive
+- Raise `TAR_BAD_ARCHIVE` warning/error when there are no valid
+  entries found in an archive
 - do not treat ignored entries as an invalid archive
 - drop support for node v4
-- unpack: conditionally use a file mapping to write files on Windows
+- unpack: conditionally use a file mapping to write files on
+  Windows
 - Set more portable 'mode' value in portable mode
 - Set `portable` gzip option in portable mode
 
@@ -69,8 +77,8 @@
 
 ## 3.1
 
-- Support `@file.tar` as an entry argument to copy entries from one tar
-  file to another.
+- Support `@file.tar` as an entry argument to copy entries from
+  one tar file to another.
 - Add `noPax` option
 - `noResume` option for tar.t
 - win32: convert `>|<?:` chars to windows-friendly form
@@ -79,12 +87,13 @@
 ## 3.0
 
 - Minipass-based implementation
-- Entirely new API surface, `tar.c()`, `tar.x()` etc., much closer to
-  system tar semantics
+- Entirely new API surface, `tar.c()`, `tar.x()` etc., much
+  closer to system tar semantics
 - Massive performance improvement
 - Require node 4.x and higher
 
 ## 0.x, 1.x, 2.x - 2011-2014
 
 - fstream-based implementation
-- slow and kinda bad, but better than npm shelling out to the system `tar`
+- slow and kinda bad, but better than npm shelling out to the
+  system `tar`

README.md

@@ -156,12 +156,13 @@ to see how tar is handling the issue.
 The API mimics the `tar(1)` command line functionality, with aliases
 for more human-readable option and function names.  The goal is that
 if you know how to use `tar(1)` in Unix, then you know how to use
-`require('tar')` in JavaScript.
+`import('tar')` in JavaScript.
 
 To replicate `tar czf my-tarball.tgz files and folders`, you'd do:
 
 ```js
-tar.c(
+import { create } from 'tar'
+create(
   {
     gzip: <true|gzip options>,
     file: 'my-tarball.tgz'
@@ -173,9 +174,12 @@ tar.c(
 To replicate `tar cz files and folders > my-tarball.tgz`, you'd do:
 
 ```js
-tar.c( // or tar.create
+// if you're familiar with the tar(1) cli flags, this can be nice
+import * as tar from 'tar'
+tar.c(
   {
-    gzip: <true|gzip options>
+    // 'z' is alias for 'gzip' option
+    z: <true|gzip options>
   },
   ['some', 'files', 'and', 'folders']
 ).pipe(fs.createWriteStream('my-tarball.tgz'))
@@ -184,9 +188,10 @@ tar.c( // or tar.create
 To replicate `tar xf my-tarball.tgz` you'd do:
 
 ```js
-tar.x(  // or tar.extract(
+tar.x( // or `tar.extract`
   {
-    file: 'my-tarball.tgz'
+    // or `file:`
+    f: 'my-tarball.tgz'
   }
 ).then(_=> { .. tarball has been dumped in cwd .. })
 ```
@@ -424,11 +429,15 @@ The following options are supported:
   that passes the filter.
 - `onwarn` A function that will get called with `(code, message, data)` for
   any warnings encountered.  (See "Warnings and Errors")
-- `noChmod` Set to true to omit calling `fs.chmod()` to ensure that the
-  extracted file matches the entry mode.  This also suppresses the call to
-  `process.umask()` to determine the default umask value, since tar will
-  extract with whatever mode is provided, and let the process `umask` apply
-  normally.
+- `chmod` Set to true to call `fs.chmod()` to ensure that the
+  extracted file matches the entry mode.  This may necessitate a
+  call to the deprecated and thread-unsafe `process.umask()`
+  method to determine the default umask value, unless a
+  `processUmask` options is also provided. Otherwise tar will
+  extract with whatever mode is provided, and let the process
+  `umask` apply normally.
+- `processUmask` Set to an explicit numeric value to avoid
+  calling `process.umask()` when `chmod: true` is set.
 - `maxDepth` The maximum depth of subfolders to extract into. This
   defaults to 1024. Anything deeper than the limit will raise a
   warning and skip the entry. Set to `Infinity` to remove the
@@ -630,6 +639,7 @@ The following options are supported:
   default" for most unix systems, based on a `umask` value of `0o22`.
 - `preservePaths` Allow absolute paths.  By default, `/` is stripped
   from absolute paths.
+
 - `linkCache` A Map object containing the device and inode value for
   any file whose nlink is > 1, to identify hard links.
 - `statCache` A Map object that caches calls `lstat`.
@@ -750,11 +760,15 @@ Most unpack errors will cause a `warn` event to be emitted.  If the
   that passes the filter.
 - `onwarn` A function that will get called with `(code, message, data)` for
   any warnings encountered.  (See "Warnings and Errors")
-- `noChmod` Set to true to omit calling `fs.chmod()` to ensure that the
-  extracted file matches the entry mode.  This also suppresses the call to
-  `process.umask()` to determine the default umask value, since tar will
-  extract with whatever mode is provided, and let the process `umask` apply
-  normally.
+- `chmod` Set to true to call `fs.chmod()` to ensure that the
+  extracted file matches the entry mode.  This may necessitate a
+  call to the deprecated and thread-unsafe `process.umask()`
+  method to determine the default umask value, unless a
+  `processUmask` options is also provided. Otherwise tar will
+  extract with whatever mode is provided, and let the process
+  `umask` apply normally.
+- `processUmask` Set to an explicit numeric value to avoid
+  calling `process.umask()` when `chmod: true` is set.
 - `maxDepth` The maximum depth of subfolders to extract into. This
   defaults to 1024. Anything deeper than the limit will raise a
   warning and skip the entry. Set to `Infinity` to remove the