archiver-node 8.0.6 → 8.0.8

package/README.md

@@ -34,13 +34,15 @@ archive.includeFile("/path/to/file4.txt", "file4.txt")
 // Add a directory from disk.
 archive.includeDirectory("/path/to/directory", "directory")
 
-// Add a directory from disk, putting its contents at the root of archive.
+// Add a directory from disk, putting its contents at the root of archive,
+// i.e. without creating a sub-directory.
 archive.includeDirectory("/path/to/directory")
 
-// Add all files matching a "glob" pattern.
+// Add all files that match a "glob" pattern relative to a certain directory.
 archive.includeFilesByMatch("/path/to/directory", "file*.txt")
 
-// Finalize the archive, i.e. we are done adding files to it.
+// Finalize the archive, i.e. nothing else will be added to it.
+// It will start writing the archive data from this point.
 const archiveDataStream = archive.write()
 
 // Pipe the archive data to an output stream.
@@ -66,7 +68,7 @@ const archive = new ZipArchive({
   zlib: { level: 9 }
 })
 
-// catch "non-critical" errors
+// Catch "non-critical" errors.
 archive.on("warning", (error) => {
   if (error.code === "ENOENT") {
     console.warn(error)
@@ -75,37 +77,44 @@ archive.on("warning", (error) => {
   }
 })
 
-// catch errors
+// Catch errors.
 archive.on("error", (error) => {
   throw error
 })
 
-// pipe archive data to the file
+// Pipe the archive data to an output stream.
+// The archive data will start being written as soon as `.finalize()` is called.
 archive.pipe(fs.createWriteStream("/path/to/archive.zip"))
 
-// append a file from stream
+// Add a file from stream.
 archive.append(fs.createReadStream("/path/to/file1.txt"), { name: "file1.txt" })
 
-// append a file from string
+// Add a file from string.
 archive.append("some text", { name: "file2.txt" })
 
-// append a file from buffer
+// Add a file from buffer.
 archive.append(Buffer.from(...);, { name: "file3.txt" })
 
-// append a file
+// Add a file from disk.
 archive.file("/path/to/file4.txt", { name: "file4.txt" })
 
-// append files from a sub-directory and naming it `new-subdir` within the archive
+// Add a directory from disk.
 archive.directory("/path/to/directory", "directory")
 
-// append files from a sub-directory, putting its contents at the root of archive
+// Add a directory from disk, putting its contents at the root of archive,
+// i.e. without creating a sub-directory.
 archive.directory("/path/to/directory", false)
 
-// append files from a glob pattern
+// Add all files that match a "glob" pattern relative to a certain directory.
 archive.glob("file*.txt", { cwd: "/path/to/directory" })
 
-// finalize the archive (ie we are done appending files but streams have to finish yet)
-// 'close', 'end' or 'finish' may be fired right after calling this method so register to them beforehand
+// Finalize the archive, i.e. nothing else will be added to it.
+// It will start writing the archive data from this point.
+//
+// "close", "end" or "finish" events may start being emitted on the `archive` instance
+// or the output stream right after calling this method, so add any required event listeners
+// on any of those streams beforehand.
+//
 archive.finalize()
 ```
 
@@ -118,14 +127,15 @@ class NewTypeOfArchive extends Archiver {
   constructor(options) {
     super(options)
     this._format = "new-type-of-archive"
-    this._module = new NewTypeOfArchiveImplementation(options)
+    this._module = new NewTypeOfArchiveModule(options)
     this._supportsDirectory = true
     this._supportsSymlink = true
     this._modulePipe()
   }
 }
 
-class NewTypeOfArchiveImplementation {
+// See TypeScript definition of `Module` class.
+class NewTypeOfArchiveModule {
   constructor(options) { ... }
   append(source, data, callback) { ... }
   finalize() { ... }

package/index.d.ts

@@ -28,12 +28,13 @@ interface EntryData {
 	stats?: fs.Stats | undefined;
 }
 
-interface ZipEntryData extends EntryData {
+interface ZipEntryData {
 	/** Sets the compression method to STORE */
 	store?: boolean | undefined;
 }
 
-type TarEntryData = EntryData;
+interface TarEntryData {}
+interface JsonEntryData {}
 
 interface ProgressData {
 	entries: {
@@ -49,7 +50,7 @@ interface ProgressData {
 /** A function that lets you either opt out of including an entry (by returning false), or modify the contents of an entry as it is added (by returning an EntryData) */
 type EntryDataFunction = (entry: EntryData) => false | EntryData;
 
-class ArchiverError extends Error {
+declare class ArchiverError extends Error {
 	code: string; // Since archiver format support is modular, we cannot enumerate all possible error codes, as the modules can throw arbitrary ones.
 	data: any;
 	path?: any;
@@ -88,22 +89,48 @@ interface TarOptions {
 	gzipOptions?: ZlibOptions | undefined;
 }
 
-export class Archiver extends stream.Transform {
+interface JsonOptions {}
+
+declare class Module<Options, AdditionalEntryData> {
+  constructor(options?: Options);
+
+  append(
+		source: Buffer | stream.Readable,
+		data: EntryData & AdditionalEntryData,
+		// If there's an `error` argument, it doesn't pass the `data` argument.
+		// Otherwise, when `error` argument is `null`, it does pass the `same `data` argument
+		// that was passed when calling the `append()` function, with potential modifications to it
+		// such as setting the values of some of its properties.
+		callback: (error: Error | null, data?: EntryData & AdditionalEntryData) => void
+	): void;
+
+  on(event: "end", listener: () => void): void;
+  on(event: "error", listener: (error: Error) => void): void;
+
+  finalize(): void;
+  pipe(): void;
+  unpipe(): void;
+}
+
+export class Archiver<
+	ModuleOptions extends Record<string, any>,
+	AdditionalEntryData extends Record<string, any>
+> extends stream.Transform {
 	_format: string;
-	_module: Module;
+	_module: Module<ModuleOptions, AdditionalEntryData>;
 	_supportsDirectory: boolean;
 	_supportsSymlink: boolean;
 	_modulePipe: () => void;
 
-	constructor(options?: ArchiverOptions);
+	constructor(options?: ArchiverOptions & ModuleOptions);
 
 	abort(): this;
-	append(source: stream.Readable | Buffer | string, data?: EntryData | ZipEntryData | TarEntryData): this;
+	append(source: stream.Readable | Buffer | string, data?: EntryData & AdditionalEntryData): this;
 
 	/** if false is passed for destpath, the path of a chunk of data in the archive is set to the root */
-	directory(dirpath: string, destpath: false | string, data?: Partial<EntryData> | EntryDataFunction): this;
-	file(filename: string, data: EntryData): this;
-	glob(pattern: string, options?: GlobOptions, data?: Partial<EntryData>): this;
+	directory(dirpath: string, destpath: false | string, data?: Partial<EntryData & AdditionalEntryData> | EntryDataFunction): this;
+	file(filename: string, data: EntryData & AdditionalEntryData): this;
+	glob(pattern: string, options?: GlobOptions, data?: Partial<EntryData & AdditionalEntryData>): this;
 	finalize(): Promise<void>;
 
 	setFormat(format: string): this;
@@ -121,18 +148,10 @@ export class Archiver extends stream.Transform {
 	on(event: "progress", listener: (progress: ProgressData) => void): this;
 	on(event: "close" | "drain" | "finish", listener: () => void): this;
 	on(event: "pipe" | "unpipe", listener: (src: stream.Readable) => void): this;
-	on(event: "entry", listener: (entry: EntryData) => void): this;
+	on(event: "entry", listener: (entry: EntryData & AdditionalEntryData) => void): this;
 	on(event: string, listener: (...args: any[]) => void): this;
 }
 
-export class ZipArchive extends Archiver {
-	constructor(options?: ArchiverOptions & ZipOptions);
-}
-
-export class TarArchive extends Archiver {
-	constructor(options?: ArchiverOptions & TarOptions);
-}
-
-export class JsonArchive extends Archiver {
-	constructor(options?: ArchiverOptions);
-}
+export class ZipArchive extends Archiver<ZipOptions, ZipEntryData> {}
+export class TarArchive extends Archiver<TarOptions, TarEntryData> {}
+export class JsonArchive extends Archiver<JsonOptions, JsonEntryData> {}

package/lib/exports/zip.js

@@ -48,21 +48,34 @@ export default class ZipArchive {
     // A `Promise<void>` that resolves when the archive has been written.
     this.promise = new Promise((resolve, reject) => {
       // Listens for all archive data to be written.
-      // 'close' event is fired when all data has been written.
+      // "close" event is fired when all data has been written.
+      //
+      // P.S. Not all stream types are guaranteed to emit the "close" event.
+      // For example, a standard `process.stdout` stream may stay open
+      // for the life of the process and not output a "close" event,
+      // but an `fs.createWriteStream()` will typically emit a "close" event.
+      //
+      // In Node.js streams, the "finish" event signifies that all data has been
+      // successfully flushed to the underlying system, while the "close" event
+      // indicates that the stream's underlying resource (like a file descriptor)
+      // has been fully shut down. The "finish" event always occurs before the "close" event
+      // in a normal, successful operation.
+      //
+      // If you need to know when you can safely perform an action that requires
+      // all data to be persisted (like reading a file you just wrote), you should
+      // wait for the "close" event. If you only need to know when you can stop writing
+      // more data to the stream, the finish "event" is sufficient.
+      //
       this._outputStream.on('close', () => {
         this.size = archive.pointer()
         resolve()
       })
 
-      // // Listens for all archive data to be written.
-      // // `end` event is fired when all archive data has been consumed by a consumer stream.
-      // // @see: https://nodejs.org/api/stream.html#stream_event_end
-      // archive.on('end', function() {
-      //   this.size = archive.pointer()
-      //   resolve()
-      // })
-
-      // Catch "warnings", whatever those're.
+      // Catch "warnings":
+      // * `ArchiverError("DIRECTORYNOTSUPPORTED")` — When the type of archive doesn't support creating directories inside of it.
+      // * `ArchiverError("SYMLINKNOTSUPPORTED")` — When the type of archive doesn't support creating symlinks inside of it.
+      // * `ArchiverError("ENTRYNOTSUPPORTED")` — When the type of archive doesn't support adding a particular "entry" to it: one that's neither a file, nor a directory, nor a symlink. This seems to be some kind of "future proofing".
+      // * `fs.lstat()` errors, such as `{ code: "ENOENT" }` when the file is not found. `Archiver` calls `fs.lstat()` on every `.append(filepath, object)` call in order to determine the file size. After the file size has been determined, it puts the file to the "main queue" for writing it inside the archive.
       archive.on('warning', function(error) {
         reject(error)
         // The following code sample is from `archiver` README:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archiver-node",
-  "version": "8.0.6",
+  "version": "8.0.8",
   "description": "a streaming interface for archive generation",
   "homepage": "https://github.com/catamphetamine/node-archiver",
   "author": {
@@ -22,6 +22,11 @@
       "import": "./index.js",
       "require": "./index.cjs"
     },
+    "./zip": {
+      "types": "./zip/index.d.ts",
+      "import": "./zip/index.js",
+      "require": "./zip/index.cjs"
+    },
     "./package.json": "./package.json"
   },
   "engines": {