From 0d144fef7a6223ecddf1c5d8d961cecedd2a69dd Mon Sep 17 00:00:00 2001 From: Dimitri Benin Date: Sat, 2 Feb 2019 18:16:38 +0100 Subject: [PATCH] [adm-zip] Cleanup types and docs, add missing parameters --- types/adm-zip/adm-zip-tests.ts | 61 ++++---- types/adm-zip/index.d.ts | 248 +++++++++++++-------------------- types/adm-zip/tsconfig.json | 4 +- types/adm-zip/tslint.json | 78 +---------- 4 files changed, 130 insertions(+), 261 deletions(-) diff --git a/types/adm-zip/adm-zip-tests.ts b/types/adm-zip/adm-zip-tests.ts index 2418597087..bd17c098be 100644 --- a/types/adm-zip/adm-zip-tests.ts +++ b/types/adm-zip/adm-zip-tests.ts @@ -1,62 +1,69 @@ - -import AdmZip = require("adm-zip"); +import AdmZip = require('adm-zip'); // reading archives -var zip = new AdmZip("./my_file.zip"); -var zipEntries: AdmZip.IZipEntry[] = zip.getEntries(); // an array of ZipEntry records +const zip = new AdmZip('./my_file.zip'); +const zipEntries: AdmZip.IZipEntry[] = zip.getEntries(); // an array of ZipEntry records -zipEntries.forEach(function (zipEntry) { +zipEntries.forEach(zipEntry => { console.log(zipEntry.toString()); // outputs zip entries information - if (zipEntry.entryName == "my_file.txt") { + if (zipEntry.entryName === 'my_file.txt') { console.log(zipEntry.getData().toString('utf8')); } }); // outputs the content of some_folder/my_file.txt -console.log(zip.readAsText("some_folder/my_file.txt")); +console.log(zip.readAsText('some_folder/my_file.txt')); // extracts the specified file to the specified location -zip.extractEntryTo(/*entry name*/"some_folder/my_file.txt", /*target path*/"/home/me/tempfolder", /*overwrite*/true) +zip.extractEntryTo( + /*entry name*/ 'some_folder/my_file.txt', + /*target path*/ '/home/me/tempfolder', + /*overwrite*/ true +); // extracts everything -zip.extractAllTo(/*target path*/"/home/me/zipcontent/", /*overwrite*/true); +zip.extractAllTo(/*target path*/ '/home/me/zipcontent/', /*overwrite*/ true); // extracts everything and calls callback -> async extracction -zip.extractAllToAsync(/*target path*/"/home/me/zipcontent/", /*overwrite*/true, (error: Error)=> {}); +zip.extractAllToAsync( + /*target path*/ '/home/me/zipcontent/', + /*overwrite*/ true, + (error: Error) => {} +); // creating archives -var zip = new AdmZip(); +new AdmZip(); // add file directly -zip.addFile("test.txt", new Buffer("inner content of the file"), "entry comment goes here"); +zip.addFile('test.txt', new Buffer('inner content of the file'), 'entry comment goes here'); // add local file -zip.addLocalFile("/home/me/some_picture.png"); +zip.addLocalFile('/home/me/some_picture.png'); // get everything as a buffer -var willSendthis = zip.toBuffer(); +const willSendthis = zip.toBuffer(); // or write everything to disk -zip.writeZip(/*target file name*/"/home/me/files.zip"); +zip.writeZip(/*target file name*/ '/home/me/files.zip'); function processZipEntry(zipEntry: AdmZip.IZipEntry) { console.log('comment', zipEntry.comment); } -//tests taken from examples at https://github.com/cthackers/adm-zip/wiki/ADM-ZIP -import Zip = require("adm-zip"); +// tests taken from examples at https://github.com/cthackers/adm-zip/wiki/ADM-ZIP +import Zip = require('adm-zip'); // loads and parses existing zip file local_file.zip -var zip = new Zip("local_file.zip"); +new Zip('local_file.zip'); // creates new in memory zip -zip = new Zip(); +new Zip(); // loads and parses existing zip file local_file.zip -zip = new Zip("local_file.zip"); +new Zip('local_file.zip'); // get all entries and iterate them -zip.getEntries().forEach((entry) => { - var entryName = entry.entryName; - var decompressedData = zip.readFile(entry); // decompressed buffer of the entry - console.log(zip.readAsText(entry)); // outputs the decompressed content of the entry +zip.getEntries().forEach(entry => { + const entryName = entry.entryName; + const decompressedData = zip.readFile(entry); // decompressed buffer of the entry + console.log(zip.readAsText(entry)); // outputs the decompressed content of the entry }); // will extract the file myfile.txt from the archive to /home/user/folder/subfolder/myfile.txt -zip.extractEntryTo("folder/subfolder/myfile.txt", "/home/user/", true, true); +zip.extractEntryTo('folder/subfolder/myfile.txt', '/home/user/', true, true); // will extract the file myfile.txt from the archive to /home/user/myfile.txt -zip.extractEntryTo("folder/subfolder/myfile.txt", "/home/user/", false, true); +zip.extractEntryTo('folder/subfolder/myfile.txt', '/home/user/', false, true); function isAdmZipEntry(obj: any): obj is AdmZip.IZipEntry { - return obj !== null && typeof obj === "object" && typeof obj['entryName'] === 'string'; + return obj !== null && typeof obj === 'object' && typeof obj['entryName'] === 'string'; } diff --git a/types/adm-zip/index.d.ts b/types/adm-zip/index.d.ts index 39725932fc..52fd86a9e0 100644 --- a/types/adm-zip/index.d.ts +++ b/types/adm-zip/index.d.ts @@ -1,90 +1,56 @@ -// Type definitions for adm-zip v0.4.4 +// Type definitions for adm-zip 0.4 // Project: https://github.com/cthackers/adm-zip -// Definitions by: John Vilk , Abner Oliveira +// Definitions by: John Vilk +// Abner Oliveira +// BendingBender // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped /// - declare class AdmZip { /** - * Create a new, empty archive. + * @param fileNameOrRawData If provided, reads an existing archive. Otherwise creates a new, empty archive. */ - constructor(); + constructor(fileNameOrRawData?: string | Buffer); /** - * Read an existing archive. + * Extracts the given entry from the archive and returns the content. + * @param entry The full path of the entry or a `IZipEntry` object. + * @return `Buffer` or `null` in case of error. */ - constructor(fileName: string); - constructor(rawData: Buffer); + readFile(entry: string | AdmZip.IZipEntry): Buffer | null; /** - * Extracts the given entry from the archive and returns the content as a - * Buffer object. - * @param entry String with the full path of the entry - * @return Buffer or Null in case of error + * Asynchronous `readFile`. + * @param entry The full path of the entry or a `IZipEntry` object. + * @param callback Called with a `Buffer` or `null` in case of error. */ - readFile(entry: string): Buffer; - /** - * Extracts the given entry from the archive and returns the content as a - * Buffer object. - * @param entry ZipEntry object - * @return Buffer or Null in case of error - */ - readFile(entry: AdmZip.IZipEntry): Buffer; - /** - * Asynchronous readFile - * @param entry String with the full path of the entry - * @param callback Called with a Buffer or Null in case of error - */ - readFileAsync(entry: string, callback: (data: Buffer, err: string) => any): void; - /** - * Asynchronous readFile - * @param entry ZipEntry object - * @param callback Called with a Buffer or Null in case of error - * @return Buffer or Null in case of error - */ - readFileAsync(entry: AdmZip.IZipEntry, callback: (data: Buffer, err: string) => any): void; + readFileAsync( + entry: string | AdmZip.IZipEntry, + callback: (data: Buffer | null, err: string) => any + ): void; /** * Extracts the given entry from the archive and returns the content as - * plain text in the given encoding - * @param entry String with the full path of the entry - * @param encoding Optional. If no encoding is specified utf8 is used - * @return String + * plain text in the given encoding. + * @param entry The full path of the entry or a `IZipEntry` object. + * @param encoding If no encoding is specified `"utf8"` is used. */ - readAsText(fileName: string, encoding?: string): string; + readAsText(fileName: string | AdmZip.IZipEntry, encoding?: string): string; /** - * Extracts the given entry from the archive and returns the content as - * plain text in the given encoding - * @param entry ZipEntry object - * @param encoding Optional. If no encoding is specified utf8 is used - * @return String - */ - readAsText(fileName: AdmZip.IZipEntry, encoding?: string): string; - /** - * Asynchronous readAsText - * @param entry String with the full path of the entry + * Asynchronous `readAsText`. + * @param entry The full path of the entry or a `IZipEntry` object. * @param callback Called with the resulting string. - * @param encoding Optional. If no encoding is specified utf8 is used + * @param encoding If no encoding is specified `"utf8"` is used. */ - readAsTextAsync(fileName: string, callback: (data: string) => any, encoding?: string): void; - /** - * Asynchronous readAsText - * @param entry ZipEntry object - * @param callback Called with the resulting string. - * @param encoding Optional. If no encoding is specified utf8 is used - */ - readAsTextAsync(fileName: AdmZip.IZipEntry, callback: (data: string) => any, encoding?: string): void; + readAsTextAsync( + fileName: string | AdmZip.IZipEntry, + callback: (data: string) => any, + encoding?: string + ): void; /** * Remove the entry from the file or the entry and all its nested directories - * and files if the given entry is a directory - * @param entry String with the full path of the entry + * and files if the given entry is a directory. + * @param entry The full path of the entry or a `IZipEntry` object. */ - deleteFile(entry: string): void; - /** - * Remove the entry from the file or the entry and all its nested directories - * and files if the given entry is a directory - * @param entry A ZipEntry object. - */ - deleteFile(entry: AdmZip.IZipEntry): void; + deleteFile(entry: string | AdmZip.IZipEntry): void; /** * Adds a comment to the zip. The zip must be rewritten after * adding the comment. @@ -92,72 +58,55 @@ declare class AdmZip { */ addZipComment(comment: string): void; /** - * Returns the zip comment * @return The zip comment. */ getZipComment(): string; /** - * Adds a comment to a specified zipEntry. The zip must be rewritten after + * Adds a comment to a specified file or `IZipEntry`. The zip must be rewritten after * adding the comment. * The comment cannot exceed 65535 characters in length. - * @param entry String with the full path of the entry + * @param entry The full path of the entry or a `IZipEntry` object. * @param comment The comment to add to the entry. */ - addZipEntryComment(entry: string, comment: string): void; - /** - * Adds a comment to a specified zipEntry. The zip must be rewritten after - * adding the comment. - * The comment cannot exceed 65535 characters in length. - * @param entry ZipEntry object. - * @param comment The comment to add to the entry. - */ - addZipEntryComment(entry: AdmZip.IZipEntry, comment: string): void; + addZipEntryComment(entry: string | AdmZip.IZipEntry, comment: string): void; /** * Returns the comment of the specified entry. - * @param entry String with the full path of the entry. - * @return String The comment of the specified entry. + * @param entry The full path of the entry or a `IZipEntry` object. + * @return The comment of the specified entry. */ - getZipEntryComment(entry: string): string; - /** - * Returns the comment of the specified entry - * @param entry ZipEntry object. - * @return String The comment of the specified entry. - */ - getZipEntryComment(entry: AdmZip.IZipEntry): string; + getZipEntryComment(entry: string | AdmZip.IZipEntry): string; /** * Updates the content of an existing entry inside the archive. The zip - * must be rewritten after updating the content - * @param entry String with the full path of the entry. + * must be rewritten after updating the content. + * @param entry The full path of the entry or a `IZipEntry` object. * @param content The entry's new contents. */ - updateFile(entry: string, content: Buffer): void; - /** - * Updates the content of an existing entry inside the archive. The zip - * must be rewritten after updating the content - * @param entry ZipEntry object. - * @param content The entry's new contents. - */ - updateFile(entry: AdmZip.IZipEntry, content: Buffer): void; + updateFile(entry: string | AdmZip.IZipEntry, content: Buffer): void; /** * Adds a file from the disk to the archive. * @param localPath Path to a file on disk. * @param zipPath Path to a directory in the archive. Defaults to the empty * string. + * @param zipName Name for the file. */ - addLocalFile(localPath: string, zipPath?: string): void; + addLocalFile(localPath: string, zipPath?: string, zipName?: string): void; /** * Adds a local directory and all its nested files and directories to the * archive. * @param localPath Path to a folder on disk. - * @param zipPath Path to a folder in the archive. Defaults to an empty - * string. + * @param zipPath Path to a folder in the archive. Default: `""`. + * @param filter RegExp or Function if files match will be included. */ - addLocalFolder(localPath: string, zipPath?: string): void; + addLocalFolder( + localPath: string, + zipPath?: string, + filter?: RegExp | ((filename: string) => boolean) + ): void; /** * Allows you to create a entry (file or directory) in the zip file. - * If you want to create a directory the entryName must end in / and a null + * If you want to create a directory the `entryName` must end in `"/"` and a `null` * buffer should be provided. - * @param entryName Entry path + * @param entryName Entry path. * @param content Content to add to the entry; must be a 0-length buffer * for a directory. * @param comment Comment to add to the entry. @@ -165,89 +114,81 @@ declare class AdmZip { */ addFile(entryName: string, data: Buffer, comment?: string, attr?: number): void; /** - * Returns an array of ZipEntry objects representing the files and folders - * inside the archive + * Returns an array of `IZipEntry` objects representing the files and folders + * inside the archive. */ getEntries(): AdmZip.IZipEntry[]; /** - * Returns a ZipEntry object representing the file or folder specified by - * ``name``. + * Returns a `IZipEntry` object representing the file or folder specified by `name`. * @param name Name of the file or folder to retrieve. - * @return ZipEntry The entry corresponding to the name. + * @return The entry corresponding to the `name`. */ getEntry(name: string): AdmZip.IZipEntry; /** - * Extracts the given entry to the given targetPath. + * Extracts the given entry to the given `targetPath`. * If the entry is a directory inside the archive, the entire directory and * its subdirectories will be extracted. - * @param entry String with the full path of the entry - * @param targetPath Target folder where to write the file - * @param maintainEntryPath If maintainEntryPath is true and the entry is - * inside a folder, the entry folder will be created in targetPath as - * well. Default is TRUE + * @param entry The full path of the entry or a `IZipEntry` object. + * @param targetPath Target folder where to write the file. + * @param maintainEntryPath If maintainEntryPath is `true` and the entry is + * inside a folder, the entry folder will be created in `targetPath` as + * well. Default: `true`. * @param overwrite If the file already exists at the target path, the file - * will be overwriten if this is true. Default is FALSE - * - * @return Boolean + * will be overwriten if this is `true`. Default: `false`. */ - extractEntryTo(entryPath: string, targetPath: string, maintainEntryPath?: boolean, overwrite?: boolean): boolean; + extractEntryTo( + entryPath: string | AdmZip.IZipEntry, + targetPath: string, + maintainEntryPath?: boolean, + overwrite?: boolean + ): boolean; /** - * Extracts the given entry to the given targetPath. - * If the entry is a directory inside the archive, the entire directory and - * its subdirectories will be extracted. - * @param entry ZipEntry object - * @param targetPath Target folder where to write the file - * @param maintainEntryPath If maintainEntryPath is true and the entry is - * inside a folder, the entry folder will be created in targetPath as - * well. Default is TRUE + * Extracts the entire archive to the given location. + * @param targetPath Target location. * @param overwrite If the file already exists at the target path, the file - * will be overwriten if this is true. Default is FALSE - * @return Boolean - */ - extractEntryTo(entryPath: AdmZip.IZipEntry, targetPath: string, maintainEntryPath?: boolean, overwrite?: boolean): boolean; - /** - * Extracts the entire archive to the given location - * @param targetPath Target location - * @param overwrite If the file already exists at the target path, the file - * will be overwriten if this is true. Default is FALSE + * will be overwriten if this is `true`. Default: `false`. */ extractAllTo(targetPath: string, overwrite?: boolean): void; /** - * Extracts the entire archive to the given location - * @param targetPath Target location + * Extracts the entire archive to the given location. + * @param targetPath Target location. * @param overwrite If the file already exists at the target path, the file - * will be overwriten if this is true. Default is FALSE - * @param callback The callback function will be called afeter extraction + * will be overwriten if this is `true`. Default: `false`. + * @param callback The callback function will be called after extraction. */ - extractAllToAsync(targetPath: string, overwrite: boolean, callback: (error: Error) => void): void; + extractAllToAsync( + targetPath: string, + overwrite?: boolean, + callback?: (error: Error) => void + ): void; /** * Writes the newly created zip file to disk at the specified location or - * if a zip was opened and no ``targetFileName`` is provided, it will - * overwrite the opened zip - * @param targetFileName + * if a zip was opened and no `targetFileName` is provided, it will + * overwrite the opened zip. */ - writeZip(targetPath?: string): void; + writeZip(targetFileName?: string, callback?: (error: Error | null) => void): void; /** - * Returns the content of the entire zip file as a Buffer object - * @return Buffer + * Returns the content of the entire zip file. */ toBuffer(): Buffer; } declare namespace AdmZip { /** - * The ZipEntry is more than a structure representing the entry inside the + * The `IZipEntry` is more than a structure representing the entry inside the * zip file. Beside the normal attributes and headers a entry can have, the * class contains a reference to the part of the file where the compressed * data resides and decompresses it when requested. It also compresses the * data and creates the headers required to write in the zip file. */ + // disable warning about the I-prefix in interface name to prevent breaking stuff for users without a major bump + // tslint:disable-next-line:interface-name interface IZipEntry { /** * Represents the full name and path of the file */ entryName: string; - rawEntryName: Buffer; + readonly rawEntryName: Buffer; /** * Extra data associated with this entry. */ @@ -256,15 +197,16 @@ declare namespace AdmZip { * Entry comment. */ comment: string; - name: string; + readonly name: string; /** * Read-Only property that indicates the type of the entry. */ - isDirectory: boolean; + readonly isDirectory: boolean; /** * Get the header associated with this ZipEntry. */ header: Buffer; + attr: number; /** * Retrieve the compressed data for this entry. Note that this may trigger * compression if any properties were modified. @@ -278,11 +220,7 @@ declare namespace AdmZip { /** * Set the (uncompressed) data to be associated with this entry. */ - setData(value: string): void; - /** - * Set the (uncompressed) data to be associated with this entry. - */ - setData(value: Buffer): void; + setData(value: string | Buffer): void; /** * Get the decompressed data associated with this entry. */ diff --git a/types/adm-zip/tsconfig.json b/types/adm-zip/tsconfig.json index 8e998c6f38..7bcb8d3644 100644 --- a/types/adm-zip/tsconfig.json +++ b/types/adm-zip/tsconfig.json @@ -6,7 +6,7 @@ ], "noImplicitAny": true, "noImplicitThis": true, - "strictNullChecks": false, + "strictNullChecks": true, "strictFunctionTypes": true, "baseUrl": "../", "typeRoots": [ @@ -20,4 +20,4 @@ "index.d.ts", "adm-zip-tests.ts" ] -} \ No newline at end of file +} diff --git a/types/adm-zip/tslint.json b/types/adm-zip/tslint.json index a41bf5d19a..f93cf8562a 100644 --- a/types/adm-zip/tslint.json +++ b/types/adm-zip/tslint.json @@ -1,79 +1,3 @@ { - "extends": "dtslint/dt.json", - "rules": { - "adjacent-overload-signatures": false, - "array-type": false, - "arrow-return-shorthand": false, - "ban-types": false, - "callable-types": false, - "comment-format": false, - "dt-header": false, - "eofline": false, - "export-just-namespace": false, - "import-spacing": false, - "interface-name": false, - "interface-over-type-literal": false, - "jsdoc-format": false, - "max-line-length": false, - "member-access": false, - "new-parens": false, - "no-any-union": false, - "no-boolean-literal-compare": false, - "no-conditional-assignment": false, - "no-consecutive-blank-lines": false, - "no-construct": false, - "no-declare-current-package": false, - "no-duplicate-imports": false, - "no-duplicate-variable": false, - "no-empty-interface": false, - "no-for-in-array": false, - "no-inferrable-types": false, - "no-internal-module": false, - "no-irregular-whitespace": false, - "no-mergeable-namespace": false, - "no-misused-new": false, - "no-namespace": false, - "no-object-literal-type-assertion": false, - "no-padding": false, - "no-redundant-jsdoc": false, - "no-redundant-jsdoc-2": false, - "no-redundant-undefined": false, - "no-reference-import": false, - "no-relative-import-in-test": false, - "no-self-import": false, - "no-single-declare-module": false, - "no-string-throw": false, - "no-unnecessary-callback-wrapper": false, - "no-unnecessary-class": false, - "no-unnecessary-generics": false, - "no-unnecessary-qualifier": false, - "no-unnecessary-type-assertion": false, - "no-useless-files": false, - "no-var-keyword": false, - "no-var-requires": false, - "no-void-expression": false, - "no-trailing-whitespace": false, - "object-literal-key-quotes": false, - "object-literal-shorthand": false, - "one-line": false, - "one-variable-per-declaration": false, - "only-arrow-functions": false, - "prefer-conditional-expression": false, - "prefer-const": false, - "prefer-declare-function": false, - "prefer-for-of": false, - "prefer-method-signature": false, - "prefer-template": false, - "radix": false, - "semicolon": false, - "space-before-function-paren": false, - "space-within-parens": false, - "strict-export-declare-modifiers": false, - "trim-file": false, - "triple-equals": false, - "typedef-whitespace": false, - "unified-signatures": false, - "void-return": false, - "whitespace": false - } + "extends": "dtslint/dt.json" }