s/onentry/onReadEntry/g for clarity, deprecate old name

Author: isaacs

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 7.4
+
+- Deprecate `onentry` in favor of `onReadEntry` for clarity.
+
+## 7.3
+
+- Add `onWriteEntry` option
+
 ## 7.2
 
 - DRY the command definitions into a single `makeCommand` method,

README.md

@@ -214,7 +214,7 @@ To replicate `tar tf my-tarball.tgz`, do this:
 ```js
 tar.t({
   file: 'my-tarball.tgz',
-  onentry: entry => { .. do whatever with it .. }
+  onReadEntry: entry => { .. do whatever with it .. }
 })
 ```
 
@@ -225,7 +225,7 @@ const getEntryFilenames = async tarballFilename => {
   const filenames = []
   await tar.t({
     file: tarballFilename,
-    onentry: entry => filenames.push(entry.path),
+    onReadEntry: entry => filenames.push(entry.path),
   })
   return filenames
 }
@@ -250,7 +250,7 @@ const getEntryFilenamesSync = tarballFilename => {
   const filenames = []
   tar.t({
     file: tarballFilename,
-    onentry: entry => filenames.push(entry.path),
+    onReadEntry: entry => filenames.push(entry.path),
     sync: true,
   })
   return filenames
@@ -335,6 +335,9 @@ The following options are supported:
   [Alias: `m`, `no-mtime`]
 - `mtime` Set to a `Date` object to force a specific `mtime` for
   everything added to the archive. Overridden by `noMtime`.
+- `onWriteEntry` Called with each `WriteEntry` or
+  `WriteEntrySync` that is created in the course of writing the
+  archive.
 
 The following options are mostly internal, but can be modified in some
 advanced use cases, such as re-using caches between runs.
@@ -427,7 +430,7 @@ The following options are supported:
   the archive entry. If a falsey value is provided, then the entry is
   written to disk as normal. (To exclude items from extraction, use
   the `filter` option described above.)
-- `onentry` A function that gets called with `(entry)` for each entry
+- `onReadEntry` A function that gets called with `(entry)` for each entry
   that passes the filter.
 - `onwarn` A function that will get called with `(code, message, data)` for
   any warnings encountered. (See "Warnings and Errors")
@@ -478,7 +481,7 @@ entries, use the `tar.Parse` class instead.)
 
 If a `file` option _is_ provided, then the return value will be a promise
 that resolves when the file has been fully traversed in async mode, or
-`undefined` if `sync: true` is set. Thus, you _must_ specify an `onentry`
+`undefined` if `sync: true` is set. Thus, you _must_ specify an `onReadEntry`
 method in order to do anything useful with the data it parses.
 
 The following options are supported:
@@ -493,13 +496,13 @@ The following options are supported:
 - `filter` A function that gets called with `(path, entry)` for each
   entry being listed. Return `true` to emit the entry from the
   archive, or `false` to skip it.
-- `onentry` A function that gets called with `(entry)` for each entry
+- `onReadEntry` A function that gets called with `(entry)` for each entry
   that passes the filter. This is important for when `file` is set,
   because there is no other way to do anything useful with this method.
 - `maxReadSize` The maximum buffer size for `fs.read()` operations.
   Defaults to 16 MB.
 - `noResume` By default, `entry` streams are resumed immediately after
-  the call to `onentry`. Set `noResume: true` to suppress this
+  the call to `onReadEntry`. Set `noResume: true` to suppress this
   behavior. Note that by opting into this, the stream will never
   complete until the entry data is consumed.
 - `onwarn` A function that will get called with `(code, message, data)` for
@@ -556,6 +559,9 @@ The following options are supported:
   [Alias: `m`, `no-mtime`]
 - `mtime` Set to a `Date` object to force a specific `mtime` for
   everything added to the archive. Overridden by `noMtime`.
+- `onWriteEntry` Called with each `WriteEntry` or
+  `WriteEntrySync` that is created in the course of writing the
+  archive.
 
 ### tar.r(options, fileList, callback) [alias: tar.replace]
 
@@ -608,10 +614,13 @@ The following options are supported:
   [Alias: `m`, `no-mtime`]
 - `mtime` Set to a `Date` object to force a specific `mtime` for
   everything added to the archive. Overridden by `noMtime`.
+- `onWriteEntry` Called with each `WriteEntry` or
+  `WriteEntrySync` that is created in the course of writing the
+  archive.
 
 ## Low-Level API
 
-### class tar.Pack
+### class Pack
 
 A readable tar stream.
 
@@ -640,7 +649,6 @@ 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`.
@@ -661,6 +669,9 @@ The following options are supported:
   `tar.update` or the `keepNewer` option with the resulting tar archive.
 - `mtime` Set to a `Date` object to force a specific `mtime` for
   everything added to the archive. Overridden by `noMtime`.
+- `onWriteEntry` Called with each `WriteEntry` or
+  `WriteEntrySync` that is created in the course of writing the
+  archive.
 
 #### add(path)
 
@@ -674,11 +685,11 @@ Adds an entry to the archive. Returns true if flushed.
 
 Finishes the archive.
 
-### class tar.Pack.Sync
+### class PackSync
 
-Synchronous version of `tar.Pack`.
+Synchronous version of `Pack`.
 
-### class tar.Unpack
+### class Unpack
 
 A writable stream that unpacks a tar archive onto the file system.
 
@@ -757,7 +768,7 @@ Most unpack errors will cause a `warn` event to be emitted. If the
   written to disk as normal. (To exclude items from extraction, use
   the `filter` option described above.)
 - `strict` Treat warnings as crash-worthy errors. Default false.
-- `onentry` A function that gets called with `(entry)` for each entry
+- `onReadEntry` A function that gets called with `(entry)` for each entry
   that passes the filter.
 - `onwarn` A function that will get called with `(code, message, data)` for
   any warnings encountered. (See "Warnings and Errors")
@@ -775,9 +786,9 @@ Most unpack errors will cause a `warn` event to be emitted. If the
   warning and skip the entry. Set to `Infinity` to remove the
   limitation.
 
-### class tar.Unpack.Sync
+### class UnpackSync
 
-Synchronous version of `tar.Unpack`.
+Synchronous version of `Unpack`.
 
 Note that using an asynchronous stream type with the `transform`
 option will cause undefined behavior in sync unpack streams.
@@ -810,7 +821,7 @@ The following options are supported:
 - `filter` A function that gets called with `(path, entry)` for each
   entry being listed. Return `true` to emit the entry from the
   archive, or `false` to skip it.
-- `onentry` A function that gets called with `(entry)` for each entry
+- `onReadEntry` A function that gets called with `(entry)` for each entry
   that passes the filter.
 - `onwarn` A function that will get called with `(code, message, data)` for
   any warnings encountered. (See "Warnings and Errors")

src/create.ts

@@ -45,7 +45,7 @@ const addFilesSync = (p: PackSync, files: string[]) => {
         file: path.resolve(p.cwd, file.slice(1)),
         sync: true,
         noResume: true,
-        onentry: entry => p.add(entry),
+        onReadEntry: entry => p.add(entry),
       })
     } else {
       p.add(file)
@@ -64,7 +64,7 @@ const addFilesAsync = async (
       await list({
         file: path.resolve(String(p.cwd), file.slice(1)),
         noResume: true,
-        onentry: entry => {
+        onReadEntry: entry => {
           p.add(entry)
         },
       })

src/list.ts

@@ -11,12 +11,12 @@ import {
 import { Parser } from './parse.js'
 import { stripTrailingSlashes } from './strip-trailing-slashes.js'
 
-const onentryFunction = (opt: TarOptions) => {
-  const onentry = opt.onentry
-  opt.onentry =
-    onentry ?
+const onReadEntryFunction = (opt: TarOptions) => {
+  const onReadEntry = opt.onReadEntry
+  opt.onReadEntry =
+    onReadEntry ?
       e => {
-        onentry(e)
+        onReadEntry(e)
         e.resume()
       }
     : e => e.resume()
@@ -119,6 +119,6 @@ export const list = makeCommand(
   opt => new Parser(opt),
   (opt, files) => {
     if (files?.length) filesFilter(opt, files)
-    if (!opt.noResume) onentryFunction(opt)
+    if (!opt.noResume) onReadEntryFunction(opt)
   },
 )

src/options.ts

@@ -27,6 +27,7 @@ const argmap = new Map<keyof TarOptionsWithAliases, keyof TarOptions>(
     ['p', 'preserveOwner'],
     ['L', 'follow'],
     ['h', 'follow'],
+    ['onentry', 'onReadEntry'],
   ],
 )
 
@@ -265,7 +266,7 @@ export interface TarOptions {
 
   /**
    * When parsing/listing archives, `entry` streams are by default resumed
-   * (set into "flowing" mode) immediately after the call to `onentry()`.
+   * (set into "flowing" mode) immediately after the call to `onReadEntry()`.
    * Set `noResume: true` to suppress this behavior.
    *
    * Note that when this is set, the stream will never complete until the
@@ -279,10 +280,6 @@ export interface TarOptions {
   /**
    * When creating, updating, or replacing within archives, this method will
    * be called with each WriteEntry that is created.
-   *
-   * It's not called 'onentry' because that's already taken for the ReadEntry
-   * when reading archives, and it's just easier to only have one type of
-   * options object that this whole library can pass around without issue.
    */
   onWriteEntry?: (entry: WriteEntry) => any
 
@@ -293,7 +290,7 @@ export interface TarOptions {
    * Important when listing archives synchronously from a file, because there
    * is otherwise no way to interact with the data!
    */
-  onentry?: (entry: ReadEntry) => any
+  onReadEntry?: (entry: ReadEntry) => any
 
   /**
    * Pack the targets of symbolic links rather than the link itself.
@@ -477,6 +474,13 @@ export interface TarOptions {
    * Forcibly trigger a chown on every entry, no matter what.
    */
   forceChown?: boolean
+
+  /**
+   * ambiguous deprecated name for {@link onReadEntry}
+   *
+   * @deprecated
+   */
+  onentry?: (entry: ReadEntry) => any
 }
 
 export type TarOptionsSync = TarOptions & { sync: true }

src/parse.ts

@@ -147,8 +147,8 @@ export class Parser extends EE implements Warner {
     if (typeof opt.onwarn === 'function') {
       this.on('warn', opt.onwarn)
     }
-    if (typeof opt.onentry === 'function') {
-      this.on('entry', opt.onentry)
+    if (typeof opt.onReadEntry === 'function') {
+      this.on('entry', opt.onReadEntry)
     }
   }
 

src/replace.ts

@@ -239,7 +239,7 @@ const addFilesSync = (p: Pack, files: string[]) => {
         file: path.resolve(p.cwd, file.slice(1)),
         sync: true,
         noResume: true,
-        onentry: entry => p.add(entry),
+        onReadEntry: entry => p.add(entry),
       })
     } else {
       p.add(file)
@@ -258,7 +258,7 @@ const addFilesAsync = async (
       await list({
         file: path.resolve(String(p.cwd), file.slice(1)),
         noResume: true,
-        onentry: entry => p.add(entry),
+        onReadEntry: entry => p.add(entry),
       })
     } else {
       p.add(file)

test/create.ts

@@ -241,7 +241,7 @@ t.test('create tarball out of another tarball', t => {
     list({
       f: out,
       sync: true,
-      onentry: entry => {
+      onReadEntry: entry => {
         if (entry.path === 'hardlink-2') {
           t.equal(entry.type, 'Link')
         } else if (entry.path === 'symlink') {