From 2a90e32c89212f1ed183b0412e74ec6149c4ed7b Mon Sep 17 00:00:00 2001 From: Jeff Schiller Date: Sun, 12 Dec 2021 11:01:41 -0800 Subject: [PATCH] Updates to jsdoc for better IDE analysis. A couple other minor tweaks. --- archive/unzip.js | 57 ++++++++++++++++++++++++++++---------- build/io/Makefile | 2 +- build/io/bytebuffer-def.js | 8 ++++++ io/bytebuffer-worker.js | 8 ++++++ io/bytebuffer.js | 8 ++++++ io/bytestream-worker.js | 2 +- io/bytestream.js | 2 +- 7 files changed, 69 insertions(+), 18 deletions(-) diff --git a/archive/unzip.js b/archive/unzip.js index 9017823..484c2ee 100644 --- a/archive/unzip.js +++ b/archive/unzip.js @@ -72,7 +72,6 @@ const BIT = [0x01, 0x02, 0x04, 0x08, 0x100, 0x200, 0x400, 0x800, 0x1000, 0x2000, 0x4000, 0x8000]; - class ZipLocalFile { // takes a ByteStream and parses out the local file information constructor(bstream) { @@ -209,9 +208,18 @@ class ZipLocalFile { } } -// returns a table of Huffman codes -// each entry's index is its code and its value is a JavaScript object -// containing {length: 6, symbol: X} +/** + * @typedef SymbolLengthPair + * @property {number} length + * @property {number} symbol + */ + +/** + * Returns a table of Huffman codes. Each entry's key is its code and its value is a JavaScript + * object containing {length: 6, symbol: X}. + * @param {number[]} bitLengths + * @returns {Map} + */ function getHuffmanCodes(bitLengths) { // ensure bitLengths is an array containing at least one element if (typeof bitLengths != typeof [] || bitLengths.length < 1) { @@ -251,6 +259,7 @@ function getHuffmanCodes(bitLengths) { } // Step 3: Assign numerical values to all codes + /** @type Map */ const table = new Map(); for (let n = 0; n < numLengths; ++n) { const len = bitLengths[n]; @@ -282,6 +291,7 @@ function getHuffmanCodes(bitLengths) { // fixed Huffman codes go from 7-9 bits, so we need an array whose index can hold up to 9 bits let fixedHCtoLiteral = null; let fixedHCtoDistance = null; +/** @returns {Map} */ function getFixedLiteralTable() { // create once if (!fixedHCtoLiteral) { @@ -297,6 +307,7 @@ function getFixedLiteralTable() { return fixedHCtoLiteral; } +/** @returns {Map} */ function getFixedDistanceTable() { // create once if (!fixedHCtoDistance) { @@ -309,8 +320,13 @@ function getFixedDistanceTable() { return fixedHCtoDistance; } -// extract one bit at a time until we find a matching Huffman Code -// then return that symbol +/** + * Extract one bit at a time until we find a matching Huffman Code + * then return that symbol. + * @param {bitjs.io.BitStream} bstream + * @param {Map} hcTable + * @returns {number} + */ function decodeSymbol(bstream, hcTable) { let code = 0; let len = 0; @@ -326,7 +342,7 @@ function decodeSymbol(bstream, hcTable) { if (hcTable.has(code) && hcTable.get(code).length == len) { break; } - if (len > hcTable.maxLength) { + if (len > hcTable.length) { err(`Bit stream out of sync, didn't find a Huffman Code, length was ${len} ` + `and table only max code length of ${hcTable.length}`); break; @@ -396,6 +412,13 @@ const DistLookupTable = [ [13, 16385], [13, 24577] ]; +/** + * @param {bitjs.io.BitStream} bstream + * @param {Map} hcLiteralTable + * @param {Map} hcDistanceTable + * @param {bitjs.io.ByteBuffer} buffer + * @returns + */ function inflateBlockData(bstream, hcLiteralTable, hcDistanceTable, buffer) { /* loop (until end of block code recognized) @@ -412,11 +435,9 @@ function inflateBlockData(bstream, hcLiteralTable, hcDistanceTable, buffer) { stream, and copy length bytes from this position to the output stream. */ - let numSymbols = 0; let blockSize = 0; for (; ;) { const symbol = decodeSymbol(bstream, hcLiteralTable); - ++numSymbols; if (symbol < 256) { // copy literal byte to output buffer.insertByte(symbol); @@ -458,15 +479,20 @@ function inflateBlockData(bstream, hcLiteralTable, hcDistanceTable, buffer) { return blockSize; } -// {Uint8Array} compressedData A Uint8Array of the compressed file data. -// compression method 8 -// deflate: http://tools.ietf.org/html/rfc1951 +/** + * Compression method 8. Deflate: http://tools.ietf.org/html/rfc1951 + * @param {Uint8Array} compressedData A Uint8Array of the compressed file data. + * @param {number} numDecompressedBytes + * @returns {Uint8Array} The decompressed array. + */ function inflate(compressedData, numDecompressedBytes) { // Bit stream representing the compressed data. + /** @type {bitjs.io.BitStream} */ const bstream = new bitjs.io.BitStream(compressedData.buffer, false /* rtl */, compressedData.byteOffset, compressedData.byteLength); + /** @type {bitjs.io.ByteBuffer} */ const buffer = new bitjs.io.ByteBuffer(numDecompressedBytes); let blockSize = 0; @@ -523,17 +549,18 @@ function inflate(compressedData, numDecompressedBytes) { // and distance tables together const literalCodeLengths = []; let prevCodeLength = 0; - while (literalCodeLengths.length < numLiteralLengthCodes + numDistanceCodes) { + const maxCodeLengths = numLiteralLengthCodes + numDistanceCodes; + while (literalCodeLengths.length < maxCodeLengths) { const symbol = decodeSymbol(bstream, codeLengthsCodes); if (symbol <= 15) { literalCodeLengths.push(symbol); prevCodeLength = symbol; - } else if (symbol == 16) { + } else if (symbol === 16) { let repeat = bstream.readBits(2) + 3; while (repeat--) { literalCodeLengths.push(prevCodeLength); } - } else if (symbol == 17) { + } else if (symbol === 17) { let repeat = bstream.readBits(3) + 3; while (repeat--) { literalCodeLengths.push(0); diff --git a/build/io/Makefile b/build/io/Makefile index c7c3d1d..43dcd9f 100644 --- a/build/io/Makefile +++ b/build/io/Makefile @@ -1,4 +1,4 @@ -OUT_PATH=/out/io +OUT_PATH=../../io BITSTREAM_MODULE=${OUT_PATH}/bitstream.js BITSTREAM_WORKER=${OUT_PATH}/bitstream-worker.js diff --git a/build/io/bytebuffer-def.js b/build/io/bytebuffer-def.js index 19f2f52..276e5d7 100644 --- a/build/io/bytebuffer-def.js +++ b/build/io/bytebuffer-def.js @@ -21,7 +21,15 @@ if (typeof numBytes != typeof 1 || numBytes <= 0) { throw "Error! ByteBuffer initialized with '" + numBytes + "'"; } + /** + * @type {Uint8Array} + * @public + */ this.data = new Uint8Array(numBytes); + /** + * @type {number} + * @public + */ this.ptr = 0; } diff --git a/io/bytebuffer-worker.js b/io/bytebuffer-worker.js index 8e2420f..83f33c6 100644 --- a/io/bytebuffer-worker.js +++ b/io/bytebuffer-worker.js @@ -25,7 +25,15 @@ bitjs.io.ByteBuffer = if (typeof numBytes != typeof 1 || numBytes <= 0) { throw "Error! ByteBuffer initialized with '" + numBytes + "'"; } + /** + * @type {Uint8Array} + * @public + */ this.data = new Uint8Array(numBytes); + /** + * @type {number} + * @public + */ this.ptr = 0; } diff --git a/io/bytebuffer.js b/io/bytebuffer.js index 8426ce7..4ab547c 100644 --- a/io/bytebuffer.js +++ b/io/bytebuffer.js @@ -23,7 +23,15 @@ export const ByteBuffer = if (typeof numBytes != typeof 1 || numBytes <= 0) { throw "Error! ByteBuffer initialized with '" + numBytes + "'"; } + /** + * @type {Uint8Array} + * @public + */ this.data = new Uint8Array(numBytes); + /** + * @type {number} + * @public + */ this.ptr = 0; } diff --git a/io/bytestream-worker.js b/io/bytestream-worker.js index 93e8520..5b58ea0 100644 --- a/io/bytestream-worker.js +++ b/io/bytestream-worker.js @@ -281,7 +281,7 @@ bitjs.io.ByteStream = /** * Feeds more bytes into the back of the stream. - * @param {ArrayBuffer} ab + * @param {ArrayBuffer} ab */ push(ab) { if (!(ab instanceof ArrayBuffer)) { diff --git a/io/bytestream.js b/io/bytestream.js index 1cc605c..b7960d9 100644 --- a/io/bytestream.js +++ b/io/bytestream.js @@ -279,7 +279,7 @@ export const ByteStream = /** * Feeds more bytes into the back of the stream. - * @param {ArrayBuffer} ab + * @param {ArrayBuffer} ab */ push(ab) { if (!(ab instanceof ArrayBuffer)) {